Cache key vs restore key: como funcionam as buscas de cache no CI

Por Daniel Zoghalchali·Latchkey

A cache key é o nome exato sob o qual você salva e busca primeiro. Restore keys são prefixos que capturam um quase-acerto, para que uma pequena alteração restaure um cache antigo útil em vez de nada.

O cache de CI tem dois botões que as pessoas confundem: a key precisa e as restore keys de fallback. Entender como uma busca caminha de uma para a outra é a chave tanto para altas taxas de acerto quanto para dados frescos.

A key exata

Ao salvar, o cache é armazenado sob a key. Ao restaurar, o runner primeiro busca uma correspondência exata. Uma correspondência perfeita é o ideal: ela restaura precisamente o cache para este conjunto de dependências. A key normalmente embute um hash de lockfile para que mude apenas quando deve.

Restore keys (fallback por prefixo)

Se não há correspondência exata, o runner tenta cada restore key como um *prefixo*, pegando o cache mais recente cuja key começa com esse prefixo. Isso significa que um lockfile alterado (nova key exata, sem acerto exato) ainda pode restaurar o store da execução anterior e deixar o instalador atualizar só o delta.

Exact key + prefix fallback

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

Semântica de save vs restore

Save: grava sob a key exata (no-op se essa key já existe).
Restore: key exata primeiro, depois restore-keys como prefixos, mais recente vence.
Um acerto por restore-key é parcial - o instalador reconcilia a diferença.

Ajustando o trade-off

Uma key específica demais sem restore keys → erros totais frequentes e instalações a frio. Um prefixo frouxo demais → você pode restaurar um cache obsoleto e inchado. Uma key exata apertada mais um fallback de prefixo sensato dá frescor em uma correspondência e um início aquecido em um erro.

Principais conclusões

A key exata é tentada primeiro; ela deve mudar apenas quando o conteúdo deve.
Restore keys são fallbacks por prefixo; o cache correspondente mais recente vence.
Um acerto por restore-key é parcial - o instalador preenche o delta.
Key apertada + bom prefixo = frescor no acerto, início aquecido no erro.

Perguntas frequentes

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.

Guias relacionados

Dependency Caching Strategies for Faster CIRe-downloading dependencies every run is wasted time. Learn what to cache, how to key it on a lockfile, and Docker Layer Caching Explained: Faster Image Builds in CIDocker builds images in cached layers, reusing unchanged ones to skip work. CI Caching Explained: Speed Up Pipelines Without Breaking ThemHow CI caching works, what to cache (dependencies, build outputs, Docker layers), how cache keys and restore