Cache de build em CI: chaves, fallbacks de restauração e envenenamento de cache

Objetivo

Reduzir o tempo do pipeline reaproveitando downloads de dependências e camadas de imagem, sem que o cache altere o resultado do build nem se torne um caminho para injeção de código.

Pré-requisitos

Lockfiles para cada gerenciador de pacotes do repositório; um Dockerfile ordenado de modo que a instalação das dependências venha antes da cópia do código-fonte; um sistema de CI com uma action de cache ou um registry acessível a partir do builder.

Passos

1. Use como chave dos caches de dependências o sistema operacional mais o hash do lockfile (${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}) e liste as restore-keys da mais específica para a menos específica, de modo que uma alteração no lockfile restaure o cache anterior mais próximo em vez de começar do zero. A referência do GitHub citada descreve a ordem: primeiro a correspondência exata, depois as correspondências parciais e, por fim, as restore keys em sequência.
2. Entenda o escopo: a mesma referência afirma que uma execução pode restaurar caches da própria branch ou da branch padrão (e da branch base, no caso de pull requests), mas nunca de branches irmãs ou filhas. Aqueça o cache da branch padrão a cada merge para que as branches de feature o herdem.
3. Faça cache do diretório de download do gerenciador de pacotes, e não da árvore instalada, a menos que a instalação seja uma função pura do lockfile.
4. Para imagens, exporte o cache do BuildKit de forma explícita: a página de backends citada observa que, diferentemente do cache local, que está sempre ativo, os backends externos precisam ser exportados com --cache-to e importados com --cache-from; use type=registry com mode=max para manter os estágios intermediários e importe tanto o cache da branch quanto o cache da main.
5. Ordene as instruções do Dockerfile das que mudam menos para as que mudam mais, como recomenda a página de invalidação citada, pois invalidar uma camada invalida todas as seguintes; a página também afirma que os checksums de COPY ignoram mtime.
6. Nunca grave segredos ou tokens em caminhos que entram no cache: a referência do GitHub afirma que o conteúdo do cache não é assinado nem verificado e que qualquer pessoa capaz de abrir um pull request pode ler os caches da branch base. Restrinja a gravação de cache a gatilhos confiáveis (push, schedule) e mantenha os workflows com gatilhos não confiáveis em modo somente leitura.
7. Acompanhe a remoção de entradas: a referência indica um limite padrão de 10 GB por repositório e a remoção das entradas não acessadas em 7 dias; caches grandes demais ficam sendo removidos e recriados continuamente.
8. Reconstrua sem cache em intervalos regulares (--no-cache, ou uma chave com componente de data) para detectar desvios de dependências que um cache aquecido esconde.

Resultado esperado

Um cache hit quando o lockfile não muda; um hit aproximado após uma pequena alteração no lockfile; saídas de build idênticas com ou sem cache; nenhum caminho no cache que um pull request vindo de um fork possa envenenar para uma execução privilegiada.

Limites e base de verificação

O benefício do cache depende da velocidade da rede em relação ao tempo de instalação e não é expresso como um número. A mecânica segue a documentação citada do GitHub e do Docker; outros sistemas de CI definem escopo e remoção de forma diferente.