Límite de tamaño de la caché de GitHub Actions: por qué tu caché se elimina, tarda en restaurarse o falla
GitHub Actions le da a cada repositorio 10 GB de caché. Cuando el repositorio pasa de ahí, GitHub guarda igualmente la entrada nueva y elimina las entradas leídas hace más tiempo hasta volver a estar por debajo del límite, y elimina cualquier entrada que ningún trabajo leyó en 7 días. Una rama solo lee sus propias cachés y las de la rama predeterminada, así que la primera ejecución de una rama nueva a menudo falla. Y un acierto sigue siendo una descarga: cada trabajo en un ejecutor hospedado en GitHub empieza en una VM nueva, así que vuelve a descargar y descomprimir el archivo. Puedes subir el límite, a US$ 0,07 por GB al mes por encima de 10 GB, y ajustar tus claves, pero la descarga se queda.
Skipbox elimina la descarga. Tus trabajos se ejecutan en la máquina dedicada de tu cuenta, que se mantiene entre trabajos, así que las cachés de npm, pnpm, Gradle, Go y Cargo y las capas de Docker siguen en su disco desde el último trabajo (80 GB en S, frente a 14 GB en el ejecutor de GitHub). Lo que guarda actions/cache se queda junto a la máquina, así que restaurar es una lectura local. Cambia una línea, runs-on: skipbox, por $39 fijos al mes con minutos ilimitados.
Las reglas de la caché de GitHub
Según la referencia de caché de dependencias de GitHub, la facturación de Actions y su changelog sobre las cachés de más de 10 GB:
| Regla | Lo que hace GitHub |
|---|---|
| Tamaño | 10 GB por repositorio de forma predeterminada, compartidos por todas las ramas y todos los flujos de trabajo |
| Por encima del tamaño | Guarda la entrada nueva y luego elimina entradas por último acceso, empezando por la más antigua, hasta que el repositorio queda por debajo del límite. La eliminación se ejecuta cada hora |
| Entradas sin usar | Elimina cualquier entrada que no se leyó en más de 7 días |
| Un límite mayor | En una cuenta Pro, Team o Enterprise, los administradores pueden subir el tamaño y los días. Por encima de 10 GB, US$ 0,07 por GB al mes, según el pico de cada hora. Si se alcanza un presupuesto, la caché pasa a ser de solo lectura hasta el siguiente ciclo de facturación |
| Ramas | Una ejecución restaura cachés de su rama y de la rama predeterminada; la de un pull request, también de su rama base. Nunca de una rama hermana o hija |
| Pull requests | Las cachés de un pull request se limitan a su merge ref: solo las nuevas ejecuciones de ese pull request las leen |
| Entradas | No se pueden cambiar. Una clave que ya existe no se vuelve a guardar |
| Aciertos | cache-hit es true solo con una coincidencia exacta de key; una coincidencia de restore-keys es false |
| Frecuencia | Hasta 200 subidas y 1.500 descargas por minuto y repositorio |
Por qué se elimina la caché
Unos mismos 10 GB guardan todo lo que guarda el repositorio. Cada rama y cada pull request guarda sus propias entradas. Una matriz de tres versiones de Node en dos sistemas operativos guarda seis. La caché de compilación type=gha de Docker cae en los mismos 10 GB. Cuando lo que se guarda en un día suma más que el límite, cada guardado nuevo elimina una entrada más antigua, a menudo la que necesita el siguiente trabajo. GitHub lo llama cache thrashing.
Para ver qué la llena, lista las entradas por tamaño:
gh cache list --sort size_in_bytes --limit 20
La página Actions › Caches del repositorio muestra lo mismo, con la rama y el último uso de cada entrada.
Por qué la restauración es lenta
Un acierto de caché en un ejecutor hospedado en GitHub es una descarga a una VM nueva, y luego una descompresión. Su tiempo crece con el archivo, así que una caché que creció hasta varios GB puede tardar tanto como la instalación que debía ahorrarte. Una descarga atascada la corta el tiempo de espera por segmento de actions/cache, 10 minutos de forma predeterminada (SEGMENT_DOWNLOAD_TIMEOUT_MINS).
La mayoría de las configuraciones también restauran menos de lo que se cree. La entrada cache: de setup-node guarda la caché de descargas del gestor de paquetes, no node_modules: después de restaurarla, npm ci sigue instalando cada paquete. La caché de pip de setup-python es igual: vuelven las descargas, y el entorno se instala otra vez.
Por qué falla la caché
- Cambió la clave. Una clave con
hashFiles('**/package-lock.json')falla con cada cambio del lockfile.restore-keysda una coincidencia parcial, y entoncescache-hitvalefalse. - Una rama nueva. Puede leer las cachés de la rama predeterminada, no las de otra rama de funcionalidad. Si la rama predeterminada nunca ejecutó el flujo de trabajo, no hay nada que leer.
- Se eliminó. Se la llevó el límite o los 7 días.
- Nunca se guardó. Las entradas no se pueden cambiar, así que una clave que existe nunca se vuelve a guardar, y el contenido en caché se queda tan viejo como su primer guardado. Puede que a un pull request desde un fork no se le permita guardar en absoluto.
Pasar archivos al siguiente trabajo de la misma ejecución es otra herramienta. La caché es para la siguiente ejecución; la salida de compilación que necesita un trabajo posterior del mismo flujo de trabajo pasa por actions/upload-artifact y actions/download-artifact. Los artefactos tienen su propio almacenamiento, aparte de los 10 GB, y también son una descarga a una VM nueva.
Lo que cuesta cada solución en los ejecutores de GitHub
- Subir el límite. Menos eliminaciones, a US$ 0,07 por GB al mes por encima de 10 GB (el ejemplo de GitHub: 200 GB usados por completo son US$ 13,30 al mes), en una cuenta Pro, Team o Enterprise. Las restauraciones siguen siendo descargas, y las cachés más grandes tardan más en descargarse.
- Guardar menos. Guarda en caché
~/.npmo el store de pnpm, nonode_modulesni la salida de compilación. Guarda solo en la rama predeterminada, conactions/cache/restoreen cada trabajo yactions/cache/saveen uno. Cuesta tu tiempo, y una caché más pequeña restaura menos. - Arreglar las claves. Basa la clave en el lockfile, agrega
restore-keysy ejecuta el flujo de trabajo en los push a la rama predeterminada para que las ramas nuevas tengan algo que leer. - Un ejecutor autohospedado que conserve su disco. Sin descarga, sin 10 GB. Tú mantienes la máquina: actualizaciones del sistema operativo, limpieza entre trabajos sin borrar las cachés, y arreglarla cuando se rompe.
Cuando la solución es una máquina que conserva su disco
La caché existe porque la máquina olvida. Un ejecutor hospedado en GitHub es una VM nueva para cada trabajo, así que el trabajo guarda su estado en el almacenamiento de GitHub y lo vuelve a traer la próxima vez. En una máquina que se queda, ese estado ya está en su disco: la caché del gestor de paquetes, la caché de herramientas, las imágenes y la caché de compilación de Docker, incluso la salida de compilación.
La diferencia se ve en la CI de proyectos reales, en nuestras ejecuciones de sus propios trabajos:
- astro (Node.js, Turborepo): 528 s en GitHub, 30 s en una máquina dedicada de Skipbox, que conserva la caché de turbo, así que sus ejecuciones en caliente reproducen 40 tareas de compilación en lugar de ejecutarlas.
- helix (Rust): el paso de la cadena de herramientas y la caché tardó 9-10 s en la máquina dedicada, frente a 41-46 s en GitHub.
- tauri (Rust): 246 s en GitHub, 53 s en la máquina dedicada, con
target/conservado entre trabajos.
Skipbox conserva la caché en tu máquina
Cada plan trae la máquina dedicada de tu cuenta, que se mantiene entre trabajos:
- Las cachés de paquetes se quedan en el disco:
~/.npm, el store de pnpm, el~/.cachede cada herramienta, y las cachés de Go, Gradle, Cargo y Maven, con las herramientas que instalósetup-*. Nada que restaurar. - Las imágenes, las capas y la caché de compilación de Docker también se quedan.
docker buildreutiliza las capas de la última compilación (caché de capas de Docker). - **actions/cache, setup-* y rust-cache no necesitan cambios.** Lo que guardan se queda junto a la máquina en lugar de en el almacenamiento de GitHub, con más espacio que los 10 GB por repositorio de GitHub, y una restauración lo lee en local.
- Sin caducidad a los 7 días en el disco. No se borra nada hasta que el disco está casi lleno después de un trabajo; entonces se va primero lo que se usó hace más tiempo.
Al menos 7× el espacio de caché de GitHub en S. 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 |
El ubuntu-latest de un repositorio privado tiene 2 CPU, 8 GB y 14 GB de SSD. En Skipbox 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
jobs:
test:
runs-on: skipbox # was ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci && npm test
- Inicia sesión en Skipbox con GitHub.
- Instala la app de GitHub de Skipbox y elige los repositorios.
- Cambia
runs-ony haz push.
Deja tus pasos de caché como están. La segunda ejecución encuentra en la máquina las cachés de la primera.
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. “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 VM nueva que lee tus cachés pero no puede cambiarlas.
Los detalles están en cómo se aíslan los trabajos.
Pruébalo con el trabajo cuya caché falla
La prueba es gratuita durante 7 días o 3000 minutos de trabajos, lo que ocurra primero, y no pide tarjeta. Pasa ese trabajo a runs-on: skipbox, ejecútalo dos veces y pon los pasos de restauración e instalación de la segunda ejecución junto a los de GitHub.
Preguntas frecuentes
¿Cuál es el límite de tamaño de la caché de GitHub Actions?
10 GB por repositorio de forma predeterminada, para todas las ramas y todos los flujos de trabajo juntos. Pasado ese límite, GitHub guarda igualmente la entrada nueva y elimina entradas por orden de último acceso, empezando por la más antigua, hasta que el repositorio vuelve a estar por debajo del límite. Las entradas que ningún trabajo leyó en 7 días se eliminan sea cual sea el tamaño. En una cuenta Pro, Team o Enterprise, los administradores pueden subir el límite y los días; el almacenamiento por encima de 10 GB se cobra a US$ 0,07 por GB al mes, medido por el pico de cada hora, y cuando se alcanza un presupuesto la caché pasa a ser de solo lectura hasta el siguiente ciclo de facturación.
¿Por qué mi caché de GitHub Actions se elimina tan a menudo?
Porque todo el repositorio comparte unos mismos 10 GB: cada rama, cada pull request, cada trabajo de la matriz y cada sistema operativo guarda sus propias entradas, y la caché type=gha de Docker cae en el mismo sitio. Cuando lo que se guarda en un día suma más que el límite, cada guardado elimina una entrada más antigua, y el siguiente trabajo no encuentra la que necesitaba. GitHub lo llama cache thrashing. Lista las entradas por tamaño (gh cache list --sort size_in_bytes) para ver qué la llena.
¿Por qué restaurar la caché tarda tanto como instalar desde cero?
Porque un acierto sigue siendo una descarga. Cada trabajo en un ejecutor hospedado en GitHub empieza en una VM nueva, así que actions/cache descarga el archivo y lo descomprime cada vez, y cuanto más grande es la caché, más tarda. La caché de setup-node trae de vuelta la caché de descargas del gestor de paquetes, no node_modules, así que npm ci sigue instalando cada paquete después de restaurarla. En un ejecutor que conserva su disco, las cachés ya están ahí y no se descarga nada.
¿Por qué actions/cache falla en una rama nueva?
Una ejecución puede restaurar cachés de su propia rama y de la rama predeterminada, y la ejecución de un pull request también de su rama base. No puede leer las cachés de una rama hermana. Así que la primera ejecución de una rama de funcionalidad solo acierta si la rama predeterminada guardó esa clave. Ejecuta el flujo de trabajo en los push a la rama predeterminada para que guarde, y agrega restore-keys para una coincidencia parcial; cache-hit solo es true con una coincidencia exacta de key.
¿Cuánta caché de Actions guarda Skipbox?
Más que los 10 GB por repositorio de GitHub, junto a tu máquina en lugar de en el almacenamiento de GitHub. En una máquina en la nube, lo que los trabajos guardan con actions/cache, setup-* y rust-cache se queda en el propio disco de la máquina, hasta la mitad de ese disco (80 GB en S, 160 GB en M, 320 GB en L); en un host de Skipbox, la caché del host guarda 20 GB por repositorio. En los dos casos, una entrada se conserva 7 días después de su último uso, con las reglas de ramas de GitHub. Las cachés de paquetes y las capas de Docker no pasan por ahí: se quedan en el propio disco.
¿Qué borra las cachés de una máquina de Skipbox?
Nada entre trabajos: las cachés se quedan en la máquina, y solo cuando un trabajo deja el disco casi lleno se va primero lo que se usó hace más tiempo. La máquina empieza limpia con un restablecimiento: cuando pulsas “Restablecer la máquina”, cuando se actualiza su imagen (al menos una vez al mes), cuando falla su comprobación de estado después de un trabajo y cuando un trabajo llega al límite de 6 horas. La máquina se elimina con su disco cuando termina el plan.
¿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 el trabajo cuya caché falla o tarda en restaurarse a runs-on: skipbox, ejecútalo dos veces y compara los pasos de restauración e instalación de la segunda ejecución con los de GitHub.
Actualizado el 19 de noviembre de 2026