35c2439fd9
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>
|
||
|---|---|---|
| .devcontainer | ||
| .github | ||
| acceptance | ||
| api | ||
| build | ||
| cmd | ||
| context | ||
| docs | ||
| git | ||
| internal | ||
| pkg | ||
| script | ||
| skills | ||
| test | ||
| utils | ||
| .gitattributes | ||
| .gitignore | ||
| .golangci.yml | ||
| .goreleaser.yml | ||
| AGENTS.md | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
GitHub CLI
gh is GitHub on the command line. It brings pull requests, issues, and other GitHub concepts to the terminal next to where you are already working with git and your code.
GitHub CLI is supported for users on GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server 2.20+ with support for macOS, Windows, and Linux.
Documentation
For installation options see below, for usage instructions see the manual.
Contributing
If anything feels off or if you feel that some functionality is missing, please check out the contributing page. There you will find instructions for sharing your feedback, building the tool locally, and submitting pull requests to the project.
If you are a hubber and are interested in shipping new commands for the CLI, check out our doc on internal contributions
Installation
macOS
For additional macOS packages and installers, see community-supported docs
Linux & Unix
- Debian, Raspberry Pi, Ubuntu
- Amazon Linux, CentOS, Fedora, openSUSE, RHEL, SUSE
- Precompiled binaries on releases page
For additional Linux & Unix packages and installers, see community-supported docs
Windows
For additional Windows packages and installers, see community-supported docs
Build from source
See here on how to build GitHub CLI from source.
GitHub Codespaces
To add GitHub CLI to your codespace, add the following to your devcontainer file:
"features": {
"ghcr.io/devcontainers/features/github-cli:1": {}
}
GitHub Actions
GitHub-hosted runners have the GitHub CLI pre-installed, which is updated weekly.
If a specific version is needed, your GitHub Actions workflow will need to install it based on the macOS, Linux & Unix, or Windows instructions above.
For information on all pre-installed tools, see actions/runner-images
Verification of binaries
Since version 2.50.0, gh has been producing Build Provenance Attestation, enabling a cryptographically verifiable paper-trail back to the origin GitHub repository, git revision, and build instructions used. The build provenance attestations are signed and rely on Public Good Sigstore for PKI.
There are two common ways to verify a downloaded release, depending on whether gh is already installed or not. If gh is installed, it's trivial to verify a new release:
-
Option 1: Using
ghif already installed:$ gh at verify -R cli/cli gh_2.62.0_macOS_arm64.zip Loaded digest sha256:fdb77f31b8a6dd23c3fd858758d692a45f7fc76383e37d475bdcae038df92afc for file://gh_2.62.0_macOS_arm64.zip Loaded 1 attestation from GitHub API ✓ Verification succeeded! sha256:fdb77f31b8a6dd23c3fd858758d692a45f7fc76383e37d475bdcae038df92afc was attested by: REPO PREDICATE_TYPE WORKFLOW cli/cli https://slsa.dev/provenance/v1 .github/workflows/deployment.yml@refs/heads/trunk -
Option 2: Using Sigstore
cosign:To perform this, download the attestation for the downloaded release and use cosign to verify the authenticity of the downloaded release:
$ cosign verify-blob-attestation --bundle cli-cli-attestation-3120304.sigstore.json \ --new-bundle-format \ --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \ --certificate-identity="https://github.com/cli/cli/.github/workflows/deployment.yml@refs/heads/trunk" \ gh_2.62.0_macOS_arm64.zip Verified OK
Comparison with hub
For many years, hub was the unofficial GitHub CLI tool. gh is a new project that helps us explore
what an official GitHub CLI tool can look like with a fundamentally different design. While both
tools bring GitHub to the terminal, hub behaves as a proxy to git, and gh is a standalone
tool. Check out our more detailed explanation to learn more.