github-actions-cache-bust

---

name: github-actions-cache-bust description: When a workflow keeps using a stale dep (e.g., after a package.json change), bust the GitHub Actions cache. The pattern: bump cache key (add a comment or unused var to a workflow file), commit, push; or use cache: false for one build. Use when a CI Build is using a wrong version despite the source being correct. sources: github-actions-caching

GitHub Actions Cache Bust

GitHub Actions caches node_modules based on package-lock.json hash. When the lockfile changes, the cache invalidates. But sometimes:

• The lockfile hash didn't change (sub-dep update)
• Multiple workflows share the cache
• The cache key is set explicitly and doesn't auto-invalidate

When to Bust

Bust the cache when:

• CI Build is using a stale version of a dep (e.g., still on Prisma 5.22 after the package.json says 7.8.0)
• You just regenerated the lockfile and pushed it, but CI still uses old deps
• A workflow was using cache: 'npm' and now needs to skip the cache

The Simple Bump

Add a comment to the workflow file. Even an empty change works:

name: CI Build
# cache-bust: 2026-06-12

on: { ... }

Commit. Push. The workflow file change invalidates the cache key.

Or add a no-op step:

- name: Checkout
  uses: actions/checkout@v4
- name: Cache buster
  run: echo "Cache busted at $(date -u +%Y-%m-%dT%H:%M:%SZ)"
- name: Setup Node.js
  uses: actions/setup-node@v4
  with: { node-version: '20', cache: 'npm' }

The Cache buster step doesn't change the cache key, but the workflow file change does.

Disable Cache Temporarily

For one build, you can disable the cache:

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20'
    # cache: 'npm'  # temporarily disabled

This forces a fresh install. Re-enable after the build is green.

The Manual Cache Clear

You can also clear the GitHub Actions cache via the API:

gh api repos/<org>/<repo>/actions/caches \
  -X DELETE \
  -H "Accept: application/vnd.github+json"

But this requires admin access and isn't always available.

Common Pitfalls

1. Cache key doesn't include lockfile — if cache: 'npm' without cache-dependency-path, it uses the default key which doesn't include the lockfile. Add cache-dependency-path: package-lock.json to invalidate properly.
2. Multiple workflows share a cache — if Workflow A uses a key and Workflow B has the same key, invalidating one invalidates both.
3. The cache is per-branch — pushing to a different branch gives a different cache

Related Skills & Chains

• lockfile-regen — Often you need to bust the cache after regenerating the lockfile
• fleet-ci-audit — Use to identify which workflows have stale-cache issues