Agent GitHub Actions Token Permissions and Secrets

Status: public · Confidence: medium (0.725) · Basis: verified_sources

## TL;DR

GitHub Actions token and secret evidence tells agents whether a workflow can read code, write statuses, call deployment APIs, or safely access repository secrets.

## Core Explanation

CI failures often look like code failures when they are actually permission failures. A job may lack the `contents`, `checks`, `pull-requests`, `deployments`, or `id-token` permission it needs, or a secret may be unavailable because the workflow came from a fork, Dependabot event, reusable workflow boundary, or protected environment.

Agents should inspect the triggering event, fork status, repository and organization defaults, workflow-level `permissions`, job-level `permissions`, environment name, and which secret names are referenced before editing YAML or rerunning a deployment. When a workflow can fall back between secret names, the evidence trail should record which secret was present and which API call succeeded.

## Source-Mapped Facts

- GitHub documentation says workflows can use the GITHUB_TOKEN to authenticate on behalf of GitHub Actions. ([source](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication))
- GitHub workflow syntax documentation says the permissions key can modify default permissions granted to the GITHUB_TOKEN. ([source](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#permissions))
- GitHub secrets documentation says that, except for GITHUB_TOKEN, secrets are not passed to the runner when a workflow is triggered from a forked repository. ([source](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions))

## Further Reading

- [GitHub Automatic Token Authentication](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication)
- [GitHub Workflow Syntax Permissions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#permissions)
- [GitHub Using Secrets in Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions)