13.1.3.4 Pipeline Cache Invalidation

Pipeline cache invalidation is the process of recognizing that a previously stored CI cache no longer accurately reflects the current state of whatever it was caching, and correctly discarding or bypassing it rather than risking the use of stale, no-longer-valid cached content.

Why Correct Invalidation Matters as Much as Correct Caching

A cache that's reused even after its underlying inputs have genuinely changed can produce subtly incorrect build results — invalidation, just as much as the caching itself, needs to be correctly implemented.

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

Tying the cache key directly to a hash of the actual dependency lockfile ensures this specific cache is automatically invalidated whenever that lockfile genuinely changes.

Why Manual Cache Invalidation Is Sometimes Still Necessary

Occasionally a cache needs to be invalidated for a reason not reflected in its key — a change to the build tooling itself, for instance, that the key's specific hash doesn't account for.

gh actions-cache delete npm-a1b2c3d4

Manually clearing a specific cache entry forces the next run to rebuild fresh, useful when something outside the key's normal scope has changed in a way that affects the cache's validity.

Including a Version Component for Deliberate, Manual Invalidation

Adding an explicit version segment to a cache key provides a straightforward way to deliberately invalidate a cache by simply incrementing that version.

key: npm-v2-${{ hashFiles('package-lock.json') }}

Bumping this v2 segment to v3 immediately invalidates every previously cached entry under the old version, regardless of whether the lockfile hash itself changed.

Diagnosing a Suspected Stale Cache Issue

If a build behaves unexpectedly despite no apparent relevant code change, checking whether a stale cache might be the actual cause is a reasonable early diagnostic step.

gh actions-cache list

Why Pipeline Cache Invalidation Matters

Correctly invalidating a cache exactly when its underlying inputs change — and having a deliberate mechanism for manual invalidation when needed — is essential to caching actually being a safe, reliable optimization rather than a hidden source of subtly incorrect build results.