GitHub CLI Expiring Tokens Tutorial: Enable Automatic Refresh

A GitHub command-line token that never expires can remain useful to an attacker long after it has been stolen. On October 21, 2026, GitHub introduced a public preview of expiring, automatically refreshed OAuth credentials in GitHub CLI, giving developers a way to shorten that exposure without repeatedly signing in. This tutorial explains how to enable the feature, verify that it works, configure Git over HTTPS correctly, and identify scripts that could break when tokens start expiring.

Why GitHub CLI's new authentication option matters

GitHub CLI, commonly invoked with the gh command, lets developers manage repositories, pull requests, issues, and other GitHub resources from a terminal. Its traditional login flow stores a long-lived authentication token, which can remain valid until it is revoked or otherwise invalidated. If malware, a compromised workstation, or an accidentally exposed file captures that token, the attacker may be able to use its permissions without knowing the account password.

The new expiring-token option changes how authentication credentials are maintained. Instead of relying on an access token indefinitely, GitHub CLI can store a short-lived access token alongside a rotating refresh token, which it uses to obtain fresh credentials when necessary. GitHub says the access token expires within hours, reducing the period during which a stolen access token can be reused. The feature is opt-in during its public preview, so existing installations do not automatically switch to the new behavior.

Check your GitHub CLI version before enabling expiring tokens

The feature requires GitHub CLI version 2.103.0 or later. Open a terminal, PowerShell, Windows Terminal, or your preferred shell and check the installed version before changing your authentication configuration. This first check matters because older releases may not recognize the new login option, and a failed command does not mean that your account or repository is compromised.

gh --version

If the reported version is older than 2.103.0, upgrade GitHub CLI using the package manager or installation method you originally used. For example, Windows users who installed the application through Windows Package Manager can run the following command:

winget upgrade --id GitHub.cli

After the upgrade, run gh --version again and confirm that the installed version meets the requirement. Developers using macOS, Linux, or a managed corporate workstation should use their existing installation method and follow their organization's software-update policy. Do not install a second copy from an unrelated download source just to enable this security feature.

Enable expiring credentials when you sign in

Once the supported version is installed, the simplest way to request expiring credentials is to sign in using the new --expiring flag. If you are not currently authenticated, run the following command in your terminal:

gh auth login --expiring

Follow the interactive prompts to select your GitHub host, authentication method, and Git protocol. Complete the browser-based sign-in if prompted. GitHub CLI will request expiring credentials where the host and its authentication configuration support them, then manage token refreshes when those credentials are needed.

There is an important distinction between requesting the feature and receiving it. The flag expresses a preference; it does not guarantee that every server will issue expiring credentials. GitHub.com and GitHub Enterprise Cloud support the feature, while GitHub Enterprise Server support depends on the server version. If the host cannot issue expiring credentials, GitHub CLI can fall back to a non-expiring token rather than preventing authentication altogether.

Make expiring credentials the default for future sign-ins

If you regularly sign in to GitHub CLI, you can enable a configuration setting so you do not have to remember the flag every time. Run the following command:

gh config set expiring_credentials enabled

This setting tells GitHub CLI to prefer expiring credentials during future sign-ins. It does not automatically convert every existing authentication session, so check your current credential state rather than assuming that the configuration change has already migrated your account. For an existing session, you can request refreshed credentials with the supported refresh command:

gh auth refresh --expiring

Because the feature remains in public preview, verify the result after refreshing. A server that does not support expiring credentials may continue issuing a non-expiring token, even when the preference is enabled. The practical security objective is to confirm the credential type actually issued, not merely to see a successful command exit.

Verify the authentication state without exposing your token

Use GitHub CLI's authentication-status command to check which account is active and whether its stored credentials are valid. Run:

gh auth status

With expiring credentials, the status output can also show when the current access token expires. That information helps distinguish a properly configured short-lived session from an older long-lived one. Avoid adding the --show-token flag when troubleshooting in a shared terminal, recording a screen, or collecting diagnostic output for a support ticket, because it can print the actual credential.

Next, test a normal authenticated operation that matches your workflow. For example, if you work with a repository using GitHub CLI, run a read-only command such as:

gh repo view

The command should display repository information for the active account, provided the account has access to a repository in the current context. If it fails, check the selected account, host, and repository permissions before concluding that token refresh is broken. A valid token cannot grant permissions the account does not already possess.

Configure Git over HTTPS so token refresh continues working

Git operations introduce a separate issue because Git may obtain credentials through a credential helper, which is a component that supplies authentication details to Git. If Git caches a short-lived token and keeps reusing it after expiration, commands such as git fetch or git push can fail even when GitHub CLI itself can refresh the credentials correctly. GitHub recommends configuring GitHub CLI as the Git credential helper when using expiring tokens with HTTPS remotes.

Run:

gh auth setup-git

Then check your Git version:

git --version

Git 2.46 or newer is recommended because it supports marking expiring credentials as unsuitable for caching beyond their lifetime. Older versions may still work, but a separate credential-caching helper can retain an expired token and cause authentication errors. After configuring the helper, test a fetch or another harmless Git operation against a repository you are authorized to access. If your remotes use SSH rather than HTTPS, this particular HTTPS credential-helper configuration is not required for those operations.

Find scripts that depend on a permanent token

The biggest migration risk is not necessarily interactive use; it is automation that extracts a token once and assumes that it will remain valid. For example, a script might call gh auth token, save the result in a file, and reuse that value for API requests throughout the following week. With expiring credentials, the saved access token will eventually stop working, even though GitHub CLI can obtain a replacement when asked.

Review scripts, shell profiles, local development tools, and extensions that consume GitHub CLI credentials. If a process uses gh auth token to obtain a token for an external tool, it should request a fresh token when needed rather than persist the access-token value indefinitely. A simple interactive check is:

gh auth token

Treat the command's output as a secret: do not paste it into logs, commit it to a repository, or include it in screenshots. Also remember that environment variables such as GH_TOKEN can supply authentication independently of GitHub CLI's stored credentials. Enabling expiring credentials for an interactive session does not automatically make a separately supplied environment token short-lived or refreshable.

For unattended automation, use an authentication method designed for that environment, such as the short-lived GITHUB_TOKEN provided to an appropriately configured GitHub Actions workflow, or a GitHub App installation token when a separate integration needs controlled repository access. Keep permissions narrowly scoped and avoid replacing one long-lived secret with another that has broad access.

Understand the limits before rolling the change out

Expiring credentials reduce the useful lifetime of a stolen access token, but they do not eliminate the risk of credential theft. An attacker who obtains a usable refresh token may be able to acquire new access tokens, so refresh credentials must also remain protected. Device security, secure credential storage, limited permissions, and prompt revocation of suspected compromised credentials still matter.

There is also a compatibility cost. A developer who relies on a copied token for a long-running job may see failures after migration, while a Git workflow using the supported credential helper can refresh credentials as needed. The safest rollout is to enable the feature for an interactive account first, verify the authentication status, test routine Git operations, and then audit automation before changing additional environments.

For teams managing multiple developer machines, document which environments have successfully adopted expiring credentials and which integrations still depend on static tokens. Keep the preview opt-in until the workflows that matter to your team have been tested, and revisit the configuration as GitHub CLI evolves toward making expiring credentials the default for new sign-ins.