GitHub Actions cache-mode: verificar los permisos de caché tras un CI en verde
Si un CI termina en verde pero la siguiente ejecución vuelve a descargar las dependencias, es fácil apresurarse a modificar la clave de caché. Sin embargo, ahora también es necesario verificar si el guardado se omitió debido a los permisos. El simple hecho de que un flujo de trabajo haya tenido éxito no garantiza que se haya generado la caché.
GitHub anunció la disponibilidad general de cache-mode el 10 de septiembre de 2026. Ahora es posible definir el acceso a la caché a nivel de flujo de trabajo o de trabajo individual en todos los planes de github.com. Yendo un paso más allá del artículo anterior sobre los valores predeterminados de solo lectura, esta entrega se centra en la configuración explícita y los métodos de verificación.
Funcionalidad confirmada: cuatro combinaciones de restauración y guardado
read permite únicamente la restauración, mientras que write permite tanto la restauración como el guardado. write-only solo permite el guardado y none bloquea ambos. El primer paso de verificación es no asumir erróneamente que write equivale a solo guardar.
El valor declarado en un trabajo tiene prioridad sobre la configuración global del flujo de trabajo. Por otro lado, al invocar un flujo de trabajo reutilizable, este no puede recibir más permisos de acceso que los concedidos por el invocador. No juzgue los permisos reales de toda la ejecución basándose únicamente en la declaración de un solo archivo.
Una ejecución en verde no es prueba de guardado
La documentación oficial explica que las operaciones de caché no autorizadas continúan ejecutándose tras registrar un mensaje informativo en los registros. Una restauración bloqueada se gestiona como un fallo de caché (cache miss), y un guardado bloqueado simplemente no se realiza. El aspecto clave para la observabilidad es que el flujo de trabajo en sí no falla.
Por lo tanto, resulta útil dividir los registros operativos entre el éxito de la ejecución y el resultado de la caché. Compruebe en una misma ejecución qué evento se ejecutó, qué modo se aplicó, si se restauró y si se omitió el guardado. Esta es una pauta operativa sugerida a partir de la descripción de la función oficial, no una nueva función de panel de control proporcionada automáticamente.
Crear una pequeña tabla de permisos antes de aplicar cambios
Examine los flujos de trabajo reales de su repositorio e identifique los trabajos que generan caché y los que la consumen. No es necesario agrupar bajo los mismos permisos las tareas que preparan dependencias en ramas de confianza, las que prueban cambios externos y las que validan artefactos de despliegue.
Escriba dos preguntas para cada trabajo: ¿debe este trabajo leer una caché existente?, ¿puede el resultado de este trabajo quedar guardado para que lo lea la siguiente ejecución? Si ninguna de las dos es necesaria, conviene reconsiderar la costumbre automática de adjuntar una caché. No obstante, la configuración real debe determinarse según los límites de confianza y la arquitectura de compilación del repositorio.
Experimento mínimo: un trabajo consumidor de solo lectura
Por ejemplo, en un flujo de trabajo de prueba, declare explícitamente cache-mode: read en el nivel superior y verifique que no existan anulaciones específicas por trabajo. Compare si el resultado de las pruebas al usar la caché es idéntico al resultado sin ella. Dado que la caché debe ser solo un medio secundario para reducir el tiempo de ejecución, si la exactitud cambia por no tener caché, primero debe revisar los supuestos de compilación.
El criterio de aprobación para este experimento no es solo una línea verde de CI. Debe ser capaz de explicar el intento de restauración y la omisión del guardado, y poder verificarlo nuevamente con las mismas entradas en la siguiente ejecución. Si documenta los commits antes y después del experimento, los desencadenadores, las configuraciones efectivas y la ubicación de los registros, a sus compañeros les resultará fácil reproducir las conclusiones.
En flujos de trabajo reutilizables, examine toda la ruta de invocación
Incluso si ha establecido valores predeterminados seguros en un flujo de trabajo compartido, debe revisar conjuntamente tanto el lado invocador como la configuración de cada trabajo individual. Que varios repositorios llamen al mismo archivo no significa que se ejecuten con los mismos permisos.
Durante la revisión, comience por el invocador, siga con las declaraciones de caché del trabajo y continúe con el flujo de trabajo llamado. Si los permisos esperados difieren de los registros reales, localice el origen de la configuración antes de complicar las claves. Esta es una sugerencia para reducir el tiempo de diagnóstico en organizaciones con alta reutilización y no representa cifras medidas de mejora de rendimiento.
Excepciones a considerar y orden de aplicación
Si declara explícitamente write o write-only en eventos de baja confianza como pull_request_target, puede anular la restricción predeterminada de solo lectura y aumentar el riesgo de envenenamiento de caché. En estos casos, GitHub añade una anotación de advertencia. Debe evitarse responder ampliando los permisos de escritura solo para eliminar dicha advertencia.
Por el contrario, bloquear toda la caché también conlleva un costo. Dado que los tiempos de descarga y compilación pueden aumentar, compare directamente el tiempo de ejecución en un trabajo representativo antes de ampliar el alcance. En lugar de prometer efectos de rendimiento basados en estimaciones numéricas, es preferible que el equipo defina en conjunto las restricciones de seguridad necesarias y la latencia aceptable.
Preguntas que el equipo debe verificar ahora
La tarea para hoy no es añadir la nueva configuración de forma masiva a todos los repositorios. Consiste en identificar a los productores y consumidores de caché en un flujo de trabajo importante, anotar sus permisos y verificar en una ejecución las evidencias de restauración y guardado. Si se trata de un trabajo de despliegue, mantenga los cambios pequeños para que el responsable pueda leer los registros y confirmar que coinciden con lo esperado.
Una duda práctica que puede surgir es por qué el CI tuvo éxito si se omitió el paso de guardado. Este artículo explica dicha confusión basándose en el comportamiento oficial y no plantea encuestas comunitarias externas ni tasas universales de incidentes. Al adoptar la nueva función, comprobar los resultados de rendimiento y los de permisos por separado le permitirá clasificar con mayor precisión los futuros problemas de caché.