For personal access to private repositories, start with a fine-grained personal access token (PAT) when it supports the task. Limit it to the correct resource owner, only the repositories it needs, and the relevant read permissions. For public repository data, first try unauthenticated access: a credential may not be needed. Use GitHub Actions’ built-in GITHUB_TOKEN for workflows when it is sufficient, and consider a GitHub App for integrations that act for an organization or other users. A classic PAT is a compatibility fallback, not the default, because its access can be much broader.
What does “read-only access” mean on GitHub?
Read-only access describes what a credential is allowed to do; it is not a single credential type. A fine-grained PAT can be configured with read permissions for selected repositories. Classic PATs instead use broader scopes, and GitHub documents that a classic PAT with no scopes can access public information. Fine-grained PATs always include read-only access to all public repositories on GitHub. If you only need public data, try the endpoint without a token before creating one. GitHub notes that an API endpoint may still have its own authentication requirements. See GitHub’s personal access token guidance.
A token cannot grant its owner access they do not already have: effective access is bounded by the user’s own capabilities and the token’s permissions. Keep the credential’s identity in mind, too: a PAT represents a user, while an Actions token represents a workflow and a GitHub App is designed for an integration.
Which credential should you choose?
| Use case | Best starting point | Key check |
|---|---|---|
| Read public repository data | No credential, if the endpoint permits it | If authentication is required, use the least access that works. Fine-grained PATs include public-repository read access; a classic PAT with no scopes can also access public information. |
| Read private repositories for personal work | Fine-grained PAT | Select one resource owner, only the needed repositories, and only the required read permissions. Verify the endpoint supports fine-grained PATs. |
| Run a GitHub Actions workflow | Built-in GITHUB_TOKEN, if it can do the job |
Set minimum workflow permissions rather than storing a personal credential for work performed by the workflow. GitHub’s guidance is at automatic token authentication. |
| Integrate with an organization or act for other users | GitHub App | Request only needed permissions and restrict repository access. See when to build a GitHub App. |
| Required endpoint or action is unsupported by fine-grained PATs | Check endpoint documentation and current limitations; evaluate an App or, if necessary, a classic PAT | Classic PAT access can extend to all repositories available to its user, and an organization may restrict classic PAT use. |
How to configure a fine-grained PAT for read-only repository access
- Confirm the endpoint or operation. Check GitHub’s permission requirements for fine-grained PATs and the documentation for the specific REST endpoint or Git operation. Match the permission to what the task actually reads; do not add write permissions for convenience.
- Choose the resource owner. Set it to the user or organization that owns the repository. A fine-grained PAT is limited to a single resource owner.
- Restrict repository selection. Select only the repository or repositories the task needs rather than granting access to every repository under that owner.
- Grant the minimum permissions. Select only the necessary read-level permissions for the required data. The right permission depends on the endpoint or operation, so use GitHub’s endpoint mapping rather than assuming one universal “read-only” switch covers every task.
- Set an appropriate expiration. Choose a defined lifetime that covers the work and no longer. GitHub’s security guidance recommends minimum permissions and an expiration for the minimum time needed: Keeping your API credentials secure.
- Account for organization approval. If the owner is an organization that requires approval, the PAT may need approval before it can reach private organization resources. While approval is pending, it can read public resources but not those private organization resources. Organization owners can review and revoke fine-grained PATs with access to their organization; see organization authorization for PATs.
When a fine-grained PAT is not enough
Fine-grained PAT support is not universal. GitHub’s maintained limitation list includes cases such as using one token across multiple organizations, Packages, the Checks API, contributing to public repositories where the user is not a member, and access to repositories where the user is an outside or repository collaborator. Coverage can change, so check the live endpoint documentation and limitation list for the exact operation before choosing a fallback.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
If an App or another credential type can meet the integration’s needs, assess that first. A classic PAT may be necessary for a documented compatibility gap, but its broader reach matters: a classic PAT with repository access can reach all repositories its user can access. Organizations can also restrict classic PATs. Do not confuse a classic PAT or an OAuth app’s repo scope with a fine-grained PAT configured for read permissions: GitHub says the OAuth repo scope allows broad read and write access to public and private repositories, and OAuth apps currently cannot scope source-code access to read-only. Details are in GitHub’s OAuth app scope documentation.
Expiration, revocation, and keeping tokens safe
GitHub’s credential reference describes fine-grained PAT lifetimes as configurable up to one year or with no expiration; organization or enterprise policy can block an infinite lifetime. GitHub’s account instructions likewise note that policy may constrain the available choice. Prefer an expiration aligned with the task rather than a token that persists indefinitely. Review GitHub’s credential lifetime and revocation reference and PAT instructions for current settings.
Quick Recap
Best Value
- Store a token as a secret in the system that needs it; do not share it, hardcode it, or commit it to a repository.
- If a token leaks, create a replacement, update systems that use it, and delete the compromised credential.
- For organization access, account for approval and centralized review or revocation controls.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
