In GitHub Actions, what does the permissions key do to the GITHUB_TOKEN?

## What the key controls Every job gets an installation token exposed as `secrets.GITHUB_TOKEN` and as `github.token`. The `permissions:` key decides which API scopes that token carries for the run. It can be written at the top level of the workflow (a default for all jobs) or inside a single job (which replaces the default for that job). permissions: contents: read pull-requests: write Each scope takes `read`, `write`, or `none`. `write` implies read. Commonly named scopes include `actions`, `attestations`, `checks`, `contents`, `deployments`, `discussions`, `id-token`, `issues`, `packages`, `pages`, `pull-requests`, `security-events`, and `statuses`. ## The exhaustive rule This is the part that surprises people. `permissions:` is not a delta applied on top of the defaults — **naming any scope sets every scope you did not name to `none`.** So this job's token can read the repository and nothing else: permissions: contents: read It cannot comment on a pull request, publish a package, or upload a SARIF result. That is the feature: you cannot accidentally over-grant by forgetting to deny something, only by explicitly granting it. It is also the usual cause of a sudden `Resource not accessible by integration` error after someone tightened a workflow — the fix is to add the one scope the failing API call needs, not to revert to `write-all`. Three shorthands exist. `permissions: read-all` and `permissions: write-all` set every scope to read or write. `permissions: {}` — an empty map — sets every scope to `none`, producing a token that can do essentially nothing against the API, which is the right default for a job that only builds and tests code it already checked out. ## Workflow level versus job level A job-level `permissions:` block **replaces** the workflow-level one for that job; the two are not merged. The idiomatic layout is therefore a tight default at the top and a widened block on the one job that needs more: permissions: contents: read # default for every job jobs: build: { ... } # inherits contents: read only comment: permissions: contents: read pull-requests: write # must restate contents: read steps: [ ... ] Note that `contents: read` has to be repeated in the job block: because the block replaces rather than merges, omitting it would leave the job unable to check out a private repository. ## Interaction with repository and organization settings Repositories and organizations have a default workflow-permissions setting (read-only or read/write) that applies when a workflow says nothing. Newer repositories default to read-only. There are also separate settings governing whether Actions may create or approve pull requests. Because those settings only establish the baseline, a well-run repository still writes `permissions:` explicitly in each workflow: the file then documents its own blast radius and does not change meaning when an admin flips a setting. Two things the key cannot do: it cannot grant access to another repository (the token is scoped to the repository running the workflow — cross-repository work needs a GitHub App token or a PAT), and it cannot lift the cap on fork pull-request runs, where the token is read-only and secrets are unavailable regardless of what the workflow requests. ## Where `id-token` fits `id-token: write` is unusual: it does not grant repository API access at all. It permits the job to request a short-lived OIDC token from GitHub's identity provider, which is then exchanged for cloud credentials. It is required for OIDC-based cloud login and, because it is a scope like any other, it is silently `none` unless you list it — the most common cause of `Unable to get ACTIONS_ID_TOKEN_REQUEST_URL` failures. ## Answering well Say what it is (per-run token scoping), state the exhaustive rule, mention job-level replacement, and give the concrete default you use: `permissions: contents: read` at the top of every workflow, widened only where a step genuinely calls a write API.