Verrouillage des dépendances d’action dans les flux de travail d’un dépôt

Générez un lockfile qui épingle chaque action que vos workflows utilisent à un commit vérifié et conservez-le à jour à mesure que vos dépendances changent.

Qui peut utiliser cette fonctionnalité ?

People with write access to a repository

GitHub Enterprise Cloud

Dans cet article

Le verrouillage des dépendances de vos flux de travail garantit que les actions que vous référencez contiennent le même code que celui qui a été initialement examiné. Pour plus d’informations, consultez « Fichiers de verrouillage des dépendances du workflow ».

1. Vérifiez vos références d’actions

La création d’un fichier de verrouillage épingle vos dépendances aux commits en fonction de la référence de branche actuelle ou de balise. Vérifiez qu’il s’agit des versions que vous souhaitez verrouiller.

Vérifiez que chaque uses référence de vos flux de travail pointe vers une version actuelle prise en charge de l’action. Pour connaître les meilleures pratiques, consultez Informations de référence sur l’utilisation sécurisée.

Si l’un de vos workflows appelle un flux de travail réutilisable dans un autre référentiel, vérifiez également ces références. Les dépendances d’un flux de travail réutilisable sont couvertes par le fichier de verrouillage du référentiel où il est défini, et non par votre fichier de verrou. Ce dépôt source a besoin de son propre fichier lock pour une couverture complète. Si votre organisation gère les flux de travail partagés, intégrez d’abord ces dépôts. Consultez « Réutilisation des configurations de flux de travail ».

Nous vous recommandons de laisser Dependabot gérer vos GitHub Actions dépendances. S’il n’est pas déjà activé, activez-le avant de créer le fichier lockfile. Consultez « Maintenir vos actions à jour avec Dependabot ».

2. Installer l’extension actions-lock

  1. Installez le GitHub CLI.

  2. Installez l’extension.

    Bash
    gh extension install github/gh-actions-lock

Conseil

Pour mettre à jour l’extension ultérieurement, exécutez gh extension upgrade gh-actions-lock.

3. Générer le fichier de verrouillage

À partir de la racine de votre dépôt, exécutez l’extension sans argument. Il analysera chaque workflow sous .github/workflows/, épinglera chaque action résolvable à un SHA de commit et écrira le fichier de verrouillage.

Bash
gh actions-lock

Pour intégrer un seul flux de travail au lieu de l’ensemble du répertoire, passez son chemin d’accès.

Bash
gh actions-lock .github/workflows/ci.yml

L’extension ne suit ni ne verrouille jamais une action sur un chemin d’accès local (uses: ./…). Un chemin ./ exécute tout ce qui est extrait dans l’espace de travail de l’exécuteur, de sorte que l’extension ne peut pas l’épingler ou voir ce qu’il utilise. L’utilisation d’un chemin $/ exécute l’action de votre propre dépôt au commit du workflow, de sorte qu’elle est épinglée et que les actions qu’elle utilise peuvent être verrouillées. Pour une comparaison des deux, consultez Syntaxe de flux de travail pour GitHub Actions.

Si une action locale dans votre checkout utilise d’autres actions, l’extension signale une erreur local-action et n’écrit rien, car ces actions échoueraient au moment de l’exécution sans entrées dans le fichier de verrouillage. Pour verrouiller l’action locale en tant que référence au même dépôt, exécutez :

Bash
gh actions-lock --migrate-local-actions

Pour conserver la référence ./ et la signaler plutôt comme un avertissement, passez --ignore-local-actions. Consultez Conserver une action de chemin d’accès local.

Pour l’ensemble complet d’options, exécutez gh actions-lock --help. Pour obtenir de l’aide sur une erreur ou un avertissement spécifique, consultez le guide de résolution des problèmes gh-actions-lock.

Conserver une action de chemin local

Si vous passez --ignore-local-actions, ce qui se passe au moment de l’exécution dépend des actions que l’action locale utilise :

  • Il n’utilise aucune autre action, par exemple, uniquement des étapes run: : le flux de travail s’exécute normalement.
  • Il utilise des actions qui ont des entrées de lockfile pour le même workflow : le workflow s’exécute normalement.
  • Il utilise une action qui n’a pas d’entrée de fichier de verrouillage pour ce flux de travail : le travail échoue lorsqu’il atteint l’étape de l’action locale, avec une erreur telle que lockfile missing pin for octo-org/setup-tool@v2.0.0. Les étapes précédentes ont déjà été exécutées.

Nous vous recommandons plutôt --migrate-local-actions, afin que l’action s’exécute en tant que référence épinglée $/. Si vous devez conserver la référence ./, donnez les entrées du fichier de verrouillage du workflow pour les actions qu’utilise l’action locale. Ajoutez une action composite qui utilise les mêmes actions, avec les mêmes références et appelez-la à partir du flux de travail dans une étape qui ne s’exécute jamais. Ensuite, exécutez gh actions-lock --ignore-local-actions.

# .github/actions/lock-local-deps/action.yml
name: Lock local action dependencies
description: Never runs. Lists the actions that ./.github/actions/build uses.
runs:
  using: composite
  steps:
    - uses: octo-org/setup-tool@v2.0.0

# In the workflow
steps:
  - uses: actions/checkout@v6
  - if: false
    uses: $/.github/actions/lock-local-deps
  - uses: ./.github/actions/build

Les entrées doivent être enregistrées pour le même flux de travail. Une entrée enregistrée uniquement pour un autre flux de travail ne compte pas. Lorsque les dépendances de l’action locale changent, mettez à jour l’action composite et exécutez gh actions-lock --ignore-local-actions à nouveau.

4. Passez en revue les modifications et effectuez le commit

L’extension modifie plus que le fichier lockfile, donc passez en revue la différence complète avant de valider. Il réécrit également vos références de flux de travail uses pour pointer vers la version spécifique qu’il a trouvée, de sorte qu’une référence telle que octo-org/deploy-action@v3 peut devenir octo-org/deploy-action@v3.1.0. Cela rend la référence plus spécifique sans modifier le commit auquel elle correspond.

Important

Si votre dépôt, votre organisation ou votre entreprise autorise uniquement les actions spécifiées, vérifiez la liste d’autorisation avant de valider. Une fois qu’un workflow est intégré, la liste d’autorisation est vérifiée par rapport aux SHA de commit verrouillés au lieu de tags, car un tag peut être déplacé vers un code différent, mais un SHA verrouillé ne peut pas. Les entrées épinglées à une balise, telles que actions/checkout@v6, ne correspondent plus une fois qu’un flux de travail est ajouté. Utilisez plutôt un caractère générique ou le SHA du commit complet. Consultez « Gestion des paramètres de GitHub Actions pour un référentiel ».

Si vous avez passé --migrate-local-actions, l’extension réécrit également les références aux actions dans votre propre référentiel, de uses: $/… à uses: ./…, dans vos flux de travail et les fichiers action.yml de votre référentiel. Cela se produit uniquement lorsque vous passez l’option, car les deux formes se comportent différemment. Un ./ chemin est résolu par rapport à ce qui se trouve dans l’espace de travail de l’exécuteur, tandis qu’une $/… référence s’exécute toujours au commit propre au workflow, de sorte qu’elle n’a pas besoin d’entrée de fichier de verrouillage. Passez en revue chaque ligne réécrite.

5. Conserver le fichier de verrouillage à jour

Conservez le lockfile à jour avec les fichiers de workflow de votre référentiel et les mises à jour de sécurité.

  1. Réexécutez l’extension lorsque vous modifiez les dépendances. Réexécutez gh actions-lock chaque fois que vous ajoutez un flux de travail qui a uses des dépendances, ou ajoutez ou supprimez uses des dépendances dans un flux de travail existant.

  2. Laissez Dependabot gérer les incréments de version. Lorsque vous Dependabot ouvrez une mise à jour de version pour une action dans un workflow que vous avez configuré, il régénère également l’entrée de fichier de verrouillage correspondante dans la même pull request. Votre fichier de flux de travail et votre fichier lockfile ne doivent pas diverger.

Dependabot met uniquement à jour les entrées du lockfile pour les workflows déjà onboardés. S’il met à jour une action dans un flux de travail qui n’est pas dans le fichier lockfile, il met à jour le fichier de flux de travail comme d’habitude et laisse le fichier lockfile inchangé.

  1. Résoudre à nouveau les références qui ont été déplacées. La façon dont l’extension gère une référence déplacée dépend de la référence :

    • Une branche ou une version partielle, telle que main ou v3, conserve son commit verrouillé et l’extension signale un avertissement ref-moved. Pour l’avancer, vérifiez l’historique en amont, puis exécutez gh actions-lock --relock.
    • Une balise de version complète, telle que v3.1.0, doit pointer vers son commit verrouillé. Si la balise a été déplacée, l’extension signale une erreur tant que vous n’avez pas exécuté gh actions-lock --relock ou modifié la ligne uses:.
    • Un historique réécrit, où le commit verrouillé n’est plus dans l’historique de la référence, par exemple après un push forcé, est une erreur que --relock ne résout pas. Une fois que vous avez examiné l’historique en amont, exécutez gh actions-lock --accept-moved. N’utilisez pas --accept-moved en automatisation.

Examen des modifications du lockfile

Passez en revue les modifications apportées au fichier de verrouillage comme toute autre modification de dépendance :

  • Un élément modifié commit est le code que vos workflows exécuteront. Traitez-le de la façon dont vous traitez toute autre mise à jour de version de dépendance.
  • Un(e) owner_id ou repo_id modifié(e) devrait être rare. Cela signifie que le dépôt derrière ce nom n’est pas celui que vous avez verrouillé à l’origine, donc examinez avant de fusionner.

Si un fichier lock semble incorrect, corrigez vos fichiers de workflow et régénérez-le. Ne modifiez jamais le fichier de verrouillage manuellement.

Étapes suivantes

Une fois que vous avez généré un fichier de verrouillage pour un référentiel, vérifiez qu’il est appliqué et à jour sans que les développeurs n’aient besoin de se rappeler d’exécuter des commandes. Consultez « Imposer l’utilisation de fichiers de verrouillage pour les dépendances d’action ».