GitHub CLI: Opt in to expiring, auto-refreshing OAuth tokens

You can now use expiring, automatically refreshing OAuth credentials in GitHub CLI as part of a public preview. When you opt in, gh stores an expiring access token alongside a rotating refresh token and automatically refreshes the token whenever it is needed. You stay authenticated without reauthenticating, and a leaked access token becomes unusable within hours instead of lasting indefinitely.

Opting in at login

Starting with v2.103.0, pass the new --expiring flag when you log in with gh auth login --expiring. To opt in for every sign-in without passing the flag each time, run gh config set expiring_credentials enabled. From then on, there is nothing new to run day to day: gh refreshes the credential for you in the background. To check the state of an expiring credential, including when the current access token expires, run gh auth status.

Using expiring tokens with git

If you authenticate to git over HTTPS and want to use expiring tokens, we strongly recommend configuring gh as your git credential helper by running gh auth setup-git. This lets gh serve and refresh the credential for git, so your expiring token is correctly handled.

We also strongly recommend upgrading to git 2.46 or newer, which lets gh mark expiring credentials so they are not cached past their lifetime. On older git versions, gh still works but prints a one-time recommendation to upgrade.

Good to know

• It’s opt-in and backward compatible. If you don’t opt in through the flag or configuration setting, nothing changes. Existing sign-ins and manually supplied tokens keep working exactly as before.
• You get whatever the server issues. --expiring requests refreshable credentials. If a server does not support them, gh falls back cleanly to a normal nonexpiring token.
• It will become the default over time. Expiring credentials are opt-in today. In a future release, we plan to make them the default for new sign-ins.

Things to watch out for

Expiring access tokens are short-lived, so anything that captures a token once and reuses it later can break. Scripts and extensions that run gh auth token and store the result, or copy the token into another tool, will eventually be left holding an expired token.

If you consume the token outside of gh, read it fresh each time with gh auth token. This refreshes it when needed rather than caching the value. If a workflow depends on a token that stays valid for a long time, hold off on opting in for that workflow. When gh is configured as your git credential helper, it refreshes the credential for you, so git operations over HTTPS keep working.

Who can use it

Expiring tokens are available on github.com and ghe.com today. GitHub Enterprise Server issues them starting with GHES 3.23. On earlier versions, opting in falls back to today’s nonexpiring behavior.

For more on authenticating with GitHub CLI, including expiring tokens, see Authenticating with GitHub CLI.

Install or upgrade to GitHub CLI v2.103.0 today to get started.

Have feedback or found an issue? Open an issue in the cli/cli repository.

The post GitHub CLI: Opt in to expiring, auto-refreshing OAuth tokens appeared first on The GitHub Blog.