Référence sur la mise en cache des dépendances

`cache` utilisation de l’action

L’action cache tentera d’exécuter la séquence suivante lors de la restauration d’un cache :

Tout d’abord, elle recherchera une correspondance exacte avec le key que vous avez fourni.
Si aucune correspondance exacte n’est trouvée, elle recherchera des correspondances partielles avec le key.
Si aucune correspondance n’est trouvée et que vous avez fourni le restore-keys, ces clés seront vérifiées séquentiellement pour trouver des correspondances partielles. Pour plus d’informations, consultez Correspondance des clés de cache.

S’il existe une correspondance exacte avec la clé key fournie, cela est considéré comme un accès au cache. Si aucun cache ne correspond exactement à la clé key fournie, cela est considéré comme un échec de cache. En cas d’échec d’accès au cache, l’action crée automatiquement un cache si le travail se termine correctement. Le nouveau cache utilise la key que vous avez fournie, et contient les fichiers que vous spécifiez dans path. Pour plus d’informations sur la façon dont cela est géré, consultez « Correspondances dans le cache et échecs ».

Vous ne pouvez pas modifier le contenu d’un cache existant. Au lieu de cela, vous pouvez créer un cache avec une nouvelle clé.

Paramètres d’entrée pour l’action `cache`

key : Obligatoire Clé créée lors de l’enregistrement d’un cache et clé utilisée pour rechercher un cache. Il peut s’agir de d’une combinaison quelconque de variables, de valeurs de contexte, de chaînes statiques et de fonctions. Les clés ont une longueur maximale de 512 caractères, et les clés dépassant la longueur maximale entraînent l’échec de l’action.
path : Obligatoire Chemin(s) d’accès sur l’exécuteur à mettre en cache ou à restaurer.
- Vous pouvez spécifier un chemin d’accès unique ou en ajouter plusieurs sur des lignes distinctes. Par exemple :
```
- name: Cache Gradle packages
  uses: actions/cache@v4
  with:
    path: |
      ~/.gradle/caches
      ~/.gradle/wrapper
```
- Vous pouvez spécifier des répertoires ou des fichiers individuels, et les modèles Glob sont pris en charge.
- Vous pouvez spécifier des chemins d’accès absolus ou relatifs au répertoire de l’espace de travail.
restore-keys : Facultatif Chaîne contenant d’autres clés de restauration, chacune placée sur une nouvelle ligne. Si aucune correspondance dans le cache n’a lieu pour key, ces clés de restauration sont utilisées séquentiellement dans l’ordre fourni pour trouver et restaurer un cache. Par exemple :
```
restore-keys: |
  npm-feature-${{ hashFiles('package-lock.json') }}
  npm-feature-
  npm-
```
enableCrossOsArchive : Facultatif Valeur booléenne qui, lorsqu’elle est activée, permet aux exécuteurs Windows d’enregistrer ou de restaurer des caches indépendamment du système d’exploitation sur lequel le cache a été créé. Si ce paramètre n’est pas défini, la valeur par défaut est false. Pour plus d’informations, consultez Cache entre systèmes d’exploitation dans la documentation sur le Cache Actions.

Remarque

Nous vous recommandons de ne pas stocker d’informations sensibles, telles que des jetons d’accès ou des identifiants de connexion, dans les fichiers du chemin du cache. Toute personne disposant d’un accès en lecture peut créer une demande de tirage sur un dépôt et accéder au contenu d’un cache. De plus, les duplications (forks) d’un référentiel peuvent créer des demandes de tirage sur la branche de base et accéder aux caches de cette branche.

Paramètres de sortie pour l’action `cache`

cache-hit : Valeur booléenne indiquant une correspondance exacte trouvée pour la clé.

Correspondances dans le cache et échecs

Quand key correspond exactement à un cache existant, il s’agit d’une correspondance dans le cache, et l’action restaure les fichiers mis en cache dans le répertoire path.

Quand key ne correspond pas à un cache existant, il s’agit d’une absence dans le cache, et un nouveau cache est automatiquement créé si le travail se termine correctement.

Quand une absence dans le cache se produit, l’action recherche également des correspondances dans vos restore-keys spécifiées :

Si vous fournissez des restore-keys, l’action cache recherche de manière séquentielle les caches qui correspondent à la liste de restore-keys.
- Lorsqu’il existe une correspondance exacte, l’action restaure les fichiers du cache dans le répertoire path.
- S’il n’existe aucune correspondance exacte, l’action recherche des correspondances partielles des clés de restauration. Lorsque l’action trouve une correspondance partielle, le cache le plus récent est restauré dans le répertoire path.
L’action cache se termine et l’étape suivante du travail s’exécute.
Si le travail se termine correctement, l’action crée automatiquement un nouveau cache avec le contenu du répertoire path.

Pour une explication plus détaillée du processus de correspondance des caches, consultez Correspondance des clés de cache.

Exemple d’utilisation de l’action `cache`

Cet exemple crée un cache en cas de changement des packages du fichier package-lock.json ou du système d’exploitation de l’exécuteur. La clé de cache utilise des contextes et des expressions pour générer une clé qui inclut le système d’exploitation de l’exécuteur et un hachage SHA-256 du fichier package-lock.json.

YAML

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

Utilisation de contextes pour créer des clés de cache

Une clé de cache peut inclure les contextes, fonctions, littéraux et opérateurs pris en charge par GitHub Actions. Pour plus d’informations, consultez « Référence sur les contextes » et « Évaluer les expressions dans les workflows et les actions ».

L’utilisation d’expressions pour créer une clé (key) vous permet de créer automatiquement un cache lorsque des dépendances changent.

Par exemple, vous pouvez créer une key à l’aide d’une expression qui calcule le hachage d’un fichier npm package-lock.json. Ainsi, lorsque les dépendances qui composent le fichier package-lock.json changent, la clé du cache change et un nouveau cache est automatiquement créé.

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

GitHub évalue l’expression hash "package-lock.json" pour dériver la clé (key) finale.

npm-d5ea0750

Utilisation de la sortie de l’action `cache`

Vous pouvez utiliser la sortie de l’action cache pour effectuer quelque chose en fonction de l’occurrence d’une correspondance dans le cache ou d’une absence dans le cache. Quand une correspondance exacte est trouvée pour un cache pour l’élément key spécifié, la sortie cache-hit est définie sur true.

Dans l’exemple de workflow ci-dessus, une étape répertorie l’état des modules Node si une absence dans le cache s’est produite :

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

Correspondance des clés de cache

L’action cache recherche d’abord des correspondances dans le cache pour key et dans le cache version dans la branche contenant l’exécution du workflow. Si aucune correspondance n’est trouvée, elle recherche des correspondances de préfixe pour le key, et si aucune correspondance n’est trouvée, elle recherchera le restore-keys et la version. Si aucune correspondance n’est trouvée dans la branche active, l’action cache réessaiera d’exécuter les mêmes étapes sur la branche par défaut. Notez que les restrictions d’étendue s’appliquent pendant la recherche. Pour plus d’informations, consultez « Restrictions relatives à l’accès à un cache ».

La version du cache est un moyen de marquer un cache avec les métadonnées de path et de l’outil de compression utilisé lors de la création du cache. Cela garantit que l’exécution du workflow correspond de manière unique à un cache qu’il peut réellement décompresser et utiliser. Pour plus d’informations, consultez Version du cache dans la documentation Cache Actions.

restore-keys vous permet de spécifier une liste de clés de restauration alternatives à utiliser en cas d’absence dans le cache sur key. Vous pouvez créer plusieurs clés de restauration classées de la plus spécifique à la moins spécifique. L’action cache recherche les restore-keys dans un ordre séquentiel. Lorsqu’une clé n’a pas de correspondance directe, l’action recherche les clés ayant comme préfixe la clé de restauration. S’il existe plusieurs correspondances partielles pour une clé de restauration, l’action retourne le dernier cache créé.

Exemple utilisant plusieurs clés de restauration

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

L’exécuteur évalue les expressions, qui sont résolues en ces restore-keys :

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

La clé de restauration npm-feature- correspond à n’importe quelle clé qui commence par la chaîne npm-feature-. Par exemple, les deux clés npm-feature-fd3052de et npm-feature-a9b253ff correspondent à la clé de restauration. Le cache ayant la date de création la plus récente est utilisé. Dans cet exemple, les clés sont recherchées dans l’ordre suivant :

npm-feature-d5ea0750 correspond à un hachage spécifique.
npm-feature- correspond aux clés de cache ayant comme préfixe npm-feature-.
npm- correspond à n’importe quelle clé de cache ayant comme préfixe npm-.

Exemple de priorité de recherche

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

Par exemple, si une demande de tirage contient une branche feature et cible la branche par défaut (main), l’action recherche key et restore-keys dans l’ordre suivant :

Clé npm-feature-d5ea0750 dans la branche feature
Clé npm-feature- dans la branche feature
Clé npm- dans la branche feature
Clé npm-feature-d5ea0750 dans la branche main
Clé npm-feature- dans la branche main
Clé npm- dans la branche main

`setup-*` actions pour des gestionnaires de package spécifiques

Si vous mettez en cache les gestionnaires de package répertoriés ci-dessous, l’utilisation de leurs actions setup-* respectives nécessite une configuration minimale et créera et restaurera les caches de dépendances pour vous.

Gestionnaires de package	action setup-* pour la mise en cache
npm, Yarn, pnpm	setup-node
pip, pipenv, Poetry	setup-python
Gradle, Maven	setup-java
RubyGems	setup-ruby
Go `go.sum`	setup-go
.NET/NuGet	setup-dotnet

Restrictions relatives à l’accès à un cache

Les restrictions d’accès fournissent l’isolement et la sécurité du cache en créant une limite logique entre les différentes branches ou étiquettes. Les exécutions de workflow peuvent restaurer les caches créés dans la branche actuelle ou dans la branche par défaut (généralement main). Si une exécution de workflow est déclenchée pour une demande de tirage (pull request), elle peut également restaurer les caches créés dans la branche de base, y compris les branches de base des référentiels dupliqués. Par exemple, si la branche feature-b a la branche feature-a de base, une exécution de workflow déclenchée sur une demande de tirage a accès aux caches créés dans la branche par défaut main, la branche feature-a de base et la branche feature-b actuelle.

Les exécutions de workflow ne peuvent pas restaurer les caches créés pour les branches enfants ou les branches sœurs. Par exemple, un cache créé pour la branche enfant feature-b ne serait pas accessible à une exécution de workflow déclenchée sur la branche main parente. De même, un cache créé pour la branche feature-a avec la branche main de base n’est pas accessible à sa branche feature-c sœur avec la branche main de base. Les exécutions de workflow ne peuvent pas non plus restaurer les caches créés pour différents noms d’étiquettes. Par exemple, un cache créé pour l’étiquette release-a (à partir de la base main) ne sera pas accessible à une exécution de workflow déclenchée pour l’étiquette release-b (avec la base main).

Lorsqu’un cache est créé par une exécution de workflow déclenchée sur une demande de tirage, le cache est créé pour la référence de fusion (refs/pull/.../merge). Pour cette raison, le cache aura une étendue limitée et ne peut être restauré que par les ré-exécutions de la demande de tirage. Il ne peut pas être restauré par la branche de base ou d’autres demandes de tirage ciblant cette branche de base.

Plusieurs exécutions de workflow dans un référentiel peuvent partager des caches. Un cache créé pour une branche au sein d’une exécution de workflow est accessible et peut être restauré à partir d’une autre exécution de workflow pour le même référentiel et la même branche.

Limites d’utilisation et stratégie d’éviction

GitHub supprime toutes les entrées de cache qui n’ont pas été consultées depuis plus de 7 jours. Il n'y a pas de limite au nombre de caches que vous pouvez stocker, mais la taille totale de tous les caches dans un référentiel est limitée à 10 Go. Une fois qu’un référentiel a atteint sa capacité maximale de stockage dans le cache, la stratégie d’éviction du cache libère de l’espace en supprimant les caches par ordre de date d’accès, du plus ancien au plus récent.

Si vous dépassez la limite, GitHub enregistrera le nouveau cache, mais commencera à écarter les caches jusqu’à ce que la taille totale soit inférieure à la limite du dépôt. Le processus d'éviction de la mémoire cache peut entraîner une saturation de la mémoire cache, c'est-à-dire que les caches sont créés et supprimés à une fréquence élevée. Pour limiter ce problème, vous pouvez passer en revue les caches d’un référentiel et prendre des mesures correctives, notamment la suppression de la mise en cache de workflows spécifiques. Consultez Gestion des caches.

Étapes suivantes

Pour gérer vos caches de dépendances, consultez Gestion des caches.

Référence sur la mise en cache des dépendances

Dans cet article