Referencia de almacenamiento en caché de dependencias

Uso de acciones de cache

La acción 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é.

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, consulta Aciertos y errores de caché.

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:

    - 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:

  restore-keys: |
    npm-feature-${{ hashFiles('package-lock.json') }}
    npm-feature-
    npm-
  

• enableCrossOsArchive: Opcional Valor booleano que, cuando se habilita, permite que los ejecutores de Windows guarden o restauren memorias caché independientes 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 en la documentación de caché de Acciones.

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é.

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.

name: Caching with npm
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - 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

name: Caching with npm
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - 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 Referencia de contextos y Evaluación de expresiones en flujos de trabajo y acciones.

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é.

npm-${{ hashFiles('package-lock.json') }}

GitHub evalúa la expresión hash "package-lock.json" para generar el key final.

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é:

- 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, consulta Restricciones para acceder a una memoria caché.

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é 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

restore-keys: |
  npm-feature-${{ hashFiles('package-lock.json') }}
  npm-feature-
  npm-

El ejecutor evalúa las expresiones, que se resuelven en estos restore-keys:

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

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.

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.

Límites de uso y política de desalojo

GitHub eliminará todas las entradas de caché a las que no se haya accedido en más de 7 días. No hay límite en la cantidad de cachés que puedes almacenar, pero el tamaño total de todas las cachés en un repositorio está limitado hasta 10 GB. 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 expulsión de caché puede provocar la paginación excesiva de caché, donde las memorias caché se crean y eliminan con una alta frecuencia. Para reducir esto, puedes revisar las memorias caché de un repositorio y tomar medidas correctivas, como quitar el almacenamiento en caché de flujos de trabajo específicos. Consulta Administración de cachés.

Pasos siguientes

Para administrar las memorias caché de dependencias, consulta Administración de cachés.