¿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
- Empiece con un prefijo estable que describa lo que se almacena en caché (
npm,cargo,gradle). - Añada
runner.osy la arquitectura si el contenido depende de la plataforma. - Añada
hashFiles()de los archivos que definen el contenido (lockfiles, archivos de compilación). - 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.shacomo 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é.
Términos relacionados
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.
Relacionado
- Cachear Cargo y compilaciones de Rust en GitHub ActionsCachee el registro de Cargo, las dependencias git y el directorio target en GitHub Actions con Swatinem/rust-cache o actions/cache, sin cachés inflados.
- Caché de módulos Go y de compilación en GitHub ActionsCachee los módulos Go (GOMODCACHE) y la caché de compilación (GOCACHE) en GitHub Actions con setup-go o actions/cache. Claves, go.sum y aciertos.
- Cachear compilaciones de Gradle en GitHub ActionsCachee las dependencias y la caché de compilación de Gradle en GitHub Actions con gradle/actions/setup-gradle o actions/cache. Claves, PR de solo lectura.
- Cachear dependencias de npm en GitHub ActionsAlmacene en caché las dependencias de npm en GitHub Actions con setup-node o actions/cache. YAML funcional, la clave correcta y por qué no node_modules.