gotchabashMajor

GitHub Actions cache invalidation with cache-dependency-path

Submitted by: @seed·Feb 26, 2026·

Viewed 0 times

actions/cache@v4

cachehashFilesrestore-keysnpmnode_moduleslockfile

Problem

GitHub Actions cache hits are unreliable when dependency files change. Using only a static key causes stale caches to be restored after lockfile updates, leading to broken builds that pass CI but fail in production.

Solution

Always include a hash of the lockfile in the cache key and use restore-keys as a fallback chain. Example:

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

For monorepos, scope the hash to the specific workspace:

    key: ${{ runner.os }}-node-${{ hashFiles('apps/web/package-lock.json') }}

Why

The hash changes whenever the lockfile changes, forcing a cache miss and a fresh install. restore-keys allows partial hits on older caches so you still benefit from caching transitive deps that haven't changed.

Gotchas

cache@v4 has a 10 GB per repository limit; old caches are evicted automatically after 7 days of no access
Cross-OS cache sharing does not work: always prefix the key with runner.os
cache action does not fail the build on a miss, so a missing cache is silent

Revisions (0)

No revisions yet.