Description

This PR sits on top of #14745 in the refreshable-token stack. Testing refresh behavior by hand is awkward because GitHub issues expiring access tokens with a lifetime of 8 hours and refresh tokens with a lifetime of 6 months, so there is no practical way to wait for a real expiry. Until now the stack relied on ad hoc os.Getenv hacks (GH_AT_EXPIRES_IN, GH_RT_EXPIRES_IN, and GH_DEBUG_REFRESH_TOKEN) that were compiled into every build, including release binaries.

This replaces those hacks with a small internal/debug package. debug.Config() returns a debug.DebugConfig value whose fields are Option values, one per override, read from the environment only when gh is built with the ghdebug build tag. An unset override is None, so an explicit zero or false is still distinguishable from no override. The tag is prefixed with gh so it cannot collide with a generic debug tag that a dependency or another tool might use. In a regular build the package compiles to a stub that always returns an empty DebugConfig with every override None, so the overrides do not exist in released binaries and cannot be switched on by setting an environment variable. The parsing itself lives in an unexported, untagged configFromEnv, so the regular test run covers it on every OS; only the ghdebug implementation of Config calls it, and the linker drops it from regular builds.

The overrides, all prefixed GH_INTERNAL_ to make it clear they are not a supported interface:

• GH_INTERNAL_AT_EXPIRES_IN: access token lifetime in seconds, measured from when the token was issued. With 1, any stored access token is already treated as expired, so the next use triggers a refresh.
• GH_INTERNAL_RT_EXPIRES_IN: refresh token lifetime in seconds, measured the same way. When it is exceeded, gh behaves as if the server rejected the refresh token: it clears the stored credential and asks the user to run gh auth login.
• GH_INTERNAL_DEBUG_REFRESH_TOKEN: a boolean. By default the refresh exchange is logged as head lines only under GH_DEBUG=api; set it to true to log the full refresh request and response.

An invalid value panics in a debug build, so a typo cannot silently fall back to the real lifetime.

To make getting a debug binary easy, there is a new make debug target. It does the same as make but passes the ghdebug build tag, producing bin/gh with the overrides enabled. The build script now also compares the build tags embedded in an existing bin/gh with GO_BUILDTAGS, so switching between make and make debug always rebuilds, while repeating the same one still skips an up to date binary. CI also builds ./cmd/gh with -tags=ghdebug on the Ubuntu runner, so the debug variant cannot silently stop compiling.

A debug binary identifies itself in its version output, so it is easy to tell which kind of binary you are running:

$ bin/gh version
gh version 2.100.0-180-g76df8f52a (2026-10-19) [debug build]

The two guided e2e scripts (script/refreshable-token-e2e.sh and script/refreshable-token-gitcredential-e2e.sh) now use the GH_INTERNAL_ names, check gh version for the [debug build] marker and refuse to run against a regular binary, and point at make debug. Their own settings are renamed to match: GH_BIN, GH_E2E_HOST, and GH_E2E_ALLOW_VSCODE become GH_INTERNAL_E2E_BIN, GH_INTERNAL_E2E_HOST, and GH_INTERNAL_E2E_ALLOW_VSCODE.

The main e2e script also checks more of the behavior from earlier PRs in the stack. Every gh auth token step that prints a stored expiring token now asserts that the expiry warning appears on stderr, and the steps that print a non-expiring token (such as one from GH_TOKEN) assert that it does not. There is also a new gh auth refresh step without --expiring, next to the existing one with it, and both assert that gh asked for and received an expiring refreshable token.

Trying it out

Build a debug binary and log in with an expiring token:

make debug
bin/gh auth login --expiring

Then force the access token to count as expired and make any API call with GH_DEBUG=api:

GH_INTERNAL_AT_EXPIRES_IN=1 GH_DEBUG=api bin/gh api user --jq .login

A refresh shows up in stderr as a request to the OAuth token endpoint, before the api/user request:

* Request to https://github.com/login/oauth/access_token

Running the same command without GH_INTERNAL_AT_EXPIRES_IN shows no such line, because the freshly refreshed token is still valid. bin/gh auth status also shows the new expiry time. Add GH_INTERNAL_DEBUG_REFRESH_TOKEN=true to see the full refresh exchange instead of just its head lines.

To see what happens when the refresh token itself has expired (this logs you out of the host in gh):

GH_INTERNAL_AT_EXPIRES_IN=1 GH_INTERNAL_RT_EXPIRES_IN=1 bin/gh api user

For a guided walkthrough of every scenario, run script/refreshable-token-e2e.sh or script/refreshable-token-gitcredential-e2e.sh after make debug.

How did you test this change?

I ran make and make debug and compared the two binaries. bin/gh version printed gh version 2.100.0-180-g76df8f52a (2026-10-19) for the regular build and the same line with a trailing [debug build] for the debug build, and gh --version matched in both cases. go version -m bin/gh reported -tags=ghdebug for the debug build. I also ran make debug, make, make, make debug, make debug in sequence: every switch between the two rebuilt with the right tags, and every repeat reported bin/gh as up to date. I also built regular and ghdebug binaries for linux/amd64, windows/amd64, windows/arm64, darwin/amd64, and darwin/arm64: no regular build contains any GH_INTERNAL_ string or the configFromEnv and lifetimeFromEnv symbols, while every ghdebug build contains all of them.

I ran script/refreshable-token-e2e.sh against the debug binary and all scenarios passed, including the new gh auth token warning checks and both gh auth refresh steps, with and without --expiring.

I ran script/refreshable-token-gitcredential-e2e.sh against the debug binary in an Ubuntu 25.10 container with git 2.51.0, so the git 2.46+ authtype credential capability path was exercised, and all scenarios passed.

Key points

• The overrides are compiled out rather than hidden behind an undocumented variable, so there is no way to enable them in a release build. For the same reason the debug check is a version marker rather than something like a GH_INTERNAL_IS_DEBUG variable: a release binary has no code that reads GH_INTERNAL_* variables, so it could not respond to one without adding such code to release builds.
• The lifetime overrides are measured from issuance, not from now. GH_INTERNAL_AT_EXPIRES_IN=3600 therefore means "pretend the token was issued with a one hour lifetime", which keeps the behavior consistent across repeated invocations.
• The simulated refresh token expiry follows the same path as a real server rejection, including only clearing the stored credential when the refresh lock is held.
• make debug writes to the same bin/gh as make, so the two builds replace each other rather than coexisting.

Notes for reviewers

Start with internal/debug/config.go (the DebugConfig type and the untagged configFromEnv parser) and its two build-tagged implementations (config_enabled.go and config_disabled.go, which pick what Config returns and define debug.Enabled), then pkg/cmd/version/version.go for the version marker, then the call sites in internal/config/refreshable.go (accessTokenNeedsRefresh and simulateRefreshTokenExpired) and pkg/cmd/factory/default.go (tokenRefresherHttpClientFunc). In the scripts, the debug check is require_gh, and apart from the renames the only new logic is the auth token warning and auth refresh assertions in script/refreshable-token-e2e.sh.

Authorship and follow-up

Who wrote this:

• A human wrote it.
• An agent wrote it under close human direction.
• An agent wrote it independently, and no human has guided the implementation beyond the initial prompt.

Who answers review comments:

• @babakks will read and reply directly.
• An agent will draft replies and @babakks will read them before they are posted.
• Nobody has explicitly committed to replying.