# Référence sur la mise en cache des dépendances Recherchez des informations sur la fonctionnalité de mise en cache des dépendances dans les workflows. ## Utilisation de l’action `cache` L’[`cache`action](https://github.com/actions/cache) tentera d’exécuter la séquence suivante lors de la restauration d’un cache : 1. Tout d’abord, elle recherchera une correspondance exacte avec la `key` que vous avez fournie. 2. Si aucune correspondance exacte n’est trouvée, elle recherchera des correspondances partielles de la `key`. 3. Si aucune correspondance n’est trouvée et que vous avez fourni des `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](#cache-key-matching). 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 ce processus est géré, consultez [Correspondances dans le cache et échecs](#cache-hits-and-misses). 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. Voici un exemple : ```yaml - 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. Voici un exemple : ```yaml restore-keys: | npm-feature-${{ hashFiles('package-lock.json') }} npm-feature- npm- ``` * `enableCrossOsArchive` : **Optional** 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](https://github.com/actions/cache/blob/main/tips-and-workarounds.md#cross-os-cache) dans la documentation sur le Cache Actions. > \[!NOTE] > 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 situés dans le 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 dépôt peuvent créer des demandes de tirage sur la branche de base et accéder aux caches sur 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 : 1. 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`. 2. L’action `cache` se termine et l’étape suivante du travail s’exécute. 3. 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 correspondance du cache, consultez [Correspondance d’une clé de cache](#cache-key-matching). ### 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 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 ``` ### Utilisation de contextes pour créer des clés de cache Une clé de cache peut inclure l’un des contextes, fonctions, littéraux et opérateurs pris en charge par GitHub Actions. Pour plus d’informations, consultez « [Référence des contextes](/fr/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts) » et « [Évaluer des expressions dans les workflows et les actions.](/fr/enterprise-server@3.22/actions/reference/workflows-and-actions/expressions) ». 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éé. ```yaml npm-${{ hashFiles('package-lock.json') }} ``` GitHub évalue l’expression `hash "package-lock.json"` pour dériver la dernière `key`. ```yaml 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 : ```yaml - if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }} name: List the state of node modules continue-on-error: true run: npm list ``` ## Correspondance d’une clé 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 aucun résultat n’est trouvé, elle recherche des correspondances par préfixe pour `key`, et si aucune correspondance n’est trouvée, elle effectue une recherche pour `restore-keys` et la *version*. S’il n’y a toujours aucun résultat dans la branche actuelle, l’action `cache` retente 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](#restrictions-for-accessing-a-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](https://github.com/actions/cache#cache-version) 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 ```yaml 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` : ```yaml 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 : 1. \*\* `npm-feature-d5ea0750` \*\* correspond à un hachage spécifique. 2. \*\* `npm-feature-` \*\* correspond aux clés de cache ayant comme préfixe `npm-feature-`. 3. \*\* `npm-` \*\* correspond à n’importe quelle clé ayant comme préfixe `npm-`. #### Exemple de priorité de recherche ```yaml 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 : 1. Clé `npm-feature-d5ea0750` dans la branche `feature` 2. Clé `npm-feature-` dans la branche `feature` 3. Clé `npm-` dans la branche `feature` 4. Clé `npm-feature-d5ea0750` dans la branche `main` 5. Clé `npm-feature-` dans la branche `main` 6. Clé `npm-` dans la branche `main` ## Actions `setup-*` 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ée et restaure les caches de dépendances pour vous. | Gestionnaires de package | action setup-\* pour la mise en cache | | ------------------------------------------------------------------------------------------------- | ------------------------------------- | | npm, Yarn, pnpm | | | [setup-node](https://github.com/actions/setup-node#caching-global-packages-data) | | | pip, pipenv, Poésie | | | [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) | | | Aller `go.sum` | | | [setup-go](https://github.com/actions/setup-go#caching-dependency-files-and-build-outputs) | | | .NET NuGet | | | [setup-dotnet](https://github.com/actions/setup-dotnet?tab=readme-ov-file#caching-nuget-packages) | | ## 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. > \[!NOTE] > Comme les objets sont récupérés depuis le cache ou placés dans celui-ci directement depuis les exécuteurs, les exécuteurs Actions doivent disposer d’une connectivité directe au stockage d’objets d’Actions configuré dans GitHub Enterprise Server, par exemple AWS S3 ou Stockage Blob Azure. Les exécuteurs auto-hébergés s’authentifient auprès du fournisseur de stockage d’objets blob à l’aide d’une URL d’accès fournie par l’instance GitHub Enterprise Server. Cette URL fournit au fournisseur de Stockage Blob des informations d’identification d’authentification temporaires valides. Ce processus est initié par l’instance elle-même, qui sert d’intermédiaire pour toutes les requêtes adressées au stockage d’objets. > > Cela signifie que `actions/cache` nécessite une connexion HTTPS au Stockage Blob pour fonctionner correctement. > > Toutes les métadonnées sont gérées par le service de cache des artefacts, qui est un microservice au sein de GitHub Actions. > > Pour plus d’informations sur le stockage du cache, consultez [Exigences relatives au stockage externe](/fr/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). ## Accès en cache pour les déclencheurs de flux de travail à faible niveau de fiabilité Certains flux de travail s’exécutent en réponse à des événements qui peuvent être déclenchés par des personnes qui ne disposent pas d’un accès en écriture au dépôt, comme une pull request issue d’un fork ou un commentaire sur une issue. Lorsque ces événements s’exécutent dans le contexte de la branche par défaut, ils peuvent être utilisés pour écrire un cache malveillant qu’un flux de travail plus tard, plus privilégié restaure et approuve. Cette classe d’attaque est connue sous le nom *d’empoisonnement de cache*. Pour réduire ce risque, seuls ces déclencheurs de flux de travail peuvent créer ou remplacer des caches dans l’étendue de la branche par défaut : * `push` * `workflow_dispatch` * `repository_dispatch` * `delete` * `registry_package` * `page_build` * `schedule` Les exécutions déclenchées par tout autre événement qui se résout vers la branche par défaut reçoivent un accès en lecture seule aux caches dans l’étendue de la branche par défaut. Ces exécutions peuvent restaurer des caches existants, mais ne peuvent pas les créer ou les remplacer. Cela inclut des déclencheurs dont la charge utile ou l’acteur de lancement peuvent être influencés par quelqu’un en dehors du référentiel, tel que `pull_request_target`, `issue_comment`et `workflow_run`. L’événement `pull_request` n’est pas affecté. Les caches créés par une `pull_request` exécution sont déjà limités à la référence de fusion (`refs/pull/.../merge`) et ne peuvent pas être écrits dans l’étendue de la branche par défaut. Pour plus d’informations, consultez [Restrictions relatives à l’accès à un cache](#restrictions-for-accessing-a-cache). Lorsqu’une exécution avec accès au cache en lecture seule tente d’enregistrer un cache, l’enregistrement échoue, mais l’étape et le travail ne le font pas. Le flux de travail se poursuit et l’échec est signalé comme un avertissement dans le journal de flux de travail. Dans ce cas, tenez compte des éléments suivants : * Pour conserver les avantages en matière de performances de la mise en cache dans le périmètre de la branche par défaut, assurez-vous qu’il existe un workflow de confiance qui maintient le cache à jour, par exemple une compilation CI déclenchée par un `push` vers la branche par défaut. Ces entrées de cache peuvent ensuite être restaurées par des flux de travail déclenchés par des événements à faible niveau de fiabilité, tels que `pull_request_target`. * Dans les flux de travail à faible niveau de fiabilité, basculez vers une opération de cache de restauration uniquement, par `actions/cache/restore` exemple pour effacer l’utilisation du cache prévue et éviter l’avertissement dans les journaux d’exécution du flux de travail. ## Meilleures pratiques pour l’utilisation de caches en toute sécurité Le contenu du cache n’est pas signé ou vérifié, et toute exécution de flux de travail qui peut lire un cache peut extraire son contenu. Les caches extraits peuvent modifier les fichiers qui sont ensuite exécutés dans une exécution de flux de travail, ce qui entraîne une exécution de code malveillante. Suivez ces pratiques pour réduire les risques de sécurité liés à l’utilisation de caches. * **Ne stockez pas d’informations sensibles dans un cache.** Toute personne pouvant ouvrir une demande de fusion sur votre dépôt peut lire le contenu des caches de la branche de base. N’écrivez pas de secrets, de jetons ou d’informations d’identification dans un chemin mis en cache. Stockez plutôt des valeurs sensibles en tant que secrets. Consultez « [Secrets](/fr/enterprise-server@3.22/actions/concepts/security/secrets) ». * **Enregistrez les caches à partir de déclencheurs approuvés.** Restreindre les écritures de cache dans les flux de travail déclenchés par des acteurs approuvés (généralement ceux ayant un accès en écriture au référentiel). Consultez [l’accès au cache pour les déclencheurs de flux de travail à faible niveau](#cache-access-for-low-trust-workflow-triggers) de fiabilité pour connaître les restrictions par défaut appliquées pour limiter les déclencheurs de flux de travail qui peuvent écrire dans le cache. En outre, envisagez d’utiliser des environnements avec des règles de protection de déploiement pour limiter davantage les flux de travail qui peuvent modifier le cache. Consultez « [Gestion des environnements pour le déploiement](/fr/enterprise-server@3.22/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments) ». * **Suivez les meilleures pratiques de sécurité de flux de travail pour renforcer vos flux de travail :** Limitez les flux de travail qui ont un accès en écriture du cache à ceux qui ont été renforcés contre les vulnérabilités de flux de travail. Suivez les instructions de [Informations de référence sur l’utilisation sécurisée](/fr/enterprise-server@3.22/actions/reference/security/secure-use#writing-workflows) pour empêcher les vulnérabilités dans vos flux de travail susceptibles d’entraîner l’exécution du code et l’introduction d’entrées de cache malveillantes. Pour obtenir des conseils plus larges sur la sécurisation de vos flux de travail, consultez [Informations de référence sur l’utilisation sécurisée](/fr/enterprise-server@3.22/actions/reference/security/secure-use). ## Limites d’utilisation et stratégie d’éviction GitHub applique des limites au stockage et à la rétention du cache pour gérer les coûts de stockage et empêcher les abus. La compréhension de ces limites vous permet d’optimiser l’utilisation de votre cache. ### Limites par défaut GitHub supprime toutes les entrées de cache qui n’ont pas été consultées au cours des 7 derniers jours. Il n’existe aucune limite quant au nombre de caches que vous pouvez stocker, mais la taille totale de tous les caches d’un référentiel est limitée. Par défaut, la limite est de 10 Go par référentiel, mais cette limite peut être augmentée par les propriétaires d’entreprise, les propriétaires d’organisations ou les administrateurs de référentiel. 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 du cache peut entraîner le thrashing du cache, où les caches sont créés et supprimés à une fréquence élevée. Pour réduire ce problème, vous pouvez passer en revue les caches d’un référentiel et prendre des mesures correctives, telles que la suppression de la mise en cache à partir de flux de travail. Voir [Gestion des caches](/fr/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/manage-caches). Vous pouvez également augmenter la limite de taille du cache pour un référentiel. Pour plus d’informations, consultez « [Gestion des paramètres de GitHub Actions pour un référentiel](/fr/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) ». ## Étapes suivantes Pour gérer vos caches de dépendances, consultez [Gestion des caches](/fr/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/manage-caches).