Matrice, cache et artefacts dans GitHub Actions

Trois mécanismes de GitHub Actions rendent un pipeline plus complet et plus rapide : la matrice lance le même job sur plusieurs versions ou systèmes en parallèle, le cache garde des fichiers coûteux à télécharger d'une exécution à l'autre, et les artefacts conservent les fichiers produits par un job pour les transmettre à un autre job ou les télécharger. Ce chapitre explique chacun d'eux, quand choisir l'un ou l'autre, et comment factoriser un workflow qui se répète.

La matrice : tester plusieurs versions en parallèle

sorbier-frais tourne en production sur Node.js 24. L'équipe veut vérifier qu'il fonctionne aussi sur Node.js 22, encore installé sur un ancien serveur, et sur Node.js 26, la nouvelle version LTS, pour préparer la migration. Au lieu d'écrire trois jobs identiques, on déclare une matrice :

jobs:
  tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [22, 24, 26]
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.node }}
          cache: npm
      - run: npm ci
      - run: npm test -- --ci

GitHub crée trois jobs, tests (22), tests (24) et tests (26), qui tournent en parallèle. Dans chacun, ${{ matrix.node }} vaut la version correspondante.

Une matrice peut combiner plusieurs dimensions : GitHub crée un job par combinaison.

    strategy:
      fail-fast: false
      max-parallel: 4
      matrix:
        node: [22, 24, 26]
        os: [ubuntu-latest, windows-latest]
        exclude:
          - node: 22
            os: windows-latest
        include:
          - node: 26
            os: ubuntu-latest
            experimental: true
    runs-on: ${{ matrix.os }}
    continue-on-error: ${{ matrix.experimental == true }}

Une matrice génère au maximum 256 jobs par exécution. En pratique, garde-la petite : trois versions de Node.js sur Linux suffisent pour une API ; ajoute Windows seulement si l'application y tourne vraiment.

Le cache : ne pas tout retélécharger

À chaque exécution, le runner est neuf : npm ci retélécharge toutes les dépendances depuis le registre npm, ce qui peut prendre une minute ou plus. Le cache sauvegarde un dossier à la fin d'un job et le restaure au début des suivants.

La méthode simple : le cache intégré aux actions setup-*. actions/setup-node avec cache: npm met en cache le dossier de téléchargement de npm (~/.npm, pas node_modules), avec une clé calculée à partir de package-lock.json. actions/setup-python fait de même avec cache: pip, actions/setup-java avec cache: maven.

      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm

La méthode générale : actions/cache. Pour tout autre dossier, on décrit soi-même le chemin et la clé. Exemple avec le cache de Composer pour une application PHP :

      - name: Trouver le dossier de cache de Composer
        id: composer-cache
        run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"

      - uses: actions/cache@v6
        with:
          path: ${{ steps.composer-cache.outputs.dir }}
          key: composer-${{ runner.os }}-${{ hashFiles('composer.lock') }}
          restore-keys: |
            composer-${{ runner.os }}-

      - run: composer install --no-interaction --no-progress

Le fonctionnement de la clé :

1. Au début du job, GitHub cherche un cache dont la clé est exactement composer-Linux-<empreinte de composer.lock>. S'il le trouve (cache hit), il le restaure.
2. Sinon (cache miss), il essaie les préfixes de restore-keys et restaure le cache le plus récent qui commence par composer-Linux- : une version un peu ancienne, que Composer complète.
3. À la fin du job, s'il n'y a pas eu de correspondance exacte, il enregistre le dossier sous la clé exacte.

Comme la clé contient l'empreinte de composer.lock, toute modification des dépendances produit une nouvelle clé : le cache ne peut pas servir des versions périmées.

Les artefacts : conserver et transmettre des fichiers

Un artefact est un fichier ou un dossier produit par un job et conservé après la fin de l'exécution : le dossier dist/ construit, un rapport de couverture des tests, un journal d'erreur, une archive à livrer. On l'envoie avec actions/upload-artifact et on le récupère avec actions/download-artifact, dans un autre job ou depuis la page de l'exécution.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v7
        with:
          name: site-statique
          path: dist/
          retention-days: 14
          if-no-files-found: error

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v8
        with:
          name: site-statique
          path: dist/
      - run: ls -R dist/

Le job deploy ne refait ni checkout, ni installation, ni construction : il récupère exactement les fichiers construits et testés par build. C'est la règle « construire une fois, déployer partout » du chapitre 2.

Pour un rapport de tests, envoie l'artefact même en cas d'échec, puisque c'est justement là qu'il sert :

      - run: npm test -- --ci --coverage
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: couverture-node-${{ matrix.node }}
          path: coverage/

Les artefacts se téléchargent en bas de la page de l'exécution, ou en ligne de commande avec gh run download. Ils comptent dans le quota de stockage des dépôts privés (500 Mo sur l'offre gratuite).

Cache ou artefact ?

Ne pas se répéter : workflows réutilisables et actions composites

Les jobs lint, tests et build répètent les mêmes trois étapes : checkout, setup-node, npm ci. Deux mécanismes évitent ces copies.

L'action composite regroupe des étapes dans une action locale. On crée .github/actions/preparer-node/action.yml :

name: Préparer Node.js
description: Installe Node.js et les dépendances du projet
inputs:
  node-version:
    description: Version de Node.js à installer
    default: '24'
runs:
  using: composite
  steps:
    - uses: actions/setup-node@v7
      with:
        node-version: ${{ inputs.node-version }}
        cache: npm
    - run: npm ci
      shell: bash

Dans une action composite, chaque étape run doit préciser son shell. Les jobs l'utilisent après le checkout (l'action est un fichier du dépôt, il faut d'abord le récupérer) :

    steps:
      - uses: actions/checkout@v7
      - uses: ./.github/actions/preparer-node
        with:
          node-version: 26
      - run: npm test -- --ci

Le workflow réutilisable factorise des jobs entiers. Le fichier .github/workflows/tests-node.yml se déclare avec workflow_call :

name: Tests Node.js

on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '24'

permissions:
  contents: read

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

Un autre workflow l'appelle au niveau d'un job, avec uses à la place de runs-on et steps :

jobs:
  tests-26:
    uses: ./.github/workflows/tests-node.yml
    with:
      node-version: '26'

S'il a besoin de secrets, l'appelant les transmet un par un sous secrets:, ou tous avec secrets: inherit. Une organisation peut ainsi écrire une fois son workflow de tests et l'appeler depuis tous ses dépôts, avec uses: organisation/depot/.github/workflows/tests-node.yml@v1.

Exercices

    strategy:
      matrix:
        node: [22, 24, 26]
        os: [ubuntu-latest, windows-latest]
        exclude:
          - node: 22
            os: windows-latest
        include:
          - node: 24
            os: macos-latest

jobs:
  tests:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        python: ['3.13', '3.14']
        os: [ubuntu-latest, windows-latest]
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: ${{ matrix.python }}
          cache: pip
      - run: pip install -r requirements.txt
      - run: pytest

      - uses: actions/upload-artifact@v7
        with:
          name: rapport-tests
          path: reports/junit.xml

      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: rapport-tests-node-${{ matrix.node }}
          path: reports/junit.xml