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

Un workflow est un processus automatisé que vous définissez dans votre repository. Il dit à GitHub : “Quand il se passe X, fais Y”. C’est le cœur de GitHub Actions.

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 ?)

Quand la condition est remplie, GitHub lance automatiquement les actions décrites. Vous n’avez rien à faire : tout se passe dans le cloud, sur des machines gérées par GitHub.

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 dossier spécial reconnu par GitHub. Il peut contenir d’autres choses : des templates d’issues, des fichiers de configuration pour Dependabot, des instructions pour Copilot, etc. Le sous-dossier workflows/ est réservé aux workflows GitHub Actions.

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. Mélanger les deux provoque des erreurs difficiles à diagnostiquer. Configurez votre éditeur pour convertir automatiquement les tabulations en espaces.

# 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@v4

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

Chaque ligne après le | est exécutée comme une commande séparée.

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 qui apparaît dans l’interface GitHub, dans l’onglet “Actions”. Choisissez quelque chose de descriptif pour vous y retrouver quand vous aurez plusieurs workflows.

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

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-14	macOS 14 (Sonoma)	Applications iOS/macOS

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

  test-windows:
    runs-on: windows-2022

  test-mac:
    runs-on: macos-14

Évitez les tags 'latest'

Vous verrez souvent ubuntu-24.04, windows-latest ou macos-latest dans les exemples. Évitez-les. Ces alias changent sans prévenir quand GitHub met à jour ses runners. Un jour votre workflow fonctionne, le lendemain il casse parce que ubuntu-24.04 pointe vers une nouvelle version.

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

Vous pouvez aussi utiliser vos propres machines comme runners. C’est utile pour des besoins spécifiques (GPU, réseau interne, conformité). On abordera ce sujet dans un guide avancé.

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 | permet d’écrire plusieurs commandes sur plusieurs lignes.

2. Utiliser une action (uses)

steps:
  - name: Récupérer le code
    uses: actions/checkout@v4

  - name: Configurer Node.js
    uses: actions/setup-node@v4
    with:
      node-version: 20

Une action est un bloc de code réutilisable. Plutôt que de réécrire la logique pour “récupérer le code du repo” ou “installer Node.js”, vous utilisez une action existante.

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

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
           run: |
             echo "Repository: \${{ github.repository }}"
             echo "Branche: \${{ github.ref_name }}"
             echo "Auteur du commit: \${{ github.actor }}"

3. Committez et poussez sur la branche main

4. Allez dans l’onglet Actions de votre repository sur GitHub

5. Observez votre workflow s’exécuter !

Où voir les résultats ?

Une fois votre workflow déclenché :

1. Allez sur votre repository GitHub
2. Cliquez sur l’onglet Actions
3. Vous voyez la liste de toutes les exécutions (workflow runs)
4. Cliquez sur une exécution pour voir les jobs
5. Cliquez sur un job pour voir les logs de chaque step

L’interface vous montre :

• ✅ Les steps qui ont réussi (en vert)
• ❌ Les steps qui ont échoué (en rouge)
• ⏳ Les steps en cours d’exécution
• Les logs détaillés de chaque commande

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 et détruite ensuite. C’est pour ça qu’il faut toujours commencer par récupérer le code (actions/checkout).

Les variables de contexte

Dans l’exemple précédent, vous avez vu \${{ github.repository }}. C’est une variable de contexte : GitHub met à disposition des informations sur l’exécution en cours.

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

Tout cela sera approfondi dans les modules suivants.

Contrôle des connaissances

Testez vos connaissances sur les fondamentaux des workflows GitHub Actions.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

📝 6 questions

⏱️ 5 min.

🎯 70%

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

Prochaine étape

Vous savez maintenant ce qu’est un workflow et comment il fonctionne. Avant d’aller plus loin dans la syntaxe, il est essentiel de comprendre les enjeux de sécurité. Découvrez les risques et les bonnes pratiques dans Sécurité GitHub Actions : les bases.

×

📖 Voir la documentation →