Saltar al contenido

Caché en GitHub Actions: claves, límites y ejemplos

Última actualización

Una buena caché convierte una instalación de dependencias de tres minutos en diez segundos. Una mala no ahorra nada o, peor aún, restaura archivos obsoletos que rompen su build. Esta guía explica cómo la caché de GitHub Actions elige qué restaurar, cómo escribir las claves y qué límites debe tener en cuenta.

Las dos formas de usar la caché

Caché integrada en las acciones de setup. Para los ecosistemas más comunes, basta con una línea:

- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: pnpm          # npm, yarn or pnpm
- uses: actions/setup-python@v5
  with:
    python-version: "3.13"
    cache: pip
- uses: actions/setup-go@v5
  with:
    go-version-file: go.mod

Estas acciones almacenan en caché el directorio de descargas del gestor de paquetes, usando el lockfile como clave. setup-go activa la caché por defecto. Úselas cuando se ajusten a su caso: no hay nada que mantener.

actions/cache para todo lo demás. Usted elige la ruta y la clave:

- uses: actions/cache@v4
  with:
    path: |
      ~/.gradle/caches
      ~/.gradle/wrapper
    key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
    restore-keys: |
      gradle-${{ runner.os }}-

Cómo funciona la coincidencia de claves

Al buscar en la caché, GitHub busca primero una coincidencia exacta con key. Si no la encuentra, prueba cada línea de restore-keys en orden y elige la caché creada más recientemente cuya clave empiece por ese prefijo. Con una coincidencia exacta, la acción asigna cache-hit a true y omite el paso de guardado al final del job. Con una coincidencia parcial mediante restore-keys, el job se ejecuta y después guarda una nueva caché con la key completa.

Ese comportamiento es precisamente el propósito de restore-keys. Cuando su lockfile cambia en una sola dependencia, la clave exacta no coincide, pero el prefijo restaura la caché de ayer, de modo que la instalación solo descarga la diferencia.

Una buena clave tiene tres partes: el sistema operativo y la arquitectura, la versión de la herramienta y un hash de las entradas.

key: cargo-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/Cargo.lock') }}

El generador de claves de caché crea key y restore-keys para las pilas tecnológicas más habituales.

Alcance y límites

Estos datos proceden de la documentación de GitHub sobre la caché de dependencias y los límites de uso:

  • Un workflow puede restaurar cachés creadas en la rama actual y en la rama base (y en la rama por defecto). Una rama de funcionalidad puede leer la caché de main; main no puede leer la caché de una rama de funcionalidad. Las ramas hermanas no pueden leer la caché la una de la otra.
  • En los pull requests, las cachés están limitadas a la referencia de fusión, por lo que la caché de un PR no puede reutilizarse en otro PR.
  • Las cachés que no se han usado durante 7 días se eliminan.
  • El almacenamiento total de caché predeterminado es de 10 GB por repositorio. Si lo supera, GitHub elimina las cachés menos usadas recientemente. Los propietarios pueden aumentar el límite, y el almacenamiento por encima de la cantidad incluida se factura.
  • Las entradas de caché son inmutables. No se puede actualizar una clave; hay que crear una nueva.

La consecuencia práctica: asegúrese de que main llene la caché. Ejecute el mismo paso de caché en los pushes a main, para que cada PR parta de una caché ya preparada.

Qué cachear y qué no

Cachear estoClaveOmitir esto
Caché de descargas de npm, pnpm, yarnpackage-lock.json, pnpm-lock.yaml, yarn.lockLa propia carpeta node_modules
Caché de descargas de pip, Poetry, uvrequirements*.txt, poetry.lock, uv.lockEntornos virtuales completos entre versiones de Python
Gradle, MavenArchivos de build, propiedades del wrapperSalidas de build con rutas absolutas
CargoCargo.locktarget/ de un workspace enorme, a menudo más grande que el tiempo que ahorra
Cachés del compilador (ccache, sccache)Sistema operativo, versión del compiladorNada; estas sí merecen la pena

Las cachés grandes tienen un coste. Una caché de 2 GB que tarda 40 segundos en descargarse y extraerse puede no ser más rápida que una instalación de 30 segundos. Mida el tiempo de restauración en el log del paso.

Causas habituales de fallos de caché

  1. La clave incluye algo que cambia en cada ejecución, como github.sha o una marca de tiempo. Úselo solo como última parte de una clave, combinado con restore-keys para cachés que se renuevan continuamente.
  2. hashFiles no encuentra nada. Devuelve una cadena vacía, por lo que cada ejecución usa la misma clave y nunca se actualiza. Revise el patrón glob.
  3. Sistema operativo o arquitectura distintos. Incluya runner.os y runner.arch.
  4. La ruta cambia entre el guardado y la restauración. Las rutas forman parte de la identidad de la caché.
  5. Alcance por rama. Una rama nueva solo ve sus propias cachés y las de la rama por defecto.
  6. Eliminación. Revise la lista de cachés de Actions del repositorio. Con muchas ramas, los 10 GB se llenan rápidamente.

Listar y eliminar cachés desde la CLI:

gh cache list --limit 50
gh cache delete <cache-id>

Cachés continuas para la salida de compilación

Para compiladores incrementales, conviene que cada ejecución parta de la salida de la anterior y luego guarde la nueva. Use una clave única con un prefijo de respaldo:

- uses: actions/cache@v4
  with:
    path: .turbo
    key: turbo-${{ runner.os }}-${{ github.sha }}
    restore-keys: |
      turbo-${{ runner.os }}-

Cada ejecución no encuentra la clave exacta, restaura la coincidencia de prefijo más reciente y guarda una nueva entrada. Tenga en cuenta el límite de 10 GB con este patrón; las entradas más antiguas se eliminan automáticamente.

Separar restauración y guardado

Use actions/cache/restore y actions/cache/save para guardar solo cuando el job se completa correctamente, o solo desde main:

- uses: actions/cache/restore@v4
  id: cache
  with:
    path: ~/.m2
    key: m2-${{ hashFiles('**/pom.xml') }}
- run: mvn -B verify
- uses: actions/cache/save@v4
  if: github.ref == 'refs/heads/main' && steps.cache.outputs.cache-hit != 'true'
  with:
    path: ~/.m2
    key: m2-${{ hashFiles('**/pom.xml') }}

Así se evita que las ramas de pull request llenen su cuota.

Preguntas frecuentes

¿Qué tamaño puede tener una caché de GitHub Actions?

El total para un repositorio es de 10 GB por defecto, según se indica en los límites de uso de GitHub.

¿Puedo compartir una caché entre workflows?

Sí, siempre que la clave y la ruta coincidan y el ámbito de la rama lo permita. Las cachés pertenecen al repositorio, no a un único workflow.

¿Debo almacenar también en caché las capas de Docker aquí?

Las capas de Docker tienen sus propios backends. Consulte Caché de capas de Docker en CI.

¿Está garantizado que un acierto de caché sea seguro?

Un acierto con clave exacta restaura exactamente lo que se guardó con esa clave. La seguridad depende de que la clave cubra todas las entradas que afectan a los archivos.

Dónde encaja esto

El uso de caché es una de varias soluciones para cómo acelerar GitHub Actions. Si la caché ayuda pero un job sigue siendo lento, compruebe si el job está limitado por la CPU; el modo de comparación de compiler.dev ejecuta sus jobs en una máquina más rápida para que pueda ver la diferencia en su propio workflow.

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

Pruébelo gratis