Estratégias de cache de dependências para um CI mais rápido

Por Daniel Zoghalchali·Latchkey

O maior e mais barato ganho de velocidade no CI é não rebaixar as mesmas dependências a cada execução. Cacheie o package store, chaveie no lockfile e a maioria das instalações fica quase instantânea.

A instalação de dependências domina muitos jobs de CI. Uma boa estratégia de cache restaura o package store de uma execução anterior para que o instalador só busque o que de fato mudou - transformando minutos em segundos.

Cacheie o store, não o projeto

Prefira cachear o store global ou download cache do gerenciador de pacotes (npm cache, ~/.m2, pip wheel cache, Cargo registry) em vez de um diretório de projeto como node_modules. O store é portável e permite ao instalador fazer uma instalação rápida e validada em vez de confiar cegamente em arquivos copiados.

Chaveie no lockfile

A cache key deve mudar exatamente quando as dependências mudam - um hash do lockfile (package-lock.json, poetry.lock, Cargo.lock). Mesmo lockfile → mesmo cache → acerto total. Lockfile alterado → nova entrada de cache, e um fallback de restore-key recupera a maior parte do store anterior.

Lockfile-keyed cache

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

Armadilhas comuns

Chavear em um valor que sempre muda → taxa de acerto de 0%.
Cachear node_modules diretamente, ocultando o drift do lockfile.
Não incluir OS/arch na key → restaurar binários incompatíveis.
Cachear mais rápido do que você invalida, servindo deps transitivas obsoletas.

Meça o retorno

Compare o tempo de instalação em um acerto de cache vs uma execução a frio; se forem similares, o cache não está acertando. Um cache de dependências saudável deve transformar uma instalação de vários minutos em segundos, e a taxa de acerto deve ser alta em branches que não tocam no lockfile.

Principais conclusões

Cacheie o package store/download cache, não o diretório resolvido do projeto.
Chaveie no hash de um lockfile; use restore-keys para fallback de quase-acerto.
Inclua OS/arch para não restaurar binários incompatíveis.
Verifique comparando o tempo de instalação com acerto vs a frio - similar significa que não está acertando.

Perguntas frequentes

What is Dependency caching strategies for faster CI?

Dependency installation dominates many CI jobs. A good caching strategy restores the package store from a previous run so the installer only fetches what actually changed - turning minutes into seconds.

Cache the store, not the project?

Prefer caching the package manager’s global store or download cache (npm cache, ~/.m2, pip wheel cache, Cargo registry) over a project directory like node_modules. The store is portable and lets the installer do a fast, validated install rather than blindly trusting copied files.

Key on the lockfile?

The cache key should change exactly when dependencies change - a hash of the lockfile (package-lock.json, poetry.lock, Cargo.lock). Same lockfile → same cache → full hit. Changed lockfile → new cache entry, and a restore-key fallback recovers most of the previous store.

Measure the payoff?

Compare install time on a cache hit vs a cold run; if they are similar, the cache is not hitting. A healthy dependency cache should turn a multi-minute install into seconds, and the hit rate should be high on branches that do not touch the lockfile.

Guias relacionados

Cache Key vs Restore Key: How CI Cache Lookups WorkA cache key is the exact entry to save and look up; restore keys are prefix fallbacks for a near-miss. What Is a Lockfile and Why Should You Commit It?A lockfile pins the exact versions of every dependency so builds are reproducible. Docker Layer Caching Explained: Faster Image Builds in CIDocker builds images in cached layers, reusing unchanged ones to skip work.