This is the opt-in surface for the new go-gh aggressive caching
support. Setting GH_AGGRESSIVE_CACHING_TTL to a Go duration string
(e.g. 30s, 1m, 5m, 1h) enables process-wide TTL caching for cacheable
REST and GraphQL requests on the standard authenticated HTTP client.
Motivation: heavy users running multiple parallel agent harnesses
(e.g. several Codex agents in lockstep) issue duplicate identical
requests within seconds of each other, exhausting the GitHub primary
REST rate limit and tripping secondary limits. A short TTL (~30s)
dedupes the lockstep traffic without changing what gh fundamentally
is. The trade-off (bounded staleness) is acceptable when explicitly
opted into.
Wiring:
- api/http_client.go: NewHTTPClient reads GH_AGGRESSIVE_CACHING_TTL
after honoring caller-supplied EnableCache. The env var only
activates when:
- opts.EnableCache is not already true (caller config wins)
- opts.SkipDefaultHeaders is false (PlainHttpClient bypasses
defaults and must not opt into caching by env var)
Per-request X-GH-CACHE-TTL: 0 still bypasses for individual calls.
- parseAggressiveCachingTTL is silent on failure: empty, '0',
negative, or unparseable values disable the feature. Matches the
convention for other GH_* env vars and avoids stderr noise from
a transport layer. Users diagnose via the X-GH-Cache-Status
response header.
- help_topic.go: documents the env var, format, staleness caveat,
intended use case, observability hook, cleanup path
(gh config clear-cache), and explicit precedence rules.
Tests cover:
- parseAggressiveCachingTTL edge cases (empty, valid, zero,
negative, unparseable, missing unit, plain number).
- Env var with positive duration enables caching end-to-end
(miss -> hit pattern, network call only on first request).
- Env var unset or with invalid value leaves caching disabled.
- Caller-set EnableCache + CacheTTL takes precedence over env var.
- SkipDefaultHeaders (PlainHttpClient path) bypasses aggressive
caching even when env var is set.
- Per-request X-GH-CACHE-TTL: 0 hard-bypasses cache when env var
is set, and does not pollute the cached entry.
Manual smoke verified against live api.github.com:
- REST GET: miss -> hit transitions work, X-GH-Cache-Status
visible via 'gh api -i'.
- GraphQL query: same miss -> hit pattern works.
- Per-request opt-out: header returns no X-GH-Cache-Status,
confirming bypass.
- 'gh auth status', 'gh config clear-cache' continue to work.
Out of scope here:
- ETag / If-None-Match revalidation (planned follow-up that layers
on top of the same transport).
- Rewriting commands like 'gh pr checks --watch' to take advantage
of REST + ETag (separate decision, separate PR).
Depends on go-gh changes:
- 'Fix per-request cache opt-out when global TTL is configured'
- 'Restrict cacheable responses to 2xx'
- 'Skip caching of GraphQL mutations and subscriptions'
- 'Use atomic temp-file + rename for cache writes'
- 'Vary cache key by Accept-Encoding, X-GitHub-Api-Version, ...'
- 'Emit X-GH-Cache-Status response header for cache observability'
Related: cli/cli#13279, cli/cli#13293
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Harden SpawnSendTelemetry against relative executable paths
- Use io.Copy for telemetry subprocess stdin write
- Clean up GH_TELEMETRY/DO_NOT_TRACK help text
- Fall back to built-in defaults (NoOp telemetry) on config load failure
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit changes <github.com> and <ghe.com> references to `github.com` and `ghe.com` so they are visible on the GitHub CLI marketing website.
GitHub Pages will render URLs with a protocol as clickable links, however hostnames are treated as HTML elements and not rendered.
- added support for `accessible_colors` configuration setting in `gh config` commandset
- updated default configuration file to contain `accessible_colors: disabled`
- add `GH_ACCESSIBLE_COLORS` env var to `gh environment`
- generated mocks via `go generate ./...` including previously missed prompter changes
This commit adds the new environment variable to the `gh environment` help topic.
Additionally, there is a small fix for Go linter for an unused variable raised as a problem.
- update `gh help environment` to include that upgrade notices only happen when gh or extensions are executed
- update `gh ext --help` to include reference to upgrade notices and points to `gh help environment` for info on disabling
During discussion in cli/cli#9934, we can to the conclusion that the logic around checking for core GitHub CLI updates would diverge from GitHub CLI
extension updates over time. To that end, this commit splits that logic into a separate function with a new environment variable.
After initial discussion with core maintainers, it didn't seem prudent to duplicate the GitHub Docs information on OAuth scopes within the GitHub CLI codebase.
Instead, this commit updates help usage information in relevant commands on the page within GitHub Docs for more information.
Found with
rg '(^ | \t|\t )' -g '*.go' -g '!*_test.go'
Mixed indent exceptions:
- wrapped long list items with extra 2-space indent
- code snippets using space indent
- commented code lines having "\t*// \t+" prefix
- gh help actions
- highlight 3 commands to run for more information
- gh extension
- wrapping url for online linking
- fix install subcommand missing backtick formatting
- gh release create
- fixing mixed indenting causing usage misalignment
- root help
- backtick wrap help command for more info for consistency
- gh help environment
- backtick wrap missed OWNER/REPO
- gh variable
- brought consistency to output when deleting or setting variable
When connected to a TTY, tell the jq formatter to indent the output, and
enable colorization of the output if the terminal supports it.
Co-authored-by: Mislav Marohnić <mislav@github.com>
We used to do the equivalent of `rootCmd.SetOut(os.Stdout)` because we
thought that Cobra's "Out" stream represents standard output. However,
upon closer inspection it turns out that this is Cobra's stream for
usage errors and deprecation warnings, and those we want written to
stderr as well. It is not clear to me why Cobra maintains a distinction
between "Out" and "Err" streams since both seem to go to sdterr by
default.
This change also ceases our usage of `command.Print()` functions in
favor of explicitly writing to `IOStreams.Out/ErrOut`.
The GH_DEBUG environment variable is a new gh-specific verbosity control.
For backwards-compatibility, DEBUG will still be respected if it has values
"1", "true", "yes", and "api", but any other values will be ignored.
Finally, support for "oauth" debug value has been dropped in favor of "api".
The "oauth" value only had limited, internal use.
Co-authored-by: Mislav Marohnić <mislav@github.com>
