GitHub CLI: Opt in to expiring, auto-refreshing OAuth tokens
By Steven Van ·
Opt-in for GitHub CLI v2.103.0 and later on GitHub.com and Enterprise Cloud; leaked access tokens stop working within hours.
GitHub CLI can now use GitHub OAuth credentials that expire and refresh themselves, as a public preview. With gh auth login --expiring, gh stores a short-lived access token alongside a rotating refresh token, and swaps in a new access token whenever one is needed. A leaked access token becomes unusable within hours instead of staying valid until someone revokes it. The change is described in the GitHub CLI authentication docs.
Opting in
Expiring tokens need GitHub CLI v2.103.0 or later and are available on GitHub.com and GitHub Enterprise Cloud. Pass the new flag at sign-in:
gh auth login --expiring
To request expiring credentials on every sign-in without the flag, run gh config set expiring_credentials enabled. After that, gh refreshes the credential in the background, so there is nothing new to run day to day. The flag only requests expiring credentials. If the server does not support them, gh falls back to a normal non-expiring token and shows an informational message.
The behaviour is opt-in and backward compatible. Existing sign-ins and manually supplied tokens keep working as before. GitHub says it plans to make expiring credentials the default for new sign-ins in a future release.
Using it with git
For git over HTTPS, gh needs to be your git credential helper so it can serve and refresh the credential. Signing in with expiring credentials prompts you to set this up if it is not already, and gh auth setup-git does it at any time. GitHub also recommends git 2.46 or newer, which lets gh mark an expiring credential so a caching helper does not keep it past its lifetime. On older git versions gh still works but prints a one-time recommendation to upgrade.
Checking and reading tokens
- gh auth status shows the state of an expiring credential, including when the current access token expires. It refreshes a token that is expired or near expiry, and --no-refresh reports the state without refreshing.
- gh auth token refreshes the access token if needed before printing it. Add --no-refresh to print the current token as is.
- When changing scopes with gh auth refresh --scopes SCOPES, pass --expiring (or keep the setting enabled). Otherwise the expiring credential can be replaced with a non-expiring one.
Scripts that store tokens
Because access tokens are short-lived, anything that captures a token once and reuses it can end up holding an expired one. That includes scripts and extensions that run gh auth token and save the result, or copy it into another tool. GitHub advises reading the token fresh with gh auth token each time it is needed outside of gh.
