GITHUB_TOKEN permissions: the minimal set for CI

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.

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.

how to lock down GitHub Actions with OIDC

TL;DR

Stop storing cloud access keys as GitHub repo secrets. With OIDC, GitHub mints a short-lived token per workflow run, your cloud trusts GitHub as an identity provider, and the workflow assumes a role with no stored credentials at all. Set up the trust once per cloud account, add the OIDC token permission to the workflow, scope the trust to specific repos and branches, then delete the static keys. Leaked tokens expire in minutes instead of living forever in a secret.

how to lock down GitHub Actions with OIDC

Use this when

• A workflow stores a cloud access key as a repo or org secret
• You are building deploy pipelines that touch AWS, GCP, or Azure
• An audit flags static credentials in CI
• You want deploy access scoped to a repo and branch instead of a shared key

Not for this skill when

• You want OIDC protocol theory (this is the practical setup)
• Your CI is not GitHub Actions (the pattern transfers, the clicks do not)
• You need credentials for local development (use SSO-based CLI login instead)

Steps

1. Create the cloud-side trust (AWS example)

Create an IAM role whose trust policy allows GitHub's OIDC provider, with a condition scoping it to your repo. Then verify the trust looks right:

aws iam get-role --role-name [role-name] --query 'Role.AssumeRolePolicyDocument'

Expected: a trust policy naming the GitHub OIDC provider with a subject condition like repo:[org]/[repo]:. If the condition is missing or wildcarded to , tighten it before going further.

2. Add the minimal permissions block to the workflow

The job needs write access to the OIDC token (the id-token permission) plus whatever else it does, and nothing more:

permissions:
  contents: read
  # plus the OIDC token permission (id-token) set to write,
  # so this job can mint short-lived cloud tokens

grep -n -A6 "permissions:" .github/workflows/deploy.yml

Expected: the permissions block shows contents read and the OIDC token permission at write, with no broad write-all. Reusable workflows called by this job need the permission too.

3. Assume the role with no stored keys

- uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::[account-id]:role/[role-name]
    aws-region: [region]

grep -rn "aws-access-key-id" .github/workflows/ || echo "no static keys found"

Expected: "no static keys found". The action exchanges the OIDC token for temporary role credentials. There is no access key in secrets, in the workflow file, or in logs.

4. Scope the trust to repo and branch

The subject claim is where the real security lives. Scope it to the exact repo and the branches allowed to deploy, for example repo:[org]/[repo]:ref:refs/heads/main for production deploys only:

aws iam get-role --role-name [role-name] --query 'Role.AssumeRolePolicyDocument.Statement[0].Condition'

Expected: a StringLike condition on the subject claim matching only your repo and refs. A pull-request workflow should never be able to assume the production deploy role.

5. Delete the old static keys

gh secret list --repo [org]/[repo]

Expected: no cloud credential secrets remain. Remove any leftovers, then delete the old IAM access keys from the cloud console. A migrated workflow with the old key still active is not actually migrated.

Variant: GCP workload identity federation

Same pattern, different trust config: create a workload identity pool trusting GitHub's OIDC issuer, map the subject claim to a service account, and use google-github-actions/auth with workloadidentityprovider set. No service account keys anywhere.

Variant: environment-scoped deploys

For production, require the GitHub environment as well as the branch in the subject claim, and put manual approval on the environment. The token then only exists for approved production runs.

Variant: what breaks

Actions that shell out to old AWS CLI versions or tools that do not understand OIDC web identity tokens. Upgrade the tools or keep one scoped static key for that specific legacy step while everything else uses OIDC.

Why this happens

Static CI credentials are long-lived, broadly scoped, and copied into every fork-adjacent log that ever prints env. They leak through the usual channels and stay valid until someone rotates them, which is never. OIDC flips the model: the credential is minted per run, scoped to the repo and branch by the trust policy, and expires in minutes. There is nothing to leak and nothing to rotate.

Edge cases and pitfalls

• The OIDC token lives only for the job run. Long-running jobs that need fresh credentials must re-authenticate.
• The trust's audience must match what GitHub sends (sts.amazonaws.com for AWS). A mismatch fails silently at assume-role time.
• Fork PRs get a restricted OIDC token by design. Do not loosen the trust to make forks deploy.
• Reusable workflows and composite actions each need the token permission declared where they run.
• The role ARN is not secret, but a loosely scoped trust policy is a hole. Scope first, test, then delete static keys last.

Tool notes: works with GitHub Actions on github.com and GHES 3.4+. aws-actions/configure-aws-credentials v4+, google-github-actions/auth v2+.

Provenance

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

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

Thread query: how to lock down GitHub Actions with OIDC

TL;DR: Stop storing cloud access keys as GitHub repo secrets. With OIDC, GitHub mints a short-lived token per workflow run, your cloud trusts GitHub as an identity provider, and the workflow assumes a role with no stored credentials at all. Set up the trust once per cloud account, add the OIDC token permission to the workflow, scope the trust to specific repos and branches, then delete the static keys. Leaked tokens expire in minutes instead of living forever in a secret.