| order | 140 |
|---|
Every API call runs on the token you pass, so the grants on that token decide what the action can manage. This page is the permissions model: which grant each section needs, how to scope a PAT, what a denial looks like, and the policy inputs that decide whether a denial fails the run or skips the section.
The PAT permission column in the Sections table names the grant each section needs. Grant only the permissions for the sections your settings file declares, plus the two cross-cutting grants that belong to no section:
- Contents at read when the action must fetch a settings file it does not have checked out (remote multi-repo targets). It also lets
branchestell a missing branch from an unprotected one in check mode. - Issues at read and write only when a
private-reportissue channel (issueorissue-on-failure) is enabled (see private repositories).
Beyond those the action never needs more. In multi-repo mode the token needs the same permissions on every target repository.
To manage everything in one PAT, grant Administration, Issues, Environments, Actions, Secrets, Dependabot secrets, Codespaces secrets, Agent secrets, Checks, Pages, Variables, Agent variables, Webhooks, Custom properties, and Secret scanning alerts at write, plus Contents at read and (for org repos) the Members organization permission at read.
The pre-filled token form linked from Getting started grants exactly the repository half of that set.
The default GITHUB_TOKEN can never hold most of these grants (Administration in particular), so plan on a fine-grained PAT.
A section whose token lacks its grant fails with an error naming the denied request and its HTTP status, plus advice starting "To fix, grant" that names the exact fine-grained permission. Four things worth knowing when a run fails on permissions:
- Check mode needs the read half.
mode: checkchanges no settings, so the read half of each permission is enough for a drift-report-only workflow, with the exceptions listed below. - A 404 can be a denial. Fine-grained tokens surface a missing Administration permission as a 404, not a 403, on admin endpoints. The action treats both as permission errors and its messages name the exact permission to grant.
bypass_actorsis hidden from read-only tokens. GitHub returns a ruleset'sbypass_actorsonly to a token with write access to the ruleset: a token without Administration at write reads the ruleset fine but never sees that field, so check mode leaves a declaredbypass_actorsout of the comparison and says so in a notice instead of reporting drift.- Discovery and remote targets need more.
repos: "*"discovery needs a user PAT; the workflowGITHUB_TOKENand GitHub App installation tokens cannot enumerate a user's repositories. Remote multi-repo targets also need Contents: read on every target, because each repository's own settings.yml is fetched through the contents API.
The exceptions to check mode's read-only rule:
- GitHub gates even the Codespaces secrets reads at write, so
codespaces_secretsneeds its write grant in check mode too. - GitHub gates even the Administration reads at write, so
code_quality_setupneeds its write grant in check mode too. - GitHub gates the
GET /repos/{owner}/{repo}/interaction-limits/pulls/creation-capandGET /repos/{owner}/{repo}/interaction-limits/pulls/bypass-listreads at write, sointeraction_limitsneeds its Administration write grant in check mode to verify what they return.
- The
private-reportissue channels can write even in check mode (issuewrites its report issue on every run;issue-on-failureopens it on drift and closes it on recovery), which takes the Issues grant.
Not every 403 is a missing grant. Rate limits can arrive as 403, and the action tells them apart by the API's own message; a few endpoints answer 403 for feature policies instead (an org-managed Actions cache policy, Advanced Security off on a private repository, Git LFS disabled account-wide). The troubleshooting guide walks through reading each of these.
Permission failures are the only errors the run can be told to tolerate; everything else always fails with the API message verbatim (see Semantics). Two inputs set the policy:
| Input | A denied section is | The run |
|---|---|---|
on-missing-permission: fail (the default) |
failed | fails |
on-missing-permission: warn |
skipped with a warning annotation | continues; when nothing else drifts or fails the result is partial and the run stays green |
required-sections naming the section, even under warn |
failed | fails regardless |
Under fail, an apply run stops before its first write when a read is denied: the preflight barrier probes every active section (each declared section the sections input selects; all of them when that input is unset) read-only before anything is written.
The probe cannot see the write half of a grant, though: a token that reads a section but cannot write it still fails mid-apply. The engine is idempotent, so fixing the token and re-running converges.
warn is partial success as a policy, useful when one token manages a fleet whose repositories do not all grant the same permissions.
required-sections is a minimum-requirements floor: soften everything else, but never report success while, say, rulesets could not be applied. A required section must also be allowed by the sections input when that allowlist is set. An excluded section is never attempted, so requiring it would be a promise the run cannot check, and the pairing is rejected before any API call.
Two caveats live on the organization rather than the repository:
teamsneeds the Members organization permission at read. The token form only offers organization permissions once an organization is selected as the resource owner, so add it by hand when you use the pre-filled form.- A
custom_propertieswrite can be refused upstream regardless of the grant. A 403 on the values PATCH can mean the org restricts a property's values to org actors (values_editable_by: org_actors), and a 422 means the property is not defined at the organization level.