Tecnología · GUÍA PRÁCTICA
GitHub Actions no restaura la caché: comprueba clave, versión, referencia y acceso
Que una caché exista no significa que la ejecución actual pueda leerla. Compara la ejecución que la creó con la que no pudo recuperarla antes de borrarla o cambiar de runner.
Un fallo de caché en GitHub Actions no demuestra por sí solo que nunca se guardó, que el runner esté averiado o que haya cambiado la clave. También intervienen la versión, el ámbito de la rama o referencia de la solicitud de cambios, el orden de búsqueda, el acceso y la existencia actual de la entrada.
El diagnóstico más seguro comienza con un registro comparativo de dos ejecuciones: la que creó la caché y la que no pudo usarla. Anota la clave evaluada, las entradas de rutas y compresión, la referencia resuelta, el evento, el repositorio, los permisos y los resultados de búsqueda y guardado.
Separa la falta de coincidencia exacta, la restauración parcial, el aislamiento de las solicitudes de cambios y las entradas eliminadas. Conserva las pruebas antes de rotar claves, borrar cachés, ampliar permisos o trasladar el trabajo a otro runner.
Crea un registro del productor y del consumidor
Elige una ejecución que guardó la caché y otra que debía reutilizarla. Anota en ambas el repositorio, archivo de flujo y commit, evento, github.ref, github.ref_name, referencias base y head cuando correspondan, sistema y arquitectura del runner, versión de la acción, clave principal evaluada, todas las claves de restauración, rutas, lookup-only, fail-on-cache-miss y registros finales de restauración o guardado.
No compares solo las plantillas YAML. Las expresiones pueden resolverse de forma distinta en push, pull_request, trabajos de matriz y flujos reutilizables. Obtén los valores reales de los registros o de un paso de diagnóstico seguro que solo muestre campos no secretos. No imprimas tokens, secretos del entorno, credenciales ni contenido de archivos privados.
Distingue la clave visible de la versión
La versión de caché incorpora metadatos relacionados con las rutas y la herramienta de compresión. Dos ejecuciones pueden mostrar la misma clave y generar versiones incompatibles por diferencias de entradas, plataforma, compresión o implementación de la acción.
Compara las rutas después de evaluar expresiones, incluido su orden, patrones, tilde, espacio de trabajo y diferencias entre sistemas. Registra también la imagen del runner y la versión de la acción. Añadir una marca de tiempo a la clave para ocultar una posible incompatibilidad crea entradas nuevas y dificulta comparar las pruebas originales.
Trata el ámbito de la referencia como una regla de visibilidad
La caché de una ejecución pull_request pertenece a su referencia de fusión. La puede recuperar una repetición de esa PR, pero no la rama base ni otra PR. Poder usar la rama actual y el recurso permitido a la rama predeterminada no da acceso a cualquier rama hija o hermana.
Anota el evento y la referencia resuelta en ambas ejecuciones. Si una clave funciona en push y falla en pull_request, compara el ámbito antes de cambiar el runner o la ruta. Una pregunta de la comunidad es un relato del síntoma, no una prueba de su causa: contrasta las referencias reales con las reglas oficiales de acceso.
Interpreta cache-hit junto al resultado real
cache-hit es true solo cuando la clave principal coincide exactamente. Si no coincide pero una clave de restauración encuentra un prefijo, los datos pueden recuperarse aunque la salida sea false. Tratar false como ausencia absoluta de datos puede provocar trabajo innecesario.
Conserva juntos el registro de restauración, la clave encontrada y la cadena de salida original. La sección Outputs del README documenta una cadena vacía para un fallo; no conviertas todo valor distinto de true en false. Distingue coincidencia exacta, restauración parcial y ausencia de datos usando también los registros. Tras una restauración parcial puede seguir siendo necesario instalar dependencias para conciliar los cambios. En una respuesta posterior de Stack Overflow, el autor informó de que resolvió su condición comparando con la cadena 'true' en vez del booleano sin comillas. Es una solución comunicada para ese flujo, no una explicación universal de los fallos de caché.
Comprueba por separado el modo de acceso
Registra ACTIONS_CACHE_MODE efectivo, cache-mode del flujo y del job, límites de los flujos reutilizables y mensajes de operaciones omitidas. read permite restaurar, write permite restaurar y guardar, write-only solo permite guardar y none no permite ninguna operación. Una restauración omitida por falta de lectura puede aparecer como fallo sin demostrar que la entrada no existe.
No atribuyas la misma restricción a todas las PR. La política de disparadores de baja confianza en la rama predeterminada es distinta del aislamiento de la referencia de fusión de pull_request. Compara repositorio, evento, referencia y modo efectivo. Un job exitoso puede contener un guardado rechazado u omitido. Conserva la advertencia y los valores seguros; utiliza un productor de confianza adecuado en vez de conceder escritura a código no fiable.
Demuestra que la entrada todavía existe
Un antiguo registro de guardado solo acredita que la entrada existía entonces. Los límites de almacenamiento, la retención por inactividad, el borrado manual y la eliminación frecuente por presión de espacio pueden retirarla. Con una cuenta autorizada, consulta la lista de cachés o la API para comprobar clave, referencia, fecha de creación, último acceso y tamaño.
No borres todas las cachés para diagnosticar. Si la entrada falta, conserva el registro del productor y el resultado del inventario, y crea una sustitución controlada. Si existe con otra referencia o versión incompatible, borrarla elimina pruebas sin cambiar la regla de visibilidad.
Elige el cambio mínimo que puedas verificar
Si la clave coincide pero hay un fallo, confirma primero que la lectura estaba permitida y después compara versión y referencia. Si hubo restauración parcial, revisa la condición consumidora y concilia las dependencias cuando sea necesario. Para una diferencia de ámbito de PR, utiliza un productor de confianza apropiado o acepta el aislamiento. Si falta la entrada, ejecuta una sola creación controlada y verifica el inventario. No amplíes el acceso no fiable para forzar una coincidencia.
Si todos los campos coinciden y la entrada es visible para la referencia esperada, eleva el caso con el registro comparativo. Incluye URL de las ejecuciones, valores evaluados seguros, versión de la acción, imagen del runner, pruebas del inventario y un flujo mínimo reproducible. Así se puede investigar un defecto sin borrar pruebas ni exponer secretos.
