Saltar al contenido

¿Qué es una clave de caché en GitHub Actions?

Última actualización

Una clave de caché es la cadena que GitHub Actions usa para encontrar una caché guardada. Si existe una caché con una clave que coincida exactamente, se restaura; si no, el paso informa de un fallo de caché (cache miss), su job reconstruye los datos y luego los guarda con esa clave.

Cómo funciona

actions/cache recibe un path donde guardar, una key y restore-keys opcionales. Al restaurar, primero busca una coincidencia exacta de key. Si no encuentra ninguna, prueba cada entrada de restore-keys como prefijo y usa la caché más reciente que empiece por ese prefijo. Una coincidencia por prefijo restaura datos antiguos, lo que suele ser mejor que nada, y al final del job se guarda una nueva caché con la clave completa.

Las cachés son inmutables. No puede sobrescribir una clave, así que una buena clave cambia exactamente cuando debe cambiar el contenido almacenado. El truco habitual es calcular el hash del lockfile.

Ejemplo

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-

Aquí la clave cambia cuando cambia el lockfile. Si eso ocurre, el prefijo de restore-keys restaura la caché anterior, npm solo descarga la diferencia y se guarda una caché nueva.

Cómo construir buenas claves

  1. Empiece con un prefijo estable que describa lo que se almacena en caché (npm, cargo, gradle).
  2. Añada runner.os y la arquitectura si el contenido depende de la plataforma.
  3. Añada hashFiles() de los archivos que definen el contenido (lockfiles, archivos de compilación).
  4. Añada un número de versión manual (v2) para poder invalidar la caché a propósito.

El generador de claves de caché crea claves para los stacks más comunes. Consulte caché en GitHub Actions para ver el panorama completo.

Errores comunes

  • Usar github.sha como clave. Cada commit recibe una clave nueva, por lo que nunca se acierta en la caché.
  • Calcular el hash de muy poco o de demasiado. Calcular el hash de los archivos fuente hace que las claves cambien constantemente; no calcular ninguno hace que las cachés queden obsoletas.
  • No usar restore-keys. Una sola dependencia modificada provoca una reconstrucción completa en lugar de una incremental.
  • Olvidar las reglas de alcance. Las cachés guardadas en una rama son visibles para esa rama y para su rama base, no para ramas hermanas.
  • Alcanzar los límites de tamaño. Los repositorios tienen un tamaño total máximo de caché y las entradas antiguas se eliminan. Consulte límites de caché.

Preguntas frecuentes

¿Puedo actualizar una caché existente?

No. Las claves son inmutables. Cambie la clave (por ejemplo, mediante el hash del lockfile) y se guardará una caché nueva.

¿Para qué sirve restore-keys?

Proporciona prefijos de respaldo para restaurar la caché anterior más cercana cuando la clave exacta no coincide.

¿Cómo borro una caché?

Elimínela desde la página de cachés de Actions del repositorio o con GitHub CLI, o bien cambie una cadena de versión en la clave.