Caché de capas de Docker en GitHub Actions: por qué cada compilación empieza en frío y cómo conservar las capas
La caché de capas de Docker se pierde en cada ejecución de GitHub Actions porque cada trabajo en un ejecutor hospedado en GitHub empieza en una VM nueva: sin caché de compilación, sin imágenes descargadas. El builder predeterminado de docker/setup-buildx-action (docker-container) también empieza vacío en cada trabajo y se elimina al terminar. La solución habitual es exportar la caché con buildx. cache-to: type=gha,mode=max y cache-from: type=gha guardan las capas en la caché de Actions de GitHub, 10 GB por repositorio y compartidos con todas las demás cachés; type=registry las guarda en tu registro; type=local, en un directorio que guardas con actions/cache. Cada una convierte una reconstrucción en una subida y una descarga en cada ejecución.
Skipbox conserva las capas donde se ejecuta la compilación. Tus trabajos se ejecutan en la máquina dedicada de tu cuenta, que conserva las imágenes, las capas y la caché de compilación de Docker entre trabajos, en un disco de 80 GB en S frente a 14 GB en el ejecutor de GitHub. docker build y docker compose build reutilizan las capas de la última compilación, y las imágenes que descargó compose ya están en el disco. setup-buildx-action funciona tal como está, y su builder también encuentra esas capas. Cambia una línea, runs-on: skipbox, por $39 fijos al mes con minutos ilimitados.
Por qué cada compilación empieza en frío
- Una VM nueva por trabajo. La referencia de ejecutores de GitHub: cada ejecutor hospedado en GitHub es una máquina virtual (VM) nueva hospedada por GitHub (“each GitHub-hosted runner is a new virtual machine (VM) hosted by GitHub.”). Nada de lo que compiló o descargó el último trabajo está en ella.
- Un builder vacío. docker/setup-buildx-action crea e inicia de forma predeterminada un builder con el driver
docker-container, y sucleanup(activado de forma predeterminada) elimina el builder al final del trabajo. - 14 GB de disco. El
ubuntu-latestde un repositorio privado tiene 2 CPU, 8 GB y 14 GB de SSD. Una imagen grande, su caché de compilación y un archivo de caché que descomprimir pueden quedarse sin espacio ("no space left on device").
Los backends de caché de buildx y lo que cuesta cada uno
Según los backends de caché de Docker y su gestión de la caché con GitHub Actions:
| Backend | Adónde van las capas | Lo que paga cada ejecución | Límites |
|---|---|---|---|
type=gha | La caché de Actions de GitHub | Sube las capas nuevas y descarga las que necesita | 10 GB por repositorio con todas las demás cachés, eliminando primero las más antiguas; cada compilación sobrescribe el scope predeterminado buildkit; la API de caché de GitHub limita la frecuencia |
type=registry | Una imagen de caché aparte en tu registro | Descarga la caché del registro y sube la nueva | Un inicio de sesión en el registro con permiso de push; el almacenamiento y el tráfico del registro |
type=inline | Dentro de la propia imagen | Descarga la imagen para leer su caché | Solo mode=min: las capas de las etapas intermedias no se conservan |
type=local + actions/cache | Un directorio guardado con actions/cache | Descarga y descomprime el directorio entero, y luego lo sube | Crece con cada ejecución salvo que uses reset=true (Buildx 0.35.0 o posterior); cuenta en los 10 GB |
Elijas el backend que elijas, ordena el Dockerfile para que las capas que menos cambian vayan primero: copia el lockfile e instala las dependencias antes de copiar el código. Si no, cada commit invalida la capa de instalación, y ninguna caché la recupera.
mode=min, el predeterminado, conserva solo las capas de la imagen final. mode=max conserva las capas de todas las etapas, así que una compilación de varias etapas acierta más, y sube más.
Una configuración típica de type=gha, con su propio scope por imagen:
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
with:
context: .
tags: app:ci
load: true
cache-from: type=gha,scope=app
cache-to: type=gha,scope=app,mode=max
Los cache mounts no sobreviven. RUN --mount=type=cache (la caché de un gestor de paquetes dentro de la compilación) no se guarda en la caché de GitHub Actions de forma predeterminada; la documentación de Docker remite a buildkit-cache-dance para meterla y sacarla de actions/cache, una descarga y una subida más en cada ejecución.
docker compose descarga todas las imágenes en cada trabajo
Las pruebas de integración que inician Postgres, Redis y algunos servicios con docker compose up descargan todas las imágenes en cada trabajo, porque la VM es nueva. En los ejecutores hospedados en GitHub, las opciones solo mueven la descarga:
- Guarda las imágenes en un archivo tar con
docker save, guárdalo en caché con actions/cache y cárgalo condocker loaden el siguiente trabajo. Cuenta en los 10 GB, y la carga lleva su propio tiempo. - Compila las imágenes de los servicios con buildx y uno de los backends de caché de arriba, lo que sigue dejando por descargar las imágenes base.
Cuando la solución es una máquina que conserva la caché de Docker
Cada backend de arriba existe porque el builder olvida. Un daemon de Docker que se mantiene entre trabajos ya tiene las capas de la última compilación, sus cache mounts y cada imagen que descargó, en su propio disco. No hay nada que exportar, nada que importar y ningunos 10 GB que compartir.
Skipbox conserva la caché de Docker en tu máquina
Cada plan trae la máquina dedicada de tu cuenta, que se mantiene entre trabajos:
docker buildydocker compose buildreutilizan las capas de la última compilación, sin cambiar el flujo de trabajo.- Las imágenes se quedan en el disco.
docker compose upencuentra las imágenes que descargó la última vez;docker compose pullsolo trae las capas que cambiaron. - Los cache mounts se quedan con la caché de compilación de Docker, así que
RUN --mount=type=cacheconserva la caché del gestor de paquetes sin ningún paso extra. - docker/setup-buildx-action funciona tal como está. Su builder arranca con las capas que dejó en la máquina la última compilación de tu repositorio, y puedes quitar
cache-fromycache-to. En nuestra propia ejecución de la CI de un proyecto público en una máquina de 4 vCPU (19 de noviembre de 2026, una ejecución cada vez), el paso que compila la imagen tardó 177 s en la primera ejecución y 4 s en la repetición, con 31 pasos CACHED. - Disco: no se borra nada hasta que el disco está casi lleno después de un trabajo. Entonces se van primero las imágenes colgantes y luego la caché de compilación usada hace más tiempo.
jobs:
build:
runs-on: skipbox # was ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
with:
context: .
tags: app:ci
load: true
Cada trabajo elige su tamaño con la etiqueta:
| Etiqueta | Máquina | Disco | Plan |
|---|---|---|---|
skipbox | 4 vCPU · 16 GB | 80 GB | S, $39 al mes |
skipbox-8x16 | 8 vCPU · 16 GB | 160 GB | M, $79 al mes |
skipbox-16x32 | 16 vCPU · 32 GB | 320 GB | L, $149 al mes |
Los minutos son ilimitados. Con 20.000 minutos al mes en 4 vCPU, GitHub cobra $222; Skipbox S cuesta $39, $183 menos.
Pasarte es una línea
- Inicia sesión en Skipbox con GitHub.
- Instala la app de GitHub de Skipbox y elige los repositorios.
- Cambia
runs-ony haz push.
El primer trabajo compila todas las capas. El segundo las encuentra en la máquina.
Seguridad
- La máquina es solo de tu cuenta. Ningún trabajo de otra empresa se ejecuta en ella.
- Después de cada trabajo se borran las credenciales, los procesos y los contenedores del ejecutor, y también
~/.docker/config.json, así que un inicio de sesión en el registro no pasa al siguiente trabajo. “VM nueva en cada trabajo” le da a cada trabajo una máquina nueva en su lugar. - El código de personas sin acceso de escritura (como los pull requests desde forks) se ejecuta en una máquina nueva y desechable, nunca en la tuya.
Los detalles están en cómo se aíslan los trabajos.
Pruébalo con tu compilación de Docker
La prueba es gratuita durante 7 días o 3000 minutos de trabajos, lo que ocurra primero, y no pide tarjeta. Pasa tu compilación de Docker a runs-on: skipbox, ejecútala dos veces y pon el paso de compilación de la segunda ejecución junto al de GitHub.
Preguntas frecuentes
¿Por qué se pierde la caché de capas de Docker en cada ejecución de GitHub Actions?
Porque cada trabajo en un ejecutor hospedado en GitHub empieza en una VM nueva, sin caché de compilación ni imágenes de la última ejecución. docker/setup-buildx-action suma a eso: de forma predeterminada crea un builder docker-container que empieza vacío y se elimina al final del trabajo. Así que cada capa se reconstruye, salvo que exportes la caché con cache-to y la importes con cache-from, o que ejecutes en una máquina que conserve la caché de compilación de Docker.
¿Cómo guardo en caché las capas de Docker en GitHub Actions?
En los ejecutores hospedados en GitHub, con los exportadores de caché de buildx: cache-from: type=gha y cache-to: type=gha,mode=max en docker/build-push-action guardan las capas en la caché de Actions de GitHub (10 GB por repositorio, compartidos con todas las demás cachés). type=registry las guarda como una imagen aparte en tu registro, y type=local en un directorio que guardas con actions/cache. Dale a cada imagen su propio scope con type=gha, porque cada compilación sobrescribe el scope predeterminado. En una máquina que conserva su disco, docker build reutiliza las capas sin ningún exportador.
¿Por qué buildx con cache-to type=gha sigue siendo lento?
Porque las capas siguen viajando. Con mode=max, cada ejecución sube cada capa nueva de cada etapa, y una ejecución posterior descarga las capas que necesita. La caché comparte los 10 GB por repositorio de GitHub con todo lo demás, así que se elimina, y la API de caché de GitHub limita la frecuencia de una compilación que hace demasiadas solicitudes. Un builder que ya tiene las capas en su disco se salta las dos direcciones.
¿Cómo evito que docker compose descargue las mismas imágenes en cada trabajo?
En un ejecutor hospedado en GitHub no puedes; solo puedes mover la descarga: guarda las imágenes en un archivo tar con docker save, guárdalo en caché con actions/cache y cárgalo con docker load en el siguiente trabajo. Eso cuenta en los mismos 10 GB y es una descarga y una carga en cada ejecución. En una máquina que conserva su disco, las imágenes que compose descargó la última vez ya están ahí, y docker compose pull solo trae las capas que cambiaron.
¿Tengo que cambiar mi flujo de trabajo para conservar la caché de Docker en Skipbox?
Solo runs-on: la máquina de tu cuenta conserva las imágenes, las capas y la caché de compilación de Docker entre trabajos. docker build y docker compose build las reutilizan, y docker/setup-buildx-action funciona tal como está: su builder arranca con las capas que dejó en la máquina la última compilación de tu repositorio. Puedes quitar cache-from y cache-to.
¿Cuánto cuesta probarlo?
Nada. La prueba dura 7 días o 3000 minutos de trabajos, lo que ocurra primero, y no pide tarjeta. Pasa tu compilación de Docker a runs-on: skipbox, ejecútala dos veces y compara el paso de compilación de la segunda ejecución con el de GitHub.
Actualizado el 19 de noviembre de 2026