How to Set Permissions for the GITHUB_TOKEN in GitHub Actions

The permissions key sets the scopes the automatic GITHUB_TOKEN carries, defaulting everything else to none.

Declare permissions: at the workflow or job level. Naming any scope sets all unlisted scopes to none, so list exactly what the run needs.

Steps

• Add a top-level or job-level permissions: block.
• Grant only the scopes the job uses (e.g. contents: read).
• Use permissions: {} to drop all scopes for a read-only job.

Workflow

permissions:
  contents: read
  pull-requests: write
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

Gotchas

• Once you name any scope, every unlisted scope becomes none, not its default.
• Job-level permissions overrides the workflow-level block for that job.

Related guides