À propos de la mise en cache des dépendances de workflow
Les exécutions de workflow utilisent souvent les mêmes sorties ou dépendances téléchargées d’une exécution à l’autre. Par exemple, les outils de gestion des packages et des dépendances comme Maven, Gradle, npm et Yarn conservent un cache local des dépendances téléchargées.
Les travaux sur les exécuteurs hébergés par GitHub démarrent dans une image d’exécuteur propre et doivent télécharger des dépendances à chaque fois, ce qui entraîne une utilisation accrue du réseau, un runtime plus long et un coût plus important. Pour raccourcir le temps nécessaire pour recréer des fichiers tels que des dépendances, GitHub peut mettre en cache des fichiers que vous utilisez fréquemment dans des workflows.
Pour mettre en cache les dépendances d’un travail, vous devez utiliser l’action cache
de GitHub. L’action crée et restaure un cache identifié par une clé unique. Ou bien, 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 |
pip, pipenv, Poetry | setup-python |
Gradle, Maven | setup-java |
RubyGems | setup-ruby |
Go go.sum | setup-go |
.NET/NuGet | setup-dotnet |
Avertissement : Tenez compte de ce qui suit lors de l’utilisation d’une mise en cache avec GitHub Actions :
- Nous vous recommandons de ne pas stocker d’informations sensibles dans le cache. Par exemple, les informations sensibles peuvent inclure des jetons d’accès ou des informations d’identification de connexion stockées dans un fichier se trouvant dans le chemin du cache. En outre, les programmes d’interface de ligne de commande (CLI) comme
docker login
peuvent enregistrer des informations d’identification d’accès dans un fichier de configuration. 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. Les duplications (forks) d’un dépôt peuvent également créer des demandes de tirage sur la branche de base et accéder aux caches sur cette branche. - Lorsque vous utilisez des exécuteurs auto-hébergés, les caches des exécutions du workflow sont stockés sur le stockage cloud appartenant à GitHub. Une solution de stockage appartenant au client n’est disponible qu’avec GitHub Enterprise Server.
Comparaison des artefacts et de la mise en cache des dépendances
Les artefacts et la mise en cache sont similaires, car ils permettent de stocker des fichiers sur GitHub, mais chaque fonctionnalité offre des cas d’utilisation différents et ne peut pas être utilisée de manière interchangeable.
- Utilisez la mise en cache lorsque vous souhaitez réutiliser des fichiers qui ne changent pas souvent entre les travaux ou les exécutions de workflow, comme les dépendances de build d’un système de gestion de packages.
- Utilisez les artefacts lorsque vous souhaitez enregistrer des fichiers générés par un travail pour les afficher au terme de l’exécution d’un workflow, comme des fichiers binaires générés ou des journaux de génération.
Pour plus d’informations sur les artefacts d’exécution de workflow, consultez « Stockage et partage des données d’un workflow ».
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.
Utilisation de l’action cache
L’action cache
tente de restaurer un cache en fonction de la key
que vous fournissez. Lorsque l’action trouve un cache qui correspond exactement à la clé, l’action restaure les fichiers mis en cache dans le chemin (path
) que vous configurez.
Vous pouvez éventuellement fournir une liste d’éléments restore-keys
à utiliser si la clé (key
) ne correspond pas à un cache existant. Une liste d’éléments restore-keys
est utile lorsque vous restaurez un cache à partir d’une autre branche car restore-keys
peut faire correspondre partiellement des clés de cache. Pour plus d’informations sur la correspondance d’éléments restore-keys
, consultez « Correspondance d’une clé 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@v3 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 pourkey
, 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 estfalse
. Pour plus d’informations, consultez Cache entre systèmes d’exploitation dans la documentation sur le Cache Actions.
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’actioncache
recherche de manière séquentielle les caches qui correspondent à la liste derestore-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
.
- Lorsqu’il existe une correspondance exacte, l’action restaure les fichiers du cache dans le répertoire
- 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 correspondance du cache, consultez « Correspondance d’une clé 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
.
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@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 != '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@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 != '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 « Accès à des informations contextuelles sur l’exécution d’un workflow » 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 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. S’il n’y a pas d’accès, il recherche restore-keys
et la version. S’il n’y a toujours aucun accès 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 ».
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éfixenpm-feature-
.npm-
correspond à n’importe quelle clé de cache ayant comme préfixenpm-
.
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 branchefeature
- Clé
npm-feature-
dans la branchefeature
- Clé
npm-
dans la branchefeature
- Clé
npm-feature-d5ea0750
dans la branchemain
- Clé
npm-feature-
dans la branchemain
- Clé
npm-
dans la branchemain
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’existe aucune limite au nombre de caches que vous pouvez stocker, mais la taille totale de tous les caches d’un dépôt est limitée à 10 Go. Une fois qu’un dépôt a atteint son stockage de cache maximal, la stratégie d’éviction du cache crée de l’espace en supprimant les caches les plus anciens du dépôt.
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 provoquer un vidage du cache, où 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. Pour plus d’informations, consultez « Gestion des caches ».
Gestion des caches
Pour gérer les caches créés à partir de vos workflows, vous pouvez :
- Afficher la liste de toutes les entrées de cache pour un référentiel.
- Filtrer et trier la liste des caches à l’aide de métadonnées spécifiques telles que la taille du cache, l’heure de création ou l’heure du dernier accès.
- Supprimer les entrées de cache d’un référentiel.
- Surveiller l’utilisation du cache d’agrégation pour les référentiels et les organisations.
Il existe plusieurs façons de gérer les caches de vos référentiels :
-
Utilisation de l’interface web GitHub, comme indiqué ci-dessous.
-
Utilisation de l’API REST. Pour plus d’informations, consultez « Points de terminaison REST pour l’API cache GitHub Actions ».
-
Installation de la sous-commande
gh cache
pour gérer vos caches à partir de la ligne de commande. Pour plus d’informations, consultez la documentation GitHub CLI.Remarque : si vous effectuez cette opération manuellement, vérifiez que vous disposez de la version 2.32.0 ou ultérieure de l’interface CLI installée.
Affichage des entrées de cache
Vous pouvez utiliser l’interface web pour afficher une liste des entrées de cache d’un référentiel. Dans la liste des caches, vous pouvez voir la quantité d’espace disque utilisée par chaque cache, la date de création du cache et la date de la dernière utilisation du cache.
-
Sur GitHub, accédez à la page principale du référentiel.
-
Sous le nom de votre dépôt, cliquez sur Actions.
-
Dans la barre latérale gauche, sous la section « Gestion », cliquez sur Caches.
-
Passez en revue la liste des entrées de cache pour le référentiel.
- Pour rechercher les entrées de cache utilisées pour une branche spécifique, cliquez sur le menu déroulant Branche et sélectionnez une branche. La liste des caches affiche tous les caches utilisés pour la branche sélectionnée.
- Pour rechercher des entrées de cache avec une clé de cache spécifique, utilisez la syntaxe
key: key-name
dans le champ Filtrer les caches. La liste des caches affiche les caches de toutes les branches où la clé a été utilisée.
Suppression d’entrées de cache
Les utilisateurs ayant un accès write
à un référentiel utiliser l’interface web GitHub pour supprimer les entrées de cache.
-
Sur GitHub, accédez à la page principale du référentiel.
-
Sous le nom de votre dépôt, cliquez sur Actions.
-
Dans la barre latérale gauche, sous la section « Gestion », cliquez sur Caches.
-
À droite de l’entrée du cache que vous souhaitez supprimer, cliquez sur .
Suppression forcée d’entrées de cache
Les caches ont des restrictions d’étendue de branche en place, ce qui signifie que certains caches ont des options d’utilisation limitée. Pour plus d’informations sur les restrictions d’étendue de cache, consultez « Mise en cache des dépendances pour accélérer les workflows ». Si les caches limités à une branche spécifique utilisent beaucoup de quota de stockage, cela peut entraîner la création et la suppression des caches de la branche default
à une fréquence élevée.
Par exemple, un dépôt peut avoir de nombreuses nouvelles demandes de tirage ouvertes, chacune avec ses propres caches qui sont limités à cette branche. Ces caches peuvent occuper la majorité du stockage du cache pour ce dépôt. Une fois qu’un dépôt a atteint son stockage de cache maximal, la stratégie d’éviction du cache crée de l’espace en supprimant les caches les plus anciens du dépôt. Afin d’éviter un écroulement du cache dans ce cas, vous pouvez configurer des workflows de façon à supprimer les caches à une cadence plus rapide que celle de la stratégie d’éviction du cache. Vous pouvez utiliser l’extension CLI gh-actions-cache
pour supprimer des caches pour des branches spécifiques.
L’exemple de workflow suivant utilise gh-actions-cache
pour supprimer jusqu’à 100 caches créés par une branche une fois qu’une demande de tirage est fermée.
Pour exécuter l’exemple suivant sur des demandes de tirage entre référentiels ou des demandes de tirage à partir de duplications, vous pouvez déclencher le flux de travail avec l’événement pull_request_target
. Si vous utilisez pull_request_target
pour déclencher le flux de travail, des considérations de sécurité sont à prendre en compte. Pour plus d’informations, consultez « Événements qui déclenchent des flux de travail ».
name: cleanup caches by a branch
on:
pull_request:
types:
- closed
jobs:
cleanup:
runs-on: ubuntu-latest
steps:
- name: Cleanup
run: |
gh extension install actions/gh-actions-cache
echo "Fetching list of cache key"
cacheKeysForPR=$(gh actions-cache list -R $REPO -B $BRANCH -L 100 | cut -f 1 )
## Setting this to not fail the workflow while deleting cache keys.
set +e
echo "Deleting caches..."
for cacheKey in $cacheKeysForPR
do
gh actions-cache delete $cacheKey -R $REPO -B $BRANCH --confirm
done
echo "Done"
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
REPO: ${{ github.repository }}
BRANCH: refs/pull/${{ github.event.pull_request.number }}/merge
Vous pouvez également utiliser l’API pour répertorier ou supprimer l’ensemble des caches à votre propre rythme. Pour plus d’informations, consultez « Points de terminaison REST pour l’API cache GitHub Actions ».