Ausführen von Variationen von Aufträgen in einem Workflow

Informationen zu Matrixstrategien

Mithilfe einer Matrixstrategie kannst du Variablen in einer Auftragsdefinition verwenden, um automatisch mehrere Auftragsausführungen zu erstellen, die auf Kombinationen dieser Variablen basieren. Mithilfe einer Matrixstrategie kannst du deinen Code beispielsweise in mehreren Versionen einer Sprache oder auf mehreren Betriebssystemen testen.

Hinzufügen einer Matrixstrategie zu deinem Workflowauftrag

Verwende jobs.<job_id>.strategy.matrix, um eine Matrix verschiedener Auftragskonfigurationen zu definieren. Definiere innerhalb der Matrix eine oder mehrere Variablen, gefolgt von einem Array an Werten. Die folgende Matrix verfügt beispielsweise über eine Variable namens version mit dem Wert [10, 12, 14] und über eine Variable namens os mit dem Wert [ubuntu-latest, windows-latest]:

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

Für jede mögliche Kombination der Variablen wird ein Auftrag ausgeführt. In diesem Beispiel führt der Workflow sechs Aufträge aus: einen für jede Kombination der Variablen os und version.

Die Matrix oben erstellt die Aufträge in der folgenden Reihenfolge:

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

Referenzinformationen und Beispiele findest du unter Workflowsyntax für GitHub Actions.

Erstellen von Matrizen mithilfe von Kontexten

Greife zum Erstellen von Matrizen mit Informationen zu Workflowausführungen, Variablen, Runnerumgebungen, Aufträgen und Schritten mithilfe der ${{ <context> }}-Ausdruckssyntax auf Kontexte zu. Weitere Informationen zu Kontexten findest du unter Kontextreferenz.

Beispielsweise wird der folgende Workflow für das repository_dispatch-Ereignis ausgelöst und verwendet Informationen aus der Ereignisnutzlast, um die Matrix zu erstellen. Wenn ein Repositorydispatchereignis mit einer Nutzlast wie der folgenden erstellt wird, hat die Matrixvariable version einen Wert von [12, 14, 16]. Weitere Informationen zum Trigger repository_dispatch findest du unter Ereignisse zum Auslösen von Workflows.

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

Erweitern oder Hinzufügen von Matrixkonfigurationen

Verwende jobs.<job_id>.strategy.matrix.include, um vorhandene Matrixkonfigurationen zu erweitern oder neue Konfigurationen hinzuzufügen. Der Wert von include ist eine Liste von Objekten.

Betrachte etwa die folgende Matrix:

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

Dies führt zu sechs Aufträgen mit den folgenden Matrixkombinationen:

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

Jeder include-Eintrag wurde auf folgende Weise angewendet.

{color: green} wird allen ursprünglichen Matrixkombinationen hinzugefügt, da sie hinzugefügt werden kann, ohne einen Teil der ursprünglichen Kombinationen zu überschreiben.
{color: pink, animal: cat} fügt color:pink nur den ursprünglichen Matrixkombinationen hinzu, die animal: cat enthalten. Dadurch wird die color: green überschrieben, die zuvor durch den vorherigen include-Eintrag hinzugefügt wurde.
{fruit: apple, shape: circle} fügt shape: circle nur den ursprünglichen Matrixkombinationen hinzu, die fruit: apple enthalten.
{fruit: banana} kann zu keiner ursprünglichen Matrixkombination hinzugefügt werden, ohne dass dabei ein Wert überschrieben wird. Daher wird sie als zusätzliche Matrixkombination hinzugefügt.
{fruit: banana, animal: cat} kann zu keiner ursprünglichen Matrixkombination hinzugefügt werden, ohne dass dabei ein Wert überschrieben wird. Daher wird sie als zusätzliche Matrixkombination hinzugefügt. Die {fruit: banana}-Matrixkombination wird nicht hinzugefügt, da die Kombination keine der ursprünglichen Matrixkombinationen war.

Referenz- und Beispielkonfigurationen findest du unter Workflowsyntax für GitHub Actions.

Ausschließen von Matrixkonfigurationen

Um bestimmte Konfigurationen zu entfernen, die in der Matrix definiert sind, verwende jobs.<job_id>.strategy.matrix.exclude.

Der folgende Workflow führt z. B. neun Aufträge aus: ein Auftrag für jede der 12 Konfigurationen, minus der ausgeschlossenen Aufgabe, die mit {os: macos-latest, version: 12, environment: production} übereinstimmt, und die beiden ausgeschlossenen Aufträge, die mit {os: windows-latest, version: 16} übereinstimmen.

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

Referenzinformationen findest du unter Workflowsyntax für GitHub Actions.

Verwenden einer Ausgabe zum Definieren von zwei Matrizen

Sie können die Ausgabe aus einem Auftrag verwenden, um Matrizen für mehrere Aufträge zu definieren.

Der folgende Workflow veranschaulicht beispielsweise, wie Sie eine Matrix von Werten in einem Auftrag definieren, diese Matrix in einem zweiten Auftrag verwenden, um Artefakte zu erzeugen, und diese Artefakte dann in einem dritten Auftrag verwenden. Jedes Artefakt ist einem Wert aus der Matrix zugeordnet.

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

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

Behandeln von Fehlern

Verwende jobs.<job_id>.strategy.fail-fast und jobs.<job_id>.continue-on-error, um zu steuern, wie Auftragsfehler behandelt werden.

Du kannst jobs.<job_id>.strategy.fail-fast und jobs.<job_id>.continue-on-error gemeinsam einsetzen. Der folgende Workflow startet beispielsweise vier Aufträge. Für jeden Auftrag wird continue-on-error durch den Wert von matrix.experimental bestimmt. Wenn bei einem der Aufträge mit continue-on-error: false ein Fehler auftritt, werden alle in Verarbeitung oder in der Warteschlange befindlichen Aufträge abgebrochen. Wenn beim Auftrag mit continue-on-error: true ein Fehler auftritt, sind die anderen Aufträge nicht betroffen.

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

Referenzinformationen findest du unter jobs.<job_id>.strategy.fail-fast und jobs.<job_id>.continue-on-error.

Definieren der maximalen Anzahl von gleichzeitigen Aufträgen

Um die maximale Anzahl von Aufträgen festzulegen, die bei der Auftragsstrategie matrix gleichzeitig ausgeführt werden können, verwende jobs.<job_id>.strategy.max-parallel.

Der folgende Workflow führt zum Beispiel maximal zwei Aufträge auf einmal aus, auch wenn es Runner gibt, die alle sechs Aufträge auf einmal ausführen können.

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

Referenzinformationen findest du unter Workflowsyntax für GitHub Actions.

Ausführen von Variationen von Aufträgen in einem Workflow

In diesem Artikel