Caché de capas de Docker en CI con Buildx
Última actualización
Los runners de CI empiezan vacíos, así que cada docker build comienza sin capas y lo reconstruye todo. En una imagen de aplicación típica, eso significa reinstalar todas las dependencias en cada push. La caché de capas soluciona esto guardando la caché de compilación entre ejecuciones. Esta guía muestra los dos backends que importan en GitHub Actions y cómo escribir un Dockerfile que realmente aproveche la caché.
Primero, ajuste el Dockerfile
Una caché solo es útil si las capas se mantienen idénticas entre compilaciones. Docker invalida una capa, y todas las que vienen después, cuando cambian la instrucción o los archivos que copia. Coloque en la parte superior lo que cambia con poca frecuencia:
FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:22-slim
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
CMD ["node", "dist/server.js"]
La capa npm ci se reutiliza hasta que cambie el archivo de bloqueo. Si escribió COPY . . antes de la instalación, cada edición del código fuente reinstalaría todo. Añada un .dockerignore con .git, node_modules y la salida de compilación, para que los archivos no relacionados no invaliden la caché.
Para los gestores de paquetes, los cache mounts de BuildKit conservan la caché de descargas incluso cuando la capa se reconstruye:
RUN --mount=type=cache,target=/root/.npm npm ci
Tenga en cuenta que los cache mounts residen en el builder de BuildKit, no en la caché de capas, así que requieren un tratamiento aparte en CI (más abajo).
Backend 1: la caché de GitHub Actions (type=gha)
La configuración más sencilla usa build-push-action de Docker y el servicio de caché de GitHub:
- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
with:
context: .
push: false
tags: myapp:ci
cache-from: type=gha
cache-to: type=gha,mode=max
mode=max exporta todas las capas, incluidas las de las etapas intermedias de una compilación multietapa. El valor predeterminado, mode=min, exporta solo las capas de la imagen final, lo que no encaja bien con los Dockerfiles multietapa. Use max y acepte una caché más grande.
Compromisos, según los límites indicados en la documentación de GitHub: la caché cuenta para los 10 GB de almacenamiento de caché del repositorio, las entradas sin uso durante 7 días se eliminan, y se aplica el alcance por rama como en cualquier caché de Actions. Las imágenes grandes pueden llenar la cuota rápidamente y expulsar sus otras cachés. Use un scope por imagen si un repositorio compila varias:
cache-from: type=gha,scope=api
cache-to: type=gha,scope=api,mode=max
Backend 2: una caché en el registro (type=registry)
Guarde la caché como una imagen en su registro (GHCR, ECR, Docker Hub). No consume la cuota de caché de Actions, dura más y puede compartirse con las máquinas de los desarrolladores y con otros sistemas de CI:
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v6
with:
context: .
push: true
tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache
cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache,mode=max
El job necesita permissions: packages: write para subir a GHCR. Para ECR, use image-manifest=true,oci-mediatypes=true en cache-to, porque ECR requiere tipos de medios OCI para los manifiestos de caché. Consulte la documentación de AWS y Docker para su registro; el soporte varía.
Qué backend elegir
| type=gha | type=registry | type=local + actions/cache | |
|---|---|---|---|
| Configuración | Dos líneas | Inicio de sesión y una etiqueta de caché | Paso adicional para mover |
| Límite de almacenamiento | Comparte los 10 GB de caché del repositorio | La cuota de su registro | Comparte los 10 GB de caché del repositorio |
| Compartido con portátiles | No | Sí | No |
| Coste de descarga | Servicio de caché | Salida del registro, a menudo dentro de la misma región | Servicio de caché |
Para la mayoría de los equipos: empiece con type=gha y pase a type=registry cuando las imágenes sean grandes o cuando también compile fuera de GitHub.
Cache mounts en CI
Los datos de RUN --mount=type=cache no los exporta cache-to. Si depende de los cache mounts para las descargas de paquetes, puede persistirlos con una herramienta auxiliar como reproducible-containers/buildkit-cache-dance, o prescindir de los mounts en CI y confiar en la caché de capas del paso de instalación. Para la mayoría de las aplicaciones, la segunda opción es más sencilla.
Compruebe que funciona
En el registro de compilación, los pasos en caché aparecen marcados como CACHED. Si su capa de instalación se ejecuta siempre, busque estas causas:
- Un
COPY . .antes del paso de instalación. - Un argumento de compilación o una marca de tiempo que cambia en cada ejecución (
ARG BUILD_DATEantes de la instalación). - Falta el
.dockerignore, así que el hash del contexto cambia con archivos no relacionados. - Una caché
mode=mincon compilaciones multietapa. - Una etiqueta de imagen base como
node:22-slimque se ha movido. Este comportamiento es correcto, pero invalida todo lo que viene después. Fije la imagen por digest si quiere aciertos de caché predecibles, y actualícela con Dependabot.
Otras mejoras de velocidad para las compilaciones de imágenes
- Compile una sola plataforma en CI, salvo que distribuya imágenes multiarquitectura. Las compilaciones arm64 emuladas con QEMU son muchas veces más lentas que las nativas; use un runner arm64 nativo para ese job cuando necesite ambas.
- Use una imagen base slim o distroless para reducir el tamaño de las subidas y descargas.
- Ejecute las pruebas contra la imagen compilada en un job posterior con
load: true, en lugar de volver a compilarla.
Preguntas frecuentes
¿GitHub ofrece caché de capas de Docker integrada?
Los runners alojados en GitHub no conservan las capas de Docker entre jobs. Debe exportar e importar la caché con buildx, como se indicó anteriormente.
¿Puedo usar la caché de capas sin buildx?
El builder clásico no puede importar una caché desde un almacén remoto de la misma forma. Utilice BuildKit a través de docker buildx o build-push-action.
¿Por qué mi caché es más grande que mi imagen?
mode=max almacena cada etapa y cada capa intermedia. Es el comportamiento esperado.
¿Es segura la caché del registro para los forks?
Los pull requests desde forks no tienen acceso de escritura a su registro ni a sus secrets. Use cache-from únicamente en esas ejecuciones, y escriba la caché desde main.
Próximos pasos
Consulte cómo acelerar GitHub Actions para el resto del pipeline, y la calculadora de costes para convertir los minutos ahorrados en dólares. Si sus compilaciones de imágenes están limitadas por la CPU, el modo de comparación de compiler.dev ejecuta el mismo job en una máquina más potente para que pueda comparar el tiempo y el precio por ejecución.
Relacionado
- ¿Docker build lento en CI? Encuentre la causa y solúvala¿Builds de Docker lentos en CI? Revise el tamaño del contexto, .dockerignore, el orden de capas, fallos de caché y BuildKit. Corrija primero lo más costoso.
- Caché en GitHub Actions: claves, límites y ejemplosCómo funcionan actions/cache, la caché de setup-* y restore-keys, con YAML listo para copiar, ámbito y límites de tamaño, y los errores que causan fallos.
- Límite de pull de Docker Hub en GitHub Actions: solucionesSolucione "toomanyrequests: You have reached your pull rate limit" en GitHub Actions: límites de Docker Hub, docker/login-action, mirrors y alternativas GHCR.
- Plantilla de workflow de GitHub Actions para compilar DockerFlujo de trabajo de GitHub Actions para copiar y pegar: compile imágenes Docker con Buildx, capas en caché de GitHub y publique en GHCR desde main.