Configurer un workflow GitHub Actions

  • 10 minutes

Ici, vous découvrez certaines configurations courantes dans un fichier de flux de travail. Vous explorez également les catégories de types d’événements, la désactivation et la suppression de flux de travail, ainsi que l’utilisation de versions spécifiques d’une action pour les meilleures pratiques de sécurité.

Configurer des workflows à exécuter pour des événements planifiés

Comme mentionné précédemment, vous pouvez configurer vos workflows pour qu’ils s’exécutent quand une activité spécifique se produit sur GitHub, lorsqu’un événement en dehors de GitHub se produit, ou à une heure planifiée. L’événement schedule vous permet de déclencher un workflow pour qu’il s’exécute à des heures UTC spécifiques à l’aide de la syntaxe cron POSIX. Cette syntaxe cron comporte cinq champs * et chaque champ représente une unité de temps.

Diagramme des cinq champs d'unité de temps pour la planification d'un événement dans un fichier de flux de travail.

Par exemple, si vous souhaitez exécuter un flux de travail toutes les 15 minutes, l’événement schedule ressemble à l’exemple suivant :

on:
  schedule:
    - cron:  '*/15 * * * *'

Et si vous souhaitez exécuter un workflow tous les dimanches à 3 h, l’événement schedule ressemble à ceci :

on:
  schedule:
    - cron:  '0 3 * * SUN'

Vous pouvez également utiliser des opérateurs pour spécifier une plage de valeurs ou pour établir un appel entrant dans votre workflow planifié. L’intervalle le plus court d’exécution de workflows planifiés est une fois toutes les 5 minutes, et ils s’exécutent lors de la dernière validation sur la branche de base ou par défaut.

Configurer des workflows pour exécuter des événements manuellement

En plus des événements planifiés, vous pouvez déclencher manuellement un workflow à l’aide de l’événement workflow_dispatch. Cet événement vous permet d’exécuter le workflow en tirant parti de l’API REST GitHub ou en sélectionnant le bouton Exécuter le workflow sous l’onglet Actions de votre référentiel sur GitHub. À l'aide de workflow_dispatch , vous pouvez choisir sur quelle branche vous souhaitez que le flux de travail s'exécute et définir des paramètres optionnels inputs que GitHub présente en tant qu’éléments de formulaire dans l’interface utilisateur.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'

En plus de workflow_dispatch, vous pouvez utiliser l’API GitHub pour déclencher un événement webhook appelé repository_dispatch. Cet événement vous permet de déclencher un flux de travail pour l’activité qui se produit en dehors de GitHub. Il sert essentiellement de requête HTTP à votre dépôt demandant à GitHub de déclencher un flux de travail hors d’une action ou d’un webhook. Pour utiliser cet événement manuel, vous devez effectuer deux opérations : envoyer une requête POST au point de terminaison GitHub /repos/{owner}/{repo}/dispatches avec les noms d’événements du webhook dans le corps de la demande, et configurer votre workflow pour utiliser l’événement repository_dispatch.

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

Configurer des workflows pour exécuter des événements de webhook

Enfin, vous pouvez configurer un workflow pour qu’il s’exécute lorsque des événements de webhook spécifiques se produisent sur GitHub. Vous pouvez déclencher la plupart des événements de webhook à partir de plusieurs activités associées à un webhook. Si plusieurs activités existent pour un webhook, vous pouvez spécifier un type d’activité pour déclencher le flux de travail. Par exemple, vous pouvez exécuter un flux de travail pour l’événement check_run, mais uniquement pour les types d’activité rerequested ou requested_action.

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch est un événement personnalisé dans GitHub Actions qui permet aux systèmes externes (ou même à d’autres flux de travail GitHub) de déclencher manuellement des flux de travail en envoyant une requête POST à l’API GitHub. Il permet une automatisation et une intégration flexibles avec des outils, des scripts ou des systèmes externes qui doivent démarrer des flux de travail dans votre dépôt.

Cas d’utilisation

  • Déclenchez des flux de travail à partir d’outils CI/CD externes.

  • Coordonnez les déploiements à référentiels multiples (par exemple, le référentiel A termine la génération → déclenche le référentiel B).

  • Démarrez l’automatisation en fonction des événements externes (webhooks, alertes de surveillance, travaux CRON en dehors de GitHub).

  • Chaînez les exécutions de workflow entre les référentiels ou au sein de référentiels uniques.

Exemple de flux de travail qui écoute repository_dispatch

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

Éléments clés :

  • types : facultatif. Définit des types d’événements personnalisés tels que run-tests, deploy-to-prod, etc.

  • github.event.client_payload : accès à tout autre donnée personnalisée transmise dans l’événement de dispatch.

  • github.event.action : nom du event_type envoyé.

Déclenchement de l’événement via l’API

Vous devez envoyer une requête POST au point de terminaison de l’API REST GitHub v3 :

POST https://api.github.com/repos/OWNER/REPO/dispatches

Autorisation

  • Nécessite un jeton d’accès personnel (PAT) avec une étendue de référentiel.
  • Pour les organisations, vérifiez les paramètres d’accès appropriés pour votre jeton.

Exemple de structure de commandes

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

Structure de charge utile

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

Paramètres

Terrain Catégorie Descriptif Obligatoire
event_type ficelle Nom personnalisé de l’événement. Ce nom correspond à la valeur des types dans votre déclencheur de flux de travail Oui
client_payload objet Charge utile JSON arbitraire pour envoyer des données personnalisées au flux de travail (github.event.client_payload) Non

Décomposition des paramètres de repository_dispatch

Lorsque vous effectuez une requête POST sur le point de terminaison de l’API GitHub, vous devez passer un corps JSON avec deux paramètres principaux :

  • type d'événement
  • client_payload
type d'événement

Chaîne personnalisée requise que vous définissez. GitHub traite cette valeur comme « action » ou « type » de la distribution. Il est utilisé pour identifier ce qui a déclenché le flux de travail et filtrer les flux qui surveillent des types spécifiques.

  • Format :

    • Type : chaîne
    • Exemple : « deploy », « run-tests », « sync-db », « build-docker »

  • Utilisation dans le flux de travail. Utilisé pour écouter des types d’événements spécifiques et accéder à la valeur dans le flux de travail. Cela permet de réutiliser un flux de travail unique à plusieurs fins et rend l’automatisation plus organisée et pilotée par les événements.

  • Exemple:

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"
client_payload

Objet JSON de forme libre qui vous permet d’envoyer des données personnalisées avec la distribution. Vous définissez la structure et elle est accessible à l’intérieur du flux de travail.

  • Format :

    • Type : objet
    • Clés et valeurs personnalisées

  • Utilisation dans le flux de travail : cet objet est utilisé pour les déploiements multi-environnements, les versions révisées, ou pour transmettre le contexte à partir d’un autre système ou pipeline et permet de créer des workflows paramétrés, similaires à des arguments d'entrée.

  • Exemple:

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"
Exemple de répartition de charge utile
{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

Utiliser des mots clés conditionnels

Dans votre fichier de workflow, vous pouvez accéder aux informations de contexte et évaluer des expressions. Bien que les expressions soient couramment utilisées avec le mot clé conditionnel if dans un fichier de workflow pour déterminer si une étape doit être exécutée ou non, vous pouvez utiliser n’importe quel contexte et expression compatible pour créer une expression conditionnelle. Il est important de savoir que lorsque vous utilisez des conditions dans votre flux de travail, vous devez utiliser la syntaxe ${{ <expression> }}spécifique. Cette syntaxe indique à GitHub d’évaluer une expression plutôt que de la traiter comme une chaîne.

Par exemple, un flux de travail qui utilise le conditionnement if pour vérifier si la référence de branche ou de balise github.ref qui a déclenché l’exécution du flux de travail correspond à refs/heads/main. Pour continuer, le flux de travail ressemblerait à ceci :

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

Notez que dans cet exemple, ${{ }} sont absents de la syntaxe. Avec certaines expressions, comme le if conditionnel, vous pouvez omettre la syntaxe d’expression. GitHub évalue automatiquement certaines de ces expressions communes, mais vous pouvez toujours les inclure au cas où vous auriez oublié les expressions que GitHub évalue automatiquement.

Pour plus d’informations sur la syntaxe et les expressions des workflows, consultez Syntaxe de workflow pour GitHub Actions.

Désactiver et supprimer des workflows

Après l’ajout d’un workflow à votre référentiel, il est possible que vous vous retrouviez dans une situation dans laquelle vous souhaitez désactiver temporairement le workflow. Vous pouvez empêcher le déclenchement d’un workflow sans avoir à supprimer le fichier du référentiel, soit sur GitHub, soit via l’API REST GitHub. Si vous souhaitez réactiver le workflow, vous pouvez facilement le faire en utilisant les mêmes méthodes.

Capture d'écran de la désactivation d'un flux de travail sur GitHub.

La désactivation d’un flux de travail peut être utile dans certaines des situations suivantes :

  • Une erreur sur un workflow produit des requêtes trop nombreuses ou incorrectes ayant un impact négatif sur les services externes.
  • Vous souhaitez suspendre temporairement un workflow qui n’est pas critique et qui consomme un nombre trop important de minutes sur votre compte.
  • Vous souhaitez suspendre un workflow qui envoie des requêtes à un service en panne.
  • Vous travaillez sur un fork et vous n’avez pas besoin de toutes les fonctionnalités de certains flux de travail qu’il inclut (comme les flux de travail planifiés).

Vous pouvez également annuler une exécution de workflow en cours dans l’interface utilisateur de GitHub à partir de l’onglet Actions ou en utilisant le point de terminaison de l’API GitHub DELETE /repos/{owner}/{repo}/actions/runs/{run_id}. N’oubliez pas que lorsque vous annulez une exécution de flux de travail, GitHub annule tous ses travaux et étapes au sein de cette exécution.

Utiliser un workflow basé sur un modèle d’organisation

Si vous disposez d’un flux de travail que plusieurs équipes utilisent au sein d’une organisation, vous n’avez pas besoin de recréer le même flux de travail pour chaque dépôt. Au lieu de cela, vous pouvez promouvoir la cohérence au sein de votre organisation à l’aide d’un modèle de flux de travail défini dans le référentiel de l’organisation .github . Tout membre au sein de l’organisation peut utiliser un workflow de modèle d’organisation et tout dépôt au sein de cette organisation a accès à ces workflows de modèle.

Vous pouvez trouver ces workflows en accédant à l’onglet Actions d’un dépôt au sein de l’organisation, en sélectionnant Nouveau workflow, puis en recherchant la section Modèle de workflow de l’organisation intitulée « Workflows créés parNom de l’organisation ». Par exemple, l'organisation appelée Mona a un modèle de flux de travail, comme indiqué ici.

Capture d'écran d'un modèle de flux de travail appelé Accueil et triage par Mona.

Utiliser des versions spécifiques d’une action

Lorsque vous référencez des actions dans votre workflow, nous vous recommandons de faire référence à une version spécifique de cette action plutôt qu’à l’action elle-même. En référençant une version spécifique, vous mettez en place une protection contre les modifications inattendues envoyées à l’action qui peuvent arrêter votre workflow. Il existe plusieurs façons de référencer une version spécifique d’une action :

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

Certaines références sont plus sécurisées que d’autres. Par exemple, le référencement d’une branche spécifique exécute cette action à partir des dernières modifications de cette branche, ce que vous pourriez vouloir ou non. En référençant un numéro de version ou un hachage SHA de validation spécifique, vous êtes plus précis concernant la version de l’action que vous exécutez. Pour une stabilité et une sécurité accrues, nous vous recommandons d’utiliser l’algorithme SHA de validation d’une action publiée dans vos workflows.