À 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 Enterprise Cloud 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 Enterprise Cloud 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 « Accès à des informations contextuelles sur l’exécution d’un workflow ».
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 object
s.
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 « Accès à des informations contextuelles sur l’exécution d’un workflow ».
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}
ajoutecolor:pink
uniquement aux combinaisons de matrices d’origine qui incluentanimal: cat
. Cela remplace lecolor: green
qui a été ajouté par l’entréeinclude
précédente.{fruit: apple, shape: circle}
ajouteshape: circle
uniquement aux combinaisons de matrices d’origine qui incluentfruit: 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 }}
Remarque : Toutes les combinaisons include
sont traitées après exclude
. Cela vous permet d’utiliser include
pour rajouter des combinaisons qui ont été précédemment exclues.
Exemple : Utilisation d’une sortie pour définir deux matrices
Vous pouvez utiliser la sortie d’une tâche pour définir des matrices pour plusieurs travaux.
Par exemple, le flux de travail suivant montre comment définir une matrice de valeurs dans une tâche, utiliser cette matrice dans une deuxième tâche pour produire des artefacts, puis consommer ces artefacts dans une troisième tâche. Chaque artefact est associé à une valeur de la matrice.
name: shared matrix on: push: workflow_dispatch: jobs: define-matrix: runs-on: ubuntu-latest outputs: colors: ${{ steps.colors.outputs.colors }} steps: - name: Define Colors id: colors run: | echo 'colors=["red", "green", "blue"]' >> "$GITHUB_OUTPUT" produce-artifacts: runs-on: ubuntu-latest needs: define-matrix strategy: matrix: color: ${{ fromJSON(needs.define-matrix.outputs.colors) }} steps: - name: Define Color env: color: ${{ matrix.color }} run: | echo "$color" > color - name: Produce Artifact uses: actions/upload-artifact@v4 with: name: ${{ matrix.color }} path: color consume-artifacts: runs-on: ubuntu-latest needs: - define-matrix - produce-artifacts strategy: matrix: color: ${{ fromJSON(needs.define-matrix.outputs.colors) }} steps: - name: Retrieve Artifact uses: actions/download-artifact@v4 with: name: ${{ matrix.color }} - name: Report Color run: | cat color
name: shared matrix
on:
push:
workflow_dispatch:
jobs:
define-matrix:
runs-on: ubuntu-latest
outputs:
colors: ${{ steps.colors.outputs.colors }}
steps:
- name: Define Colors
id: colors
run: |
echo 'colors=["red", "green", "blue"]' >> "$GITHUB_OUTPUT"
produce-artifacts:
runs-on: ubuntu-latest
needs: define-matrix
strategy:
matrix:
color: ${{ fromJSON(needs.define-matrix.outputs.colors) }}
steps:
- name: Define Color
env:
color: ${{ matrix.color }}
run: |
echo "$color" > color
- name: Produce Artifact
uses: actions/upload-artifact@v4
with:
name: ${{ matrix.color }}
path: color
consume-artifacts:
runs-on: ubuntu-latest
needs:
- define-matrix
- produce-artifacts
strategy:
matrix:
color: ${{ fromJSON(needs.define-matrix.outputs.colors) }}
steps:
- name: Retrieve Artifact
uses: actions/download-artifact@v4
with:
name: ${{ matrix.color }}
- name: Report Color
run: |
cat color
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 Enterprise Cloud 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 Enterprise Cloud 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]