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ügtcolor:pink
nur den ursprünglichen Matrixkombinationen hinzu, dieanimal: cat
enthalten. Dadurch wird diecolor: green
überschrieben, die zuvor durch den vorherigeninclude
-Eintrag hinzugefügt wurde.{fruit: apple, shape: circle}
fügtshape: circle
nur den ursprünglichen Matrixkombinationen hinzu, diefruit: 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.
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.