Obtaining a GitHub Personal Access Token#

A GitHub Personal Access Token (PAT) is optional for basic usage of review-pr on public repositories, but is required in some cases and strongly recommended in others. This page explains when you need one and how to create it.

Why a token?#

The GitHub REST API allows unauthenticated requests, but they are subject to strict rate limits (60 requests per hour per IP address). Authenticated requests receive a much higher limit (5 000 per hour). A token is also required when:

  • the target repository is private.

  • you use the --copilot-review flag (GitHub Models API access is tied to your GitHub account).

Token types#

GitHub offers two types of personal access tokens:

Fine-grained tokens (recommended)

Scoped to specific repositories with explicit permission grants. Available for free and paid accounts.

Classic tokens (legacy)

Broader access — suitable when fine-grained tokens are not yet supported by an integration.

Which token type should I use?#

For open-source projects you are contributing to, use a fine-grained token scoped to read-only Pull requests and Contents permissions on the target repository. This follows the principle of least privilege: if the token is ever exposed, an attacker can only read public data they could access anyway.

Use a classic token only if the upstream organisation has disabled fine-grained tokens for third-party applications (rare), or if you are accessing many repositories at once and the per-repository scoping of fine-grained tokens becomes impractical.

Creating a fine-grained token#

  1. Sign in to github.com.

  2. Click your avatar in the top-right corner and choose Settings.

  3. In the left sidebar, click Developer settings.

  4. Under Personal access tokens, choose Fine-grained tokens.

  5. Click Generate new token.

  6. Fill in:

    • Token name — a descriptive name, e.g. review-pr.

    • Expiration — choose an expiry that suits your security policy.

    • Resource owner — your personal account or an organisation.

    • Repository access — select Only select repositories and choose the repositories the token needs to access, or choose All repositories.

  7. Under Permissions → Repository permissions, grant:

    • Contents → Read-only (needed to read the repository).

    • Pull requests → Read-only (needed to fetch PR data).

    • Metadata → Read-only (required automatically).

  8. Click Generate token and copy the token immediately — it will not be shown again.

Creating a classic token#

  1. Sign in to github.com.

  2. Go to Settings → Developer settings → Personal access tokens → Tokens (classic).

  3. Click Generate new token (classic).

  4. Provide a Note, set an Expiration, and select the scopes:

    • repo — full repository access, including private repositories.

    • public_repo — read access to public repositories only (sufficient when all target repositories are public).

  5. Click Generate token and copy it.

Storing the token#

Never hard-code the token in scripts. The recommended approaches are:

Environment variable (local development):

export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
review-pr xadupre my-own-accelerator 1

The review-pr command picks up GITHUB_TOKEN automatically, so no --token flag is needed once the environment variable is set.

GitHub Actions secret#

In a GitHub Actions workflow the GITHUB_TOKEN secret is injected automatically. Pass it to the step explicitly if needed:

- name: Review PR
  run: review-pr "${{ github.repository_owner }}" "${{ github.event.repository.name }}" "${{ github.event.pull_request.number }}"
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The token provided by GitHub Actions already has contents: read and pull-requests: read permissions by default for workflows triggered on pull request events.

See also#