GitHub Actions cache: keys, scope, limits and clearing it
How actions/cache decides what to restore, why a cache you know exists still misses, and how to keep caches from evicting each other.
Sponsored by Graphide
The Graph & Build Editors · Updated
What the cache is for
Every job on a GitHub-hosted runner starts on a fresh machine, so anything a job downloads or compiles is gone when it ends. The GitHub Actions cache stores files between workflow runs (package manager downloads, compiled dependencies, build outputs) so the next run can restore them instead of rebuilding them.
It is not the same thing as artifacts. Artifacts keep the files a run produced (a test report, a binary) so people or later jobs can download them. The cache is a speed-up: if it is missing, the job should still produce the same result, only slower.
That last point is the one to hold on to. A cache should change how long a job takes, never what it decides. A key that restores the wrong build output can make a job pass or fail for a reason that has nothing to do with the change under test, so every rule below about keys is really a rule about keeping the verdict honest.
The shortest setup: let the setup action cache for you
For the common package managers you do not need actions/cache at all. The official setup actions create and restore the dependency cache themselves, keyed on your lockfile:
| Package manager | Setup action that caches it |
|---|---|
| npm, Yarn, pnpm | actions/setup-node |
| pip, pipenv, Poetry | actions/setup-python |
| Gradle, Maven | actions/setup-java |
| RubyGems (Bundler) | ruby/setup-ruby |
Go modules (go.sum) | actions/setup-go |
| .NET NuGet | actions/setup-dotnet |
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 24
cache: 'npm'
# For a lockfile outside the repository root:
# cache-dependency-path: subdir/package-lock.json
- run: npm ci
- run: npm testsetup-node caches npm's download cache, not node_modules, so npm ci still runs; it just stops fetching from the registry. In workflows that hold secrets or elevated permissions, its README recommends turning automatic caching off with package-manager-cache: false where you do not need it.
actions/cache by hand
Use actions/cache directly for anything the setup actions do not cover: build outputs, a Cargo target directory, a Bazel or Gradle build cache, downloaded toolchains. It takes three inputs that matter:
path: the files or directories to save and restore. One per line; globs and paths relative to the workspace both work.key: the exact name of the cache entry, up to 512 characters. Build it from what should invalidate the cache, usually the runner OS and a hash of the lockfile.restore-keys: optional prefixes, most specific first, to fall back to when there is no exact match.
- name: Cache Cargo registry and build output
id: cargo-cache
uses: actions/cache@v6
with:
path: |
~/.cargo/registry
~/.cargo/git
target
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
restore-keys: |
${{ runner.os }}-cargo-
- name: Fetch dependencies on an exact miss
if: steps.cargo-cache.outputs.cache-hit != 'true'
run: cargo fetchThe cache-hit output is 'true' only when the exact key matched. A restore from one of the restore-keys counts as a miss, which is why the install step above still runs then: the restored files are a close starting point, not a guaranteed match for the current lockfile.
A cache entry can never be changed once saved. On a miss, the action saves a new entry under key when the job finishes successfully; on a hit it saves nothing. To refresh a cache, change the key.
The major versions in these snippets are the ones each action's own README shows in November 2026. actions/cache v5 and later run on Node.js 24 and need Actions Runner 2.327.1 or newer, which matters on self-hosted runners. Check each action's releases before you pin, and pin to a commit SHA if your policy requires it.How a key is matched
On restore, the action searches in this order and stops at the first match:
- An exact match for
keyon the branch the run is for. - A prefix match for
keyon that branch. - Each of the
restore-keys, in order, on that branch. When several entries share a prefix, the most recently created one wins. - The same three steps again on the repository's default branch.
Each entry also carries a version: a hash of its path list and the compression tool used. Two entries with the same key but a different version are different caches. That is why a cache saved on windows-latest does not restore on ubuntu-latest, and why changing the path list silently starts a fresh cache even when the key stays the same. Windows runners can opt into sharing with enableCrossOsArchive: true.
Keys should name what invalidates the contents, nothing more. Put the OS (runner.os) and the lockfile hash in; leave out the commit SHA and run number unless you mean every run to save a new entry, because each extra entry counts against the repository's storage limit.
Which branches can restore which caches
Most "the cache exists but my job missed it" reports come down to scope, not to the key. A run can restore caches created on:
- its own branch,
- the default branch (usually
main), - for a pull request, its base branch, including base branches of forks.
It cannot restore caches from child or sibling branches, or from other tags. And a cache saved by a pull_request run is scoped to the pull request's merge ref (refs/pull/<number>/merge), so only re-runs of that same pull request can use it. The base branch and other pull requests never see it.
The practical consequence: if nothing runs on push to the default branch and saves a cache there, every new pull request starts cold. A small workflow that runs on push to main with the same keys keeps one warm entry that every pull request can fall back to.
Restoring and saving as separate steps
actions/cache restores at the start and saves at the end of a successful job. The actions/cache/restore and actions/cache/save sub-actions split those two halves, which helps in three cases:
- Save even when tests fail, so one flaky test does not throw away a long dependency build.
- Restore only, in jobs that should never write a cache (a fork's pull request, a release job).
- Save once in one job and restore it in many others.
- name: Restore build cache
id: restore
uses: actions/cache/restore@v6
with:
path: ~/.gradle/caches
key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
- run: ./gradlew build
- name: Save build cache, even if the build failed
if: always() && steps.restore.outputs.cache-hit != 'true'
uses: actions/cache/save@v6
with:
path: ~/.gradle/caches
key: ${{ steps.restore.outputs.cache-primary-key }}Two more inputs are worth knowing: lookup-only: true checks whether an entry exists without downloading it, and fail-on-cache-miss: true fails the job when there is no match, for jobs that must not run without a prepared cache.
Size limits, eviction and rate limits
| Rule | What GitHub documents |
|---|---|
| Unused entries | Removed after 7 days without being accessed. |
| Storage per repository | 10 GB by default. Owners and admins can raise it; usage beyond 10 GB is billed. |
| When storage is full | New caches are still saved; the oldest-accessed entries are evicted until the total is under the limit. |
| Number of entries | No limit on the count, only on total size. |
| Upload rate | Up to 200 cache uploads per minute per repository. |
| Download rate | Up to 1,500 cache downloads per minute per repository. |
The failure mode to watch for is thrashing. Pull request caches pile up (each one is scoped to its own merge ref and helps nobody else), fill the 10 GB, and push out the default-branch entries every pull request depends on. The fix is usually to delete pull request caches when the pull request closes (below) and to keep keys from multiplying, before paying for more storage.
For what extra storage costs, see the usage limits section of GitHub's dependency caching reference and your account's billing settings; the rate depends on your plan and budget settings, so check it there rather than relying on a number copied elsewhere.
How to clear the GitHub Actions cache
Since entries cannot be overwritten, "clearing" means deleting entries or changing the key. Four ways:
- In the browser: the repository's Actions tab, then Caches under Management in the sidebar. Filter with
key: <name>or by branch, and delete with the trash icon. Needs write access. - From the command line:
gh cache listto see entries,gh cache delete <id or key>to remove one, andgh cache delete --allto empty the repository's cache. - Through the REST API, to list or delete on your own schedule.
- By changing the key, for example a
v2-prefix, so the next run ignores the old entries and lets them age out after 7 days.
To stop pull request caches from crowding out the default branch, GitHub's docs give a workflow that deletes a pull request's caches when it closes:
name: Clean up caches of closed pull requests
on:
pull_request:
types: [closed]
jobs:
cleanup:
runs-on: ubuntu-latest
permissions:
actions: write
steps:
- name: Delete this pull request's caches
run: |
ids=$(gh cache list --ref "$BRANCH" --limit 100 --json id --jq '.[].id')
set +e
for id in $ids; do gh cache delete "$id"; done
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
BRANCH: refs/pull/${{ github.event.pull_request.number }}/mergeKeep untrusted runs from writing caches
Cache contents are not signed or verified, and anyone who can open a pull request can read the caches on its base branch. So: never put tokens or credentials in a cached path, and do not let untrusted code write a cache that a privileged workflow will later restore and run (cache poisoning).
GitHub enforces part of this for you. Only trusted triggers (push, workflow_dispatch, repository_dispatch, schedule and a few others) can write caches in the default branch's scope; runs from pull_request_target, issue_comment and workflow_run get read-only access there, and a save from them logs a warning instead of failing the job. The cache-mode key (read, write, write-only or none, set per workflow or per job) tightens access further. Declaring write on a low-trust trigger turns that protection off, so treat any cache it saves as untrusted.
When a warm cache does not make the job faster
A cache hit is not free. Restoring means downloading and decompressing an archive, and saving means compressing and uploading one, so a multi-gigabyte cache of things that are quick to rebuild can cost more than it saves. Check the time the cache steps themselves take in the job log before adding more paths.
- Cache what is slow to produce: compiled dependencies and build outputs usually save more than package downloads.
- Prefer the package manager's own cache directory (
~/.npm,~/.cache/pip) over installed trees likenode_modules, which tie the cache to one exact install. - Check whether compiled outputs are reused after restore. Some build tools rebuild anyway because a fresh checkout gives every file a new modification time.
- If dependencies are already warm and the job is still slow, the time is usually in the test step itself, and the fix there is splitting tests across machines, not more caching.
The site's piece on diagnosing the CI bottleneck before changing runners walks through telling those cases apart.
Moving the job is the other option. Graphide CI, this publication's sponsor, runs a team's existing GitHub Actions jobs on its own runners with dependencies and build caches already on the runner when a job starts, and every test the job runs today still runs. Switching changes each x64 Linux job's runs-on line to runs-on: graphide; see its setup docs for what it supports and its pricing page for terms.

