Saltar al contenido

Caché de Docker Buildx en GitHub Actions: gha, registry

Última actualización

Para almacenar en caché las compilaciones de Docker en GitHub Actions, use docker/setup-buildx-action y docker/build-push-action con cache-from: type=gha y cache-to: type=gha,mode=max. Así se guarda la caché de capas de BuildKit en la caché de GitHub Actions. Existen cuatro backends (gha, registry, inline, local); esta guía muestra cada uno, cuándo elegirlo y sus límites.

Si su compilación es lenta y no sabe por qué, empiece por Docker build slow in CI. Para los conceptos, consulte Docker layer caching in CI.

La configuración predeterminada: type=gha

name: Docker
on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v7
        with:
          context: .
          push: false
          tags: app:ci
          cache-from: type=gha
          cache-to: type=gha,mode=max

Configurar Buildx es obligatorio. La documentación de Docker (revisada en octubre de 2026) indica que el controlador predeterminado docker solo funciona con el backend gha cuando el almacén de imágenes de containerd está habilitado; de lo contrario, necesita otro controlador, y setup-buildx-action lo crea. La URL de la caché y el token se rellenan automáticamente dentro de un workflow.

Parámetros importantes

Según la documentación del backend gha de Docker:

ParámetroPredeterminadoSignificado
scopebuildkitNombre del objeto de caché. Use uno por imagen.
modeminmin exporta solo las capas de la imagen final; max exporta todas las capas de todas las etapas.
ignore-errorfalseNo hacer fallar la compilación si falla la exportación de la caché.

Use mode=max en compilaciones de varias etapas. Con min, las etapas intermedias (por ejemplo, la instalación de dependencias o el paso de compilación) no están en la caché, y son las más costosas. max las almacena a cambio de una caché más grande.

Defina un scope por imagen. El scope predeterminado es compartido, así que dos imágenes compiladas en un mismo repositorio sobrescriben mutuamente su caché:

cache-from: type=gha,scope=web
cache-to: type=gha,scope=web,mode=max

En una matriz, incluya el valor de la matriz en el scope, por ejemplo scope=build-${{ matrix.platform }}.

La documentación también describe una API más reciente del servicio de caché (v2), seleccionada mediante la URL o un ajuste version. Si aparecen errores de caché tras un cambio en GitHub, compruebe que sus versiones de Buildx y BuildKit estén actualizadas, porque las anteriores apuntan a la API antigua.

Limitación de velocidad

La exportación intensiva de caché puede alcanzar los límites de la API. La action de compilación pasa github-token (predeterminado secrets.GITHUB_TOKEN) a Buildx para ayudar a evitar la limitación; manténgalo configurado.

Límites de type=gha

  • Vive en la caché de GitHub Actions, así que comparte la cuota de 10 GB por repositorio con npm, pip y todo lo demás. Una caché de Docker con mode=max puede ocupar varios GB por sí sola.
  • Las entradas no usadas durante 7 días se eliminan, y las menos usadas recientemente se borran primero cuando el repositorio supera la cuota. Consulte límites de caché.
  • Los PR leen la caché de la rama base y escriben sus propias entradas con scope. Compile también en main para mantener la caché base actualizada.
  • Los runners autoalojados pueden no tener acceso al servicio de caché de GitHub, según la configuración. Compruébelo antes de depender de él; una caché de registro evita el problema.

type=registry

Almacene la caché como una imagen en un registro de contenedores:

- uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v7
  with:
    context: .
    push: true
    tags: ghcr.io/${{ github.repository }}:latest
    cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache
    cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache,mode=max

Úselo cuando la caché sea grande, cuando los runners no estén en la red de caché de GitHub o cuando quiera que los desarrolladores locales y el CI compartan una caché. No cuenta contra la cuota de 10 GB de Actions (se aplican en su lugar las normas de almacenamiento del registro). Subir y descargar una caché grande por red lleva tiempo, así que mantenga el registro cerca del runner. Algunos registros no admiten manifiestos de caché; compruebe el suyo.

type=inline

Incrusta los metadatos de caché en la imagen que sube, de modo que cache-from puede usar la propia imagen:

cache-from: type=registry,ref=ghcr.io/org/app:latest
cache-to: type=inline

Es la opción más sencilla y no necesita una etiqueta adicional. La contrapartida: solo se admite mode=min, así que las etapas intermedias de una compilación de varias etapas no se almacenan en caché. Adecuado para un Dockerfile de una sola etapa, pero débil para varias etapas.

type=local

Escribe la caché en un directorio, que se guarda con actions/cache:

- uses: actions/cache@v6
  with:
    path: /tmp/.buildx-cache
    key: buildx-${{ runner.os }}-${{ github.sha }}
    restore-keys: |
      buildx-${{ runner.os }}-
- uses: docker/build-push-action@v7
  with:
    context: .
    cache-from: type=local,src=/tmp/.buildx-cache
    cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max

Es el patrón heredado. Nunca se reduce por sí solo, porque cada exportación añade datos al directorio, así que se suele añadir un paso que mueve -new sobre el directorio antiguo. type=gha lo sustituye en la mayoría de los casos. Use local si necesita una caché que controle por completo con las claves de actions/cache.

¿Qué backend elegir?

NecesidadUsar
Imágenes sencillas de tamaño pequeño a medianotype=gha,mode=max con un scope
Caché grande, compartida con portátiles, o no alojada en la caché de GitHubtype=registry,mode=max
Dockerfile de una sola etapa, configuración mínimatype=inline
Control total mediante actions/cachetype=local

Cache mounts y por qué se pierden en runners nuevos

RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt proporciona a un paso de compilación un directorio persistente, de modo que pip no vuelve a descargar todo cuando se reejecuta la capa. Es una función excelente en su portátil o en un builder de larga duración.

En los runners alojados en GitHub, por defecto, no le aporta nada. Un cache mount reside en el estado local de BuildKit en el builder, no en la caché de capas que exporta cache-to. Un runner nuevo implica un BuildKit nuevo, así que el mount está vacío en cada job. type=gha y type=registry exportan capas, no mounts.

Opciones si depende de los cache mounts:

  1. Considérelos solo como una optimización local y confíe en la caché de capas en CI.
  2. Persista usted mismo el directorio del mount. Existen herramientas de terceros, como la acción reproducible-containers/buildkit-cache-dance, que guardan y restauran el contenido de los cache mounts mediante actions/cache. Evalúelas según sus necesidades de seguridad antes de adoptarlas.
  3. Use un builder persistente. Los servicios de compilación dedicados mantienen el estado de BuildKit entre ejecuciones. Depot lo hace para las compilaciones de Docker; consulte la comparativa con Depot. Un runner autoalojado con disco persistente también puede funcionar.

Consiga que la caché acierte

  1. Ordene el Dockerfile de modo que las capas de dependencias vayan primero (consulte compilaciones lentas de Docker).
  2. Mantenga .dockerignore bien ajustado.
  3. Use --progress=plain o el resumen de la compilación para buscar líneas CACHED.
  4. Compile en main para que las ramas tengan una base de la que leer.

compiler.dev mantiene una caché de capas de Docker en la máquina entre jobs, de modo que un docker build normal puede reutilizar capas sin exportarlas. Cambie a ella con runs-on: [self-hosted, Linux, compiler-ci]; consulte los precios.

Preguntas frecuentes

¿Debo usar mode=max o mode=min?

max para compilaciones de varias etapas, ya que almacena en caché las etapas intermedias. min es más pequeño y adecuado para imágenes de una sola etapa.

¿Por qué dos imágenes sobrescriben la caché de la otra?

Comparten el scope por defecto buildkit. Asigne a cada una un scope único.

¿Puedo usar type=gha en runners autoalojados?

Depende de si el runner puede acceder al servicio de caché de GitHub. Pruébelo con una compilación pequeña o use una caché de registro.

¿La caché gha cuenta para mi límite de 10 GB?

Sí. Se almacena en la misma caché de Actions.

¿Necesito setup-buildx-action?

Para type=gha y la mayoría de los backends, sí. El driver por defecto no los admite sin el image store de containerd.

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

Pruébelo gratis