Est.

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 managerSetup action that caches it
npm, Yarn, pnpmactions/setup-node
pip, pipenv, Poetryactions/setup-python
Gradle, Mavenactions/setup-java
RubyGems (Bundler)ruby/setup-ruby
Go modules (go.sum)actions/setup-go
.NET NuGetactions/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 test

setup-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 fetch

The 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:

  1. An exact match for key on the branch the run is for.
  2. A prefix match for key on that branch.
  3. Each of the restore-keys, in order, on that branch. When several entries share a prefix, the most recently created one wins.
  4. 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

RuleWhat GitHub documents
Unused entriesRemoved after 7 days without being accessed.
Storage per repository10 GB by default. Owners and admins can raise it; usage beyond 10 GB is billed.
When storage is fullNew caches are still saved; the oldest-accessed entries are evicted until the total is under the limit.
Number of entriesNo limit on the count, only on total size.
Upload rateUp to 200 cache uploads per minute per repository.
Download rateUp 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:

  1. 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.
  2. From the command line: gh cache list to see entries, gh cache delete <id or key> to remove one, and gh cache delete --all to empty the repository's cache.
  3. Through the REST API, to list or delete on your own schedule.
  4. 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 }}/merge

Keep 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 like node_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.

Sources

  1. Dependency caching reference (GitHub Docs)
  2. Managing caches (GitHub Docs)
  3. actions/cache README
  4. actions/cache caching strategies
  5. actions/setup-node README
  6. gh cache (GitHub CLI manual)

Read next