GitHub Actions pour débutants : bases des workflows YAML et configuration des déclencheurs

L’erreur rouge à l’écran donne envie de jeter le clavier.

Le code tourne parfaitement en local, mais dès qu’on pousse sur GitHub, tout plante. Ce fichier YAML a été modifié six fois, et à chaque fois c’était un problème d’indentation. Comment ça peut être plus dur que d’écrire du code ?

En réalité, GitHub Actions n’est pas si compliqué. Ce qui pose problème, ce sont les docs : des centaines de pages de configuration dès le départ, de quoi avoir le tournis. Cet article vous explique la structure centrale d’un workflow YAML de la façon la plus simple possible.

Vous allez apprendre :

• Les quatre champs clés d’un fichier YAML et le rôle de chacun
• Comment configurer 8 déclencheurs courants et leurs cas d’usage
• Un modèle de workflow complet que vous pouvez copier directement
• Les pièges que j’ai rencontrés et comment les éviter

Prêt ? C’est parti.

Fichier de workflow YAML : les quatre champs clés

Franchement, quand j’ai découvert GitHub Actions, les fichiers YAML dans .github/workflows me semblaient illisibles. Des tonnes d’indentation, des deux-points partout, et une seule espace mal placée suffisait à tout casser.

Puis j’ai compris : en fait, il n’y a que quatre parties essentielles. Une fois celles-ci maîtrisées, le reste n’est que du bonus.

name : nommer le workflow

Ce champ est le plus simple, mais beaucoup de gens (moi y compris au début) l’ignorent.

name: CI for Node.js App

name est le nom affiché dans l’onglet GitHub Actions. Après un push, quand vous ouvrez la page Actions du dépôt, c’est ce texte que vous voyez.

Un petit conseil pour le nommage : nom du projet + description de la fonction. Par exemple MyApp CI, Backend Deploy. Quand vous aurez plusieurs workflows, vous trouverez celui que vous cherchez d’un coup d’œil.

Ce champ est optionnel. Si vous ne le renseignez pas, GitHub utilise le nom du fichier. Je déconseille de l’omettre : les noms de fichiers sont souvent des abréviations en anglais, moins parlantes.

on : quand déclencher

on est l’« interrupteur » du workflow. Vous indiquez à GitHub dans quelles conditions exécuter ce workflow.

La forme la plus simple :

on: push

Cela signifie : déclencher dès qu’il y a un push de code.

En projet réel, vous avez souvent besoin d’un contrôle plus fin. Par exemple, ne lancer le workflow que lors d’un push sur main :

on:
  push:
    branches: [main]

Ou déclencher aussi à la création d’une Pull Request :

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

Les déclencheurs sont le cœur de GitHub Actions ; une section entière est consacrée plus bas aux 8 cas courants. Pour l’instant, retenez que on définit le « moment de déclenchement » du workflow.

jobs : définir ce qu’il faut faire

jobs est le corps du workflow : il définit « quelles tâches exécuter concrètement ».

Un workflow peut contenir plusieurs jobs, exécutés en parallèle par défaut. Chaque job doit spécifier l’environnement d’exécution via le champ runs-on :

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # ... liste des étapes

Ce code définit un job nommé build, qui s’exécute sur la dernière version Ubuntu fournie par GitHub.

Si le workflow comporte plusieurs jobs, vous pouvez définir des dépendances avec le champ needs :

jobs:
  test:
    runs-on: ubuntu-latest
    # ... étapes de test

  deploy:
    needs: test  # attend la fin de test
    runs-on: ubuntu-latest
    # ... étapes de déploiement

Ainsi, deploy attend la fin de test. Si test échoue, deploy ne s’exécute pas.

steps : les étapes d’exécution concrètes

steps est la plus petite unité d’exécution dans un job : commandes ou Actions exécutées l’une après l’autre.

Chaque step se définit de deux façons :

1. Avec run pour exécuter une commande :

steps:
  - name: Install dependencies
    run: npm ci

  - name: Run tests
    run: npm test

Après run, vous mettez la commande à exécuter dans le terminal, comme en local.

2. Avec uses pour appeler une Action :

steps:
  - name: Checkout code
    uses: actions/checkout@v4

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

uses est l’atout majeur de GitHub Actions : vous réutilisez des Actions écrites par d’autres. Par exemple, actions/checkout@v4 récupère le code, actions/setup-node@v4 configure l’environnement Node.js.

with sert à passer des paramètres à l’Action. Ici, node-version: '20' indique à setup-node d’utiliser Node.js 20.

Voilà pour les quatre champs. Plus simple que prévu, non ?

Déclencheurs en détail : 8 cas courants

Comme indiqué plus haut, le champ on fixe le moment de déclenchement. GitHub Actions en propose des dizaines, mais en pratique seuls quelques-uns sont vraiment utilisés.

J’ai regroupé un tableau pour voir rapidement chaque déclencheur et son usage :

Déclencheur	Cas typique	Exemple de configuration
push	Push de code sur une branche	on: push: branches: [main]
pull_request	Création ou mise à jour de PR	on: pull_request: types: [opened, synchronize]
schedule	Tâche planifiée (Cron)	on: schedule: - cron: '0 0 * * *'
workflow_dispatch	Déclenchement manuel	on: workflow_dispatch: inputs: env: ...
workflow_call	Workflow réutilisable	on: workflow_call: inputs: ...
release	Événement de release	on: release: types: [published]
issues	Événement Issue	on: issues: types: [opened, labeled]
repository_dispatch	Événement externe	on: repository_dispatch: types: [deploy]

Voici les plus courants en détail.

push : le déclencheur de base

push est le premier que vous rencontrerez. Il se déclenche quand du code est poussé sur une branche.

Configuration simple :

on: push

Mais avec cette config, tout push sur n’importe quelle branche déclenche le workflow. Si le dépôt a 20 branches et que chaque push lance le workflow, le quota gratuit part vite.

Une config plus raisonnable limite les branches :

on:
  push:
    branches: [main, develop]

Ou avec des wildcards :

on:
  push:
    branches:
      - 'main'
      - 'release/**'  # correspond à release/v1.0, release/v2.0, etc.

pull_request : le gardien avant fusion

pull_request se déclenche à la création ou à la mise à jour d’une PR, souvent pour lancer les tests ou vérifier le style de code.

on:
  pull_request:
    branches: [main]

Le champ types permet d’affiner le moment de déclenchement :

on:
  pull_request:
    types: [opened, synchronize, reopened]

• opened : PR nouvellement créée
• synchronize : nouveaux commits sur la PR
• reopened : PR rouverte

Avec cette config, le workflow ne tourne que dans ces trois cas, sans gaspiller de ressources.

schedule : tâches planifiées

schedule utilise une expression Cron pour un déclenchement périodique. Par exemple, lancer les tests chaque nuit :

on:
  schedule:
    - cron: '0 0 * * *'  # chaque jour à 0 h UTC

L’expression Cron comporte 5 champs : minute, heure, jour du mois, mois, jour de la semaine.

Quelques horaires courants :

• 0 0 * * * : chaque jour à 0 h UTC (8 h du matin à Pékin)
• 0 */6 * * * : toutes les 6 heures
• 30 2 * * 1 : chaque lundi à 2 h 30 UTC

Attention : GitHub utilise l’heure UTC. Pour lancer une tâche à 9 h du matin à Pékin, configurez 1 h UTC (0 1 * * *).

workflow_dispatch : déclenchement manuel

Parfois vous ne voulez pas un déclenchement automatique, mais un bouton à cliquer. C’est le rôle de workflow_dispatch.

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environnement de déploiement'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

Une fois configuré, la page Actions affiche un bouton « Run workflow » ; vous choisissez les paramètres puis lancez l’exécution.

Ce déclencheur est très pratique pour le déploiement : tests automatiques, déploiement manuel.

workflow_call : réutiliser un workflow

Si la logique est complexe ou si plusieurs dépôts partagent le même flux, workflow_call transforme le workflow en composant réutilisable.

Définir un workflow réutilisable :

# .github/workflows/ci.yml
on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci && npm test

L’appeler depuis un autre workflow :

# .github/workflows/main.yml
on: push

jobs:
  call-ci:
    uses: ./.github/workflows/ci.yml
    with:
      node-version: '20'

Vous réutilisez ainsi la même logique CI entre dépôts : une modification, effet partout.

Les autres déclencheurs (release, issues, repository_dispatch) sont moins fréquents ; je ne les détaille pas ici. Consultez la documentation officielle GitHub si besoin.

Mise en pratique : premier modèle de workflow

Assez de théorie, passons à la pratique.

Voici un workflow CI complet pour un projet Node.js. Vous pouvez le copier tel quel dans votre projet :

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

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

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

      # 3. Installer les dépendances
      - name: Install dependencies
        run: npm ci

      # 4. Lancer les tests
      - name: Run tests
        run: npm test

Comment l’utiliser ?

Étape 1 : Créez le dossier .github/workflows à la racine du projet (s’il n’existe pas encore).

Étape 2 : Créez le fichier ci.yml dans ce dossier et collez-y le code ci-dessus.

Étape 3 : Commitez et poussez sur GitHub.

Après le push, ouvrez l’onglet Actions du dépôt : le workflow devrait être en cours d’exécution.

Explication ligne par ligne

• name: CI : nom du workflow, affiché sur la page Actions
• on: push: branches: [main] : déclenché lors d’un push sur main
• on: pull_request: branches: [main] : déclenché aussi lors d’une PR vers main
• jobs: build: : définit un job nommé build
• runs-on: ubuntu-latest : s’exécute sur la dernière Ubuntu fournie par GitHub
• actions/checkout@v4 : Action officielle qui récupère le code sur la VM
• actions/setup-node@v4 : Action officielle qui configure Node.js
• npm ci : installe les dépendances (plus rapide et plus propre que npm install)
• npm test : lance les tests

Si votre projet n’est pas en Node.js, remplacez les étapes du milieu. Par exemple pour Python :

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-python@v5
    with:
      python-version: '3.11'
  - run: pip install -r requirements.txt
  - run: pytest

En gros, c’est toujours le même schéma : récupérer le code → configurer l’environnement → installer les dépendances → lancer les tests.

Dépannage des erreurs de configuration courantes

Les pièges que j’ai rencontrés — pour que vous ne les refassiez pas.

Voici une checklist à parcourir en cas de problème :

Symptôme	Cause probable	Solution
Le workflow ne se déclenche pas	Filtre de branche incorrect	Vérifier branches et la casse du nom de branche
Échec d’analyse YAML	Indentation avec Tab	Utiliser uniquement des espaces ; YAML n’accepte pas Tab
Secrets inefficaces	Mauvaise portée	Vérifier que les secrets sont au bon niveau (job ou step)
Échec de dépendance entre jobs	Référence needs incorrecte	Vérifier l’orthographe du job-id, sensible à la casse
Workflow très lent	Pas de cache	Ajouter actions/cache pour mettre en cache les dépendances
Erreur de permissions	GITHUB_TOKEN insuffisant	Ajouter permissions dans le job

Erreur 1 : mauvaise indentation

C’est l’erreur la plus fréquente, sans conteste.

YAML est extrêmement sensible à l’indentation. Il faut des espaces, pas de Tab. Chaque niveau doit utiliser 2 espaces (ou un autre nombre cohérent ; GitHub Actions utilise 2 par défaut).

# Exemple incorrect : indentation incohérente
jobs:
  build:
  runs-on: ubuntu-latest  # cette ligne devrait être indentée de 4 espaces

# Forme correcte
jobs:
  build:
    runs-on: ubuntu-latest  # 4 espaces d'indentation

La plupart des éditeurs (VS Code, WebStorm) peuvent être configurés pour « insérer des espaces à la place de Tab ». Activez cette option pour éviter de taper les espaces à la main.

Erreur 2 : mauvais nom de branche

Les noms de branche GitHub sont sensibles à la casse. main et Main sont deux branches différentes.

# Si votre branche s'appelle main
on:
  push:
    branches: [Main]  # incorrect, ne se déclenchera pas

# Forme correcte
on:
  push:
    branches: [main]  # minuscules

En cas de doute, consultez la page du dépôt sur GitHub ou exécutez git branch en local.

Erreur 3 : faute de frappe dans le job-id

Quand plusieurs jobs ont des dépendances, le champ needs doit référencer exactement l’id des autres jobs.

jobs:
  test:
    runs-on: ubuntu-latest
    # ...

  deploy:
    needs: Test  # incorrect, casse incompatible
    runs-on: ubuntu-latest

# Forme correcte
jobs:
  test:
    runs-on: ubuntu-latest

  deploy:
    needs: test  # minuscules, identique à l'id du job ci-dessus
    runs-on: ubuntu-latest

Erreur 4 : mauvais niveau pour les Secrets

Les Secrets GitHub ont deux portées : niveau dépôt et niveau environnement. On les référence avec ${{ secrets.XXX }}.

# Exemple incorrect : secrets mal placés
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      API_KEY: secrets.MY_KEY  # incorrect, pas de ${{ }}

# Forme correcte
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      API_KEY: ${{ secrets.MY_KEY }}  # entouré de ${{ }}

Les Secrets sont chiffrés : leur valeur n’apparaît pas dans les logs. Pour vérifier qu’ils sont bien transmis sans les exposer :

- name: Debug
  run: echo "API_KEY is set: ${{ secrets.MY_KEY != '' }}"

Cela ne divulgue pas la clé réelle, mais confirme qu’elle n’est pas vide.

GitHub Actions vs autres outils CI/CD

Vous avez peut-être déjà utilisé Jenkins, GitLab CI ou CircleCI. Quels avantages et inconvénients par rapport à GitHub Actions ?

Voici un tableau comparatif :

Critère	GitHub Actions	GitLab CI	Jenkins	CircleCI
Langage de config	YAML	YAML	Groovy	YAML
Hébergement	Cloud natif	Cloud / auto-hébergé	Auto-hébergé	Cloud natif
Intégration	Native GitHub	Native GitLab	À configurer	À configurer
Courbe d’apprentissage	Faible	Faible	Élevée	Moyenne
Quota gratuit	2000 min/mois (dépôts privés)	400 min/mois	Illimité (auto-hébergé)	6000 min/mois
Dépôts publics	Illimité	Illimité	Illimité	Illimité

Avantages de GitHub Actions

1. Intégration sans configuration

Si votre code est déjà sur GitHub, GitHub Actions est le choix le plus naturel. Pas de webhook à configurer, pas de serveur à maintenir, pas de plugin à installer. Créez un fichier YAML, poussez-le, et ça tourne.

2. Écosystème Marketplace

Le GitHub Marketplace propose des milliers d’Actions ; AWS, Azure et Google Cloud ont des Actions officielles. Pour la plupart des besoins, quelqu’un l’a déjà écrit — il suffit de l’appeler avec uses.

3. Quota gratuit adapté aux développeurs individuels

Usage illimité sur les dépôts publics, 2000 minutes par mois sur les dépôts privés. Pour un projet personnel ou une petite équipe, c’est largement suffisant.

Quand ne pas choisir GitHub Actions ?

1. Votre code n’est pas sur GitHub

Si vous utilisez GitLab ou Bitbucket, préférez leur CI/CD intégré. GitHub Actions peut être déclenché via webhook, mais c’est plus simple d’utiliser la solution native.

2. Vous avez besoin d’un contrôle total sur l’environnement d’exécution

Les runners GitHub Actions ont des environnements fixes (Ubuntu/Windows/macOS) ; vous ne pouvez pas y installer librement vos propres logiciels. Dans ce cas, Jenkins avec un runner auto-hébergé est plus flexible.

3. Exigences de sécurité extrêmes

Les runners GitHub Actions sont des machines virtuelles hébergées par GitHub. Pour du code très sensible, un CI auto-hébergé peut être nécessaire. GitHub propose aussi les self-hosted runners comme compromis.

Mon conseil

Pour la plupart des développeurs individuels et des petites équipes :

• Code sur GitHub → GitHub Actions
• Code sur GitLab → GitLab CI
• Besoin de personnalisation poussée → Jenkins ou self-hosted runner

Il n’y a pas de solution universellement optimale ; la meilleure est celle qui vous convient.

Conclusion

Vous devriez maintenant avoir une bonne idée du fonctionnement d’un workflow YAML GitHub Actions.

Points clés :

• Quatre champs essentiels : name pour nommer, on pour déclencher, jobs pour définir les tâches, steps pour exécuter les étapes
• Huit déclencheurs courants : les plus utilisés sont push, pull_request et schedule
• Un modèle reproductible : récupérer le code → configurer l’environnement → installer les dépendances → lancer les tests
• Quatre pièges fréquents : indentation, nom de branche, job-id, Secrets

Ensuite, vous pouvez :

1. Créer votre premier workflow dans votre projet (copiez le modèle de cet article et adaptez-le)
2. Lire l’article avancé de la série « Stratégie de cache GitHub Actions : accélérer votre pipeline CI/CD par 5 », pour faire tourner vos workflows plus vite
3. Parcourir le GitHub Marketplace pour découvrir des Actions utiles prêtes à l’emploi

Une fois que vous avez goûté à l’automatisation, difficile de revenir en arrière.