Fichiers de verrouillage des dépendances du workflow

Un fichier de verrouillage fige chaque action dont vos flux de travail dépendent sur un commit vérifié, de sorte que le code que vous avez examiné est le code qui s’exécute.

Dans cet article

Pourquoi verrouiller les dépendances de workflow ?

Les flux de travail font souvent référence à une action par une balise ou une branche, comme uses: octo-org/deploy-action@v3 ou uses: octo-org/deploy-action@main. GitHub Actions résout cette référence vers le commit vers lequel pointe la balise ou la branche au moment de l’exécution.

Les tags et les branches peuvent être déplacés. Par conséquent, il n’est pas garanti qu’il s’agisse du code que l’auteur du flux de travail a examiné à l’origine. Si le compte d’un mainteneur amont est compromis et qu’un tag est repointé, vos dépôts pourraient exécuter du code malveillant.

Un fichier de verrouillage des dépendances du workflow associe un SHA de commit à chaque action dont dépendent vos workflows, y compris les dépendances transitives. Il n’épingle pas les appels aux flux de travail réutilisables (jobs.<job_id>.uses). Pour épingler un flux de travail réutilisable, référencez-le par son SHA de commit complet. Un fichier de verrouillage contrôle le code d’action qui s’exécute sur le runner. Il ne contrôle pas d’autres entrées de build, telles que les paramètres d’entrée, les secrets ou l’image de l’exécuteur. Un fichier de verrouillage vous donne les informations suivantes pour le code d’action qu’il couvre :

  • Résolution reproductible des dépendances d’action
  • Modifications des dépendances révisables et Dependabot mises à jour de version
  • Inventaire auditable des dépendances d’action de vos systèmes CI/CD

Comment fonctionne le fichier lockfile ?

Le fichier de verrouillage est défini dans un référentiel à l’adresse .github/workflows/actions.lock. Elle est générée par gh actions-lock, une GitHub CLI extension et ne doit jamais être modifiée manuellement.

Vous pouvez migrer les flux de travail d’un référentiel vers le lockfile un à la fois ou tous à la fois. Une fois qu’un workflow est mis en service :

  • Chaque dépendance d’action utilisée par le flux de travail doit être présente dans le fichier de verrouillage.
  • Le commit verrouillé est ce qui s’exécute lorsque le flux de travail s’exécute et ce que les stratégies d’actions autorisées vérifient.
  • Ce commit doit être accessible à partir de la branche ou de la balise enregistrée pour celui-ci dans le fichier de verrouillage, dans le dépôt de l’action. Un commit qui existe uniquement dans un fork, ou qui n’est plus accessible à partir de cette branche ou de cette balise, est rejeté lorsque le flux de travail s’exécute.

Un fichier de verrouillage couvre les flux de travail dans son propre référentiel, y compris les dépendances transitives (actions que vos dépendances d’action utilisent), à l’exception des dépendances des appels de flux de travail réutilisables. Les flux de travail réutilisables peuvent également avoir leurs propres fichiers de verrouillage. 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 le fichier de verrouillage du référentiel qui l’appelle.

Que contient le fichier de verrouillage ?

Le fichier de verrouillage comporte deux sections. workflows enregistre les dépendances que chaque flux de travail intégré utilise, et dependencies enregistre vers quel commit chacune de ces références se résout.

# This file is machine-generated by `gh actions-lock`.
# Do not edit by hand; run `gh actions-lock` to update.
# Docs: https://gh.io/actions-lockfile
version: 'v0.0.3'
workflows:
    '.github/workflows/ci.yml':
        - 'octo-org/deploy-action@v3.1.0'
dependencies:
    'octo-org/deploy-action@v3.1.0':
        ref: 'v3.1.0'
        commit: 'sha1-...'
        owner_id: 44036562
        repo_id: 197814629

Chaque dépendance enregistre :

  • ref: balise ou branche à partir duquel le commit a été résolu.
  • commit : Le commit exact auquel la référence a été résolue. Il s’agit du code qui s’exécutera.
  • owner_id et repo_id: Identité numérique du dépôt source. GitHub Actions utilise ces éléments pour confirmer au moment de l’exécution que le dépôt associé au nom est toujours celui que vous avez verrouillé.

Ce format structuré offre aux outils comme Dependabot un enregistrement lisible par ordinateur qu’ils peuvent utiliser pour gérer les mises à jour des dépendances, sans s’appuyer sur des commentaires YAML en tant qu’annotations de version.

Comment les fichiers de verrouillage se comparent-ils à l’épinglage SHA ?

GitHub a historiquement recommandé d’épingler des actions tierces à un SHA de commit complet dans vos fichiers de flux de travail. Pour les dépôts qui adoptent un fichier de verrou, l’épinglage SHA dans les fichiers de workflow n’est plus nécessaire. Le fichier de verrouillage est la meilleure option, car il :

  • Prend en charge les dépendances transitives
  • Facilite la lecture des fichiers de flux de travail
  • Enregistre l’identité du référentiel source

Un fichier de verrouillage satisfait également à la stratégie distincte Exiger que les actions soient épinglées à un SHA de commit complet pour les workflows qui y sont intégrés. Consultez « Gestion de l’exécution des workflows GitHub Actions ».

Étapes suivantes

Pour créer un fichier de verrouillage pour un référentiel, consultez Verrouillage des dépendances d’action dans les flux de travail d’un dépôt.