# Varianten von Aufgaben in einem Workflow ausführen Erstelle eine Matrix, um Variationen für jeden Auftrag zu definieren. ## 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..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]`: ```yaml jobs: example_matrix: strategy: matrix: version: [10, 12, 14] os: [ubuntu-latest, windows-latest] ``` Für jede mögliche Kombination der Variablen wird ein Job 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](/de/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrix). ## Erstellen von Matrizen mithilfe von Kontexten Zum Erstellen von Matrizen mit Informationen zu Workflowausführungen, Variablen, Läuferumgebungen, Aufträgen und Schritten greifen Sie mithilfe der `${{ }}` Ausdruckssyntax auf Kontexte zu. Weitere Informationen zu Kontexten findest du unter [Kontextreferenz](/de/actions/reference/workflows-and-actions/contexts). 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](/de/actions/reference/workflows-and-actions/events-that-trigger-workflows#repository_dispatch). ```json { "event_type": "test", "client_payload": { "versions": [12, 14, 16] } } ``` ```yaml 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@v7 with: node-version: ${{ matrix.version }} ``` ## Erweitern oder Hinzufügen von Matrixkonfigurationen Verwende `jobs..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: ```yaml 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](/de/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrixinclude). ## Matrixkonfigurationen ausschließen Um bestimmte Konfigurationen zu entfernen, die in der Matrix definiert sind, verwende `jobs..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. ```yaml 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](/de/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrixexclude). ## 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 copy 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@v5 with: name: ${{ matrix.color }} - name: Report Color run: | cat color ``` ## Behandeln von Fehlern Verwende `jobs..strategy.fail-fast` und `jobs..continue-on-error`, um zu steuern, wie Auftragsfehler behandelt werden. Du kannst `jobs..strategy.fail-fast` und `jobs..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. ```yaml 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..strategy.fail-fast`](/de/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategyfail-fast) und [`jobs..continue-on-error`](/de/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idcontinue-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..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. ```yaml 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](/de/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymax-parallel).