Caché de compilación en CI: claves, restauración alternativa y envenenamiento de la caché

Objetivo

Reducir el tiempo de los pipelines reutilizando las descargas de dependencias y las capas de imagen, sin que la caché altere los resultados de la compilación ni se convierta en una vía para inyectar código.

Requisitos previos

Lockfiles para cada gestor de paquetes del repositorio; un Dockerfile ordenado de modo que la instalación de dependencias preceda a la copia del código fuente; un sistema de CI con una acción de caché o un registro accesible desde el builder.

Pasos

1. Genera la clave de las cachés de dependencias a partir del sistema operativo más un hash del lockfile (${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}) y enumera las restore-keys de la más específica a la menos específica, de modo que un cambio en el lockfile restaure la caché anterior más cercana en lugar de empezar desde cero. La referencia de GitHub citada describe primero la coincidencia exacta, después las coincidencias parciales y, por último, las claves de restauración en orden.
2. Ten en cuenta el ámbito: la misma referencia indica que una ejecución puede restaurar cachés de su propia rama o de la rama por defecto (y de la rama base en el caso de los pull requests), nunca de ramas hermanas ni hijas. Calienta la caché de la rama por defecto en cada merge para que las ramas de funcionalidad la hereden.
3. Almacena en caché el directorio de descargas del gestor de paquetes, y no el árbol instalado, salvo que la instalación sea una función pura del lockfile.
4. Para las imágenes, exporta la caché de BuildKit de forma explícita: la página de backends citada señala que, a diferencia de la caché local, que siempre está activa, los backends externos deben exportarse con --cache-to e importarse con --cache-from; usa type=registry con mode=max para conservar las etapas intermedias e importa tanto la caché de la rama como la de main.
5. Ordena las instrucciones del Dockerfile de las que cambian con menos frecuencia a las que cambian con más, como recomienda la página de invalidación citada, porque invalidar una capa invalida todas las siguientes; la página también indica que los checksums de COPY ignoran mtime.
6. No escribas nunca secretos ni tokens en rutas que se almacenen en caché: la referencia de GitHub señala que el contenido de la caché no se firma ni se verifica y que cualquiera que pueda abrir un pull request puede leer las cachés de la rama base. Limita la escritura de la caché a disparadores de confianza (push, schedule) y mantén los workflows con disparadores no confiables en modo de solo lectura.
7. Vigila la expulsión de entradas: la referencia indica un límite por defecto de 10 GB por repositorio y la eliminación de las entradas a las que no se ha accedido en 7 días; las cachés demasiado grandes provocan un reemplazo constante.
8. Recompila sin caché de forma periódica (--no-cache, o una clave con un componente de fecha) para detectar la deriva de dependencias que oculta una caché caliente.

Resultado esperado

Un acierto de caché cuando los lockfiles no cambian; un acierto parcial tras un cambio pequeño en el lockfile; salidas de compilación idénticas con o sin caché; ninguna ruta en la caché que un pull request desde un fork pueda envenenar para una ejecución con privilegios.

Límites y base de verificación

El beneficio de la caché depende de la velocidad de red en relación con el tiempo de instalación y no se expresa con una cifra. Los mecanismos descritos siguen la documentación de GitHub y Docker citada; otros sistemas de CI delimitan el ámbito y expulsan entradas de forma diferente.