How to Restrict GITHUB_TOKEN Permissions in Workflows: Read-Only Defaults, Per-Job Scopes and an Audit You Can Repeat

Every GitHub Actions job receives a GITHUB_TOKEN, and any step in that job, including third-party actions, can use whatever that token is allowed to do. This guide covers one task: moving an organisation from broad token permissions to read-only defaults with explicit per-job scopes, without breaking builds, and then auditing that it stays that way. It is written for platform engineers and organisation owners on GitHub.com who already know the basics of Actions. For the wider credential picture, including OIDC, GitHub Apps and runners, see the GitHub and GitHub Actions Security Guide; this page goes deeper on the token alone.

This is an independent guide from NHI Mgmt Group, based on GitHub's public documentation as of November 2026. It is not sponsored or reviewed by GitHub. Product features change, so confirm settings against GitHub's current documentation.

Key takeaways

• Two layers set the token's power. The default at enterprise, organisation or repository level, then the workflow's permissions key, workflow level first and job level after.
• Listing one scope sets the rest to none. GitHub's workflow syntax states that once any permission is specified, all unspecified ones become none, which is what makes per-job blocks safe.
• Set the default to read, then grant write per job. The restricted default gives read access to contents and packages only; jobs that publish, comment or deploy ask for exactly what they need.
• Fork and trigger rules matter as much as scopes. pull_request_target receives a read and write token even from a public fork, so treat those workflows as privileged.
• Audit by API and by file. Default settings are readable through the REST API, and workflow files can be scanned for missing or broad permissions blocks on a schedule.

When you need this

• Organisation default is still read and write: older organisations and repositories may have been created when the permissive default was common. Every workflow without a permissions key inherits it.
• Third-party actions in use: GitHub notes that an action can read the token through the github.token context even when the workflow does not pass it explicitly. The token's scope is the blast radius of any action you run.
• Audit or certification finding: a least privilege finding on CI credentials, or a low OpenSSF Scorecard Token-Permissions result, which the Scorecard project rates as a high-risk check.
• After a workflow incident: tightening scopes is a standard hardening step once a compromised action or injection has been contained. See the CI/CD Pipeline Compromise Playbook.

Before you start

• Access: organisation owner for the organisation default; repository admin for repository settings. Reading the defaults by API needs the Administration permission (read) on a fine-grained token or GitHub App, or admin:org (organisation) or repo (repository) on a classic token.
• Inventory workflows: list every .github/workflows/*.yml file across repositories, and note which have a top-level permissions key, which set it per job, and which have none.
• Know what writes: for each workflow without a permissions key, work out what it changes in GitHub: pushes, tags, releases, comments, labels, packages, Pages, deployments, code scanning uploads. That list becomes its job-level grants.
• Pick a pilot: a handful of busy repositories with different workflow styles, so failures show up early.

Step-by-step

1. Add explicit permissions to workflows first

Start in the files, because a workflow with its own permissions key behaves the same whatever the default is. That lets you flip the default later with little breakage.

1. Top of every workflow: add permissions: {} (no access) or permissions: contents: read. Scorecard's remediation advice is read-all or contents: read at the top level; contents: read is the narrower of the two.
2. Per job: add jobs.<job_id>.permissions with only the scopes that job uses. Job-level settings apply after the workflow-level ones, so a release job can have contents: write while the test job stays read-only.
3. Remember the reset: because unlisted scopes become none, a job that sets issues: write loses contents: read unless you list it too. Jobs that check out code need contents: read in their own block.
4. Avoid write-all: it grants write on every scope that accepts it. If a job seems to need it, split the job.

The full list of scopes in GitHub's workflow syntax reference as of November 2026 is: actions, artifact-metadata, attestations, checks, code-quality, contents, copilot-requests, deployments, discussions, id-token, issues, packages, pages, pull-requests, security-events, statuses and vulnerability-alerts. Some accept only certain values: vulnerability-alerts takes read or none, while id-token and copilot-requests take write or none.

2. Set the restricted default

1. Organisation: in the organisation's Actions settings, under Workflow permissions, select the read-only option for contents and packages. GitHub states that when an organisation selects the more restrictive default, its repositories inherit it and the permissive option is disabled for them.
2. Enterprise: where you run GitHub Enterprise Cloud, set the same default at enterprise level so new organisations start restricted. A restricted default at a higher level applies to everything beneath it.
3. Repository (personal accounts or exceptions): Settings > Actions > General > Workflow permissions. GitHub states new repositories in a personal account start with read access for contents and packages only.
4. Create and approve pull requests: in the same section, leave "Allow GitHub Actions to create and approve pull requests" off unless a named automation needs it. GitHub's REST reference flags enabling the related can_approve_pull_request_reviews field as a security risk, because it lets a workflow approve its own changes.
5. By API: PUT /orgs/{org}/actions/permissions/workflow or PUT /repos/{owner}/{repo}/actions/permissions/workflow with default_workflow_permissions set to read and can_approve_pull_request_reviews set to false. A repository call returns 409 when the organisation blocks the change.

3. Lock down fork and privileged triggers

• Fork pull requests: for pull requests from forks, GitHub downgrades write permissions to read-only unless "Send write tokens to workflows from pull requests" is selected. For private repositories, leave that setting and "Send secrets to workflows from pull requests" off, and keep "Require approval for fork pull request workflows" on.
• pull_request_target: receives a read and write repository token even from a public fork. Give these workflows explicit minimal permissions blocks, never check out and run the pull request's code in them, and list them for review.
• Dependabot runs: GitHub treats Dependabot-triggered runs like fork runs: read-only token and no secrets. Workflows that need to act on Dependabot pull requests should be designed for that rather than widened.
• Do not swap in a broad personal access token: events triggered by the GITHUB_TOKEN do not start new workflow runs, apart from workflow_dispatch and repository_dispatch, and pull requests it opens wait for approval. GitHub suggests a GitHub App installation token or a personal access token if runs must chain; prefer a narrowly installed GitHub App. See the GitHub Personal Access Tokens Security Guide.

Verify it worked

1. Defaults by API: GET /orgs/{org}/actions/permissions/workflow returns default_workflow_permissions: read and can_approve_pull_request_reviews: false. Run the repository variant across all repositories to find any set differently.
2. Workflow files: scan every workflow for a top-level permissions key and for write-all. Scorecard's Token-Permissions check does this per repository and warns on sensitive job-level write scopes such as contents, packages and actions. Scorecard notes it cannot see the repository default setting, so pair it with the API check.
3. Negative test: in a pilot repository, add a step that tries a write the job was not granted (for example, labelling an issue from a read-only job) and confirm it fails.
4. Change watch: alert on changes to Actions settings in the audit log. See the GitHub Audit Log Detection Guide.

Rollback and common errors

The default is one setting and can be switched back at the organisation or repository level in seconds, so rollback is easy. The better rollback is narrower: when a workflow fails, add the missing scope to that job instead of reopening the default for everyone.

Hardening afterwards

• Pin actions: least privilege limits what a compromised action can do; pinning to a full commit SHA limits which code runs. See the GitHub Organisation Security Checklist.
• Move long-lived secrets out: use OIDC federation for cloud access rather than stored keys. See How to set up workload identity federation for GitHub Actions to AWS.
• Guard against injection: scoped tokens reduce the damage of script injection and poisoned pipeline execution but do not prevent them. See the OWASP CI/CD Top 10 CICD-SEC-4 Poisoned Pipeline Execution Guide.
• Review on change: add a CODEOWNERS entry for .github/workflows/ so any new permissions grant gets a second reviewer.

Where this sits in common frameworks (our mapping):

Practitioner checklist

• Inventory workflows and record which lack a permissions key.
• Add a top-level permissions: {} or contents: read to every workflow.
• Grant write scopes per job, listing contents: read where a job also checks out code.
• Set the restricted default at enterprise and organisation level.
• Turn off "Allow GitHub Actions to create and approve pull requests" except for named automations.
• Keep fork write tokens and fork secrets off; require approval for fork workflows.
• Review every pull_request_target workflow and give it minimal explicit scopes.
• Check defaults by REST API and workflow files by scan or Scorecard on a schedule.
• Alert on Actions settings changes in the audit log.

Standards and references

• GitHub Docs: GITHUB_TOKEN
• GitHub Docs: Workflow syntax for GitHub Actions, permissions
• GitHub Docs: GITHUB_TOKEN reference
• GitHub Docs: Managing GitHub Actions settings for a repository
• GitHub Docs: REST API endpoints for GitHub Actions permissions
• GitHub Docs: Using custom workflows with GitHub Pages
• GitHub Docs: Using artifact attestations
• OpenSSF Scorecard: Checks, Token-Permissions
• NIST: SP 800-53 Rev 5, Security and Privacy Controls

Related NHI Mgmt Group resources: GitHub and GitHub Actions Security Guide · GitHub Organisation Security Checklist · CI/CD Pipeline Identity Security Guide · OpenSSF Scorecard Guide