Teams should observe the actual API calls a workflow makes, then map each HTTP verb and path to the corresponding GitHub permission. A job that only reads issues does not need write access, and a job that pushes code or creates pull requests needs only the specific scopes required for those actions. The right goal is least privilege per job, not a broad token that fits every workflow.
How to measure the minimum permission set for a workflow
The most reliable method is to start from the workflow’s actual behavior, not from an assumed role template. Capture the requests a job makes, then translate each operation into the narrowest GitHub permission that satisfies it. If a step only reads metadata, it should not inherit repository write scope, and if it only opens pull requests, it should not gain unrelated admin capabilities.
A useful way to think about this is by action type. Read-only operations should stay read-only, write operations should be scoped to the exact repository object being changed, and any capability that crosses trust boundaries, such as modifying code or creating automation artifacts, should be granted only when the job truly needs it. That keeps the token aligned to the job’s blast radius instead of the repository’s maximum power.
Teams get better results when they treat permission mapping as an evidence exercise. Review the workflow source, the runner logs, and the API activity together, then compare those calls against the permissions documented by GitHub for the relevant endpoint. That approach exposes hidden dependencies, such as a job that appears to “just build” but also comments on issues, updates release metadata, or writes status checks.
When the job interacts with repository content, the practical question is whether it needs content read, content write, pull request, issues, or packages capability. The answer should be derived from the smallest set of endpoints that can complete the job successfully. The goal is not to guess a future use case or to pre-authorize every nearby task, but to allow only the operations that the current workflow is designed to perform.
Where least privilege usually breaks down in GitHub Actions
Over-permissioning often happens because teams start with broad defaults, then add exceptions until the token becomes effectively universal. That is convenient in the short term, but it hides job boundaries and makes later review harder. A workflow that only needs to label issues or publish a release note can end up with full repository write access simply because the original template was copied forward.
The other common failure is assuming that a token required for one step should be valid for the entire job. In practice, many workflows contain mixed-risk steps, and only one of them truly needs elevated access. That is why job-level scoping matters: if the build step needs no write access, it should not receive it just because a later deployment step does. Separate jobs, or separate permission blocks, make the trust boundary visible.
Supply-chain abuse of GitHub Actions has repeatedly shown that broad workflow access can be exploited once a job or action is compromised. The safer posture is to reduce the value of any one token, limit what a compromised step can do, and avoid storing or exposing capabilities the workflow never uses. For background on the broader secret exposure problem in CI/CD, see Ultimate Guide to NHIs — Key Challenges and Risks and Guide to the Secret Sprawl Challenge.
Workflow-specific attack examples also matter here because they show why the minimum viable token is a security control, not just an administrative preference. If an action dependency is hijacked or a token leaks from a runner, the attacker inherits whatever the job could do. Cases such as Reviewdog GitHub Action supply chain attack and GitHub Action tj-actions Supply Chain Attack are reminders that excess permission turns a workflow compromise into a repository compromise.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Non-Human Identity Top 10 address the attack and risk surface, while CIS Controls v8 and NIST CSF 2.0 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| OWASP Non-Human Identity Top 10 | Non-Human Identity Top 10 | GitHub Actions job tokens are non-human secrets needing least privilege and rotation. |
| Recommendation — Map job tokens to the narrowest required permissions and remove excess standing access. | ||
| CIS Controls v8 | 6 — Access Control Management | Least-privilege token scoping is an access control practice for operational safeguards. |
| Recommendation — Restrict each workflow token to the minimum permissions needed for its endpoints. | ||
| NIST CSF 2.0 | PR.AC — Identity Management, Authentication and Access Control | Workflow permissions are an access-control decision affecting who can do what in automation. |
| Recommendation — Apply least-privilege access control to each GitHub Actions job token. | ||
Practitioner Guidance
What to verify: Check whether each job can still complete when permissions are reduced to the smallest documented endpoint set. If a workflow only fails because a hidden step depends on extra access, that is usually a design issue worth fixing rather than a reason to keep the broader token.
Decision rule: If a step needs write access, isolate that step and grant write only at the narrowest scope available. If the same job mixes read, write, and release actions, split it so the routine path stays low privilege and only the exceptional path elevates.
What practitioners underestimate: The hardest part is not identifying obvious permissions, it is discovering indirect calls made by reusable actions, third-party dependencies, and post-job cleanup. Those paths often explain why a token appears to need more access than the workflow’s main logic suggests.
Practitioner takeaway: Treat the workflow as the unit of analysis, but the endpoint call as the unit of permission, then keep each job’s token no broader than the specific operations it actually performs.
Related resources from NHI Mgmt Group
Deepen Your Knowledge
Reviewed and updated by the NHIMG editorial team on September 18, 2026.
NHI Mgmt Group — the #1 independent authority on Non-Human Identity, IAM, and Agentic AI security. nhimg.org
