How to Bust a Cache With a Version Prefix in GitHub Actions

Add a version segment to the cache key and bump it to force every branch onto a fresh cache.

Because a cache key is immutable, you cannot overwrite bad cache content under the same key. Add a v1 style segment (or a repository variable) to the key and increment it when you need to discard a poisoned cache across the whole repo.

Steps

• Add a static version token to the key, e.g. v1.
• Optionally source it from a repo/env variable like CACHE_VERSION.
• Bump the token to invalidate every existing entry at once.

Workflow

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

Gotchas

• Old caches are not deleted by a bump; they age out via LRU or the 7-day rule.
• Prefer a variable so one edit busts caches across every workflow that reads it.

Related guides