Configurer un workflow GitHub Actions

  • 10 minutes

Vous allez découvrir ici certaines configurations courantes au sein d’un fichier de workflow. Vous allez également explorer les catégories de types d’événements, la désactivation et la suppression des workflows et 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.

Diagram of the five unit-of-time fields for scheduling an event in a workflow file.

Par exemple, si vous souhaitez exécuter un workflow toutes les 15 minutes, l’événement schedule ressemble à ce qui suit :

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 la branche sur laquelle vous souhaitez que le workflow s’exécute, et définir l’option facultative 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 workflow pour l’activité qui se produit en dehors de GitHub, et sert essentiellement de requête HTTP à votre dépôt, demandant à GitHub de déclencher un workflow à partir 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 d’un webhook. Par conséquent, si plusieurs activités existent pour un webhook, vous pouvez spécifier un type d’activité déclenchant le workflow. Par exemple, vous pouvez exécuter un workflow pour l’événement check_run, mais uniquement pour les types d’activité rerequested ou requested_action.

on:
  check_run:
    types: [rerequested, requested_action]

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 workflow, vous devez utiliser la syntaxe spécifique ${{ <expression> }}, qui indique à GitHub d’évaluer une expression plutôt que de la traiter comme une chaîne.

Par exemple, un workflow utilisant l’expression conditionnelle if pour vérifier si github.ref (la branche ou la référence de balise qui a déclenché l’exécution du workflow) correspond à refs/heads/main pour effectuer les étapes suivantes dans le workflow 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 dans le cas des expressions conditionnelles if, vous pouvez omettre la syntaxe de l’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.

Screenshot of disabling a workflow on GitHub.

La désactivation d’un workflow peut être utile dans certaines situations, par exemple :

  • 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 une fourche et n’avez pas besoin de l’ensemble des fonctionnalités de certains workflows qu’elle contient (telles que des workflows 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 workflow, GitHub annule tous les travaux et étapes dans cette exécution.

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

Si vous avez un workflow utilisé par plusieurs équipes au sein d’une organisation, au lieu de recréer le même workflow pour chaque dépôt, vous pouvez favoriser la cohérence au sein de votre organisation à l’aide d’un modèle de workflow défini dans le dépôt .github de l’organisation. 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 workflow, comme illustré ci-dessous.

Screenshot of a template organization workflow called greet and triage by 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 fait de référencer une branche spécifique exécute cette action sur la base des dernières modifications de cette branche, ce que vous pourriez vouloir ou exclure. 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.