Configurer un workflow GitHub Actions
Ici, vous découvrez quelques configurations courantes dans un fichier de workflow. Vous explorez également les catégories de types d’événements, la désactivation et la suppression des workflows, ainsi que l’utilisation de versions spécifiques d’une action pour respecter les bonnes pratiques de sécurité.
Configurer les workflows pour s’exécuter lors d’événements planifiés
Comme mentionné précédemment, vous pouvez configurer vos workflows pour qu’ils s’exécutent lorsqu’une activité spécifique se produit sur GitHub, lorsqu’un événement externe à GitHub survient, ou à un moment planifié. L’événement de planification vous permet de déclencher un workflow à des heures UTC spécifiques en utilisant la syntaxe cron POSIX. Cette syntaxe cron comporte cinq champs représentés par des astérisques (*), et chaque champ correspond à une unité de temps.
Par exemple, si vous souhaitez exécuter un workflow toutes les 15 minutes, l’événement de planification ressemblerait à l’exemple suivant :
on:
schedule:
- cron: '*/15 * * * *'Et si vous souhaitez exécuter un workflow tous les dimanches à 3h00 du matin, l’événement de planification ressemblerait à ceci :
on:
schedule:
- cron: '0 3 * * SUN'Vous pouvez également utiliser des opérateurs pour spécifier une plage de valeurs ou affiner l’exécution planifiée de votre workflow. L’intervalle le plus court pour exécuter des workflows planifiés est toutes les cinq minutes, et ils s’exécutent sur le dernier commit de la branche par défaut ou de base.
Configurer les workflows pour s’exécuter manuellement
En plus des événements planifiés, vous pouvez déclencher manuellement un workflow en utilisant l’événement workflow_dispatch. Cet événement vous permet d’exécuter le workflow via l’API REST de GitHub ou en sélectionnant le bouton Run workflow dans l’onglet Actions de votre dépôt sur GitHub. Grâce à workflow_dispatch, vous pouvez choisir sur quelle branche exécuter le workflow et définir des entrées facultatives que GitHub présente sous forme de champs 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 workflow pour une activité qui se produit en dehors de GitHub. Il fonctionne essentiellement comme une requête HTTP envoyée à votre dépôt, demandant à GitHub de lancer un workflow à partir d’une action ou d’un webhook.
L’utilisation de cet événement manuel nécessite deux étapes :
- Envoyer une requête POST au point de terminaison GitHub
/repos/{owner}/{repo}/dispatchesavec les noms d’événements webhook dans le corps de la requête. - 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 les workflows pour s’exécuter lors d’événements webhook
Enfin, vous pouvez configurer un workflow pour qu’il s’exécute lorsque des événements webhook spécifiques se produisent sur GitHub. La plupart des événements webhook peuvent être déclenchés par plusieurs types d’activités. Si plusieurs activités existent pour un webhook, vous pouvez spécifier un type d’activité pour déclencher le workflow.
Par exemple, vous pouvez exécuter un workflow pour l’événement check_run, mais uniquement pour les types d’activités 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 à des systèmes externes (ou même à d’autres workflows GitHub) de déclencher manuellement des workflows en envoyant une requête POST à l’API GitHub. Cela permet une automatisation flexible et une intégration avec des outils, scripts ou systèmes externes qui doivent démarrer des workflows dans votre dépôt.
Cas d’utilisation
- Déclencher des workflows à partir d’outils CI/CD externes.
- Coordonner des déploiements multi-dépôts (par exemple, le dépôt A termine une compilation → déclenche le dépôt B).
- Lancer une automatisation basée sur des événements externes (webhooks, alertes de surveillance, tâches CRON en dehors de GitHub).
- Enchaîner l’exécution de workflows entre plusieurs dépôts ou à l’intérieur de monorepos.
Exemple de workflow écoutant 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: Optionnel. Définit des types d’événements personnalisés commerun-tests,deploy-to-prod, etc.github.event.client_payload: Permet d’accéder à d’autres données personnalisées transmises dans l’événementdispatch.github.event.action: Nom duevent_typeenvoyé.
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 suivant :
POST https://api.github.com/repos/OWNER/REPO/dispatchesAutorisation
- Nécessite un jeton d’accès personnel (PAT) avec l’autorisation
repo. - Pour les organisations, assurez-vous que les paramètres d’accès de votre jeton sont correctement configurés.
Structure d’une commande exemple
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 du contenu (Payload)
{
"event_type": "run-tests",
"client_payload": {
"env": "staging"
}
}Paramètres
| Champ | Type | Description | Obligatoire |
|---|---|---|---|
event_type | string | Un nom personnalisé pour l’événement. Ce nom correspond à la valeur types dans le déclencheur du workflow. | Oui |
client_payload | object | Un contenu JSON arbitraire pour envoyer des données personnalisées au workflow (github.event.client_payload). | Non |
Détails des paramètres de repository_dispatch
Lorsque vous effectuez une requête POST vers le point de terminaison de l’API GitHub, vous devez transmettre un corps JSON contenant deux paramètres principaux :
event_type
- Type : chaîne de caractères (
string) - Obligatoire : Oui
- Description : Une chaîne personnalisée que vous définissez. GitHub considère cette valeur comme l’« action » ou le « type » du dispatch. Elle est utilisée pour identifier ce qui a déclenché le workflow et pour filtrer les workflows qui écoutent des types spécifiques.
- Exemples :
"deploy","run-tests","sync-db","build-docker" - Utilisation dans le workflow : Permet d’écouter des types d’événements spécifiques et d’accéder à cette valeur dans le workflow. Cela facilite la réutilisation d’un même workflow pour plusieurs objectifs et rend l’automatisation plus organisée et orientée événement.
- name: Print event type
run: echo "Event type: ${{ github.event.action }}"client_payload
Un objet JSON librement structuré qui vous permet d’envoyer des données personnalisées avec l’événement dispatch. Vous définissez sa structure, et il est accessible à l’intérieur du workflow.
- Format :
- Type : objet (
object) - Clés et valeurs personnalisées
- Type : objet (
- Utilisation dans le workflow :
Cet objet est utilisé pour :- des déploiements multi-environnements,
- des versions versionnées,
- ou pour transmettre un contexte depuis un autre système ou pipeline.
Il permet de créer des workflows paramétrés, similaires à l’utilisation d’arguments d’entrée. - Exemple:
- name: Show payload values
run: |
echo "Environment: ${{ github.event.client_payload.env }}"
echo "Version: ${{ github.event.client_payload.version }}"Décomposition d’un exemple de payload
{
"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 s’exécuter ou non, vous pouvez utiliser n’importe quel contexte et expression pris en charge pour créer une condition.
Il est important de savoir que lorsque vous utilisez des conditions dans votre workflow, vous devez utiliser la syntaxe spécifique :${{ <expression> }}
Cette syntaxe indique à GitHub qu’il faut évaluer une expression plutôt que de la traiter comme une simple chaîne de caractères.
Exemple :
Un workflow qui utilise la condition if pour vérifier si github.ref (la branche ou l’étiquette qui a déclenché l’exécution du workflow) correspond à refs/heads/main.
Pour que le workflow continue, il ressemblerait à ceci :
name: CI
on: push
jobs:
prod-check:
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
...Remarquez que dans cet exemple, la syntaxe ${{ }} est absente.
Avec certaines expressions, comme la condition if, vous pouvez omettre la syntaxe d’expression. GitHub évalue automatiquement certaines de ces expressions courantes, mais vous pouvez toujours inclure la syntaxe ${{ }} au cas où vous oublieriez lesquelles sont évaluées automatiquement.
Pour plus d’informations sur la syntaxe des workflows et les expressions, consultez la documentation Workflow syntax for GitHub Actions.
Désactiver et supprimer des workflows
Après avoir ajouté un workflow à votre dépôt, vous pourriez rencontrer une situation où vous souhaitez le désactiver temporairement.
Vous pouvez empêcher un workflow d’être déclenché sans avoir à supprimer le fichier du dépôt, que ce soit via l’interface GitHub ou l’API REST de GitHub.
Lorsque vous souhaitez réactiver le workflow, vous pouvez facilement le faire en utilisant les mêmes méthodes.
Désactiver un workflow peut être utile dans les situations suivantes :
- Une erreur dans un workflow génère trop de requêtes (ou des requêtes incorrectes) qui affectent négativement des services externes.
- Vous souhaitez mettre temporairement en pause un workflow non critique qui consomme trop de minutes sur votre compte.
- Vous voulez suspendre un workflow qui envoie des requêtes à un service actuellement hors ligne.
- Vous travaillez sur un fork et n’avez pas besoin de toutes les fonctionnalités de certains workflows inclus (comme les workflows planifiés).
Vous pouvez également annuler une exécution de workflow en cours depuis l’interface GitHub (onglet Actions) ou en utilisant l’API GitHub avec le point de terminaison suivant :
DELETE /repos/{owner}/{repo}/actions/runs/{run_id}À noter : lorsque vous annulez une exécution de workflow, GitHub annule tous les jobs et étapes associés à cette exécution.
Utiliser un workflow modèle d’organisation
Si vous avez un workflow utilisé par plusieurs équipes au sein d’une organisation, vous n’avez pas besoin de le recréer dans chaque dépôt.
Vous pouvez promouvoir la cohérence dans votre organisation en utilisant un modèle de workflow défini dans le dépôt .github de l’organisation.
- Tout membre de l’organisation peut utiliser un workflow modèle.
- Tous les dépôts de l’organisation ont accès à ces workflows modèles.
Comment les trouver :
- Accédez à l’onglet Actions d’un dépôt de l’organisation.
- Cliquez sur New workflow.
- Recherchez la section intitulée « Workflows créés par [nom de l’organisation] ».
Par exemple, l’organisation appelée Mona propose un modèle de workflow comme illustré ici.
Utiliser des versions spécifiques d’une action
Lorsque vous faites référence à des actions dans votre workflow, il est recommandé d’utiliser une version spécifique de l’action plutôt que de simplement mentionner l’action elle-même.
En référant une version précise, vous vous protégez contre des modifications inattendues qui pourraient être apportées à l’action et qui risqueraient de casser votre workflow.
Voici 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@mainCertaines références sont plus sûres que d’autres.
Par exemple, faire référence à une branche spécifique exécute l’action à partir des dernières modifications de cette branche, ce qui peut être souhaité ou non.
En revanche, en faisant référence à un numéro de version ou à un hash SHA de commit, vous êtes plus précis sur la version de l’action que vous exécutez.
Pour plus de stabilité et de sécurité, il est recommandé d’utiliser le SHA du commit d’une action publiée dans vos workflows.
