Fix your GitHub Actions cache: misses, thrash, and key design

Symptoms

How to tell if your cache is broken or thrashing

GitHub Actions doesn't fail a job when caching breaks. Instead, it silently falls through to a cold install. Cache thrash is even harder to spot because entries are saved and restored, but the restored data doesn't help. Look for these symptoms:

• Low or zero cache hit rate. Expand the actions/cache step in your workflow logs. If it says Cache not found for input keys on most runs, your key pattern is wrong or your caches are being evicted before reuse.

• Cache restore followed by full install. If the logs say Cache restored from key but npm ci or pip install still takes the same time as a cold run, you're restoring stale data. The cache hit is an illusion because it matched a prefix via restore-keys but the content is too outdated to help.

• Consistent install times across runs. If npm ci, pip install, or bundle install takes the same amount of time on every run, even when dependencies haven't changed, nothing is being cached. A working cache should reduce install time by 50–90%.

• First PR run always cold. Every new pull request starts with a full dependency install, even though main just ran the same workflow with the same lockfile. This points to a branch scoping issue where your PR can't access the cache created by main because the key doesn't match.

• Cache size near the 10 GB limit. Check your repository's cache usage under Settings → Actions → Caches. If you're at or near 10 GB with hundreds of entries, you're creating too many unique cache keys. GitHub evicts the least recently used entries first, potentially including caches your workflows depend on.

• Build failures that disappear on re-run. Stale caches can restore outdated build artifacts, incompatible dependency versions, or corrupted state. If your CI fails with cryptic errors that vanish when you re-run the job (or clear the cache), a broad restore-keys pattern is likely restoring data from a different context.

Metrics

What broken caching costs you

Dependency installation is often the single largest chunk of CI runtime. When caching works, it eliminates that chunk. When it misses, you pay for a full install on every run. When it thrashes, you pay for a full install plus cache upload and download overhead. Here's what that looks like for a team running 40 CI jobs per day on Linux:

At $0.006/min (Linux 2-core), 40 runs/day. A thrashing cache is $11/month worse than no cache at all because it adds upload and download overhead on every run without saving any install time. On macOS runners at $0.062/min, the same pattern costs $109/mo more than no cache. Fix the keys and you save $37/mo on Linux or $444/year per workflow.

Fix 1

Stop using commit SHAs in cache keys

The most common cache misconfiguration is using github.sha, github.run_id, or github.run_number in the cache key. Since these change on every push, you get a unique key every time, which means a cache miss every time. The cache is created but never restored by exact match. A repository running 40 jobs/day with SHA-based keys creates 40 new cache entries daily, filling the 10 GB repo limit within days and evicting the caches that matter.

The correct pattern keys on the OS and the hash of your lockfile. The cache only changes when dependencies actually change. Between dependency updates, every run gets an exact match.

- uses: actions/cache@v4
  with:
    path: node_modules
    key: ${{ runner.os }}-${{ github.sha }}
    restore-keys: |
      ${{ runner.os }}-

# Key changes every commit
# restore-keys matches any OS entry
# → restores stale data every time
# → saves a new 400 MB entry every time

- uses: actions/cache@v4
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

# Key only changes when lockfile changes
# → exact hit on most runs
# → prefix match after dep update

One caveat: hashFiles() runs against the working directory, so it must come after actions/checkout. If you place the cache step before checkout, hashFiles() returns an empty string, silently producing the same key for every run regardless of whether dependencies changed. No error is raised.

Also avoid using hashFiles('**/package-lock.json') with the recursive glob. After npm ci runs, nested package-lock.json files inside node_modules can match the glob, producing a different hash at save time than at restore time. Reference the lockfile directly: hashFiles('package-lock.json').

Fix 2

Add layered restore keys for partial cache hits

When a developer adds a new dependency, the lockfile hash changes and the exact cache key no longer matches. Without restore keys, the runner falls back to a full install from scratch. With restore keys, it finds the closest previous cache and only installs the delta.

Restore keys are evaluated as prefixes, in order, and the most recently created match wins. Order them from most specific to least specific. But make the prefixes specific enough to match only caches from the same context. A broad prefix like ${{ runner.os }}- matches any cache for that OS, including entries from different workflows or dependency managers. Scope it to ${{ runner.os }}-node- so it only matches relevant entries.

- uses: actions/checkout@v4

- uses: actions/cache@v4
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

- run: npm ci

Here's how the lookup works: GitHub first tries the exact key (Linux-node-abc123). If the lockfile changed, that misses. It then tries the prefix Linux-node-, which matches any previous Node cache for this OS. The restored node_modules is stale but usable, so npm ci only needs to fetch the diff, which is typically a few seconds instead of a few minutes.

For matrix builds, include the matrix variable in both the key and the restore-key prefix to avoid cross-version collisions. Without it, a Node 18 job may restore a cache created by a Node 20 job, causing native module incompatibilities:

key: ${{ runner.os }}-node-${{ matrix.node-version }}-${{ hashFiles('package-lock.json') }}
restore-keys: |
  ${{ runner.os }}-node-${{ matrix.node-version }}-
  ${{ runner.os }}-node-

One caveat: don't over-scope restore keys either. If your restore-key is identical to your primary key minus the hash, a single prefix is correct. Adding more layers just widens the blast radius without improving hit rates.

Fix 3

Split dependency and build caches into separate entries

Use separate cache entries for dependencies and build artifacts. Dependencies change rarely (when the lockfile changes). Build artifacts change on every commit (when source code changes). A single cache entry that bundles both invalidates on every push, reproducing the thrash pattern even with a good cache key.

# Cache 1: Dependencies (changes when lockfile changes)
- uses: actions/cache@v4
  with:
    path: node_modules
    key: ${{ runner.os }}-deps-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-deps-

- run: npm ci

# Cache 2: Build output (changes when source changes)
- uses: actions/cache@v4
  with:
    path: .next/cache
    key: ${{ runner.os }}-nextjs-${{ hashFiles('src/**') }}
    restore-keys: |
      ${{ runner.os }}-nextjs-

- run: npm run build

The dependency cache hits on every run that doesn't change package-lock.json, which is most runs. The build cache invalidates more frequently but is smaller and restores a partial build state that still speeds up the next build. Each cache does its job without poisoning the other.

One caveat: some build tools produce caches that become stale over time. The Next.js team has documented that a stale .next/cache can make builds 30% slower than a clean build. If your build cache grows unbounded or build times increase over time, add a time-based component to the key (e.g., the current week number) to force periodic invalidation.

Fix 4

Replace manual cache config with setup action caching

GitHub's official setup-* actions have built-in caching that handles key generation, path detection, and restore logic automatically. One parameter replaces 5+ lines of cache configuration. This eliminates most key misconfiguration issues.

- uses: actions/checkout@v4

- uses: actions/setup-node@v4
  with:
    node-version: 20

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

- run: npm ci

- uses: actions/checkout@v4

- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'npm'

- run: npm ci

This works for Node (setup-node with cache: 'npm', 'yarn', or 'pnpm'), Python (setup-python with cache: 'pip'), Ruby (setup-ruby with bundler-cache: true), Go (setup-go with cache: true), and Java (setup-java with cache: 'gradle' or 'maven').

One caveat: these actions cache the package manager download cache, not the installed output. For Node, that means ~/.npm is cached, not node_modules. The npm ci step still runs, but it skips downloading tarballs and installs from the local cache instead. This typically saves 30–60% of install time. If you need to skip the install entirely, cache node_modules directly with actions/cache, but make sure to include the Node version in the key to avoid cross-version breakage.

Fix 5

Warm the default branch cache for all PRs

GitHub Actions cache has strict branch scoping rules. A workflow run can only restore caches from its own branch or the default branch (usually main). PRs can also access the base branch cache. But caches created during a PR workflow are scoped to refs/pull/.../merge and can't be shared with other PRs or the base branch.

This means the first run of every new PR starts cold unless main has a matching cache. The fix is a lightweight workflow that runs on pushes to main and creates a warm cache entry that every PR can restore from.

name: Warm Cache

on:
  push:
    branches: [main]
    paths:
      - 'package-lock.json'  # Only run when deps change

jobs:
  warm:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - uses: actions/cache@v4
        with:
          path: node_modules
          key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}

      - run: npm ci

The paths filter ensures this workflow only runs when the lockfile actually changes on main, not on every merge. When it does run, it creates a cache entry on the default branch. Every subsequent PR that uses the same cache key pattern will get an immediate hit, because PR workflows can always read from the default branch cache.

One caveat: caches are immutable in GitHub Actions. If the key already exists, the save step is silently skipped. This is fine for lockfile-based keys, since the cache only needs to be created once per lockfile version. But if you use time-based or run-based keys, you'll create many unique entries and fill your 10 GB quota faster.

Reference

Cache key design checklist

A well-designed cache key follows the pattern ${{ runner.os }}-purpose-version-${{ hashFiles('lockfile') }}. Use this table to audit your cache keys against the most common mistakes:

The purpose segment (e.g., deps, build) prevents cross-cache collisions. The version segment prevents cross-tool collisions. The lockfile hash ensures the cache only invalidates when its contents would actually change. Always include ${{ runner.os }} in your cache key because caches from Linux runners can't be restored on macOS or Windows.

Reference

Correct cache keys by ecosystem

Each language ecosystem has a different lockfile, cache path, and package manager. Here are the recommended key patterns and the setup action shorthand for the most common ones: