Utilisation d’une matrice pour vos travaux

À propos des stratégies de matrice

Une stratégie de matrice vous permet d’utiliser des variables dans une définition de travail unique pour créer automatiquement plusieurs exécutions de travaux basées sur les combinaisons des variables. Par exemple, vous pouvez utiliser une stratégie de matrice pour tester votre code dans plusieurs versions d’un langage ou sur plusieurs systèmes d’exploitation.

Utilisation d’une stratégie de matrice

Utilisez jobs.<job_id>.strategy.matrix pour définir une matrice de différentes configurations de travail. Dans votre matrice, définissez une ou plusieurs variables suivies d’un tableau de valeurs. Par exemple, la matrice suivante a une variable appelée version avec la valeur [10, 12, 14], et une variable appelée os avec la valeur [ubuntu-latest, windows-latest] :

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

Un travail s’exécute pour chaque combinaison possible des variables. Dans cet exemple, le workflow exécute six travaux, un pour chaque combinaison des variables os et version.

Par défaut, GitHub optimise le nombre de travaux exécutés en parallèle en fonction de la disponibilité des exécuteurs. L’ordre des variables dans la matrice détermine l’ordre dans lequel les travaux sont créés. La première variable que vous définissez est le premier travail créé dans votre exécution de workflow. Par exemple, la matrice ci-dessus crée les travaux dans l’ordre suivant :

• {version: 10, os: ubuntu-latest}
• {version: 10, os: windows-latest}
• {version: 12, os: ubuntu-latest}
• {version: 12, os: windows-latest}
• {version: 14, os: ubuntu-latest}
• {version: 14, os: windows-latest}

Une matrice génère au maximum 256 travaux par exécution de workflow. Cette limite s’applique aux exécuteurs hébergés sur GitHub et à ceux qui sont autohébergés.

Les variables que vous définissez deviennent des propriétés dans le contexte matrix. Vous pouvez référencer la propriété dans d’autres zones de votre fichier de workflow. Dans cet exemple, vous pouvez utiliser matrix.version et matrix.os pour accéder aux valeurs actuelles de version et os utilisées par le travail. Pour plus d’informations, consultez « Contextes ».

Exemple : Utilisation d’une matrice à une seule dimension

Vous pouvez spécifier une seule variable pour créer une matrice unidimensionnelle.

Par exemple, le workflow suivant définit la variable version avec les valeurs [10, 12, 14]. Le workflow exécute trois travaux, un pour chaque valeur de la variable. Chaque travail accède à la valeur version via le contexte matrix.version, et passe la valeur en tant que node-version à l’action actions/setup-node.

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.version }}

Exemple : Utilisation d’une matrice à plusieurs dimensions

Vous pouvez spécifier plusieurs variables pour créer une matrice multidimensionnelle. Un travail s’exécute pour chaque combinaison possible des variables.

Par exemple, le workflow suivant spécifie deux variables :

• Deux systèmes d’exploitation spécifiés dans la variable os
• Trois versions de Node.js spécifiées dans la variable version

Le workflow exécute six travaux, un pour chaque combinaison des variables os et version. Chaque travail affecte la valeur runs-on à la valeur os actuelle, et passe la valeur version actuelle à l’action actions/setup-node.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [ubuntu-22.04, ubuntu-20.04]
        version: [10, 12, 14]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.version }}

Une configuration de variable dans une matrice peut être un array de objects.

matrix:
  os:
    - ubuntu-latest
    - macos-latest
  node:
    - version: 14
    - version: 20
      env: NODE_OPTIONS=--openssl-legacy-provider

Cette matrice produit quatre travaux avec des contextes correspondants.

- matrix.os: ubuntu-latest
  matrix.node.version: 14
- matrix.os: ubuntu-latest
  matrix.node.version: 20
  matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider
- matrix.os: macos-latest
  matrix.node.version: 14
- matrix.os: macos-latest
  matrix.node.version: 20
  matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider

Exemple : Utilisation de contextes pour créer des matrices

Vous pouvez utiliser des contextes pour créer des matrices. Pour plus d’informations sur les contextes, consultez « Contextes ».

Par exemple, le workflow suivant se déclenche sur l’événement repository_dispatch et utilise les informations de la charge utile de l’événement pour générer la matrice. Lorsqu’un événement de répartition de référentiel est créé avec une charge utile comme celle ci-dessous, la variable de matrice version a la valeur [12, 14, 16]. Pour plus d’informations sur le déclencheur repository_dispatch, consultez « Événements qui déclenchent des flux de travail ».

{
  "event_type": "test",
  "client_payload": {
    "versions": [12, 14, 16]
  }
}

on:
  repository_dispatch:
    types:
      - test
 
jobs:
  example_matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ${{ github.event.client_payload.versions }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.version }}

Développement ou ajout de configurations de matrice

Utilisez jobs.<job_id>.strategy.matrix.include pour développer des configurations de matrice existantes ou ajouter de nouvelles configurations. La valeur de include est une liste d’objets.

Pour chaque objet de la liste include, les paires clé:valeur dans l’objet sont ajoutées à chacune des combinaisons de matrices si aucune des paires clé:valeur ne remplace les valeurs de matrice d’origine. Si l’objet ne peut pas être ajouté à l’une des combinaisons de matrices, une nouvelle combinaison de matrices est créée à la place. Notez que les valeurs de matrice d’origine ne seront pas remplacées, mais que les valeurs de matrice ajoutées peuvent être remplacées.

Par exemple, cette matrice :

strategy:
  matrix:
    fruit: [apple, pear]
    animal: [cat, dog]
    include:
      - color: green
      - color: pink
        animal: cat
      - fruit: apple
        shape: circle
      - fruit: banana
      - fruit: banana
        animal: cat

entraîne six travaux avec les combinaisons de matrices suivantes :

• {fruit: apple, animal: cat, color: pink, shape: circle}
• {fruit: apple, animal: dog, color: green, shape: circle}
• {fruit: pear, animal: cat, color: pink}
• {fruit: pear, animal: dog, color: green}
• {fruit: banana}
• {fruit: banana, animal: cat}

en suivant cette logique :

• {color: green} est ajouté à toutes les combinaisons de matrices d’origine, car il peut être ajouté sans remplacer aucune partie des combinaisons d’origine.
• {color: pink, animal: cat} ajoute color:pink uniquement aux combinaisons de matrices d’origine qui incluent animal: cat. Cela remplace le color: green qui a été ajouté par l’entrée include précédente.
• {fruit: apple, shape: circle} ajoute shape: circle uniquement aux combinaisons de matrices d’origine qui incluent fruit: apple.
• {fruit: banana} ne peut pas être ajouté à une combinaison de matrices d’origine sans remplacer une valeur. Il est donc ajouté en tant que combinaison de matrices supplémentaire.
• {fruit: banana, animal: cat} ne peut pas être ajouté à une combinaison de matrices d’origine sans remplacer une valeur. Il est donc ajouté en tant que combinaison de matrices supplémentaire. Cela ne l’ajoute pas à la combinaison de matrices {fruit: banana}, car cette combinaison n’était pas l’une des combinaisons de matrices d’origine.

Exemple : Développement de configurations

Par exemple, le workflow suivant exécute quatre tâches, un pour chaque combinaison de os et node. Lorsque le travail pour la valeur os de windows-latest et la valeur node de 16 s’exécute, une variable supplémentaire appelée npm avec la valeur 6 sera incluse dans le travail.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest]
        node: [14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

Exemple : Ajout de configurations

Par exemple, cette matrice exécutera 10 travaux, un pour chaque combinaison de os et version dans la matrice, plus un travail pour la valeur os de windows-latest et la valeur version de 17.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
        version: [12, 14, 16]
        include:
          - os: windows-latest
            version: 17

Si vous ne spécifiez aucune variable de matrice, toutes les configurations sous include sont exécutées. Par exemple, le workflow suivant exécuterait deux travaux, un pour chaque entrée include. Cela vous permet de tirer parti de la stratégie de matrice sans avoir une matrice entièrement remplie.

jobs:
  includes_only:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - site: "production"
            datacenter: "site-a"
          - site: "staging"
            datacenter: "site-b"

Exclusion de configurations de matrice

Pour supprimer des configurations spécifiques définies dans la matrice, utilisez jobs.<job_id>.strategy.matrix.exclude. Une configuration exclue a seulement besoin d’être une correspondance partielle pour être exclue. Par exemple, le workflow suivant exécute neuf travaux : un travail pour chacune des 12 configurations, moins un travail exclu qui correspond à {os: macos-latest, version: 12, environment: production}, et les deux travaux exclus qui correspondent à {os: windows-latest, version: 16}.

strategy:
  matrix:
    os: [macos-latest, windows-latest]
    version: [12, 14, 16]
    environment: [staging, production]
    exclude:
      - os: macos-latest
        version: 12
        environment: production
      - os: windows-latest
        version: 16
runs-on: ${{ matrix.os }}

Gestion des échecs

Vous pouvez contrôler la façon dont les échecs de travaux sont gérés avec jobs.<job_id>.strategy.fail-fast et jobs.<job_id>.continue-on-error.

jobs.<job_id>.strategy.fail-fast s’applique à l’ensemble de la matrice. Si jobs.<job_id>.strategy.fail-fast est défini sur true, ou son expression aboutit à true, GitHub annule tous les travaux en cours et en file d’attente dans la matrice en cas d’échec d’un des travaux de la matrice. Cette propriété a la valeur par défaut true.

jobs.<job_id>.continue-on-error s’applique à un seul travail. Si jobs.<job_id>.continue-on-error a la valeur true, les autres travaux de la matrice continuent de s’exécuter même en cas d’échec du travail avec jobs.<job_id>.continue-on-error: true.

Vous pouvez utiliser jobs.<job_id>.strategy.fail-fast et jobs.<job_id>.continue-on-error ensemble. Par exemple, le workflow suivant démarre quatre travaux. Pour chaque travail, continue-on-error est déterminé par la valeur de matrix.experimental. En cas d’échec de l’un des travaux avec continue-on-error: false, tous les travaux en cours ou en file d’attente sont annulés. En cas d’échec du travail avec continue-on-error: true, les autres travaux ne sont pas affectés.

jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: true
      matrix:
        version: [6, 7, 8]
        experimental: [false]
        include:
          - version: 9
            experimental: true

Définition du nombre maximal de travaux simultanés

Par défaut, GitHub optimise le nombre de travaux exécutés en parallèle en fonction de la disponibilité de l’exécuteur. Pour définir le nombre maximal de travaux pouvant s’exécuter simultanément lors de l’utilisation d’une stratégie de travail matrix, utilisez jobs.<job_id>.strategy.max-parallel.

Par exemple, le workflow suivant exécute au maximum de deux travaux à la fois, même s’il existe des exécuteurs disponibles pour exécuter les six travaux en même temps.

jobs:
  example_matrix:
    strategy:
      max-parallel: 2
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]