Cache Key vs Restore Key: How CI Cache Lookups Work
The cache key is the exact name you save under and look for first. Restore keys are prefixes that catch a near-miss, so a small change restores a useful older cache instead of nothing.
CI caching has two knobs that people conflate: the precise key and the fallback restore keys. Understanding how a lookup walks from one to the other is the key to both high hit rates and fresh data.
The exact key
On save, the cache is stored under the key. On restore, the runner first looks for an exact match. A perfect match is the ideal: it restores precisely the cache for this dependency set. The key usually embeds a lockfile hash so it changes only when it should.
Restore keys (prefix fallback)
If there is no exact match, the runner tries each restore key as a *prefix*, taking the most recent cache whose key starts with that prefix. This means a changed lockfile (new exact key, no exact hit) can still restore the previous run’s store and let the installer update just the delta.
key: deps-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
deps-Save vs restore semantics
- Save: writes under the exact key (no-op if that key already exists).
- Restore: exact key first, then restore-keys as prefixes, newest wins.
- A restore-key hit is partial - the installer reconciles the difference.
Tuning the trade-off
Too specific a key with no restore keys → frequent total misses and cold installs. Too loose a prefix → you may restore a stale, bloated cache. A tight exact key plus a sensible prefix fallback gives you freshness on a match and a warm start on a miss.
Key takeaways
- The exact key is tried first; it should change only when content should.
- Restore keys are prefix fallbacks; the newest matching cache wins.
- A restore-key hit is partial - the installer fills in the delta.
- Tight key + good prefix = freshness on hit, warm start on miss.