Token Setup

Token Setup

The plugin uses a GitHub Personal Access Token (PAT) to authenticate with the GitHub API. A token is required to:

• Publish a release (create release, upload assets)
• Download from private repositories
• Update dependencies (updateGithubDependencies task)
• Clone private resource repositories

Public repository downloads work without a token.

Creating a token

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click Generate new token (classic)
3. Give it a descriptive name (e.g. github-gradle)
4. Select scopes:
   • repo — full access to public and private repositories (required for publishing and private downloads)
   • read:packages — only needed if you use GitHub Packages alongside this plugin
5. Click Generate token and copy it immediately (it is shown only once)

Fine-grained tokens also work if you grant Contents: Read and write on the target repository.

Supplying the token

Option 1 — Inline (not recommended for shared builds)

github {
    accessToken = "ghp_YOUR_TOKEN_HERE"
}

Option 2 — Gradle properties (recommended)

Add to ~/.gradle/gradle.properties (user home, not the project):

githubToken=ghp_YOUR_TOKEN_HERE

Then reference it in build.gradle:

github {
    accessToken = project.findProperty("githubToken") ?: ""
}

Option 3 — File path

github {
    accessToken = file("${System.getProperty('user.home')}/.github_token")
}

The plugin reads the token from the file at build time.

Option 4 — Environment variable

github {
    accessToken = System.getenv("GITHUB_TOKEN") ?: ""
}

This is the recommended approach for CI/CD pipelines (GitHub Actions, etc.).

GitHub Actions

In a GitHub Actions workflow the token is available automatically:

- name: Publish release
  run: gradle publishGithub
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

// build.gradle
github {
    accessToken = System.getenv("GITHUB_TOKEN") ?: ""
}

secrets.GITHUB_TOKEN has repo scope for the current repository, which is sufficient for publishing.

Security notes

• Never commit a raw token to source control
• Use ~/.gradle/gradle.properties for local development
• Use repository secrets for CI/CD
• Rotate tokens that may have been exposed