GitHub Actions permissions: Every Scope and What Needs It

By Kaveh Alemi·Latchkey

Declaring a permissions: block replaces the defaults entirely rather than adding to them, so an incomplete block breaks steps that worked yesterday.

The GITHUB_TOKEN is minted per job with a permission set. It comes from repository or organisation defaults unless the workflow declares its own, and the moment it does, the declaration is the complete set.

That replacement behaviour is the single most common cause of a permissions failure appearing right after someone tightened security: the block lists the scope they were thinking about and silently drops the ones that were previously default.

Every scope

The replacement rule

# Before: repository defaults, whatever they are
# (no permissions block)

# After: contents is the ONLY permission this job has.
# A step that used to comment on a PR now fails with 403.
permissions:
  contents: read

# Correct: list everything the job needs
permissions:
  contents: read
  pull-requests: write
  checks: write

What no permissions block can grant

• Fork pull requests. A pull_request event from a fork gets a read-only token and no access to secrets, by design and regardless of any permissions: declaration.
• Cross-repository access. GITHUB_TOKEN is scoped to the repository running the workflow. Another repository needs a PAT or a GitHub App token.
• Anything above the repository or organisation default. If the default is restricted to read, a workflow cannot grant itself write.
• Triggering another workflow. Events created using GITHUB_TOKEN do not start new workflow runs, which is a loop-prevention rule rather than a permission.

Common combinations

# push a container image to GHCR
permissions:
  contents: read
  packages: write

# authenticate to a cloud provider with OIDC
permissions:
  contents: read
  id-token: write

# comment on a PR and publish check results
permissions:
  contents: read
  pull-requests: write
  checks: write

# upload code scanning results
permissions:
  contents: read
  security-events: write

Diagnose it: what token do you actually have?

Permission failures in Actions are almost never about your repository settings alone. Three things combine: the default GITHUB_TOKEN permission set for the repo or organization, the permissions: block in the workflow, and whether the event is a fork pull request, which downgrades the token to read-only regardless of everything else.

- name: Show the token scopes actually granted
  run: |
    curl -sI -H "Authorization: Bearer $GITHUB_TOKEN" \
      https://api.github.com/ | grep -i "^x-oauth-scopes\|^x-accepted"
    echo "event: ${{ github.event_name }}"
    echo "fork PR: ${{ github.event.pull_request.head.repo.fork }}"
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Grant the narrowest permission that works

Declaring a permissions: block switches the job from the repository default to exactly what you list, so an incomplete block is a common cause of a new failure right after someone tightened security. List every scope the job needs, not just the one that failed.

permissions:
  contents: read        # checkout
  packages: write       # push to GHCR
  id-token: write       # OIDC to a cloud provider
  pull-requests: write  # comment on or label a PR
  checks: write         # publish check runs

Frequently asked questions

Related guides

References

• GitHub: permissions for GITHUB_TOKEN (verified 2026-08-20)
• GitHub Actions contexts reference (verified 2026-08-20)
• GitHub Actions documentation
• Workflow syntax for GitHub Actions