actions/cache: Keys, Restore Keys & Best Practices

actions/cache is the biggest CI speedup when keyed correctly - and a silent no-op when keyed wrong.

Cache the expensive, rarely-changing work and key it so the cache changes exactly when the content should.

Key vs restore-keys

The key is an exact match (a lockfile hash). restore-keys are prefix fallbacks so a near-miss restores a useful older cache instead of nothing.

Pattern

.github/workflows/ci.yml

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

Pitfalls

Keying on a commit SHA → 0% hit rate.
Keying on something too stable → stale deps forever.
Caching the rebuilt output instead of the download store.

Related guides

How to Cache Dependencies in GitHub Actions (Every Ecosystem)Cache dependencies in GitHub Actions with actions/cache - correct keys and paths for npm, yarn, pnpm, pip, Ma… CI Caching Explained: Speed Up Pipelines Without Breaking ThemHow CI caching works, what to cache (dependencies, build outputs, Docker layers), how cache keys and restore…