Fichiers de verrouillage GitHub Actions : votre première PR

Adoptez un fichier de verrouillage GitHub Actions en commençant par modifier un seul flux de travail que votre équipe peut expliquer et examiner. Vérifiez les commits d’actions qu’il consigne, prévoyez des protections distinctes pour les entrées non couvertes et désignez une personne pour examiner les futures mises à jour. Le premier résultat utile est une demande de fusion, ou PR, au périmètre clair, accompagnée d’une exécution réussie sur la révision examinée.

L’objectif paraît modeste à côté d’une refonte de la sécurité de tout le dépôt. Une petite équipe peut pourtant le mener à terme. Un fichier généré devient utile lorsque les relecteurs comprennent quel code exécutable ils ont approuvé et ce qui peut encore changer autour de lui.

Les fichiers de verrouillage des flux de travail sont disponibles depuis le 28 octobre dans les offres Free, Team et Enterprise Cloud de GitHub, y compris Enterprise Cloud avec résidence des données. Le guide publié le 11 novembre par Hugo van Kemenade a remis leur adoption au premier plan. Pour votre équipe, la question est de mettre cette protection en place sans perdre de vue le reste du flux de travail.

Ce que vous approuvez en verrouillant un flux de travail

Un fichier de verrouillage consigne les commits d’actions qu’un flux de travail intégré au dispositif doit exécuter, y compris les dépendances transitives entre actions. Selon la documentation conceptuelle de GitHub, l’exécuteur applique cette résolution, vérifie l’identité du dépôt source et rejette un commit consigné qui n’est pas accessible depuis la référence amont indiquée.

Vous disposez ainsi d’un ensemble précis de dépendances à approuver. La référence visible d’une action peut être facile à lire, alors que son exécution fait intervenir d’autres actions. Consigner ces dépendances donne aux relecteurs une vue plus complète du code qui sera exécuté.

L’approbation exige toujours un jugement. Le commit consigné peut contenir du code qui lit davantage de fichiers, contacte un nouveau service ou utilise des privilèges que le flux de travail n’aurait jamais dû accorder. Un fichier de verrouillage peut parfaitement préserver ce choix. Les recommandations de sécurité de GitHub restent donc pertinentes : examiner le code source des actions, limiter les permissions des jetons et traiter avec précaution le contenu non fiable des PR.

Posez deux questions pendant la revue : « Cette exécution utilisera-t-elle le code des actions consigné dans le fichier ? » et « Devons-nous autoriser ce code à s’exécuter ici ? » Le verrouillage aide à répondre à la première. La seconde dépend du code, de l’événement déclencheur, de l’exécuteur et des pouvoirs dont il dispose.

Limitez la première PR pour pouvoir la comprendre

Imaginez une startup de quatre personnes avec un flux de travail de test, un autre de déploiement, un flux de travail réutilisable partagé et une étape Docker. Cet exemple d’adoption est hypothétique. Commencez par le flux de travail dont un responsable peut expliquer l’objectif, les entrées et les résultats attendus. Supposons qu’il s’agisse ici de celui des tests.

Avant toute génération, décrivez son déroulement actuel dans la PR. Précisez l’événement qui le déclenche, l’origine du code extrait du dépôt, les droits du jeton, les secrets disponibles et l’exécuteur utilisé. Si des contributeurs externes peuvent le déclencher, considérez leur code comme une entrée. Même une tâche de test apparemment banale peut franchir une frontière de confiance sensible.

Le guide d’intégration de GitHub permet de limiter la génération à un seul flux de travail. Profitez-en pour que la première modification reste facile à examiner. Suivez la documentation actuelle pour l’installation et la génération, puis examinez les modifications du flux de travail et le fichier actions.lock.

Prêtez une attention particulière aux actions locales. Une référence ./ utilise le contenu extrait dans l’espace de travail. La migration vers $/ fait pointer la référence vers le commit du flux de travail lui-même. Le comportement peut changer si la révision du flux de travail diffère de celle du code extrait. Vérifiez explicitement la source voulue avant d’accepter cette réécriture ; une dépendance locale non résolue mérite un examen.

Votre première PR doit fournir à un collègue les éléments nécessaires pour décider :

1. Périmètre : le flux de travail intégré au dispositif et ceux qui le seront plus tard.
2. Résolution : les modifications de dépendances générées, y compris les actions transitives.
3. Comportement : toute migration de référence locale ou autre modification du flux de travail.
4. Validation : la méthode de vérification et une exécution réussie du flux de travail sur la révision examinée.
5. Exceptions : les entrées exécutables non couvertes par le fichier de verrouillage, avec un responsable et une décision pour chacune.

Des tests au vert montrent que l’exécution observée s’est terminée avec succès. Lisez aussi la sortie des tâches concernées : les tests prévus ont-ils été exécutés, les artefacts attendus ont-ils été produits, une étape a-t-elle suivi un chemin différent ? Placez le lien vers cette exécution à côté des modifications pour que le relecteur puisse examiner les deux.

Recensez les entrées non couvertes par le fichier de verrouillage

Le périmètre du fichier devient particulièrement important lorsque le flux de travail appelle d’autres composants. Le README officiel de l’outil en ligne de commande décrit ses limites, notamment les appels à des flux de travail réutilisables externes et les images de conteneurs. Votre première PR doit expliquer brièvement comment ces entrées sont maîtrisées.

Les flux de travail réutilisables demandent une attention particulière. La documentation conceptuelle de GitHub explique que le fichier de verrouillage de l’appelant ne verrouille pas les appels via jobs.<job_id>.uses. Pour fixer l’appel à un flux de travail réutilisable sur un commit précis, indiquez son SHA complet. Les dépendances entre actions à l’intérieur du flux appelé relèvent du fichier de verrouillage de son dépôt. Le seul examen du fichier généré chez l’appelant ne permet pas d’établir la couverture dans le dépôt appelé.

Dans notre startup hypothétique, la PR du flux de travail de test peut s’appuyer sur ce tableau. Remplacez les rôles donnés en exemple par les noms des personnes concernées avant la revue.

La ligne consacrée aux outils téléchargés découle de la lecture des commandes exécutées par l’interpréteur. Une commande peut récupérer du code exécutable au-delà des références d’actions consignées dans le fichier de verrouillage. Examinez ce chemin et décidez comment l’équipe identifiera et vérifiera l’artefact. Traitez toute entrée non résolue comme une exception explicite qui appelle une décision.

Examinez aussi les accès accordés à l’exécution. Les images des exécuteurs, les entrées et les identifiants restent distincts de la résolution des actions consignée dans le fichier. Notre liste de contrôle des accès d’un bac à sable pour agents développe cette question plus large : que peut lire, modifier et contacter une exécution ? Posez la même question pour la CI sans supposer qu’un fichier de dépendances y répond.

Désignez un responsable de la prochaine mise à jour des dépendances

La prochaine mise à jour transforme la décision d’adoption en pratique de maintenance. Indiquez qui examine les modifications du fichier de verrouillage, quels éléments sont attendus et comment un nouveau flux de travail sera intégré au dispositif.

Les recommandations de GitHub sur l’application des règles préconisent un essai sur un périmètre limité avant une généralisation. Dependabot maintient les entrées des flux de travail déjà intégrés ; il n’y ajoute pas automatiquement les nouveaux. Ajoutez donc cette intégration à la liste des vérifications lors de la revue d’un nouveau flux de travail, sans présumer que le robot de mise à jour s’en chargera.

Choisissez la vérification selon la question posée. La documentation de l’outil en ligne de commande distingue la vérification de couverture hors ligne avec --verify-local des vérifications de provenance en ligne avec --verify. Notez la méthode exécutée et examinez les échecs avant d’étendre la couverture. Une vérification locale de couverture réussie et une vérification de provenance en ligne apportent des éléments différents.

L’outil documente aussi une limite à garder en tête lors des revues : le retour d’une référence mobile à un commit antérieur de son historique n’est pas détecté. Examinez les modifications réelles des dépendances même lorsque la vérification réussit. Demandez-vous quel code a changé, si le comportement ou les permissions nécessaires ont évolué et si la révision sélectionnée est bien celle que vous souhaitez approuver.

Si votre organisation utilise des modes de déploiement des règles, vérifiez leur disponibilité avant de promettre une procédure précise. GitHub réserve le mode Evaluate à Enterprise Cloud. Une équipe qui n’en dispose pas peut tout de même commencer par un flux de travail examiné et une vérification obligatoire.

Étendez le dispositif lorsque le responsable peut expliquer la couverture de l’essai, ses exceptions et la procédure de mise à jour. Traitez le flux de travail de déploiement comme une décision distincte : ses conséquences diffèrent et il peut recevoir d’autres identifiants.

Rattachez les preuves de vérification au rapport concernant la CI

L’adoption courante d’un fichier de verrouillage relève de votre PR technique. Si le travail fait suite à un rapport de vulnérabilité, reliez le constat à cette PR et aux preuves de vérification. Consignez ce qui était exposé, ce qui a changé, la révision vérifiée et les points encore non résolus.

Cette démarche diffère de la reconstitution d’un incident. Notre guide sur la compromission d’un dépôt et les étapes de publication explique comment établir si du code suspect a atteint une version publiée ou ses utilisateurs. Consultez-le lorsque ces questions se posent ; remplir le tableau d’adoption ne permet pas d’établir une exposition passée.

Le processus de sécurité de Kit peut réunir le responsable d’un rapport, les liens vers les preuves techniques et la décision humaine de vérification. Son cycle de vie distingue la résolution de la vérification du correctif, et la personne qui vérifie peut ajouter une note. Votre équipe technique doit toujours générer le fichier de verrouillage, examiner le flux de travail et décider si le correctif fonctionne. Kit n’effectue pas cette évaluation et n’exige pas de preuve documentaire à chaque vérification.

Pour votre première PR, choisissez un seul flux de travail, examinez les modifications exécutables, nommez les entrées non couvertes et désignez un responsable pour la prochaine mise à jour. Si un rapport de sécurité est à l’origine du travail, ajoutez-y les références de la PR et de l’exécution. Laissez au prochain relecteur assez d’éléments pour comprendre précisément ce que l’équipe a approuvé.