Microsoft-owned GitHub has introduced fine-grained personal access tokens (PATs), now in beta preview, fixing a problem with tokens used in scripts to access GitHub repositories.

The new tokens really are fine-grained, with 25 types of per-repository permissions, most of which can be set to read-only, read-write, or no access, and another 14 permissions relating to account management.

GitHub embraced OAuth authentication in 2020 and said in August 2021 that “we will no longer accept account passwords when authenticating Git operations on GitHub.com. Instead, token-based authentication (for example, personal access, OAuth, SSH Key, or GitHub App installation token) will be required for all authenticated Git operations.”

The snag with this enforcement is that a large proportion of GitHub use is via scripts and automation tools and it is not always easy to get these to use OAuth 2.0 authorization flows. GitHub offers personal access tokens as an alternative, and the user interface for generating these (in GitHub settings) informs developers that “they can be used instead of a password for Git over HTTPS, or can be used to authenticate to the API over Basic Authentication.” If that sounds like old-style passwords, that is because there is little difference, especially if the token has full permissions, though they are long and unguessable.

Until now, GitHub’s personal access tokens could be given restricted permissions, but not per-repository, and only in a few broad categories. This meant that if a developer had a small demo project in the same account as a major production application, and needed a personal access token to use with scripts, the token would give equal access to both.

“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,” said GitHub’s Hirsch Singhal, Staff Product Manager, in a post. A GitHub App is a custom application that extends GitHub, as described here, and which can already have fine-grained permissions.

The new fine-grained tokens have additional features, including being subject to approval and potential revocation by organization owners, and having a maximum lifetime of one year.

There are also limitations, including no usage beyond organizations the developer belongs to, no support for enterprise account APIs, usage only with REST APIs, not GraphQL, and lack of support for GitHub Packages. Singhal adds that “for long-term automation needs, we recommend using GitHub Actions or GitHub Apps wherever possible.” Even fine-grained PATs are a compromise.

Developers have questioned the decision to enforce expiration. “Forced expiry … means folks will just come up with trivial ways to reissue new ones, which will defeat the purpose anyways. It’s like a forced password reuse policy – it seems like it helps security, but it actually harms it,” said one.

GitHub staff responded that reminder emails will be sent before the token expires.

Despite these grumbles, the reception is positive overall. “Finally. The fact that so far any token reasonably operating on repositories had to have the full repo scope … was ridiculous,” said another dev. “Time to decommission all these existing tokens. Thanks GitHub!”

• The Git team also reports on security vulnerabilities in git that are fixed in the latest version, 2.38.1, so upgrade is recommended.