Matrix strategy GitHub Actions

Imaginez que vous devez tester votre application sur 3 systèmes d'exploitation et 3 versions de Node.js. Cela fait 9 combinaisons à tester. Sans outil adapté, vous devriez copier-coller le même code 9 fois. La matrix strategy résout ce problème élégamment.

Ce que vous allez apprendre

• Construire une première matrix qui multiplie un job sur plusieurs versions ou systèmes
• Comprendre comment GitHub calcule les combinaisons et nomme les jobs produits
• Ajouter ou retirer des combinaisons avec include et exclude
• Contrôler l'exécution avec fail-fast et max-parallel
• Éviter l'explosion du nombre de jobs grâce aux règles d'or de la page

C'est quoi une matrix, concrètement ?

Une matrix décrit des axes de variation, et GitHub génère un job par combinaison. Vous écrivez la définition du job une seule fois, la duplication est prise en charge par la plateforme. La documentation officielle détaille chaque clé de strategy.matrix.

Avant/après : la puissance de la matrix

❌ Sans matrix : duplication massive

jobs:
  test-ubuntu-18:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: 18
      - run: npm test

  test-ubuntu-20:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: 20
      - run: npm test

  test-ubuntu-22:
    # ... encore et encore
  test-windows-18:
    # ... 6 autres jobs identiques

✅ Avec matrix : un seul bloc

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-24.04, windows-2022, macos-14]
        node: [18, 20, 22]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: ${{ matrix.node }}
      - run: npm test

Gain de temps

Non seulement vous écrivez moins de code, mais les 9 jobs s'exécutent en parallèle. Ce qui prendrait 45 minutes en séquentiel ne prend que 5 minutes avec une matrix !

Votre première matrix en 3 étapes

1. Définir les axes : quelles variables voulez-vous combiner ?

   strategy:
     matrix:
       os: [ubuntu-24.04, windows-2022]
       python: ['3.10', '3.11', '3.12']

2. Utiliser les variables : accédez aux valeurs avec ${{ matrix.xxx }}

   runs-on: ${{ matrix.os }}
   steps:
     - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
       with:
         python-version: ${{ matrix.python }}

3. Lancer le workflow : GitHub génère automatiquement 2 × 3 = 6 jobs

Exemple complet commenté

name: Tests multi-configurations

on: [push, pull_request]

jobs:
  test:
    # Le nom du job affiche les valeurs de la matrix
    name: Test Python ${{ matrix.python }} sur ${{ matrix.os }}

    strategy:
      matrix:
        # Axe 1 : les systèmes d'exploitation
        os: [ubuntu-24.04, windows-2022]
        # Axe 2 : les versions de Python
        python: ['3.10', '3.11', '3.12']

    # Cette ligne UTILISE la valeur de matrix.os
    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      # Cette action UTILISE la valeur de matrix.python
      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ matrix.python }}

      - run: pip install -e ".[test]"
      - run: pytest

Résultat dans l'interface GitHub :

✓ Test Python 3.10 sur ubuntu-24.04    (2m 15s)
✓ Test Python 3.11 sur ubuntu-24.04    (2m 08s)
✓ Test Python 3.12 sur ubuntu-24.04    (2m 12s)
✓ Test Python 3.10 sur windows-2022   (3m 45s)
✓ Test Python 3.11 sur windows-2022   (3m 38s)
✓ Test Python 3.12 sur windows-2022   (3m 42s)

Comment ça marche techniquement ?

Le nombre de jobs générés se calcule, il ne se devine pas. Savoir le prévoir évite la mauvaise surprise du workflow qui lance soudain quarante exécutions.

Le produit cartésien

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

GitHub calcule le produit cartésien de tous les axes. Ne vous laissez pas intimider par ce terme mathématique : c'est simplement toutes les combinaisons possibles entre vos listes de valeurs.

Imaginez un menu de restaurant : si vous avez 2 entrées et 3 plats, vous pouvez composer 2 × 3 = 6 menus différents. Le produit cartésien, c'est exactement ça !

Avec une matrix à deux axes :

Axe 1: [A, B]      ┐
                   ├──→ Combinaisons: [A,X], [A,Y], [B,X], [B,Y]
Axe 2: [X, Y]      ┘

2 × 2 = 4 jobs

Comment lire ce schéma ? GitHub prend chaque valeur du premier axe (A, puis B) et l'associe à chaque valeur du second axe (X, puis Y). Résultat : 4 combinaisons, donc 4 jobs parallèles.

Avec trois axes, le principe reste le même, on multiplie simplement les possibilités :

os:       [ubuntu, windows]        2 valeurs
node:     [18, 20, 22]             3 valeurs
database: [postgres, mysql]        2 valeurs
                                   ─────────
                                   2 × 3 × 2 = 12 jobs

Traduction concrète : chaque combinaison OS + version Node + base de données sera testée. Ubuntu avec Node 18 et Postgres, Ubuntu avec Node 18 et MySQL, Ubuntu avec Node 20 et Postgres... et ainsi de suite jusqu'aux 12 combinaisons.

Attention à l'explosion combinatoire

Une matrix avec 4 axes de 5 valeurs chacun génère 5⁴ = 625 jobs ! Chaque job consomme des minutes de CI. Restez raisonnable.

Les variables de la matrix

Chaque valeur définie dans la matrix devient accessible via le context matrix :

strategy:
  matrix:
    fruit: [pomme, banane]
    couleur: [rouge, jaune]

# Dans les steps, vous pouvez utiliser :
# ${{ matrix.fruit }}   → "pomme" ou "banane"
# ${{ matrix.couleur }} → "rouge" ou "jaune"

Include : ajouter ou enrichir des combinaisons

Le mot-clé include est comme un bonus pour votre matrix. Il permet deux choses :

1. Ajouter des combinaisons qui n'existent pas dans le produit cartésien
2. Enrichir des combinaisons existantes avec des variables supplémentaires

Cas 1 : Ajouter une combinaison spéciale

Imaginons que vous voulez tester Node 22, mais uniquement sur Ubuntu (car c'est expérimental sur les autres OS) :

strategy:
  matrix:
    os: [ubuntu-24.04, windows-2022]
    node: [18, 20]
    include:
      # Cette combinaison N'EXISTE PAS dans le produit cartésien
      # (node 22 n'est pas dans la liste originale)
      - os: ubuntu-24.04
        node: 22
        experimental: true    # Variable bonus pour cette combinaison

Sans include : 2 × 2 = 4 combinaisons Avec include : 4 + 1 = 5 combinaisons

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Cas 2 : Enrichir une combinaison existante

Parfois, vous avez besoin de variables différentes selon la combinaison. Par exemple, le shell par défaut varie selon l'OS :

strategy:
  matrix:
    os: [ubuntu-24.04, windows-2022, macos-14]
    include:
      # Ces lignes ENRICHISSENT les combinaisons existantes
      # en ajoutant une variable "shell"
      - os: windows-2022
        shell: pwsh           # PowerShell pour Windows
      - os: ubuntu-24.04
        shell: bash           # Bash pour Ubuntu
      - os: macos-14
        shell: bash           # Bash pour macOS

runs-on: ${{ matrix.os }}
defaults:
  run:
    shell: ${{ matrix.shell }}   # Utilise le shell approprié

Astuce : identifier include

Pour savoir si include ajoute ou enrichit :

• Si les valeurs correspondent à une combinaison existante → enrichit
• Si les valeurs créent une nouvelle combinaison → ajoute

Cas 3 : Matrix basée uniquement sur include

Vous pouvez créer une matrix sans axes, uniquement avec include. Utile pour des configurations très différentes :

strategy:
  matrix:
    include:
      - name: 'Production EU'
        region: 'eu-west-1'
        env: 'prod'
        replicas: 3
      - name: 'Production US'
        region: 'us-east-1'
        env: 'prod'
        replicas: 3
      - name: 'Staging'
        region: 'eu-west-1'
        env: 'staging'
        replicas: 1

# 3 jobs avec des configurations complètement personnalisées

Exclude : retirer des combinaisons indésirables

exclude fait l'inverse de include : il retire des combinaisons du produit cartésien. C'est comme dire "je veux tout, sauf ça".

Pourquoi exclure des combinaisons ?

Quelques raisons courantes :

• Une version n'est pas supportée sur un OS particulier
• Une combinaison est redondante ou inutile
• Économiser des minutes de CI sur des tests non pertinents

Exemple concret

strategy:
  matrix:
    os: [ubuntu-24.04, windows-2022, macos-14]
    node: [18, 20, 22]
    exclude:
      # Node 22 a des problèmes connus sur Windows
      - os: windows-2022
        node: 22
      # On ne teste pas toutes les versions sur macOS (coûteux)
      - os: macos-14
        node: 18

Calcul des jobs :

• Produit cartésien : 3 × 3 = 9 combinaisons
• Exclusions : -2 combinaisons
• Total : 7 jobs

Contrôler l'exécution : fail-fast et max-parallel

Par défaut, une matrix lance tout en parallèle et s'arrête au premier échec. Ces deux réglages permettent d'arbitrer entre la vitesse de retour et la quantité d'informations obtenue en une exécution.

fail-fast : tout arrêter ou continuer ?

Par défaut, fail-fast est à true. Cela signifie que si un seul job de la matrix échoue, GitHub annule tous les autres immédiatement.

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Quand garder fail-fast: true (défaut) :

• Vous voulez un feedback rapide
• Un échec rend les autres résultats inutiles
• Vous économisez des minutes de CI

Quand utiliser fail-fast: false :

• Vous voulez voir tous les résultats
• Vous debuggez et cherchez quelles combinaisons échouent
• Les jobs sont indépendants

strategy:
  fail-fast: false  # Continue même si un job échoue
  matrix:
    node: [18, 20, 22]

max-parallel : limiter les jobs simultanés

Par défaut, GitHub lance tous les jobs en parallèle. Avec max-parallel, vous pouvez limiter ce nombre :

strategy:
  max-parallel: 2  # Maximum 2 jobs en même temps
  matrix:
    node: [18, 20, 22]  # 3 jobs au total

Pourquoi limiter le parallélisme ?

Situation	Raison
Tests avec base de données partagée	Éviter les conflits de données
API externe avec rate limiting	Ne pas dépasser les quotas
Runners self-hosted limités	Éviter la saturation
Économiser les minutes	Réduire les coûts (repos privés)

Glissez pour voir

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Techniques avancées

Ces constructions servent quand les valeurs de la matrix ne sont pas connues à l'écriture du workflow, ou quand elles dépendent du contexte d'exécution.

Matrix dynamique avec fromJSON

Parfois, vous ne connaissez pas les valeurs de la matrix à l'avance. Par exemple, vous voulez tester uniquement les modules modifiés. La solution : générer la matrix dynamiquement dans un premier job.

jobs:
  # Job 1 : Déterminer quoi tester
  setup:
    runs-on: ubuntu-24.04
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - id: set-matrix
        run: |
          # Génère un JSON qui sera la matrix
          echo 'matrix={"version":["1.0","2.0","3.0"]}' >> $GITHUB_OUTPUT

  # Job 2 : Utilise la matrix générée
  build:
    needs: setup
    strategy:
      # fromJSON convertit la string en objet
      matrix: ${{ fromJSON(needs.setup.outputs.matrix) }}
    runs-on: ubuntu-24.04
    steps:
      - run: echo "Building version ${{ matrix.version }}"

Comment ça marche ?

1. Le job setup génère une string JSON : {"version":["1.0","2.0","3.0"]}
2. Cette string est passée via outputs
3. fromJSON() la convertit en objet utilisable par matrix

Matrix depuis un fichier de configuration

Pour une meilleure maintenabilité, stockez la matrix dans un fichier :

Fichier .github/matrix.json :

{
  "include": [
    { "name": "app-frontend", "path": "./apps/frontend" },
    { "name": "app-backend", "path": "./apps/backend" },
    { "name": "app-api", "path": "./apps/api" }
  ]
}

Workflow :

jobs:
  setup:
    runs-on: ubuntu-24.04
    outputs:
      matrix: ${{ steps.read.outputs.matrix }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - id: read
        run: |
          # jq -c compacte le JSON sur une ligne
          echo "matrix=$(cat .github/matrix.json | jq -c .)" >> $GITHUB_OUTPUT

  test:
    needs: setup
    strategy:
      matrix: ${{ fromJSON(needs.setup.outputs.matrix) }}
    runs-on: ubuntu-24.04
    steps:
      - run: echo "Testing ${{ matrix.name }} at ${{ matrix.path }}"

Voir le guide jq pour maîtriser le traitement JSON en ligne de commande.

Exemples prêts à l'emploi

Ces workflows sont complets et fonctionnent tels quels. Adaptez les versions et les noms de dépôt, le reste tient sans modification.

Test multi-versions Python

Un classique : tester sur plusieurs versions de Python et plusieurs OS.

name: Tests Python

on: [push, pull_request]

permissions:
  contents: read

jobs:
  test:
    name: Python ${{ matrix.python }} / ${{ matrix.os }}
    strategy:
      fail-fast: false    # Voir tous les résultats
      matrix:
        os: [ubuntu-24.04, windows-2022, macos-14]
        python: ['3.10', '3.11', '3.12']
        exclude:
          # macOS coûte cher, on limite les versions testées
          - os: macos-14
            python: '3.10'

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ matrix.python }}

      - run: pip install -e ".[test]"
      - run: pytest --verbose

Build multi-architecture Docker

Pour créer des images Docker ARM64 et AMD64 :

name: Build Multi-Arch

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  build:
    name: Build ${{ matrix.platform }}
    strategy:
      matrix:
        include:
          - platform: linux/amd64
            runner: ubuntu-24.04
          - platform: linux/arm64
            runner: ubuntu-24.04-arm    # Runner ARM natif

    runs-on: ${{ matrix.runner }}

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Build image
        run: |
          docker build \
            --platform ${{ matrix.platform }} \
            -t myapp:${{ github.sha }}-${{ matrix.platform }} .

Déploiement multi-environnements

Déployer sur staging ou production selon le choix de l'utilisateur :

name: Deploy

on:
  workflow_dispatch:
    inputs:
      target:
        description: 'Où déployer ?'
        type: choice
        options: [staging, production]
        default: staging

permissions:
  contents: read

jobs:
  deploy:
    name: Deploy to ${{ matrix.env }}
    strategy:
      matrix:
        include:
          - env: staging
            url: https://staging.example.com
            replicas: 1
          - env: production
            url: https://example.com
            replicas: 3
        exclude:
          # Astuce : exclure l'environnement non choisi
          - env: ${{ github.event.inputs.target == 'staging' && 'production' || 'staging' }}

    environment: ${{ matrix.env }}
    runs-on: ubuntu-24.04

    steps:
      - run: |
          echo "🚀 Deploying to ${{ matrix.env }}"
          echo "URL: ${{ matrix.url }}"
          echo "Replicas: ${{ matrix.replicas }}"

Les 5 règles d'or des matrix

Ces cinq réflexes séparent une matrix lisible et économe d'une matrix qui sature les runners sans qu'on sache pourquoi.

1. Nommez vos jobs explicitement

Sans nom personnalisé, GitHub affiche "test (1)", "test (2)"... Peu utile !

jobs:
  test:
    # ✅ Nom explicite avec les valeurs de la matrix
    name: Test ${{ matrix.os }} / Node ${{ matrix.node }}
    strategy:
      matrix:
        os: [ubuntu-24.04, windows-2022]
        node: [18, 20]

Résultat dans l'interface :

✓ Test ubuntu-24.04 / Node 18    (2m 15s)
✓ Test ubuntu-24.04 / Node 20    (2m 08s)
✓ Test windows-2022 / Node 18   (3m 45s)
✓ Test windows-2022 / Node 20   (3m 38s)

2. Utilisez fail-fast: false pour débugger

Quand vous cherchez quelles combinaisons échouent, vous voulez tous les résultats :

strategy:
  fail-fast: false  # Ne pas annuler les autres jobs en cas d'échec
  matrix:
    node: [18, 20, 22]

3. Limitez la taille de votre matrix

Piège courant

Une matrix trop large consomme énormément de minutes CI et ralentit le feedback. Visez 10-20 combinaisons maximum pour un workflow de PR.

# ❌ ÉVITER : 3 × 4 × 3 = 36 combinaisons !
matrix:
  os: [ubuntu, windows, macos]
  node: [16, 18, 20, 22]
  database: [postgres, mysql, sqlite]

# ✅ PRÉFÉRER : combinaisons ciblées
matrix:
  include:
    # Test complet sur Ubuntu (référence)
    - os: ubuntu-24.04
      node: 20
      database: postgres
    # Validation Windows
    - os: windows-2022
      node: 20
      database: postgres
    # Test rétro-compatibilité
    - os: ubuntu-24.04
      node: 18
      database: mysql

4. Gérez les spécificités de chaque OS

Windows et Linux n'utilisent pas les mêmes commandes. Utilisez include pour personnaliser :

strategy:
  matrix:
    os: [ubuntu-24.04, windows-2022]
    include:
      - os: ubuntu-24.04
        script: ./scripts/test.sh
        shell: bash
      - os: windows-2022
        script: .\scripts\test.ps1
        shell: pwsh

steps:
  - run: ${{ matrix.script }}
    shell: ${{ matrix.shell }}

5. Documentez vos exclusions

Les exclusions peuvent être mystérieuses pour les contributeurs. Ajoutez toujours un commentaire :

exclude:
  # Python 3.9 est en fin de vie (EOL octobre 2025)
  # On ne le supporte plus que sur Ubuntu pour les systèmes legacy
  - python: '3.9'
    os: macos-14
  - python: '3.9'
    os: windows-2022

  # Node 22 a un bug connu avec Windows Server 2022
  # Voir https://github.com/nodejs/node/issues/XXXXX
  - node: 22
    os: windows-2022

À retenir

Concept	Syntaxe	Usage
Axes de la matrix	matrix: { os: [...], node: [...] }	Définir les combinaisons
Accès aux valeurs	${{ matrix.os }}	Utiliser dans les steps
Ajouter/enrichir	include: [...]	Cas spéciaux
Exclure	exclude: [...]	Retirer des combinaisons
Continuer sur échec	fail-fast: false	Debug
Limiter le parallélisme	max-parallel: N	Ressources limitées
Matrix dynamique	fromJSON(...)	Valeurs calculées

Glissez pour voir

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 →