# Referencia de almacenamiento en caché de dependencias Encuentra información sobre la funcionalidad del almacenamiento en caché de dependencias en los flujos de trabajo. ## Uso de la acción `cache` La acción [`cache`](https://github.com/actions/cache) intentará la siguiente secuencia al restaurar una caché: 1. En primer lugar, busca una coincidencia exacta con la `key` proporcionada. 2. Si no se encuentra ninguna coincidencia exacta, buscará coincidencias parciales de `key`. 3. Si todavía no se encuentra ninguna coincidencia y has proporcionado `restore-keys`, estas claves se comprobarán secuencialmente para buscar coincidencias parciales. Para obtener más información, consulta [Coincidencia de clave de caché](#cache-key-matching). Si hay una coincidencia exacta con el elemento `key` proporcionado, se considera un acierto de caché. Si ninguna memoria caché coincide exactamente con el elemento `key` proporcionado, se considera un error de caché. En un error de caché, la acción crea automáticamente una nueva memoria caché si el trabajo se completa correctamente. La nueva caché usará el elemento `key` que proporcionaste y contiene los archivos que especificaste en `path`. Para obtener más información sobre cómo se controla esto, consulte [Aciertos y errores de caché](#cache-hits-and-misses). No se puede cambiar el contenido de una memoria caché existente. En su lugar, puedes crear una nueva memoria caché con una nueva clave. ### Parámetros de entrada de la acción `cache` * `key`: **obligatorio** La clave creada al guardar una memoria caché y la clave usada para buscar una caché. Puede ser cualquier combinación de variables, valores de contexto, cadenas estáticas y funciones. Las claves tienen una longitud máxima de 512 caracteres y las claves más largas que la longitud máxima provocarán un error en la acción. * `path`: **obligatorio** Las rutas de acceso en el ejecutor para almacenar en caché o restaurar. * Puedes especificar una única ruta de acceso o agregar varias rutas de acceso en líneas independientes. Por ejemplo: ```yaml - name: Cache Gradle packages uses: actions/cache@v4 with: path: | ~/.gradle/caches ~/.gradle/wrapper ``` * Puedes especificar directorios o archivos únicos, y los patrones globales son compatibles. * Puedes especificar rutas de acceso absolutas o rutas de acceso relativas al directorio del área de trabajo. * `restore-keys`: **opcional** Una cadena que contiene claves de restauración alternativas, con cada clave de restauración colocada en una nueva línea. Si no se produce ningún acierto de caché para `key`, estas claves de restauración se usan secuencialmente en el orden proporcionado para buscar y restaurar una caché. Por ejemplo: ```yaml restore-keys: | npm-feature-${{ hashFiles('package-lock.json') }} npm-feature- npm- ``` * `enableCrossOsArchive`: **Optional** Valor booleano que, cuando está habilitado, permite a los ejecutores de Windows guardar o restaurar cachés independientemente del sistema operativo en el que se creó la memoria caché. Si no se establece este parámetro, el valor predeterminado es `false`. Para obtener más información, consulta la sección sobre [caché entre sistemas operativos](https://github.com/actions/cache/blob/main/tips-and-workarounds.md#cross-os-cache) en la documentación de caché de Acciones. > \[!NOTE] > Se recomienda no almacenar información confidencial, como tokens de acceso o credenciales de inicio de sesión, en los archivos de la ruta de acceso de la memoria caché. Cualquier usuario con acceso de lectura puede crear una solicitud de incorporación de cambios en un repositorio y acceder a los contenidos de una caché. Además, las bifurcaciones de un repositorio pueden crear solicitudes de extracción en la rama base y acceder a las cachés en la rama base. ### Parámetros de salida de la acción `cache` * `cache-hit`: valor booleano para indicar que se encontró una coincidencia exacta para la clave. ### Aciertos y errores de caché Cuando `key` coincide exactamente con una memoria caché existente, se denomina un *acierto de caché* y la acción restaura los archivos almacenados en caché en el directorio `path`. Cuando `key` no coincide con una caché existente, se denomina un *error de caché* y se crea automáticamente una caché si el trabajo se completa correctamente. Cuando se produce un error de caché, la acción también busca los elementos `restore-keys` especificados en busca de coincidencias: 1. Si proporcionas `restore-keys`, la acción `cache` busca secuencialmente las memorias caché que coincidan con la lista de `restore-keys`. * Cuando hay una coincidencia exacta, la acción restaura los archivos en la memoria caché al directorio `path`. * Si no hay coincidencias exactas, la acción busca coincidencias parciales de las claves de restauración. Cuando la acción encuentra una coincidencia parcial, se restaura la caché más reciente al directorio `path`. 2. La acción `cache` se completa y se ejecuta el paso siguiente del flujo de trabajo. 3. Si el trabajo se completa correctamente, la acción crea automáticamente una caché con los contenidos del directorio `path`. Para obtener una explicación más detallada del proceso de coincidencia de caché, consulta [Coincidencia de clave de caché](#cache-key-matching). ### Ejemplo de uso de la acción `cache` En este ejemplo se crea una nueva memoria caché cuando cambian los paquetes del archivo `package-lock.json` o cuando cambia el sistema operativo del ejecutor. La clave de caché usa contextos y expresiones para generar una clave que incluye el sistema operativo del ejecutor y un hash SHA-256 del archivo `package-lock.json`. ```yaml copy name: Caching with npm on: push jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - name: Cache node modules id: cache-npm uses: actions/cache@v4 env: cache-name: cache-node-modules with: # npm cache files are stored in `~/.npm` on Linux/macOS path: ~/.npm key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }} restore-keys: | ${{ runner.os }}-build-${{ env.cache-name }}- ${{ runner.os }}-build- ${{ runner.os }}- - if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }} name: List the state of node modules continue-on-error: true run: npm list - name: Install dependencies run: npm install - name: Build run: npm run build - name: Test run: npm test ``` ### Usar contextos para crear claves de caché Una clave de caché puede incluir cualquiera de los contextos, funciones, literales y operadores admitidos por GitHub Actions. Para más información, consulta [Contextos de referencia](/es/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts) y [Evaluación de expresiones en flujos de trabajo y acciones](/es/enterprise-server@3.22/actions/reference/workflows-and-actions/expressions). Usar expresiones para crear un elemento `key` te permite crear automáticamente una caché cuando las dependencias cambian. Por ejemplo, puedes crear una `key` mediante una expresión que calcule el hash de un archivo `package-lock.json` de npm. Por lo tanto, cuando cambian las dependencias que componen el cambio en el archivo `package-lock.json`, la clave de caché cambia y se crea automáticamente una caché. ```yaml npm-${{ hashFiles('package-lock.json') }} ``` GitHub evalúa la expresión `hash "package-lock.json"` para derivar el objeto final `key`. ```yaml npm-d5ea0750 ``` ### Uso de la salida de la acción `cache` Puedes usar la salida de la acción `cache` para hacer algo en función de si se ha producido un acierto o un error en la caché. Si se encuentra una coincidencia exacta para la caché en la `key` especificada, la salida `cache-hit` se establece en `true`. En el flujo de trabajo de ejemplo anterior, hay un paso que enumera el estado de los módulos de Node si se ha producido un error en la caché: ```yaml - if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }} name: List the state of node modules continue-on-error: true run: npm list ``` ## Coincidencia de clave de caché La acción `cache` busca primero los aciertos de caché para `key` y la *versión* de la memoria caché en la rama que contiene la ejecución del flujo de trabajo. Si no hay ningún acierto, busca coincidencias de prefijo para `key` y, si aún no hay ningún acierto, busca `restore-keys` y la *versión*. Si sigue sin haber aciertos en la rama actual, la acción `cache` reintenta los mismos pasos en la rama predeterminada. Ten en cuenta que se aplican las restricciones de ámbito durante la búsqueda. Para obtener más información, consulte [Restricciones para acceder a una memoria caché](#restrictions-for-accessing-a-cache). La versión de la memoria caché es una forma de marcar con un sello una memoria caché con metadatos de `path` y la herramienta de compresión que se usa al crear la memoria caché. Esto garantiza que la ejecución del flujo de trabajo de consumo coincida únicamente con una memoria caché que realmente puede descomprimir y usar. Para obtener más información, consulta [Versión de caché](https://github.com/actions/cache#cache-version) en la documentación de caché de Acciones. `restore-keys` permite especificar una lista de claves de restauración alternativas que se usarán cuando se produce un error de caché en `key`. Puedes crear múltiples claves de restauración ordenadas desde las más específicas hasta las menos específicas. La acción `cache` busca `restore-keys` en orden secuencial. Cuando una clave no coincide directamente, la acción busca las claves prefijadas con la clave de restauración. Si hay múltiples coincidencias parciales para una clave de restauración, la acción devuelve la caché que se creó más recientemente. ### Ejemplo usando múltiples claves de restauración ```yaml restore-keys: | npm-feature-${{ hashFiles('package-lock.json') }} npm-feature- npm- ``` El ejecutor evalúa las expresiones, que se resuelven en estos `restore-keys`: ```yaml restore-keys: | npm-feature-d5ea0750 npm-feature- npm- ``` La clave de restauración `npm-feature-` coincide con cualquier clave que comience por la cadena `npm-feature-`. Por ejemplo, las claves `npm-feature-fd3052de` y `npm-feature-a9b253ff` coinciden con la clave de restauración. Se utilizará la caché con la fecha de creación más reciente. Las claves en este ejemplo se buscan en el siguiente orden: 1. \*\* `npm-feature-d5ea0750` \*\* coincide con un hash específico. 2. \*\* `npm-feature-` \*\* coincide con las claves de caché con el prefijo `npm-feature-`. 3. \*\* `npm-` \*\* coincide con cualquier clave con el prefijo `npm-`. #### Ejemplo de prioridad de búsqueda ```yaml key: npm-feature-d5ea0750 restore-keys: | npm-feature- npm- ``` Por ejemplo, si una solicitud de incorporación de cambios contiene una rama `feature` y tiene como destino la rama predeterminada (`main`), la acción busca `key` y `restore-keys` en el orden siguiente: 1. Clave `npm-feature-d5ea0750` en la rama `feature` 2. Clave `npm-feature-` en la rama `feature` 3. Clave `npm-` en la rama `feature` 4. Clave `npm-feature-d5ea0750` en la rama `main` 5. Clave `npm-feature-` en la rama `main` 6. Clave `npm-` en la rama `main` ## Acciones de `setup-*` para administradores de paquetes específicos Si almacenas en caché los administradores de paquetes que se enumeran debajo, el uso de sus respectivas acciones setup-\* requiere una configuración mínima, y creará y restaurará las cachés de dependencias automáticamente. | Administradores de paquetes | acción de setup-\* para almacenar en caché | | ------------------------------------------------------------------------------------------------- | ------------------------------------------ | | npm, Yarn, pnpm | | | [setup-node](https://github.com/actions/setup-node#caching-global-packages-data) | | | pip, pipenv, poesía | | | [setup-python](https://github.com/actions/setup-python#caching-packages-dependencies) | | | Gradle, Maven | | | [setup-java](https://github.com/actions/setup-java#caching-packages-dependencies) | | | RubyGems | | | [setup-ruby](https://github.com/ruby/setup-ruby#caching-bundle-install-automatically) | | | Ir `go.sum` | | | [setup-go](https://github.com/actions/setup-go#caching-dependency-files-and-build-outputs) | | | NuGet de .NET | | | [setup-dotnet](https://github.com/actions/setup-dotnet?tab=readme-ov-file#caching-nuget-packages) | | ## Restricciones para acceder a una caché Las restricciones de acceso proporcionan aislamiento y seguridad de caché al crear una frontera lógica entre las ramas o etiquetas diferentes. Las ejecuciones de flujo de trabajo pueden restaurar las memorias caché creadas en la rama actual o en la rama predeterminada (normalmente `main`). Si se desencadena una ejecución de flujo de trabajo para una solicitud de incorporación de cambios, también puede restaurar las memorias caché creadas en la rama base, incluidas las ramas base de repositorios bifurcados. Por ejemplo, si la rama `feature-b` tiene la rama base `feature-a`, una ejecución de flujo de trabajo desencadenada en una solicitud de incorporación de cambios tendría acceso a las memorias caché creadas en la rama predeterminada `main`, la rama base `feature-a` y la rama actual `feature-b`. Las ejecuciones de flujo de trabajo no pueden restaurar las memorias caché creadas para ramas secundarias o ramas del mismo nivel. Por ejemplo, una memoria caché creada para la rama secundaria `feature-b` no sería accesible para una ejecución de flujo de trabajo desencadenada en la rama primaria `main`. De forma similar, una memoria caché creada para la rama `feature-a` con la rama `main` base no sería accesible para su la rama `feature-c` del mismo nivel con la rama base `main`. Las ejecuciones de flujo de trabajo tampoco pueden restaurar las memorias caché creadas para nombres de etiqueta diferentes. Por ejemplo, una memoria caché creada para la etiqueta `release-a` con la rama `main` no sería accesible para un flujo de trabajo desencadenado para la etiqueta `release-b` con la rama base `main`. Cuando se crea una memoria caché mediante una ejecución de flujo de trabajo desencadenada en una solicitud de incorporación de cambios, dicha memoria caché se crea para la referencia de combinación (`refs/pull/.../merge`). Por este motivo, la memoria caché tendrá un ámbito limitado y solo se puede restaurar mediante nuevas ejecuciones de la solicitud de incorporación de cambios. No se puede restaurar mediante la rama base u otras solicitudes de incorporación de cambios destinadas a esa rama base. Varias ejecuciones de flujo de trabajo en un repositorio pueden compartir memorias caché. Se puede acceder a una memoria caché creada para una rama en una ejecución de flujo de trabajo y restaurarla desde otra ejecución de flujo de trabajo para el mismo repositorio y rama. > \[!NOTE] > Como los objetos se recuperan desde o se almacenan en la caché directamente desde los runners, los runners de Actions deben tener conectividad directa con el almacenamiento de objetos de Actions configurado en GitHub Enterprise Server, como AWS S3 o Azure Blob Storage. Los ejecutores autohospedados se autentican con el proveedor de Blob Storage mediante una dirección URL de acceso proporcionada por la GitHub Enterprise Server instancia. Esta dirección URL proporciona al proveedor de Blob Storage credenciales de autenticación temporales válidas. La propia instancia inicia este proceso, que media en todas las solicitudes al almacenamiento de objetos. > > Esto significa que `actions/cache` necesita una conexión HTTPS al almacenamiento de blobs para que funcione correctamente. > > Todos los metadatos se administran mediante el servicio de caché de artefactos, que es un microservicio dentro de GitHub Actions. > > Para obtener más información sobre el almacenamiento en caché, consulte [Requisitos de almacenamiento externo](/es/enterprise-server@3.22/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server#external-storage-requirements). ## Acceso a caché para desencadenadores de flujo de trabajo de confianza baja Algunos flujos de trabajo se ejecutan en respuesta a eventos que pueden iniciar personas que no tienen acceso de escritura al repositorio, como una solicitud de incorporación de cambios de bifurcación o un comentario de problema. Cuando estos eventos se ejecutan en el contexto de la rama predeterminada, podrían utilizarse para crear una caché maliciosa que un flujo de trabajo posterior, con más privilegios, restaure y en la que confíe. Esta clase de ataque se conoce como *intoxicación por caché*. Para reducir este riesgo, solo estos desencadenadores de flujo de trabajo pueden crear o sobrescribir cachés en el ámbito de la rama predeterminada: * `push` * `workflow_dispatch` * `repository_dispatch` * `delete` * `registry_package` * `page_build` * `schedule` Las ejecuciones desencadenadas por cualquier otro evento que se resuelva en la rama predeterminada tienen acceso de solo lectura a las memorias caché en el ámbito de la rama predeterminada. Estas ejecuciones pueden restaurar las memorias caché existentes, pero no pueden crearlas ni sobrescribirlas. Esto incluye desencadenadores cuya carga o actor iniciador puede verse afectada por alguien fuera del repositorio, como `pull_request_target`, `issue_comment`y `workflow_run`. El `pull_request` evento no se ve afectado. Las memorias caché creadas por una `pull_request` ejecución ya están limitadas a la referencia de combinación (`refs/pull/.../merge`) y no se pueden escribir en el ámbito de la rama predeterminada. Para obtener más información, consulte [Restricciones para acceder a una memoria caché](#restrictions-for-accessing-a-cache). Cuando una ejecución con acceso de caché de solo lectura intenta guardar una memoria caché, se produce un error en el guardado, pero el paso y el trabajo no lo hacen. El flujo de trabajo continúa y el error se notifica como una advertencia en el registro de flujo de trabajo. En ese caso, tenga en cuenta lo siguiente: * Para conservar las ventajas de rendimiento del almacenamiento en caché en el ámbito de rama predeterminado, asegúrese de que haya un flujo de trabajo de confianza que mantenga actualizada la memoria caché, por ejemplo, una compilación de CI desencadenada por una `push` a la rama predeterminada. Esas entradas de caché se pueden restaurar mediante flujos de trabajo desencadenados por eventos de confianza baja, como `pull_request_target`. * En los flujos de trabajo de confianza baja, cambie a una operación de caché de solo restauración, como `actions/cache/restore` para borrar el uso previsto de la memoria caché y evitar la advertencia en los registros de ejecución del flujo de trabajo. ## Procedimientos recomendados para usar cachés de forma segura El contenido de la caché no está firmado o comprobado, y cualquier ejecución de flujo de trabajo que pueda leer una caché puede extraer su contenido. Las memorias caché extraídas pueden modificar los archivos que se ejecutan posteriormente en una ejecución de flujo de trabajo, lo que conduce a una ejecución de código malintencionada. Siga estos procedimientos para reducir el riesgo de seguridad de usar cachés. * **No almacene información confidencial en una memoria caché.** Cualquier persona que pueda abrir una solicitud de extracción contra tu repositorio puede leer el contenido de la caché de la rama base. No escriba secretos, tokens ni credenciales en una ruta de acceso almacenada en caché. Almacene valores confidenciales como secretos en su lugar. Consulte [Secretos](/es/enterprise-server@3.22/actions/concepts/security/secrets). * **Guarde las memorias caché de los desencadenadores de confianza.** Restrinja las escrituras de caché en los flujos de trabajo desencadenados por actores de confianza (normalmente aquellos con acceso de escritura al repositorio). Consulte [Acceso a caché para desencadenadores de flujo de trabajo de confianza baja](#cache-access-for-low-trust-workflow-triggers) para conocer las restricciones predeterminadas que se aplican para limitar qué desencadenadores de flujo de trabajo pueden escribir en la memoria caché. Además, considere la posibilidad de usar entornos con reglas de protección de implementación para limitar aún más los flujos de trabajo que pueden modificar la memoria caché. Consulte [Administrar entornos para la implementación](/es/enterprise-server@3.22/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments). * **Siga los procedimientos recomendados de seguridad de flujo de trabajo para proteger los flujos de trabajo:** Limite los flujos de trabajo que tienen acceso de escritura en caché a los que se han protegido contra vulnerabilidades de flujo de trabajo. Siga las instrucciones de [Referencia de uso seguro](/es/enterprise-server@3.22/actions/reference/security/secure-use#writing-workflows) para evitar vulnerabilidades en los flujos de trabajo que podrían provocar la ejecución del código y la introducción de entradas de caché malintencionadas. Para obtener instrucciones más amplias sobre cómo proteger los flujos de trabajo, consulte [Referencia de uso seguro](/es/enterprise-server@3.22/actions/reference/security/secure-use). ## Límites de uso y política de desalojo GitHub aplica límites al almacenamiento en caché y la retención para administrar los costos de almacenamiento y evitar el abuso. Comprender estos límites le ayuda a optimizar el uso de la memoria caché. ### Límites predeterminados GitHub quitará todas las entradas de caché a las que no se haya accedido en más de 7 días. No hay ningún límite en el número de memorias caché que puede almacenar, pero el tamaño total de todas las cachés de un repositorio está limitado. De forma predeterminada, el límite es de 10 GB por repositorio, pero este límite puede aumentarse por los propietarios de la empresa, los propietarios de la organización o los administradores de repositorios. Una vez que un repositorio haya alcanzado su almacenamiento máximo de caché, la directiva de expulsión de caché creará espacio eliminando las cachés en orden de la última fecha de acceso, de más antigua a más reciente. Si excedes el límite, GitHub guardará la nueva caché, pero comenzará a desalojar las cachés hasta que el tamaño total sea inferior al límite del repositorio. El proceso de desalojo de la caché puede provocar inestabilidad de la caché, en la que las entradas de caché se crean y se eliminan con mucha frecuencia. Para reducir esto, puede revisar las memorias caché de un repositorio y tomar medidas correctivas, como quitar el almacenamiento en caché de flujos de trabajo. Consulte [Administración de cachés](/es/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/manage-caches). También puede aumentar el límite de tamaño de caché de un repositorio. Para más información, consulta [Administración de la configuración de Acciones de GitHub para un repositorio](/es/enterprise-server@3.22/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#configuring-cache-storage-for-a-repository). ## Pasos siguientes Para administrar las memorias caché de dependencias, consulta [Administración de cachés](/es/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/manage-caches).