Saltar al contenido

Límite, tamaño y expulsión de la caché de GitHub Actions

Última actualización

El límite de caché de GitHub Actions sorprende a muchos equipos: cada repositorio dispone de 10 GB por defecto y, cuando se llena, GitHub expulsa las cachés más antiguas, lo que puede volver a ralentizar sus builds sin un motivo aparente. Esta guía trata sobre los límites, la expulsión, el tamaño de caché y los detalles de pnpm y Docker. Para los conceptos básicos de actions/cache, lea primero la guía de caché; esta continúa donde termina aquella. Las cifras que aparecen a continuación proceden de la documentación de GitHub sobre caché de dependencias, revisada el 11/10/2026.

Cuáles son los límites

  • Tamaño total por repositorio: 10 GB por defecto entre todas las cachés. Los propietarios y administradores pueden aumentarlo, y el almacenamiento por encima de 10 GB se factura.
  • Retención: una entrada de caché que no se ha usado durante 7 días se elimina.
  • Expulsión: cuando el repositorio supera su límite, GitHub guarda igualmente la nueva caché y después expulsa cachés (primero las usadas menos recientemente) hasta que el total queda por debajo del límite.
  • Número de cachés: no hay límite en cuanto al número, solo en cuanto al tamaño total.

El uso de caché es visible en la página Actions, Caches del repositorio, y también con la CLI: gh cache list --sort size_in_bytes.

Por qué la expulsión ralentiza la CI

La expulsión puede provocar thrashing de caché: cada ejecución guarda una caché nueva, que expulsa otra, y esta falla en la siguiente ejecución. Síntomas: "Cache not found for input keys" en los registros de ramas que se ejecutaron hace poco, o una tasa de aciertos que baja a medida que crece el equipo.

Causas habituales:

  1. Una clave nueva por commit. Claves como ${{ github.sha }} crean una caché por cada push. Llenan 10 GB rápidamente y nunca se reutilizan.
  2. Cachés grandes duplicadas por SO o celda de matriz. 6 celdas de matriz por 700 MB son 4.2 GB.
  3. Cachear node_modules o directorios de build que cambian con cada edición del lockfile, de modo que cada cambio añade otra copia completa.
  4. Alcance por rama. Un workflow puede restaurar cachés creadas en la rama actual, en la rama base o en la rama por defecto, pero no en ramas hermanas. Las cachés de las pull requests se crean para la referencia de fusión, así que una caché creada en una PR no es visible desde otra PR. Caliente la rama por defecto para que todos puedan restaurar desde ella, por ejemplo mediante un job programado (véanse los cron schedules).

Soluciones

Claves que aciertan

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-${{ runner.os }}-${{ hashFiles('**/requirements*.txt') }}
    restore-keys: |
      pip-${{ runner.os }}-

Use como clave el lockfile, no el commit. restore-keys permite que una coincidencia parcial restaure la caché similar más reciente, y después se guarda una nueva con la clave exacta. El generador de claves de caché las crea.

Guarde menos y guarde una sola vez

  • Cachee la caché de descargas del gestor de paquetes, no el árbol instalado, cuando sea posible. Es más pequeña y reutilizable entre versiones de Node o Python.
  • Use actions/cache/restore en la mayoría de los jobs y actions/cache/save en un único job (por ejemplo, en los push a main), de modo que las ejecuciones de PR solo lean y no escriban nuevas entradas cada una.
  • Elimine las cachés obsoletas al cerrar una PR con gh cache delete para liberar espacio para la rama por defecto.
- uses: actions/cache/restore@v4
  with: { path: ~/.cache/pip, key: pip-${{ hashFiles('requirements.txt') }} }

Compruebe el tamaño de la caché antes de guardar

Las entradas grandes tardan más en guardarse y restaurarse. Si restaurar tarda más que la instalación que reemplaza, elimine la caché. Una restauración de 1.5 GB por la red puede tardar más que una instalación rápida de paquetes, un motivo habitual de "caché lenta en GitHub Actions".

Notas sobre la caché v4

actions/cache@v4 usa el servicio de caché más reciente de GitHub, y GitHub ha dejado obsoletas las versiones antiguas de la acción que usaban el backend de caché heredado, por lo que las versiones fijadas antiguas pueden fallar. Si su workflow usa alguna, actualice a @v4. v4 también expone cache-hit como salida: true solo con una coincidencia exacta de clave, lo que le permite omitir pasos como npm ci cuando cachea node_modules. Consulte el README de la acción para ver las entradas actuales.

Detalles de pnpm

pnpm mantiene un único almacén direccionado por contenido y enlaza los archivos mediante hard links en node_modules. Cachee el almacén, no node_modules:

- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: pnpm
- run: pnpm install --frozen-lockfile

setup-node con cache: pnpm cachea el almacén indexado por pnpm-lock.yaml. Si cachea manualmente, obtenga la ruta con pnpm store path. Restaurar el almacén y ejecutar pnpm install --frozen-lockfile --prefer-offline suele ser rápido, porque solo enlaza archivos. En un monorepo, un único lockfile significa una sola clave, lo que mantiene bajo el número de cachés.

Caché de imágenes Docker

Cachear capas de Docker con actions/cache puede ocupar muchos gigabytes y alcanzar el tope de 10 GB. Opciones:

  • La caché type=gha en Buildx guarda las capas en el mismo servicio de caché y cuenta contra el mismo límite. Use mode=min para guardar solo las capas de la imagen final, en lugar de mode=max, si el tamaño es un problema.
  • Una caché de registro (type=registry) guarda las capas en su registro de contenedores, fuera del límite de 10 GB.
  • Ordene el Dockerfile para que las capas de dependencias vayan antes de copiar el código fuente, de modo que las capas costosas rara vez cambien.
- uses: docker/build-push-action@v6
  with:
    cache-from: type=gha
    cache-to: type=gha,mode=min

Más opciones en Caché de capas Docker en CI.

¿El almacenamiento de caché tiene coste?

Dentro del límite por defecto, no hay cargo adicional. Aumentar el límite por encima de 10 GB factura el almacenamiento adicional utilizado. Consulte Precios de GitHub Actions explicados para ver el resto de conceptos de facturación y la calculadora de coste.

Cuándo la caché no es la solución

Si las cachés son grandes y las restauraciones lentas, un runner con disco persistente local o una red más rápida puede ayudar más que ajustar las claves. Compárelos en runners más rápidos para GitHub Actions. Más soluciones en la guía para acelerar la CI y el centro de CI lenta.

Preguntas frecuentes

¿Cuál es el límite de tamaño de caché de GitHub Actions?

10 GB por repositorio de forma predeterminada, sumando todas las cachés. Los administradores pueden aumentarlo, y el uso por encima de 10 GB se factura.

¿Cuánto tiempo guarda GitHub una caché?

Las entradas a las que no se ha accedido durante 7 días se eliminan. Las entradas también se desalojan cuando el repositorio supera su límite de tamaño.

¿Por qué no se restaura mi caché de GitHub Actions?

Compruebe que la clave coincide, que la caché se creó en una rama a la que puede acceder, que no fue desalojada y que está usando actions/cache@v4.

¿Debo almacenar en caché pnpm node_modules?

Almacene en caché el store de pnpm, usando setup-node con cache: pnpm.

Ejecute este workflow en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis