Almacenar en caché las dependencias para agilizar los flujos de trabajo

Acerca de almacenar en caché las dependencias de flujo de trabajo

Las ejecuciones de flujo de trabajo a menudo reutilizan las mismas salidas o dependencias descargadas de una ejecución a otra. Por ejemplo, las herramientas de administración de paquetes y dependencias como Maven, Gradle, npm y Yarn mantienen una caché local de las dependencias descargadas.

Jobs on GitHub-hosted runners start in a clean runner image and must download dependencies each time, causing increased network utilization, longer runtime, and increased cost. Para ayudar a agilizar el tiempo que toma el recrear archivos como dependencias, GitHub puede almacenar los archivos en caché que utilizas frecuentemente en los flujos de trabajo.

Para almacenar las dependencias en caché para un job, puedes utilizar la GitHubacción de cache`` de . La acción crea y restablece un caché identificado con una llave única. Como alternativa, si estás almacenando los siguientes administradores de paquetes en caché, el utilizar sus acciones respectivas de setup-* requiere de una configuración mínima y creará y restablecerá los cachés de dependencia para ti.

Comparar artefactos y caché de dependencias

Los artefactos y el almacenamiento en caché son similares porque brindan la posibilidad de almacenar archivos en GitHub, pero cada característica ofrece diferentes casos de uso y no se puede usar indistintamente.

• Use caching when you want to reuse files that don't change often between jobs or workflow runs, such as build dependencies from a package management system.
• Use artifacts when you want to save files produced by a job to view after a workflow run has ended, such as built binaries or build logs.

Para obtener más información sobre los artefactos de ejecución de flujos de trabajo, consulta la sección "Datos persistentes de flujos de trabajo que utilizan artefactos".

Restricciones para acceder a una caché

Un flujo de trabajo puede acceder y restaurar una caché creada en la rama actual, la rama base (incluidas las ramas base de los repositorios bifurcados) o la rama predeterminada (por lo general main). Por ejemplo, un caché creado en la rama predeterminada sería accesible desde cualquier solicitud de cambios. También, si la rama feature-b tiene la rama base feature-a, un flujo de trabajo activado en feature-b tendría acceso a las cachés creadas en la rama predeterminada (main), feature-a y feature-b.

Las restricciones de acceso proporcionan aislamiento y seguridad de caché al crear una frontera lógica entre las ramas diferentes. Por ejemplo, una solicitud de cambios para la rama feature-c (con la base main) no podría acceder a un caché que se creó para la rama feature-a (con la base main).

Los flujos de trabajo múltiples dentro de un repositorio comparten entradas de caché. Puede accederse a un caché que se crea para una rama dentro de un flujo de trabajo y se puede establecer desde otro flujo de trabajo para el mismo repositorio y rama.

Usando la acción cache

La acción cache intentará restablecer un caché con base en la key que proporciones. Cuando la acción encuentra una memoria caché, la acción restaura los archivos almacenados en la caché al path (ruta) que configures.

Si no hay una coincidencia exacta, la acción creará automáticamente un caché nuevo si el job se completa con éxito. El caché nuevo utilizará la key que proporcionaste y contendrá los archivos que especificaste en path.

De manera opcional, puedes proporcionar una lista de restore-keys para usar cuando la key no coincida con una memoria caché existente. Una lista de restore-keys es útil cuando estás restaurando una caché desde otra rama porque restore-keys pueden coincidir parcialmente con claves de caché. Para obtener más información acerca de la coincidencia restore-keys, consulta Hacer coincidir una clave de caché".

Parámetros de entrada para la acción chache

• key: Obligatorio La clave que se crea cuando se guarda una memoria caché y la clave utilizada para buscar una caché. Puede ser cualquier combinación de variables, valores de contexto, secuencias 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: Requerido La(s) ruta(s) en el ejecutor para almacenar en caché o restablecer.

  • Puedes especificar una sola ruta o puedes agregar varias en líneas separadas. Por ejemplo:

    - name: Cache Gradle packages
      uses: actions/cache@v3
      with:
        path: |
          ~/.gradle/caches
          ~/.gradle/wrapper
    

  • Puedes especificar cualquiera de los directorios o archivos simples y los patrones globales son compatibles.

  • Puedes especificar las rutas absolutas o las relativas al directorio del espacio de trabajo.

• restore-keys: Opcional Una secuencia que contiene claves de restablecimiento alternas, con cada llave de restablecimiento colocada en una línea nueva. Si no se suscita ninguna ocurrencia en caché para key, estas llaves de restablecimiento se utilizarán secuencialmente en el orden proporcionado para encontrar y restablecer un caché. Por ejemplo:

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

Parámetros de salida para la acción cache

• cache-hit: Un valor booleano para indicar que se encontró una coincidencia exacta para la llave.

Ejemplo de uso para la acción cache

Este ejemplo crea una nueva memoria caché cuando los paquetes en el archivo package-lock.json cambian 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@v3

      - name: Cache node modules
        id: cache-npm
        uses: actions/cache@v3
        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 == 'false' }}
        name: List the state of node modules
        continue-on-error: true
        run: npm list

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm build

      - name: Test
        run: npm test

Cuando key empata con un caché existente, a esto se le llama una ocurrencia en caché y la acción restablece los archivos almacenados en caché al directorio de la path.

Cuando key no coincide con un caché existente, se le llama una omisión de caché y se crea un caché nuevo automáticamente si el job se completa con éxito.

Cuando se suscita una omisión de caché, la acción también busca tus restore-keys para cualquier coincidencia:

1. Si proporcionas restore-Keys, la acción cache busca cualquier caché en forma secuencial que coincida 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 el siguiente paso en el job se ejecuta.
3. Si el job se completa con éxito, la acción crea automáticamente un caché nuevo con el contenido del directorio path.

Para obtener una explicación más detallada del proceso de coincidencia de caché, consulta la sección "Hacer coincidir a una llave de caché". Una vez que creas una caché, no puedes cambiar los contenidos de una memoria caché existente, pero puedes crear una nueva caché con una clave nueva.

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 obtener más información, consulta las secciones "Contextos" y "Expresiones".

El utilizar expresiones para crear una key te permite crear automáticamente un caché nuevo cuando las dependencias cambian.

Por ejemplo, puedes crear una key utilizando una expresión que calcule el hash de un archivo package-lock.json de npm. Así que, cuando cambian las dependencias que conforman el archivo package-lock.json, la llave del caché cambia y un caché nuevo se crea automáticamente.

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

GitHub evalúa la expresión hash "package-lock.json" para obtener la última key.

npm-d5ea0750

Utilizar la salida de la acción cache

Puedes utilizar la salida de la acción cache para hacer algo con base en si se suscita una ocurrencia u omisión en caché. Si se suscita una omisión en caché (no se encontró una coincidencia exacta para un caché en la key especificada), la salida cache-hit se configura en false.

En el flujo de trabajo del ejemplo anterior, hay un paso que lista el estado de los módulos de nodo si se suscitó una omisión de caché:

- if: ${{ steps.cache-npm.outputs.cache-hit == 'false' }}
  name: List the state of node modules
  continue-on-error: true
  run: npm list

Hacer coincidir una clave de caché

La acción cache busca primero las coincidencias de caché para key y restore-keys en la rama que contiene la ejecución del flujo de trabajo. Si no hay coincidencias en la rama actual, la acción chache busca a key y restore-keys en la rama padre y en las ramas ascendentes.

restore-keys te permite especificar una lista de llaves de restablecimiento alternas a utilizar cuando hay una omisión de caché en la 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 las 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 resuelven estas restore-keys:

restore-keys: |
  npm-feature-d5ea0750
  npm-feature-
  npm-

La llave de restablecimiento npm-feature- coincide con cualquier llave que inicie con la secuencia npm-feature-. Por ejemplo, ambas llaves: npm-feature-fd3052de y npm-feature-a9b253ff, coinciden con la llave de restablecimiento. 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 llaves de caché que tienen el prefijo npm-feature-.
3. npm coincide con cualquier clave prefijada con npm.

Ejemplo de prioridad de búsqueda

key:
  npm-feature-d5ea0750
restore-keys: |
  npm-feature-
  npm-

Por ejemplo, si una solicitud de cambios contiene una rama de feature y apunta a la rama predeterminada (main), la acción busca a key y restore-keys en el siguiente orden:

1. La llave npm-feature-d5ea0750 en la ruta feature
2. La llave npm-feature- en la rama feature
3. La llave npm- en la rama feature
4. La llave npm-feature-d5ea0750 en la rama main
5. La llave npm-feature- en la rama main
6. La llave npm- en la rama main

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 todos ellos en un repositorio se limita a 10 GB.

If you exceed the limit, GitHub will save the new cache but will begin evicting caches until the total size is less than the repository limit.

Administrar los cachés

Puedes utilizar la API de REST de GitHub Enterprise Cloud para administrar tus cachés. Puedes utilizar la API para listar y borrar entradas de caché y ver tu uso de caché. Para obtener más información, consulta la sección "Caché de GitHub Actions" en la documentación de la API de REST.

You can also install a CLI de GitHub extension to manage your caches from the command line. For more information about the extension, see the extension documentation. For more information about CLI de GitHub extensions, see "Using GitHub CLI extensions."