Exécution de variantes de tâches dans un workflow

Créez une matrice pour définir les variantes de chaque travail.

Dans cet article

À 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.

Ajout d’une stratégie de matrice à votre travail de workflow

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.

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}

Pour obtenir des informations de référence et exemples, consultez Workflow syntax for GitHub Actions.

Utilisation de contextes pour créer des matrices

Pour créer des matrices avec des informations sur les exécutions de flux de travail, les variables, les environnements d’exécuteur, les travaux et les étapes, accédez aux contextes à l’aide de la syntaxe d’expression ${{ <context> }}. Pour plus d’informations sur les contextes, consultez « Référence sur les 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

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

Par exemple, considérez le mappage suivant.

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

Ceci entraînera 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}

Ce entrée include a été appliquée de la manière suivante.

  • {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.

Pour obtenir des informations de référence et des exemples de configurations, consultez Workflow syntax for GitHub Actions.

Exclusion de configurations de matrice

Pour supprimer des configurations spécifiques définies dans la matrice, utilisez jobs.<job_id>.strategy.matrix.exclude.

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 }}

Pour obtenir des informations de référence, consultez Workflow syntax for GitHub Actions

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.

YAML
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

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

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

Pour obtenir des informations de référence, consultez jobs.<job_id>.strategy.fail-fast et jobs.<job_id>.continue-on-error.

Définition du nombre maximal de travaux simultanés

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]

Pour obtenir des informations de référence, consultez Workflow syntax for GitHub Actions.