GitHub Actions Resource not accessible by integration: permissions debugging

Not specified by the original author.

Fix GitHub Actions "Resource not accessible by integration"

TL;DR

The workflow's token does not have permission for what the step is trying to do. Find which API call fails, check the repo's workflow permissions default, and add an explicit permissions block to the job granting only what it needs. The default token is deliberately least-privilege now, so write operations have to be opted into.

GitHub Actions "Resource not accessible by integration": permissions debugging

Steps

1. Find the failing call. Read the failed step's logs and note what it touches: PR comments, labels, packages, deployments, checks. Expected: you know which permission scope is missing.

2. Check the repo default. Go to repo Settings, then Actions, then General, and read the Workflow permissions setting. Expected: you see whether the default is read-only or read-and-write.

3. Declare job-level permissions. Add a permissions block to the job granting only the scopes it needs, for example pull-requests write and issues write for a step that comments on PRs. Expected: the workflow file carries explicit permissions for that job.

4. Re-run the failed job. Use the re-run button rather than pushing an empty commit. Expected: the permissions error is gone and the step succeeds.

5. If you use a personal token instead of the built-in one, check its scopes. Fine-grained tokens need the right repository permissions; classic tokens need the right scopes. Expected: the token covers every API call the workflow makes.

Use this when

• A workflow step fails with "Resource not accessible by integration"
• API calls from Actions return 403
• A workflow that used to work starts failing after a permissions tightening

Not for this skill when

• The error is "Bad credentials" (the token itself is invalid or expired)
• OIDC federation to a cloud provider fails (that is the cloud trust config)
• The workflow file cannot be found or parsed (that is a syntax or path problem)

Variant phrasings

• github token 403 resource not accessible
• gha permissions error
• integration permissions github actions
• github actions 403 writing to pull request

Why it happens

GitHub reduced the default token to read-only for most scopes. Any write (posting comments, adding labels, pushing packages) must now be declared, either in the repo default or per workflow/job. The error is the API telling you the token was never granted that scope.

Edge cases

• Permissions set at the workflow top level apply to every job. Prefer job-level so each job gets only what it needs.
• Reusable workflows need permissions passed in by the caller. The callee cannot grant itself more.
• The same error appears when a token tries to act on a different repository than the one that issued it.
• Fork PRs from outside collaborators run with read-only tokens no matter what you declare. Design those workflows accordingly.

Provenance

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

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

Thread query: GitHub Actions "Resource not accessible by integration": permissions debugging

TL;DR: The workflow's token does not have permission for what the step is trying to do. Find which API call fails, check the repo's workflow permissions default, and add an explicit permissions block to the job granting only what it needs. The default token is deliberately least-privilege now, so write operations have to be opted into.

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.

HTTP 403: Resource not accessible by integration (gh CLI)

TL;DR: your token is missing the scope that endpoint needs. Run gh auth refresh -s repo -s workflow and retry — that fixes it in most cases. In GitHub Actions, the automatic GITHUB_TOKEN can never cover some endpoints no matter what permissions you grant, so use a personal access token stored as a repository secret there instead.

HTTP 403: Resource not accessible by integration

Steps

1. Check what your token can do:

gh auth status

Expected: shows your account and the granted scopes. If workflow or repo is missing for the endpoint you are hitting, that is the problem.

2. Add the missing scopes:

gh auth refresh -s repo -s workflow

Expected: a success message. Re-run gh auth status and confirm repo and workflow are now listed.

3. Retry the failing command.
4. In GitHub Actions, if it still 403s: replace secrets.GITHUB_TOKEN with a personal access token secret (classic PAT with repo scope, or a fine-grained token with Administration read and write). GITHUB_TOKEN has no permission covering repository administration endpoints, so it always 403s there regardless of the workflow permissions block.

When this applies

• gh api, gh workflow run, gh release, branch protection or ruleset calls fail with this exact 403
• other gh commands with the same token work fine
• you recently switched from a classic PAT to a fine-grained token or to GITHUB_TOKEN

When it doesnt

• Bad credentials (401) — your token is expired or invalid, re-authenticate with gh auth login
• Must have admin rights to Repository — you genuinely lack admin on the repo, ask an owner
• 404s — usually a wrong repo name or missing access, not a scope problem

Compatibility

GitHub CLI 2.x against github.com and GitHub Enterprise Server.

Why it happens

GitHub checks the token's granted scopes per endpoint, and this 403 names no missing permission. Fine-grained tokens and the Actions GITHUB_TOKEN carry narrower grants than a classic PAT with repo scope, so calls that used to work start failing with an opaque message.

Edge cases

• gh auth login --scopes "repo,workflow" sets scopes at login time if you prefer that over refresh
• organization SSO: if the org enforces SAML, authorize the token for the org after refreshing scopes
• in Actions, the PAT must be stored as a repository secret — never print it into logs

Find this skill again

curl -s 'https://vectle.com/api/v1/search?q=gh+resource+not+accessible+by+integration'

gh CLI users hit HTTP 403 Resource not accessible by integration when their token lacked the scopes an endpoint required, with no hint about which permission was missing. The verified fix: gh auth refresh -s repo -s workflow (or gh auth login --scopes repo,workflow), and in GitHub Actions replace the automatic GITHUBTOKEN with a real personal access token stored as a repository secret, since GITHUBTOKEN can never cover repository administration endpoints. Source: https://github.com/berlysia/dotfiles/blob/HEAD/.skills/renovate-github-action-guide/references/GHCLISETUP.md