Fix: Resource not accessible by integration and other GitHub Actions permission errors

A step that calls the GitHub API, pushes a commit, comments on a pull request or publishes a package fails with one of these:

RequestError [HttpError]: Resource not accessible by integration

remote: Permission to acme/app.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/acme/app/': The requested URL returned error: 403

HTTP 403: Resource not accessible by integration (https://api.github.com/repos/acme/app/issues/42/comments)

The “integration” in the message is the GitHub Actions app itself. Its per-run GITHUB_TOKEN did not have the permission the call needed. There are four places that decide what the token can do; check them in this order.

Cause 1: the workflow does not request the scope

Since 2023 new repositories give GITHUB_TOKEN read-only access by default. Anything that writes needs an explicit permissions block, at the top level or on the job:

permissions:
  contents: write
  pull-requests: write

jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh pr comment "$PR" --body "Build finished"

Match the scope to the action: contents: write to push commits, create releases or tags; pull-requests: write to comment on or label pull requests; issues: write for issues; packages: write to publish to GitHub Packages or ghcr.io; pages: write plus id-token: write for Pages deployments; checks: write to publish check runs; security-events: write to upload code scanning results. The full list is in the documentation linked below. Once you set any permissions block, every scope you do not name becomes none, so a job that worked before can break when you add a block elsewhere; set contents: read explicitly if steps still need to check out code.

Cause 2: the repository or organization caps the token

Settings > Actions > General > Workflow permissions has two settings: Read repository contents and packages permissions (the default) or Read and write permissions, and a checkbox Allow GitHub Actions to create and approve pull requests. The workflow’s permissions block can only narrow what this setting allows, never widen it; if the organization setting is read-only, a repository cannot override it. If your workflow needs to open pull requests, the checkbox must be ticked regardless of the YAML.

Cause 3: the event only grants a read-only token

• pull_request from a fork: the token is read-only and secrets are not available, by design, because the pull request contains untrusted code. Steps that need to write (post a comment, upload coverage) must move to a second workflow triggered by workflow_run or pull_request_target, which runs in the base repository’s context. Never check out and execute the pull request’s code in a pull_request_target workflow; that hands write access to anyone who opens a pull request.
• Dependabot pull requests: the token is read-only and only Dependabot secrets are available. Guard writing steps with if: github.actor != 'dependabot[bot]' or give them a separate workflow.
• schedule and workflow_dispatch run on the default branch with full configured permissions; if those fail, it is cause 1 or 2.

Cause 4: the token cannot do it at all

• Commits, tags and releases created with GITHUB_TOKEN do not trigger other workflows. If your release workflow is supposed to start a deploy workflow and nothing happens, that is why, and no permission fixes it. Use a GitHub App installation token (for example with actions/create-github-app-token) or a fine-grained personal access token stored as a secret.
• Access to other repositories: the token is scoped to the current repository. Checking out a private sibling repository or pushing to another one needs a deploy key or a token with access to both.
• Editing files under .github/workflows/ needs the workflows scope, which GITHUB_TOKEN never has; the push fails with refusing to allow a GitHub App to create or update workflow.
• actions/checkout stores the token in the repository’s Git config by default (persist-credentials: true), so a later git push uses it. If you set persist-credentials: false, that push has no credentials and fails with 403 even with the right scopes.

How to see what the token has

Every job log starts with a collapsed Set up job section that lists GITHUB_TOKEN Permissions with the effective scopes after all four causes are applied. Open it before changing anything; it tells you whether the problem is the YAML (the scope is missing) or the event (the scope is present but marked read).

- name: Show token scopes
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    gh api repos/${{ github.repository }} --jq .permissions
    gh api rate_limit --jq .rate

The first call shows what the token may do on this repository; the second confirms the token authenticates at all (an unauthenticated call has a much lower rate limit).

Checklist

1. Read the GITHUB_TOKEN Permissions list in Set up job.
2. Add the missing scope to a permissions block on the job that needs it, keep every other scope minimal.
3. Confirm the repository and organization Workflow permissions setting allows it, and tick create and approve pull requests if needed.
4. If the run came from a fork or Dependabot, move the writing step to a workflow_run workflow or skip it there.
5. If the action must trigger another workflow or touch another repository, switch to a GitHub App token or a fine-grained PAT.

Official documentation

• Automatic token authentication (GITHUB_TOKEN permissions)
• Workflow syntax: permissions
• Security hardening for GitHub Actions