Unique cache keys versus restore-key fallbacks for dependency caching

Direct answer

Use a content‑based primary key that incorporates the lockfile hash and a narrow scope identifier (e.g., the sub‑package path) and keep restore-keys limited to that same scope. Avoid timestamps or run‑specific version prefixes in the primary key.

Likely explanation (assumption)

Embedding a version or timestamp forces a new cache entry on every run, guaranteeing freshness but rapidly exhausting the 10 GB repository quota and lowering overall hit rate. A broad restore-keys prefix (e.g., deps-) maximizes reuse but can pull artifacts from an incompatible branch or older transitive versions, causing stale restores.

Confirmed facts

• The actions/cache action matches a cache only when the primary key is an exact string; restore‑keys are evaluated in order and provide a best‑effort partial restore when the primary key is missing.
• A partial restore does not fill missing files, so a full run npm ci (or equivalent) must still execute to ensure correctness.
• The 10 GB repository‑wide cache limit and the 7‑day LRU eviction apply to all workflows sharing the same repository, so many distinct keys accelerate eviction.
• actions/cache@v4 adds an explicit version label to the key namespace; it does not automatically invalidate caches when lockfile contents change.

Steps for this monorepo case

1. Generate the primary key as deps-${{ hashFiles('**/package-lock.json') }}-${{ github.workflow }}-${{ github.scope }}, where github.scope is the path or name of the sub‑package being cached.
2. Define restore-keys as a short, ordered list that mirrors the primary key hierarchy, for example:

   restore-keys:
     - deps-${{ hashFiles('**/package-lock.json') }}
     - deps-

3. Run the restore step before installing dependencies; if a match occurs, the cache will be used, otherwise the workflow proceeds with a fresh install.
4. Monitor cache usage in the workflow logs (look for “Cache hit” / “Cache miss”) and track the total size via the repository’s cache metrics to ensure it stays below the 10 GB quota.
5. Periodically review the restore-keys list to prune overly broad entries that could pull stale artifacts from other branches.

Influence of the 10 GB limit

Aggressive key rotation creates many distinct cache entries, each consuming space and increasing the chance that the 10 GB quota is reached, which triggers early eviction of older, still‑useful caches. A narrow primary key with a limited set of restore‑keys reduces the number of unique keys, preserving hit rate under the quota constraint.

Effect of actions/cache@v4 versioning

Versioning changes only the key namespace; it does not provide automatic invalidation on dependency updates. It can be used to segment caches by major version of a toolchain, but it does not eliminate the trade‑off between freshness and hit rate.

Missing diagnostic detail

Are the caches for each workflow (job) isolated, or do they share the same repository‑wide cache namespace? This determines whether a broad restore-keys prefix could contaminate unrelated jobs.