Ton premier workflow

Où placer un fichier workflow ?

GitHub Actions lit automatiquement les fichiers de workflow qui se trouvent dans un dossier précis de ton dépôt : .github/workflows/. Tout fichier .yml ou .yaml dans ce dossier est un workflow potentiel.

La structure minimale de ton dépôt ressemble à ceci :

mon-projet/
├── .github/
│   └── workflows/
│       └── mon-workflow.yml   ← ton fichier workflow
├── src/
└── package.json

Anatomie d'un fichier workflow YAML

Un workflow est un fichier YAML structuré en plusieurs clés obligatoires. Voici les blocs essentiels, annotés ligne par ligne :

# Nom affiché dans l'onglet "Actions" de GitHub
name: Mon premier workflow

# Événements qui déclenchent ce workflow
on:
  push:                        # se déclenche à chaque push
    branches:
      - main                    # uniquement sur la branche main
  pull_request:               # et sur les pull requests

# Liste des jobs à exécuter
jobs:
  mon-job:                     # identifiant du job (choisi par toi)
    runs-on: ubuntu-latest    # type de runner (machine virtuelle)

    # Étapes exécutées dans l'ordre
    steps:
      - name: Étape 1           # nom affiché dans les logs
        run: echo "Bonjour !"   # commande shell à exécuter

Chaque bloc a un rôle précis :

• name — le titre du workflow, visible dans l'interface GitHub.
• on — les événements déclencheurs (push, PR, cron, manuel…).
• jobs — un ou plusieurs jobs qui s'exécutent en parallèle ou en séquence.
• runs-on — le type de machine virtuelle fournie par GitHub (runner).
• steps — la liste ordonnée des actions à effectuer dans ce job.

Ton premier workflow "Hello World"

Voici le workflow le plus simple possible. Il affiche un message dans les logs à chaque push sur main. C'est le point de départ idéal pour vérifier que tout fonctionne.

name: Hello World

on:
  push:
    branches:
      - main

jobs:
  dire-bonjour:
    runs-on: ubuntu-latest

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

      - name: Afficher la date
        run: date

      - name: Lister les fichiers
        run: ls -la

Les déclencheurs courants (on)

La clé on accepte une grande variété d'événements. Voici les plus utilisés au quotidien :

on:

  # Déclenché à chaque push sur les branches listées
  push:
    branches:
      - main
      - develop

  # Déclenché quand une pull request est ouverte ou mise à jour
  pull_request:
    branches:
      - main

  # Déclenché manuellement depuis l'interface GitHub
  workflow_dispatch:

  # Déclenché selon un planning (syntaxe cron)
  schedule:
    - cron: "0 8 * * 1-5"     # tous les jours de semaine à 8h UTC

Le déclencheur workflow_dispatch est particulièrement utile en développement : il ajoute un bouton "Run workflow" dans l'onglet Actions de GitHub, ce qui te permet de lancer le workflow à la demande sans avoir à pousser un commit.

Workflow CI pour un projet Node.js

En pratique, le workflow CI le plus courant enchaîne trois actions : récupérer le code, configurer l'environnement, puis exécuter les tests. GitHub met à disposition des actions officielles (préfixées uses:) pour simplifier ces étapes.

name: CI Node.js

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

jobs:
  tests:
    runs-on: ubuntu-latest

    steps:
      # 1. Récupère le code du dépôt dans le runner
      - name: Checkout du code
        uses: actions/checkout@v4

      # 2. Installe Node.js dans la version souhaitée
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"           # met en cache node_modules

      # 3. Installe les dépendances
      - name: Installer les dépendances
        run: npm ci              # npm ci est plus strict que npm install

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

Deux mots-clés nouveaux apparaissent ici :

• uses — invoque une action GitHub réutilisable (hébergée sur GitHub). La syntaxe est propriétaire/action@version.
• with — passe des paramètres à l'action (équivalent d'arguments de fonction).

Visualiser les résultats dans l'onglet "Actions"

Une fois ton workflow poussé sur GitHub, tout se passe dans l'onglet Actions de ton dépôt. Voici ce que tu vas y trouver :

1. Liste des exécutions — chaque push ou PR déclenche une nouvelle ligne avec son statut (vert ✓, rouge ✗, jaune en cours).
2. Détail d'un run — clique sur une exécution pour voir tous les jobs qu'elle contient.
3. Logs d'un job — clique sur un job pour voir chaque step et ses logs en temps réel.
4. Re-lancer un job — en cas d'échec, un bouton "Re-run jobs" relance uniquement les étapes en erreur.