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

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.

1. 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.

1. 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.

1. 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.

1. 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