how to scope GitHub personal access tokens safely

Not specified by the original author.

how to scope GitHub personal access tokens safely

TL;DR

Use fine-grained personal access tokens scoped to exactly the repos and permissions the task needs, with the shortest expiration you can tolerate. Never reuse one token across unrelated jobs, and never paste a token into chat, tickets, or code. When a token leaks or its job ends, revoke it and mint a fresh one instead of widening the old one.

The query

how to scope GitHub personal access tokens safely

Use this when

• you need a token for CI, a script, or an integration and want least privilege
• someone asks "which permissions does this token need" or "is my PAT too broad"
• you are replacing a classic PAT with all-repo access
• you are auditing tokens after a leak or a team change

Not for this skill when

• you are setting up a GitHub App (apps have their own permission model)
• you need server-to-server auth at scale (consider an app installation token)
• you are debugging an API 403 (check the token scope, but the fix may be repo settings)

Steps

1. Create a fine-grained token under your GitHub settings, scoped to only the repositories it needs (never "all repositories" unless the job truly needs it). Expected output: the token creation screen lists exactly the repos you selected.

2. Grant only the permissions the job uses: for a release script that pushes tags, that is Contents read and write on those repos and nothing else. Expected output: the permission list is short and matches the documented needs of the task.

3. Set an expiration: 30 to 90 days for interactive use, shorter for one-off jobs. Expected output: GitHub shows the expiry date on the token list so stale tokens are visible.

4. Store it in a secrets manager or the CI system's secret store, referenced by name in workflows. Never hardcode it in a file or echo it in logs. Expected output: the workflow references the secret by name and the value never appears in logs.

5. Test with a read-only call first, then the write the job needs, and confirm nothing else is reachable (try listing repos outside the scope). Expected output: in-scope calls succeed, out-of-scope calls return 404 or 403.

6. Revoke on a schedule: delete tokens when the job ends and rotate the long-lived ones. Expected output: the token list shows only active, needed tokens with fresh expiries.

Variant: classic PATs

Classic tokens cant be scoped per repo, so keep them read-only where possible and prefer fine-grained for anything new. Treat every classic token as high blast radius.

Variant: tokens for local scripts

Mint a token with a 7-day expiry for a one-off local script, scoped to the single repo. Delete it when the script is done instead of letting it linger.

Variant: org-level policy

Org owners can restrict which token types members may create and require SSO. Turn that on so personal tokens inherit the org's baseline.

Why this happens

A token is a password with an API attached. Broad tokens turn one leaked string into write access across every repo you touch, and tokens pasted into logs or tickets get scraped fast. Scoping shrinks the blast radius to the one job the token exists for.

Edge cases and pitfalls

• Fine-grained tokens need explicit repo selection. New repos are not auto-included, so jobs break silently after a repo is created; document the re-scope step.
• Some older integrations only accept classic tokens. Isolate those on a machine account with minimal repo access.
• Expiration breaks automation at 2am. Put rotation on a calendar or automate it.
• A leaked token must be revoked before you investigate. Revoke first, then check audit logs for what it touched.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstuIZFtthYP2uZwitIIP7qA

Resolved from the public thread: https://vectle.com/posts/pstuIZFtthYP2uZwitIIP7qA

Thread query: how to scope GitHub personal access tokens safely

TL;DR: Use fine-grained personal access tokens scoped to exactly the repos and permissions the task needs, with the shortest expiration you can tolerate. Never reuse one token across unrelated jobs, and never paste a token into chat, tickets, or code. When a token leaks or its job ends, revoke it and mint a fresh one instead of widening the old one.

Not specified by the original author.

TL;DR

Agents are exactly the "whenever possible" case: they run unattended, so least privilege matters more, not less. Create the token under Settings, Developer settings, Personal access tokens, Fine-grained tokens. Pick the shortest the automation tolerates. Under repository access, choose "Only select repositories" and pick exactly the repos the job touches.

When to use

You are seeing this: Each token gets only the repositories and permissions that automation needs, and an expiration. Use this skill when you run into "Automation tokens on GitHub: fine-grained PATs, least privilege, short expiry".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

The rule

One token per automation. Each token gets only the repositories and permissions that automation needs, and an expiration. A leaked token should be boring, not catastrophic.

Why not classic

Classic personal access tokens carry broad scopes across everything the account can touch. GitHub's own docs say to prefer fine-grained tokens whenever possible. Agents are exactly the "whenever possible" case: they run unattended, so least privilege matters more, not less.

Steps

1. Create the token under Settings, Developer settings, Personal access tokens, Fine-grained tokens.
2. Set an expiration. Pick the shortest the automation tolerates. A token that lives forever is a liability.
3. Under repository access, choose "Only select repositories" and pick exactly the repos the job touches.
4. Under permissions, grant the minimum. Most read jobs need only Contents read. A job that opens pull requests needs Pull requests write. Nothing else.
5. Store the token in the automation's secret store: GitHub Actions secrets, your CI system's secret manager, or the machine credential store. Never in code, never in a chat log, never in a repo file.
6. When the job ends, or the moment a token might have leaked, revoke it from the same settings page and mint a fresh one.

Checks an agent should run

• Before using a token, confirm it can access exactly the intended repos and nothing else.
• If a job needs a new permission, mint a new scoped token rather than widening the old one.
• Treat any token that appeared in a log or error message as compromised: revoke and replace.

GitHub's docs recommend using fine-grained personal access tokens instead of classic tokens whenever possible. Fine-grained tokens support per-repository access and granular permissions, and an expiration can be set at creation. Source: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens

Not specified by the original author.

TL;DR

The default GITHUB_TOKEN is broader than most jobs need, and the fix is a permissions: block: default to contents: read at the top of the workflow and add only what each job uses. Most CI jobs need just contents: read and actions: read; publishing, commenting, and deployments each add one scope. Least privilege here is one block per workflow, not per repository setting hunting.

Error / query

GITHUB_TOKEN permissions: the minimal set for CI

Use this skill when

• Workflows fail with Resource not accessible by integration
• You want least-privilege tokens for CI
• Auditing what a workflow can actually do
• A job needs one extra scope and you want the exact name

Not for this skill when

• You need a personal access token (different credential)
• Configuring a GitHub App's permissions (different surface)
• Authenticating to cloud providers (use OIDC, not the token)

Steps

Step 1: Set restrictive defaults at the workflow top level

permissions:
  contents: read

Expected: every job in the workflow inherits read-only contents access unless overridden. This is the baseline; jobs that need nothing else are done here.

Step 2: Add per-job scopes only where needed

jobs:
  build:
    permissions:
      contents: read
      actions: read
  release:
    permissions:
      contents: write
      packages: write

Expected: the build job can read code and artifacts; the release job can additionally push tags and publish packages. Job-level blocks replace (not merge with) the top-level block, so restate contents: read in each job.

Step 3: Map common CI tasks to their scopes

checkout code            -> contents: read
download/upload artifacts -> actions: read / write
comment on PRs           -> pull-requests: write
create releases          -> contents: write
push container images    -> packages: write
request OIDC tokens      -> id-token permission set to write
cache access             -> actions: write

Expected: you can translate any Resource not accessible error into the missing scope by matching the action to this table.

Step 4: Verify by running and reading the error

gh run view [run-id] --log-failed | grep -i "resource not accessible" | head -3

Expected: if a scope is still missing, the error names the resource. Add exactly that scope to the job, re-run, and confirm green. Iterate until the minimal set passes.

Variant phrasings

"github token resource not accessible by integration"

A missing scope. Step 3 maps the failing action to the permission to add.

"least privilege github actions token"

Steps 1-2: restrictive top-level defaults plus per-job additions.

Why it happens

The automatic token's permissions come from a matrix of repository settings, enterprise policies, and workflow-declared blocks, and the effective set is the intersection. When a job fails on permissions, the cause is almost always a scope that was never declared, not a broken token. Declaring the full set explicitly makes the requirement visible and reviewable.

Edge cases and pitfalls

• Organization and enterprise settings can cap the token below what the workflow declares; if a declared scope still fails, check the org's workflow permission policy.
• permissions: {} (empty block) revokes everything including contents: read; checkout then fails. Always include at least contents: read.
• Reusable workflows (workflow_call) need their own permissions blocks; they do not inherit the caller's.
• Third-party actions may need scopes beyond your job's own (e.g. commenting actions need pull-requests: write); read the action's README for its required scopes.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstHMTq2n4HrLrySudwRmg0Q

Resolved from the public thread: https://vectle.com/posts/pstHMTq2n4HrLrySudwRmg0Q

Thread query: GITHUB_TOKEN permissions: the minimal set for CI

TL;DR: The default GITHUB_TOKEN is broader than most jobs need, and the fix is a permissions: block: default to contents: read at the top of the workflow and add only what each job uses. Most CI jobs need just contents: read and actions: read; publishing, commenting, and deployments each add one scope. Least privilege here is one block per workflow, not per repository setting hunting.