GitHub authentication
Implement and manage GitHub authentication
Choose by repository reach, permissions, and who should own the identity.
| Mechanism | Identity and reach | Lifetime / prerequisite |
|---|---|---|
GITHUB_TOKEN | Per-job GitHub App installation token; permissions limited to the workflow repository | Job end or effective maximum lifetime |
| GitHub App | App installation with explicitly granted repositories and permissions | Generated installation token lasts one hour; the workflow needs the App's private key |
| Personal access token | User-bound; fine-grained tokens can select owner, repositories and permissions | Chosen expiration and organization policy/approval; loses access with the user |
Start with GITHUB_TOKEN
GitHub creates a unique token at the start of each job. Use it when the workflow repository boundary and available permissions are sufficient. GitHub manages issuance and expiry, so there is no token value to store or rotate.
permissions:
contents: read
packages: writeEffective defaults can come from enterprise, organization, repository, event, workflow, and job settings. Declare only the required workflow/job permissions. When any named permission is specified, unspecified permissions become none.
When GITHUB_TOKEN is not enough
For additional repositories or organization resources, register a GitHub App, grant only the required permissions, store its private key as a secret, install it with access to each target repository, and generate an installation token in the workflow. The generated token lasts one hour; the private key is still a managed credential.
A PAT is a documented alternative but remains tied to its creator. Prefer a fine-grained PAT where the operation supports it, with selected repositories, minimum permissions, expiration, and any required organization approval. A deploy key is different: it is a non-expiring, single-repository Git credential that cannot be reused across repositories and does not authenticate API requests.
Primary sources
- https://learn.microsoft.com/en-us/credentials/certifications/resources/study-guides/az-400
- https://docs.github.com/en/actions/concepts/security/github_token
- https://docs.github.com/en/actions/tutorials/authenticate-with-github_token
- https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
- https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow
- https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app
- https://docs.github.com/en/rest/apps/apps?apiVersion=2026-03-10
- https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
- https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys