Caché de GitHub Actions: cómo funciona y qué oculta

Cómo funciona la caché

La acción actions/cache guarda un conjunto de rutas bajo una clave al final de un job y las restaura al comienzo de otro posterior. Una configuración típica de npm almacena en caché la caché de descargas del gestor de paquetes y usa como clave el lockfile:

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

Al restaurar, la acción busca primero una coincidencia exacta con key, después una coincidencia parcial y luego cada prefijo de restore-keys por orden. Cuando varias cachés coinciden con un prefijo, restaura la creada más recientemente. Esa alternativa es lo que mantiene rápidos los builds después de un cambio en el lockfile, y también significa que un job puede empezar desde una caché creada para un lockfile más antiguo.

A menudo ni siquiera necesita la acción. setup-node, setup-python, setup-java, setup-go, setup-ruby y setup-dotnet llevan la caché integrada. Para Node.js, setup-node almacena en caché los datos globales de paquetes de npm, Yarn y pnpm, no node_modules, y activa automáticamente la caché de npm cuando package.json declara npm como su packageManager.

Alcance y límites

Regla	Qué hace GitHub
Qué cachés puede restaurar una ejecución	Las de su propia rama y de la rama predeterminada; las pull requests, también las de su rama base
Qué puede escribir una pull request	Solo cachés limitadas a su referencia de fusión, no a la rama predeterminada
Almacenamiento	10 GB por repositorio por defecto; los propietarios de organizaciones y empresas pueden ampliarlo
Expulsión	Las entradas sin acceso durante más de 7 días y, con el almacenamiento lleno, las de uso menos reciente
Secretos	No los almacene en caché: cualquiera con acceso a pull requests puede leer el contenido de la caché

Qué oculta la caché a su SBOM

Una caché es un atajo que evita el registro de paquetes. Para eso sirve, y por eso mismo confunde a cualquier registro de lo que utilizó un build:

Sin descarga, sin rastro. Los paquetes restaurados desde una caché se instalan sin ninguna petición al registro de paquetes. Un registro construido a partir del tráfico de red del build los pasa por alto, salvo que siga la caché.
Contenido antiguo bajo una clave nueva. Una coincidencia parcial de restore-keys restaura una caché creada para un lockfile anterior. Después, la instalación añade o sustituye lo que ha cambiado, pero el punto de partida del job no es lo que describe el lockfile actual.
Más que sus dependencias. Las cachés también contienen herramientas de build, compiladores y archivos generados, que ningún manifiesto de aplicación enumera.
Un escaneo no puede saberlo. Una SBOM basada en el lockfile describe lo que dice el lockfile, tanto si el job instaló exactamente eso desde su caché como si no.

Para ver cómo encaja esto en el problema más amplio, consulte por qué un lockfile no es un registro de lo distribuido y dependencias transitivas.

Envenenamiento de la caché

Las cachés se comparten entre los workflows de un repositorio, lo que las convierte en una vía entre ellos. En mayo de 2024, el investigador de seguridad Adnan Khan demostró que cualquiera que pueda ejecutar código en el contexto de la rama predeterminada, mediante un workflow vulnerable de pull_request_target o una dependencia comprometida, puede sobrescribir archivos en los workflows que restauran cachés. Con el token de caché de un job en ejecución, un atacante puede llenar la caché del repositorio para que GitHub expulse las entradas legítimas y después escribir entradas envenenadas bajo las mismas claves. Un workflow de lanzamiento que las restaure ejecuta los archivos del atacante con sus propios secretos.

Para reducir el riesgo:

Compile las versiones desde un estado limpio o desde cachés que solo escriba el workflow de lanzamiento.
Nunca ejecute código no fiable de pull requests en el contexto de la rama predeterminada.
Mantenga los secretos y tokens fuera de las rutas almacenadas en caché.
Trate lo que restaura una caché como una entrada del build que requiere el mismo escrutinio que una descarga.

Cómo gestiona CRACI las cachés

CRACI es un runner de GitHub Actions, de modo que actions/cache y las cachés de setup-* funcionan como hoy, junto con la caché de capas de contenedor. La caché también es parte de la razón por la que CRACI ejecuta los builds aproximadamente el doble de rápido que los runners alojados por GitHub, con hardware más rápido y tiempos de cola más cortos.

Lo que cambia es el registro. El proxy de CRACI que entiende de paquetes registra los paquetes que descarga un job, y la evidencia viaja con las cachés: cuando un job restaura una caché, CRACI traslada las dependencias que conoce a la SBOM de ese job.

Completitud por caché. Cada caché tiene un estado de completitud, igual que cada job. Un job que restaura una caché incompleta obtiene una SBOM incompleta, y una caché que produzca arrastra ese estado, de modo que una laguna nunca se convierte sin aviso en un registro completo.
Sin deducciones a partir del archivo. CRACI no lee los manifiestos de paquetes dentro del archivo de la caché. Sabe lo que hay en una caché porque registró el job que la produjo.
Una caché por cada job productor mantiene fiable esa evidencia, junto con una política de salida con default: deny en el job productor. La guía de completitud de cachés y SBOM ofrece los detalles.

Consulte SBOM durante el build para saber cómo funciona el registro, o reserve una demo para ejecutar uno de sus workflows con caché en CRACI.

Caché de GitHub Actions: preguntas frecuentes

¿Cuánto tiempo conserva GitHub una caché de Actions?

GitHub elimina las entradas de caché a las que no se ha accedido en más de 7 días. Cuando un repositorio supera su límite de almacenamiento, 10 GB por defecto, también expulsa cachés por orden de último acceso, empezando por la más antigua.

¿setup-node almacena node_modules en caché?

No. La entrada cache de actions/setup-node almacena los datos globales de paquetes del gestor de paquetes para npm, Yarn o pnpm, no node_modules. El paso de instalación se sigue ejecutando, pero lee los paquetes de la caché restaurada en lugar de descargarlos.

¿Una pull request puede leer cachés de la rama principal?

Sí. Una ejecución de workflow puede restaurar cachés de su propia rama y de la rama predeterminada, y una pull request también puede restaurar cachés de su rama base. Las cachés creadas en una pull request se limitan a su referencia de fusión, de modo que no se pueden escribir en el ámbito de la rama predeterminada.

¿Es seguro usar la caché de Actions en workflows de lanzamiento?

Tiene ventajas e inconvenientes. Una investigación publicada en 2024 demostró que cualquiera que pueda ejecutar código en un workflow de la rama predeterminada puede envenenar cachés que restauran otros workflows, incluidos los de lanzamiento. Los workflows que publican versiones o tienen acceso a secretos de despliegue son más seguros si compilan desde un estado limpio o desde cachés que solo ellos escriben.

¿Una caché restaurada cambia mi SBOM?

Puede hacerlo. Los paquetes restaurados desde una caché se instalan sin descargarse, de modo que un registro construido a partir del tráfico de red los pasa por alto, salvo que siga la caché. Y un escaneo del lockfile no le dice si la caché contenía exactamente esas versiones.