gh cache list: Inspect Actions Caches in CI
gh cache list shows the Actions caches in a repository with their keys, sizes, and last-used times.
When a cache balloons or a stale key keeps winning, gh cache list is how you see what is stored before pruning it.
What it does
gh cache list returns the GitHub Actions caches for a repository, including the cache key, the ref it was created on, the size, and when it was last accessed. Filters narrow the list by key prefix or ref.
Common usage
gh cache list
gh cache list --key node-modules-
gh cache list --ref refs/heads/main --sort size_in_bytes
gh cache list --json id,key,sizeInBytesFlags
| Flag | What it does |
|---|---|
| --key <prefix> | Filter caches by key prefix |
| --ref <ref> | Filter caches by the git ref |
| -L, --limit <n> | Maximum number of caches to list |
| -S, --sort <field> | Sort by created_at, last_accessed_at, or size_in_bytes |
| --json <fields> | Output cache data as JSON |
| -R, --repo <owner/repo> | Target a specific repository |
In CI
Set GH_TOKEN and permissions: { actions: read }. Total cache storage per repository is capped (10 GB), and GitHub evicts least-recently-used caches when full, so listing by --sort size_in_bytes surfaces the biggest culprits to delete.
Common errors in CI
"gh: To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable" means GH_TOKEN is unset. An empty list can simply mean no caches exist yet. "could not determine base repository" outside a checkout is fixed with -R owner/repo.
Using this in CI
CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.
- uses: actions/checkout@v4
with:
fetch-depth: 0 # history, tags, and git describe all need this
- run: |
git rev-parse --is-shallow-repository # expect false
git rev-parse --abbrev-ref HEAD # prints HEAD when detached