Introducing fine-grained personal access tokens for GitHub

Stolen and compromised credentials are the number one cause of data breaches across the industry. GitHub has a long history of protecting developers and enterprises from such threats with security efforts like making it easier for developers to adopt 2FA with the GitHub mobile app and robust webauthn support, and scanning for secrets at the point of push for GitHub Advanced Security customers.

But safeguarding credentials perfectly is extremely difficult. That’s why it’s important that all actors accessing your repositories and data have the least access they need to work.

Until now, personal access tokens (PATs) have only provided very coarse-grained permissions. That includes granting access to all of the repositories and organizations that the owning user can access, without providing any control or visibility to organization owners. To enhance the level of security available to developers and organizations using PATs, today we are introducing a new type of personal access token in Public Beta: fine-grained personal access tokens.

Fine-grained personal access tokens give developers granular control over the permissions and repository access they grant to a PAT. Organization administrators are in control too, with approval policies and full visibility for tokens that access organization resources.

The existing personal access tokens continue to be fully supported, and are now called personal access tokens (classic).

Fine-grained personal access tokens: in action

PATs are an easy way to mint tokens that can be used to call the GitHub API and establish git connections over HTTPs. They’re best used for creating quick scripts and testing integrations.

Personal access tokens (classic) are given permissions from a broad set of read and write scopes. They have access to all of the repositories and organizations that the user could access, and are allowed to live forever. As an example, the repo scope provides broad access to all data in private repositories the user has access to, in perpetuity.

Fine-grained personal access tokens, by contrast, are given permissions from a set of over 50 granular permissions that control access to GitHub’s organization, user, and repository APIs. Each permission can be granted on a ‘no access’, ‘read’ or ‘read and write’ basis. As an example, you can now create a PAT that can only read issues and do nothing else – not even read the contents of a repository.

Fine-grained personal access tokens also expire, and they don’t have access to all the repositories a user can access. Instead, they only have access to the repositories or organizations that they explicitly are granted access to. They can even be targeted at a single repository in an organization.

Creating personal access tokens

You can create a new fine-grained PAT via the Developer Settings section in your account settings.

Fine-grained personal access tokens make it much easier to build integrations with PATs and GitHub Apps, and to migrate scripts from a PAT to a GitHub App once initial testing has been completed. The permissions available to fine-grained personal access tokens are the same permissions available to GitHub Apps, and repository targeting works the same too.

Approving and auditing personal access tokens

While personal access tokens (classic) do not offer organization or enterprise administrators any control over their use, fine-grained personal access tokens bring new control to Organization and Enterprise Owners.

In the new Personal Access Tokens tab in the Organization Settings, Organization Owners can choose to approve each fine-grained PAT that developers target at that Organization or any of its repositories. This option is enabled by default.

Organization Owners can also view and revoke access to fine-grained PATs that were previously granted access to their Organization. PATs (classic) provides similar functionality, but it’s available only to organizations using SAML Single Sign On.

Finally, Organization Owners can block the use of personal access tokens (classic) in their organization. This does have some trade-offs, though, which are detailed in the next section.

Enterprise Owners can also set policies across their Organizations via the new Personal Access Tokens page in the Policies tab.

Choosing the right programmatic access method

Whenever possible, GitHub recommends using fine-grained PATs instead of PATs (classic). With the ability to target PATs just with the permissions and repository access they need, fine-grained PATs give you the power to vastly decrease the surface area of attacks if these credentials are compromised.

There are some cases where it isn’t possible to use a fine-grained PAT – yet. For now, you need to use PATs (classic) for access beyond organizations you’re a member of. That means some open source and innersource contributions cannot yet be managed with a fine-grained PAT. In addition, integrating with the enterprise account APIs also requires a PAT (classic) or oAuth app.

For long-term automation needs, we recommend using GitHub Actions or GitHub Apps wherever possible. GitHub Apps provide the same highly targeted permissions options and administrator controls available with fine-grained PATs. They’re also long-lived, and they’re not associated with an individual user who may leave your company or project.

Coming next

With this release, hardened, fine-grained PATs are now available to all users, organizations, and enterprises on GitHub.com. We want your feedback about how they work for you. You can give that feedback via this dedicated discussion forum.

We also have a set of enhancements planned that we intend to address before making fine-grained personal access tokens generally available. These changes include:

• Support for GraphQL. Currently, fine-grained PATs can only be used against the REST APIs
• The ability to target a PAT against repositories in multiple Organizations, and Organizations and repositories that you’re not a member of.

A few API endpoints also do not yet support fine-grained permissions. As a result, you need to use a PAT (classic) or oAuth app when calling these APIs. Over time, we’ll be expanding API support for fine-grained permissions across GitHub. You can read the details of the permissions each endpoint supports in our documentation.

For administrators, we also intend to add features to make it easy to set and enforce PAT policies at scale, including APIs for approving and revoking access.

We’ll publish further details as they develop on the GitHub roadmap and changelog, so keep an eye on those.

Get started

Fine-grained PATs are available immediately for all users to create on GitHub.com, next to PATs (classic) in your account’s Developer Settings. You can create fine-grained PATs to access your personal repositories, and if the Organizations you belong to have enabled fine-grained PATs, you’ll also see those organizations in the Resource Owner dropdown when creating a new fine-grained PAT.

For Organizations, the use of fine-grained PATs is opt-in during the beta. Organization Owners can allow access from fine-grained PATs by setting this policy in the new Personal access tokens page under Organization Settings. There, owners can also disable the use of PATs (classic), and choose whether to require approval for fine-grained personal access token requests. Enterprise Owners can also set policies across their Organizations via the new Personal access tokens page in the Policies tab.

To learn more about fine-grained PATs, read the documentation. And if you have any feedback, we’d love to hear it via our dedicated discussion forum.

Written by

Hirsch Singhal

@hpsin