# Caché de capas de Docker en GitHub Actions: por qué cada compilación empieza en frío y cómo conservar las capas

> Cada trabajo de GitHub Actions empieza en una VM nueva sin caché de compilación de Docker ni imágenes descargadas, y el builder predeterminado de setup-buildx-action empieza vacío. El cache-to y el cache-from de buildx (gha, registry, local) devuelven las capas como descargas, dentro de los 10 GB de GitHub. Un ejecutor que conserva la caché de compilación de Docker en su disco no necesita nada de eso, por $39 fijos al mes.

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.

- GitHub: una VM nueva por trabajo, así que sin capas, sin imágenes y con un builder de buildx vacío en cada ejecución
- Skipbox: la caché de compilación y las imágenes de Docker se quedan en el disco de tu máquina, así que las capas que no cambiaron no se reconstruyen ni se descargan
- 20.000 minutos al mes en 4 vCPU: $222 en GitHub, $39 en Skipbox

**GitHub Actions a precio fijo, minutos ilimitados** Skipbox ejecuta tus trabajos de GitHub Actions en tu propia máquina dedicada: $39 al mes, ejecutes los minutos que ejecutes. Las capas de Docker y las cachés de dependencias se conservan entre trabajos, así que el siguiente trabajo empieza enseguida.

Un ejecutor de 4 vCPU, 20.000 minutos al mes: GitHub $222 → Skipbox $39. Ahorras $183 cada mes.

Pasarte lleva una sola línea: `runs-on: skipbox`.

[Empezar mi prueba gratuita de 7 días](https://app.skipbox.dev/sign-in?ref=g-docker-layer-cache-github-actions-es)

## Por qué cada compilación empieza en frío

- **Una VM nueva por trabajo.** La [referencia de ejecutores](https://docs.github.com/en/actions/reference/runners/github-hosted-runners) 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](https://github.com/docker/setup-buildx-action) crea e inicia de forma predeterminada un builder con el driver `docker-container`, y su `cleanup` (activado de forma predeterminada) elimina el builder al final del trabajo.
- **14 GB de disco.** El `ubuntu-latest` de 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é](https://docs.docker.com/build/cache/backends/) de Docker y su [gestión de la caché con GitHub Actions](https://docs.docker.com/build/ci/github-actions/cache/):

| 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`](https://docs.docker.com/build/cache/backends/local/) (Buildx 0.35.0 o posterior); cuenta en los 10 GB |

Elijas el backend que elijas, [ordena el Dockerfile](https://docs.docker.com/build/cache/optimize/) 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:

```yaml
- 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](https://github.com/reproducible-containers/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 con `docker load` en 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 build` y `docker compose build`** reutilizan las capas de la última compilación, sin cambiar el flujo de trabajo.
- **Las imágenes se quedan en el disco.** `docker compose up` encuentra las imágenes que descargó la última vez; `docker compose pull` solo trae las capas que cambiaron.
- **Los cache mounts se quedan** con la caché de compilación de Docker, así que `RUN --mount=type=cache` conserva 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-from` y `cache-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.

```yaml
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

1. Inicia sesión en Skipbox con GitHub.
2. Instala la app de GitHub de Skipbox y elige los repositorios.
3. Cambia `runs-on` y 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](https://docs.skipbox.dev/es/isolation).

## 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 2026-11-19 · https://skipbox.dev/es/guides/docker-layer-cache-github-actions
