cache key vs restore key: CIのcacheルックアップの仕組み

著者 Daniel Zoghalchali·Latchkey

cache keyは、あなたが保存し最初に探す正確な名前だ。restore keysはニアミスを捕まえるprefixで、小さな変更が何もない代わりに有用な古いcacheを復元する。

CIのcacheには、人々が混同する2つのつまみがある: 正確なkeyと、fallbackのrestore keysだ。ルックアップが一方から他方へどう歩くかを理解することが、高いhit率と新鮮なデータの両方の鍵だ。

正確なkey

保存時、cacheはkeyの下に格納される。復元時、runnerはまず完全一致を探す。完全一致が理想だ: この依存関係セットのためのcacheを正確に復元する。keyは通常lockfileのhashを埋め込むため、変わるべきときだけ変わる。

restore keys(prefixのfallback)

完全一致がなければ、runnerは各restore keyを*prefix*として試し、そのprefixで始まるkeyを持つ最新のcacheを取る。つまり変わったlockfile(新しい正確なkey、完全hitなし)でも、前の実行のstoreを復元し、インストーラにdeltaだけを更新させられる。

Exact key + prefix fallback

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

save vs restoreのセマンティクス

save: 正確なkeyの下に書き込む(そのkeyが既にあればno-op)。
restore: まず正確なkey、次にrestore-keysをprefixとして、最新が勝つ。
restore-keyのhitは部分的だ - インストーラが差分を調整する。

トレードオフの調整

restore keysなしで具体的すぎるkey → 頻繁な完全missとcoldインストール。緩すぎるprefix → 古く肥大化したcacheを復元しうる。きつい正確なkeyに、妥当なprefixのfallbackを加えると、一致では鮮度、missではwarm startが得られる。

重要なポイント

正確なkeyが最初に試される; それは内容が変わるべきときだけ変わるべきだ。
restore keysはprefixのfallback; 一致する最新のcacheが勝つ。
restore-keyのhitは部分的だ - インストーラがdeltaを埋める。
きついkey + 良いprefix = hit時の鮮度、miss時のwarm start。

よくある質問

What is Cache key vs restore Key: how CI cache lookups work?

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.

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.