Saltar al contenido

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=ghatype=registrytype=local + actions/cache
ConfiguraciónDos líneasInicio de sesión y una etiqueta de cachéPaso adicional para mover
Límite de almacenamientoComparte los 10 GB de caché del repositorioLa cuota de su registroComparte los 10 GB de caché del repositorio
Compartido con portátilesNoSíNo
Coste de descargaServicio de cachéSalida del registro, a menudo dentro de la misma regiónServicio 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_DATE antes de la instalación).
  • Falta el .dockerignore, así que el hash del contexto cambia con archivos no relacionados.
  • Una caché mode=min con compilaciones multietapa.
  • Una etiqueta de imagen base como node:22-slim que 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.

Ejecute esta compilación de Docker en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis