Gérer et déboguer des flux de travail dans GitHub Actions

Rappelez-vous que votre objectif est d’automatiser le processus de génération et de publication du code afin que les fonctionnalités soient mises à jour chaque fois qu’un développeur ajoute une modification à la base de code.

Pour implémenter ce processus, vous allez apprendre à :

• Identifiez l’événement qui a déclenché un flux de travail.
• Utilisez les journaux de flux de travail GitHub Actions.
• Enregistrer les artefacts de build et y accéder.
• Automatiser l'ajout d'une étiquette à un pull request après une révision.

Identifier l’événement qui a déclenché un flux de travail

Comprendre ce qui a déclenché un flux de travail GitHub Actions est essentiel pour le débogage, l’audit et l’amélioration des pipelines CI/CD. Le type des déclencheurs inclut un envoi (push) vers une branche, une demande de tirage (pull request) créée ou mise à jour, une tâche planifiée ou une répartition manuelle. Vous pouvez identifier l’événement déclencheur en examinant l’exécution du flux de travail, les modifications du référentiel, le ticket GitHub lié ou la proposition de modification.

Qu’est-ce qu’un déclencheur de flux de travail ?

Un déclencheur de flux de travail est un événement qui provoque l’exécution d’un flux de travail. GitHub prend en charge différents types de déclencheurs, notamment :

• push ou pull_request (en fonction des modifications de code)
• workflow_dispatch (un déclencheur manuel)
• schedule (travaux cron)
• repository_dispatch (systèmes externes)
• Problèmes, discussion et événements de demande de tirage (pull request) (par exemple, issues.opened, pull_request.closed)

Identifier l’événement de déclencheur

Vous pouvez identifier un événement de déclencheur de flux de travail de plusieurs façons :

• Utilisez l’interface utilisateur GitHub Actions :

  1. Dans votre référentiel, sélectionnez l’onglet Actions .
  2. Sélectionnez une exécution de workflow.

  Un type d’événement, tel que push, pull_requestou workflow_dispatch, apparaît en haut du résumé de l’exécution du flux de travail.

• Utilisez github.event_name dans les journaux ou dans un workflow.

  • GitHub expose les données de contexte pendant une exécution de flux de travail. La github.event_name variable vous indique quel événement a déclenché le flux de travail.

  • Vous pouvez imprimer les informations dans une étape de débogage :

    -name: Show event trigger
      run: echo "Triggered by ${{ github.event_name }}"
    

• Utiliser les détails de l’exécution du workflow :

  • Si vous inspectez les exécutions de flux de travail par programmation, par exemple à l’aide de l’API, l’objet d’exécution inclut une event propriété qui spécifie le déclencheur.
  • Vous pouvez trouver le Secure Hash Algorithm (SHA) de validation, l’intervenant et l’horodatage pour tracer la cause du déclenchement.

Déduire le déclencheur à partir des effets du référentiel

Vous ne disposez peut-être pas d’un accès direct à l’exécution du flux de travail, mais vous souhaitez toujours déduire ce qui a déclenché l’exécution du flux de travail en fonction de l’activité du référentiel :

En examinant les horodatages, l’activité des pull requests et l’historique des validations, vous pouvez souvent identifier l’action à l’origine de l’exécution du workflow.

Pour résumer comment identifier ce qui a déclenché un flux de travail :

• Vérifiez le résumé de l’exécution du flux de travail sous l’onglet Actions .
• Imprimez ou journalisez github.event_name dans le flux de travail pour plus de visibilité.
• Comparez les horodatages et l’activité du référentiel (validations, demandes de tirage, problèmes) pour déduire le déclencheur.
• Utilisez le contexte complet event pour une investigation plus approfondie.

Ces pratiques vous aident à déboguer, auditer et améliorer la fiabilité des flux de travail dans vos pipelines de développement et de déploiement.

Comprendre un effet de flux de travail en lisant son fichier de configuration

Pour comprendre les effets d’un flux de travail à partir de la lecture de son fichier de configuration, analysez la structure et le contenu du .yml fichier stocké dans .github/workflows/.

Le fichier de configuration du flux de travail spécifie les informations suivantes sur le flux de travail :

• Lorsqu’il s’exécute (dans la section on).
• Qu’est-ce qu’il fait (dans jobs et steps).
• Où il s’exécute (la section runs-on).
• Pourquoi il s’exécute (son objectif, tel que le test, le déploiement ou le linting).
• Comportement dans des conditions spécifiques (environnement, filtres, logique).

Interpréter un effet de flux de travail

1. Identifiez le déclencheur.

   Pour identifier l’action lancée par le flux de travail, consultez la on section du flux de travail.

   Par exemple:

   on:
     push:
       branches: [main]
     pull_request:
       types: [opened, synchronize]
     workflow_dispatch:
   

   Cet exemple de flux de travail :

   • S’exécute automatiquement lorsque le code est transféré à la branche principale (push).
   • S’exécute lorsqu’une demande de tirage (pull request) est créée ou mise à jour (pull_request).
   • Peut être déclenché manuellement par un utilisateur (workflow_dispatch).

2. Identifiez les tâches et les étapes du flux de travail.

   Pour déterminer ce que fait le flux de travail, consultez les sections jobs et steps du flux de travail.

   Par exemple:

   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout code
           uses: actions/checkout@v3
         - name: Install dependencies
           run: npm install
         - name: Run tests
           run: npm test
   

   Cet exemple de flux de travail :

   • Utilise un environnement virtuel Linux (runs-on).
   • Consulte le code du dépôt (steps>name).
   • Installe les dépendances de projet (steps>name).
   • Exécute des tests automatisés (steps>name).

3. Évaluez l’objectif et le résultat du flux de travail.

   En lisant le fichier de configuration, vous pouvez décrire le résultat prévu du flux de travail :

   « Ce flux de travail est un pipeline d’intégration continue (CI). Il garantit que tout nouveau code envoyé au référentiel ou soumis via une pull request est automatiquement testé. Si les tests échouent, l’interface utilisateur du flux de travail GitHub affiche ce résultat pour vous aider à maintenir la qualité du code.

4. Identifiez ou définissez des fonctionnalités facultatives qui affectent la façon dont le flux de travail s’exécute :

   • env définit des variables d’environnement.
   • if ajoute une logique conditionnelle pour exécuter des étapes spécifiques uniquement lorsque les critères sont remplis.
   • timeout-minutes ou continue-on-error définissez l’exécution du flux de travail et la gestion des erreurs.

Diagnostiquer une exécution de flux de travail ayant échoué

1. Dans votre référentiel, accédez à l’onglet Actions .

2. Recherchez l’exécution ayant échoué (généralement indiquée par un X rouge).

3. Sélectionnez le flux de travail ayant échoué pour ouvrir le résumé de l’exécution.

4. Dans les journaux de flux de travail, passez en revue l’erreur.

   1. Dans le résumé de l'exécution, développez chaque tâche et chaque étape jusqu'à ce que vous trouviez celle qui indique une défaillance.

   2. Sélectionnez la tâche ou l’étape pour afficher ses journaux.

   3. Rechercher :

      • Messages d’erreur
      • Arborescences des appels de procédure
      • Codes de sortie

   Par exemple, un test ayant échoué peut s’afficher npm ERR! Test failed ou exit code 1.

5. Vérifiez le fichier de configuration du flux de travail.

   Utilisez le .yml fichier pour déterminer :

   • Qu’est-ce que chaque étape essayait de faire ?
   • S’il existe des variables d’environnement (env) ou des conditions (if) qui affectent l’exécution.
   • Si l’échec est dû à une dépendance manquante, une erreur de syntaxe ou une étape mal configurée.

   Si une étape échoue, vérifiez les causes suivantes :

   • Les dépendances ont-elles été installées correctement à l’étape précédente ?
   • Les fichiers de test existent-ils et réussissent-ils localement ?

Scénarios d’échec courants

Le tableau suivant décrit les scénarios courants d’échec de flux de travail :

Identifier comment accéder aux journaux de flux de travail dans GitHub

1. Dans votre référentiel, accédez à l’onglet Actions .

2. Dans la liste des flux de travail, sélectionnez le flux de travail approprié.

   Par exemple, si votre .yml fichier contient le code suivant, un lien intitulé Flux de travail CI apparaît dans la liste :

   name: CI Workflow
   

3. Sélectionnez une exécution spécifique.

   Dans la liste des exécutions qui affichent l’état, sélectionnez l’horodatage ou le message de validation de l’exécution spécifique que vous souhaitez inspecter.

4. Développez chaque tâche et étape.

   La page récapitulative d’exécution affiche les travaux tels qu’ils sont définis dans le fichier de flux de travail, comme la génération ou le test :

   1. Sélectionnez une tâche pour la développer.
   2. Dans le travail, développez des étapes individuelles, telles que « Installer des dépendances » ou « Exécuter des tests ».

5. Affichez la sortie du journal.

   Pour afficher la sortie complète du log, y compris les logs de console, les messages d’erreur et les informations de débogage, sélectionnez une étape d'un flux de travail. Vous pouvez copier, rechercher et télécharger les logs.

Le tableau suivant récapitule les étapes à suivre pour accéder aux journaux de flux de travail :

Journaux des actions pour la build

Lorsqu’un flux de travail s’exécute, il produit un journal qui inclut les détails de ce qui s’est passé et les erreurs ou les échecs de test.

Si une erreur se produit ou si un test échoue, un X rouge apparaît dans les journaux de bord au lieu d’une coche verte. Vous pouvez examiner les détails de l’erreur ou de l’échec pour examiner ce qui s’est passé.

Utiliser des artefacts

Lorsqu’un flux de travail produit quelque chose d’autre qu’une entrée de journal, le produit est appelé artefact. Par exemple, la build Node.js produit un conteneur Docker qui peut être déployé. Le conteneur est un artefact que vous pouvez charger dans le stockage à l’aide de l’action actions/upload-artifact . Vous pouvez ensuite télécharger l’artefact à partir du stockage à l’aide d’actions/download-artifact.

Le stockage d’un artefact permet de le conserver d’un travail à l’autre. Chaque travail utilise une nouvelle instance d’une machine virtuelle. Vous ne pouvez donc pas réutiliser l’artefact en l’enregistrant sur la machine virtuelle. Si vous avez besoin de votre artefact dans un autre travail, vous pouvez charger l’artefact dans un travail et le télécharger pour l’autre travail.

Stockage d’artefacts

Les artefacts sont stockés dans l’espace de stockage sur GitHub. L'espace est gratuit pour les référentiels publics, et un espace de stockage est gratuit pour les référentiels privés, selon le type de compte. GitHub stocke vos artefacts pendant 90 jours.

Dans l’extrait de flux de travail suivant, notez que, dans l’action actions/upload-artifact@main , il existe un path attribut. La valeur de cet attribut est le chemin d’accès pour stocker l’artefact. Dans cet exemple, vous spécifiez public/ pour charger tout dans un répertoire. Si vous ne souhaitez charger qu’un seul fichier, utilisez quelque chose comme public/mytext.txt.

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@main
        with:
          name: webpack artifacts
          path: public/

Pour télécharger l’artefact à des fins de test, la build doit s’exécuter correctement et charger l’artefact. Dans le code suivant, vous spécifiez que le travail de test dépend du travail de génération.

test:
    needs: build
    runs-on: ubuntu-latest

Dans l’extrait de flux de travail suivant, vous téléchargez l’artefact. À présent, le processus de test peut utiliser l'artefact pour les essais.

steps:
    - uses: actions/checkout@v3
    - uses: actions/download-artifact@main
      with:
        name: webpack artifacts
        path: public

Pour plus d’informations sur l’utilisation d’artefacts dans les flux de travail, consultez Stockage des données de flux de travail en tant qu’artefacts.

Automatiser les révisions dans GitHub à l’aide de flux de travail

Outre le démarrage d’un flux de travail via des événements GitHub, vous pushpull-requestpouvez exécuter un flux de travail selon une planification ou après un événement en dehors de GitHub.

Vous souhaiterez peut-être qu’un workflow s’exécute uniquement une fois qu’un utilisateur a terminé une action spécifique, par exemple après qu’un développeur approuve une pull request. Pour ce scénario, vous pouvez activer pull-request-review.

Une autre action que vous pouvez effectuer consiste à ajouter une étiquette à la pull request. Dans ce cas, utilisez l’action pullreminders/label-when-approved-action.

Par exemple:

    steps:
     - name: Label when approved
       uses: pullreminders/label-when-approved-action@main
       env:
         APPROVALS: "1"
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         ADD_LABEL: "approved"

Dans le env bloc, vous définissez les variables d’environnement pour l’action. Par exemple, vous pouvez définir le nombre d’approbateurs requis pour exécuter le flux de travail. Dans cet exemple, il s'agit d'un seul. La secrets.GITHUB_TOKEN variable d’authentification est requise, car l’action doit apporter des modifications à votre référentiel en ajoutant une étiquette. Enfin, vous entrez le nom de l’étiquette à ajouter.

L’ajout d’une étiquette peut être un événement qui démarre un autre flux de travail, tel qu’une fusion. Nous abordons cet événement dans le module suivant, qui décrit l’utilisation de la livraison continue dans GitHub Actions.