Qu'est-ce qu'un workflow GitHub Actions ?

Un workflow est un processus automatisé que vous décrivez dans un fichier YAML, rangé dans votre dépôt. Il tient en une phrase : « quand il se passe ceci, fais cela ». C'est l'unité de base de GitHub Actions, et tout le reste s'y rattache.

C'est quoi un workflow ?

Un workflow, c'est un fichier texte (YAML) qui décrit :

1. Quand s'exécuter (à chaque push ? chaque PR ? tous les lundis ?)
2. Quoi faire (lancer des tests ? construire une image ? déployer ?)
3. Où le faire (sur quelle machine ?)

Dès que la condition de déclenchement est remplie, GitHub exécute les étapes décrites sans que vous interveniez, sur des machines qu'il fournit et administre. Vous ne gérez ni le matériel, ni le système : vous décrivez le résultat attendu.

Où placer un workflow ?

Les workflows doivent être placés dans un dossier précis de votre code source :

mon-projet/
├── src/
│   └── ...
├── package.json
└── .github/
    └── workflows/
        ├── ci.yml        ← Un workflow
        ├── deploy.yml    ← Un autre workflow
        └── tests.yml     ← Encore un autre

Les règles à retenir :

• Le dossier doit s'appeler exactement .github/workflows/ (avec le point devant)
• Les fichiers doivent avoir l'extension .yml ou .yaml
• Vous pouvez avoir autant de workflows que vous voulez
• Le nom du fichier n'a pas d'importance technique (mais choisissez des noms explicites)

Pourquoi ce dossier ?

Le dossier .github/ est un emplacement conventionnel que GitHub reconnaît. Il accueille aussi les gabarits d'issues, la configuration de Dependabot et d'autres réglages du dépôt. Seul le sous-dossier workflows/ est lu par GitHub Actions : un fichier posé ailleurs ne sera jamais exécuté, et c'est une cause fréquente de « mon workflow ne démarre pas ».

L'essentiel sur la syntaxe des workflows

Les workflows sont écrits en YAML, un format de configuration lisible. Voici les règles essentielles pour éviter les erreurs.

L'indentation est critique

En YAML, l'indentation définit la structure. Pas d'accolades ni de parenthèses : c'est le nombre d'espaces en début de ligne qui compte.

Règle absolue

Utilisez uniquement des espaces (2 espaces par niveau), jamais de tabulations : le format YAML les refuse, et le message d'erreur ne le dit pas toujours clairement. Réglez votre éditeur pour qu'il convertisse les tabulations à la frappe, c'est le seul moyen fiable de ne plus y penser.

# Niveau 0 (pas d'indentation)
jobs:
  # Niveau 1 (2 espaces)
  build:
    # Niveau 2 (4 espaces)
    runs-on: ubuntu-24.04
    steps:
      # Niveau 3 (6 espaces)
      - name: Checkout
        # Niveau 4 (8 espaces)
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

Erreur classique :

# ❌ ERREUR : steps n'est pas indenté sous build
jobs:
  build:
    runs-on: ubuntu-24.04
steps:                        # ← Mauvais niveau !
  - run: echo "Hello"

# ✅ CORRECT : steps est au bon niveau (4 espaces)
jobs:
  build:
    runs-on: ubuntu-24.04
    steps:
      - run: echo "Hello"

Commandes sur plusieurs lignes

Pour exécuter plusieurs commandes, utilisez le caractère | (pipe) :

- name: Build and test
  run: |
    echo "Installation..."
    npm ci
    npm test
    npm run build

Le bloc entier forme un seul script, que le runner passe à bash -e {0} sur Linux et macOS. Deux conséquences que l'on découvre en général dans la douleur : l'option -e arrête le step à la première commande qui échoue, donc npm test ne sera pas lancé si npm ci retourne une erreur ; et une variable définie sur une ligne vaut encore sur les suivantes, puisqu'il s'agit du même interpréteur.

Ce n'est vrai que du shell implicite. Si vous écrivez shell: bash explicitement, GitHub lance bash --noprofile --norc -eo pipefail {0}, et l'ajout de pipefail change le comportement : un échec au milieu d'un tube fait alors échouer le step, là où le shell par défaut ne regarde que la dernière commande du tube.

Quand utiliser des guillemets ?

Les guillemets sont optionnels sauf quand votre texte contient des caractères spéciaux (: # { } & * ?) :

# ❌ Les deux-points cassent l'interprétation
message: Note: important

# ✅ Guillemets nécessaires
message: "Note: important"

Pour approfondir YAML, consultez notre guide complet sur YAML.

Les 3 grandes parties d'un workflow

Tout workflow est structuré en trois parties principales :

1. Le nom (name)

name: Tests unitaires

C'est le nom affiché dans l'onglet Actions de votre dépôt, et donc le seul repère dont vous disposerez le jour où dix workflows tourneront en parallèle. Préférez un intitulé descriptif, « Tests et build », plutôt que « CI » : il se lit dans une liste, sans contexte.

2. Le déclencheur (on)

on:
  push:
    branches: [main]

Le déclencheur définit quand le workflow s'exécute. C'est l'événement qui "réveille" votre workflow. Sans déclencheur, le workflow ne s'exécute jamais.

3. Les jobs (jobs)

jobs:
  test:
    runs-on: ubuntu-24.04
    steps:
      - run: npm test

Les jobs définissent ce que fait le workflow. Un job est un ensemble de tâches (steps) qui s'exécutent sur une même machine.

Les déclencheurs : quand le workflow s'exécute

Le bloc on: définit les événements qui déclenchent votre workflow. Voici les plus utilisés :

Déclencheur	Quand ça se déclenche	Cas d'usage typique
push	Quand du code est poussé	Tests, lint, build
pull_request	Quand une PR est ouverte ou mise à jour	Validation avant merge
workflow_dispatch	Manuellement (bouton dans l'interface)	Déploiement à la demande
schedule	À heures fixes (syntaxe cron)	Scans de sécurité nocturnes
release	Quand une release est publiée	Publication de packages

Glissez pour voir

Vous pouvez combiner plusieurs déclencheurs :

on:
  push:
    branches: [main]      # À chaque push sur main
  pull_request:
    branches: [main]      # À chaque PR vers main
  workflow_dispatch:       # Et manuellement si besoin

Les jobs : les unités de travail

Un job est une unité de travail indépendante. Chaque job :

• S'exécute sur sa propre machine virtuelle (appelée runner)
• Peut contenir plusieurs étapes (steps)
• Peut dépendre d'autres jobs ou s'exécuter en parallèle

jobs:
  build:
    runs-on: ubuntu-24.04
    steps:
      - run: echo "Je construis"

  test:
    runs-on: ubuntu-24.04
    steps:
      - run: echo "Je teste"

Par défaut, les jobs s'exécutent en parallèle. Dans l'exemple ci-dessus, build et test démarrent en même temps.

Exécuter des jobs dans un ordre précis

Si un job doit attendre qu'un autre soit terminé, utilisez needs :

jobs:
  build:
    runs-on: ubuntu-24.04
    steps:
      - run: echo "Build"

  test:
    runs-on: ubuntu-24.04
    needs: build            # Attend que "build" soit terminé
    steps:
      - run: echo "Test"

  deploy:
    runs-on: ubuntu-24.04
    needs: [build, test]    # Attend que les deux soient terminés
    steps:
      - run: echo "Deploy"

Les runners : où s'exécute le code

Le runner est la machine qui exécute votre job. GitHub propose des runners hébergés (gratuits dans certaines limites) :

Runner	Système	Cas d'usage
ubuntu-24.04	Linux Ubuntu 24.04	Le plus courant, rapide, économique
windows-2022	Windows Server 2022	Applications .NET, tests Windows
macos-15	macOS 15 (Sequoia)	Applications iOS/macOS

Glissez pour voir

jobs:
  test-linux:
    runs-on: ubuntu-24.04

  test-windows:
    runs-on: windows-2022

  test-mac:
    runs-on: macos-15

Évitez les tags 'latest'

Vous verrez souvent ubuntu-latest, windows-latest ou macos-latest dans les exemples. Évitez-les. Ces alias mobiles suivent les mises à jour de GitHub : le jour où ubuntu-latest bascule vers une nouvelle version majeure, votre workflow change d'environnement d'exécution sans qu'une seule ligne de votre dépôt ait bougé. Un build qui cassait hier sans explication vient souvent de là.

Utilisez toujours une version explicite (ubuntu-24.04, ubuntu-22.04...) pour des builds reproductibles.

Une version explicite ne dispense pas de suivre les fins de support, et c'est l'autre moitié du travail. GitHub a ouvert la dépréciation de macos-14 le 6 juillet 2026, avec des coupures programmées qui font échouer les jobs concernés avant le retrait complet, annoncé pour le 2 novembre 2026. Un label figé qui disparaît casse le pipeline aussi sûrement qu'un alias qui bouge : la différence est que vous êtes prévenu.

Vos propres machines peuvent aussi servir de runners auto-hébergés, ce qui répond à des besoins que les machines de GitHub ne couvrent pas : accès à un réseau interne, carte GPU, contrainte de conformité. Cette option demande des précautions particulières, traitées dans le module consacré aux runners.

Les steps : les tâches individuelles

Les steps sont les tâches à exécuter dans un job. Elles s'exécutent séquentiellement (l'une après l'autre) sur la même machine.

Il existe deux types de steps :

1. Exécuter une commande shell (run)

steps:
  - name: Afficher un message
    run: echo "Bonjour !"

  - name: Plusieurs commandes
    run: |
      echo "Première ligne"
      echo "Deuxième ligne"
      npm install
      npm test

Le | regroupe plusieurs lignes dans un même script, avec les conséquences vues plus haut : arrêt à la première erreur, et variables partagées d'une ligne à l'autre.

2. Utiliser une action (uses)

steps:
  - name: Récupérer le code
    uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

  - name: Configurer Node.js
    uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
    with:
      node-version: 20

Une action est un bloc de code réutilisable, publié par GitHub, par un éditeur ou par n'importe qui. Plutôt que de réécrire la logique qui récupère le code du dépôt ou installe Node.js, vous appelez une action existante avec uses:. C'est le mécanisme qui rend les workflows courts, et c'est aussi celui qui fait entrer du code tiers dans votre pipeline.

Jobs vs Steps : comprendre la différence

C'est une source de confusion fréquente. Voici comment les distinguer :

Workflow
├── Job 1 (machine A)
│   ├── Step 1: récupérer le code
│   ├── Step 2: installer les dépendances
│   └── Step 3: lancer les tests
│
└── Job 2 (machine B)
    ├── Step 1: récupérer le code
    └── Step 2: déployer

Concept	Définition	Environnement
Job	Un groupe de tâches	Chaque job a sa propre machine
Step	Une tâche individuelle	Tous les steps d'un job partagent la même machine

Glissez pour voir

Conséquence importante :

• Les fichiers créés par un step sont disponibles pour les steps suivants du même job (même machine)
• Les fichiers créés dans un job ne sont pas disponibles dans un autre job (machines différentes). Il faut utiliser les artifacts pour partager des fichiers entre jobs.

Votre premier workflow

1. Créez le dossier .github/workflows/ à la racine de votre projet

2. Créez un fichier hello.yml dans ce dossier avec ce contenu :

   name: Hello World
   
   on:
     push:
       branches: [main]
     workflow_dispatch:
   
   jobs:
     hello:
       runs-on: ubuntu-24.04
       steps:
         - name: Dire bonjour
           run: echo "Hello, GitHub Actions!"
   
         - name: Afficher des infos sur le contexte
           env:
             DEPOT: \${{ github.repository }}
             BRANCHE: \${{ github.ref_name }}
             AUTEUR: \${{ github.actor }}
           run: |
             echo "Dépôt : $DEPOT"
             echo "Branche : $BRANCHE"
             echo "Auteur du commit : $AUTEUR"

   Ces trois valeurs passent par un bloc env: au lieu d'être écrites directement dans le run:. La raison tient en une phrase : un nom de branche est choisi par la personne qui ouvre la pull request, et une valeur insérée dans le script par ${{ }} y est collée telle quelle avant exécution. Le guide Sécurité : les bases montre ce que cela permet à un attaquant.

3. Committez et poussez sur la branche main

4. Allez dans l'onglet Actions de votre dépôt sur GitHub

5. Observez votre workflow s'exécuter !

Où voir les résultats ?

Une fois votre workflow déclenché :

1. Allez sur votre dépôt GitHub
2. Cliquez sur l'onglet Actions
3. Vous voyez la liste des exécutions (workflow runs)
4. Cliquez sur une exécution pour voir ses jobs
5. Cliquez sur un job pour dérouler les journaux de chaque step

Cette vue est l'outil de diagnostic principal, et elle distingue quatre états :

• les steps réussis, en vert ;
• les steps en échec, en rouge, sur lesquels l'exécution s'est arrêtée ;
• les steps en cours ;
• les journaux détaillés de chaque commande, dépliables ligne à ligne.

Le cycle de vie d'un workflow

Quand un événement déclenche un workflow, voici ce qui se passe :

1. Événement : quelqu'un pousse du code, ouvre une PR, etc.
2. Détection : GitHub détecte l'événement et cherche les workflows correspondants
3. Mise en file d'attente : le workflow est ajouté à la queue d'exécution
4. Attribution d'un runner : GitHub assigne une machine virtuelle
5. Exécution : les jobs et steps s'exécutent
6. Nettoyage : la machine est détruite, les résultats sont conservés

Chaque exécution est éphémère : la machine est créée pour l'occasion, puis détruite. Rien n'y survit, ni votre code, ni les fichiers produits par l'exécution précédente. C'est la raison pour laquelle un workflow commence presque toujours par actions/checkout : sans lui, le dépôt n'est pas présent sur le runner.

Les variables de contexte

Dans l'exemple précédent, vous avez vu \${{ github.repository }}. C'est une variable de contexte : GitHub expose sous le préfixe github. une série d'informations sur l'exécution en cours, du nom du dépôt à l'auteur du commit. Ces valeurs sont remplacées avant exécution, ce qui explique les précautions vues plus haut.

Quelques variables utiles :

Variable	Contenu
github.repository	Nom du repo (owner/repo)
github.ref_name	Nom de la branche ou du tag
github.actor	Utilisateur qui a déclenché le workflow
github.event_name	Type d'événement (push, pull_request...)
github.sha	SHA du commit
github.run_id	ID unique de cette exécution

Glissez pour voir

Tout cela sera approfondi dans les modules suivants.

Prochaine étape

Vous savez désormais lire et écrire un workflow, et vous connaissez ses quatre pièces : déclencheur, jobs, steps et runner. La suite logique n'est pas plus de syntaxe, mais les risques que ce pouvoir d'exécution ouvre : Sécurité GitHub Actions : les bases montre comment un pipeline se fait détourner, et ce qui l'empêche.

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

×

📖 Voir la documentation →