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.
Verwenden einer Matrixstrategie
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.
Standardmäßig maximiert GitHub die Anzahl der parallel ausgeführten Aufträge basierend auf der Runnerverfügbarkeit. Die Reihenfolge der Variablen in der Matrix bestimmt die Reihenfolge, in der die Aufträge erstellt werden. Die erste Variable, die du definierst, entspricht dem ersten Auftrag, der in deiner Workflowausführung erstellt wird. Die Matrix oben erstellt die Aufträge beispielsweise 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}
Eine Matrix generiert maximal 256 Aufträge pro Workflowausführung. Dieser Grenzwert gilt sowohl für von GitHub gehostete als auch selbstgehostete Runner.
Die von dir definierten Variablen werden zu Eigenschaften im matrix-Kontext, und du kannst in anderen Bereichen deiner Workflowdatei auf die Eigenschaft verweisen. In diesem Beispiel kannst du matrix.version und matrix.os verwenden, um auf die aktuellen Werte von version und os zuzugreifen, die der Auftrag nutzt. Weitere Informationen findest du unter Zugreifen auf kontextbezogene Informationen zu Workflowausführungen.
Beispiel: Verwenden einer Matrix mit einer einzelnen Dimension
Du kannst eine einzelne Variable angeben, um eine Matrix mit einer einzelnen Dimension zu erstellen.
Der folgende Workflow definiert beispielsweise die Variable version mit den Werten [10, 12, 14]. Dieser Workflow führt drei Aufträge aus, einen für jeden Wert in der Variablen. Jeder Auftrag greift über den matrix.version-Kontext auf den version-Wert zu und übergibt den Wert als node-version an die actions/setup-node-Aktion.
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
steps:
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.version }}
Beispiel: Verwenden einer Matrix mit mehreren Dimensionen
Du kannst mehrere Variablen angeben, um eine mehrdimensionale Matrix zu erstellen. Für jede mögliche Kombination der Variablen wird ein Auftrag ausgeführt.
Der folgende Workflow gibt beispielsweise zwei Variablen an:
- Zwei Betriebssysteme, die in der Variable
osangegeben sind - Drei Node.js-Versionen, die in der Variable
versionangegeben sind
Der Workflow führt sechs Aufträge aus, einen für jede Kombination der Variablen os und version. Jeder Auftrag legt den Wert runs-on auf den aktuellen Wert os fest und übergibt den aktuellen Wert version an die Aktion 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 }}
Eine Variablenkonfiguration in einer Matrix kann ein array von objecten sein.
matrix:
os:
- ubuntu-latest
- macos-latest
node:
- version: 14
- version: 20
env: NODE_OPTIONS=--openssl-legacy-provider
Diese Matrix erzeugt 4 Aufträge mit entsprechenden Kontexten.
- 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
Beispiel: Erstellen von Matrizen mithilfe von Kontexten
Du kannst Kontexte verwenden, um Matrizen zu erstellen. Weitere Informationen zu Kontexten findest du unter Zugreifen auf kontextbezogene Informationen zu Workflowausführungen.
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.
Die Schlüssel-Wert-Paare im Objekt werden für jedes Objekt in der include-Liste zu jeder der Matrixkombinationen hinzugefügt, wenn keines der Schlüssel-Wert-Paare einen der ursprünglichen Matrixwerte überschreibt. Wenn das Objekt zu keiner der Matrixkombinationen hinzugefügt werden kann, wird stattdessen eine neue Matrixkombination erstellt. Beachte, dass die ursprünglichen Matrixwerte nicht überschrieben werden, hinzugefügte Matrixwerte jedoch überschrieben werden können.
Diese Matrix ergibt sechs Aufträge mit den folgenden Matrixkombinationen:
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
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}
Sie befolgen diese Logik:
{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:pinknur den ursprünglichen Matrixkombinationen hinzu, dieanimal: catenthalten. Dadurch wird diecolor: greenüberschrieben, die zuvor durch den vorherigeninclude-Eintrag hinzugefügt wurde.{fruit: apple, shape: circle}fügtshape: circlenur den ursprünglichen Matrixkombinationen hinzu, diefruit: appleenthalten.{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.
Beispiel: Erweitern von Konfigurationen
Beispielsweise führt der folgende Workflow vier Jobs aus, einen für jede Kombination von os und node. Wenn der Auftrag für den os-Wert von windows-latest und den node-Wert von 16 ausgeführt wird, wird eine zusätzliche Variable namens npm mit dem Wert 6 in den Auftrag einbezogen.
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
Beispiel: Hinzufügen von Konfigurationen
Diese Matrix führt beispielsweise zehn Aufträge aus, einen für jede Kombination von os und version in der Matrix sowie einen Auftrag für den Wert os von windows-latest und den Wert version von 17.
jobs:
example_matrix:
strategy:
matrix:
os: [macos-latest, windows-latest, ubuntu-latest]
version: [12, 14, 16]
include:
- os: windows-latest
version: 17
Wenn du keine Matrixvariablen angibst, werden alle Konfigurationen unter include ausgeführt. Der folgende Workflow würde beispielsweise zwei Aufträge ausführen, einen für jeden include-Eintrag. Auf diese Weise kannst du die Matrixstrategie nutzen, ohne eine vollständig ausgefüllte Matrix zu haben.
jobs:
includes_only:
runs-on: ubuntu-latest
strategy:
matrix:
include:
- site: "production"
datacenter: "site-a"
- site: "staging"
datacenter: "site-b"
Ausschließen von Matrixkonfigurationen
Um bestimmte Konfigurationen zu entfernen, die in der Matrix definiert sind, verwende jobs.<job_id>.strategy.matrix.exclude. Eine ausgeschlossene Konfiguration muss nur eine teilweise Übereinstimmung sein, damit sie ausgeschlossen werden kann. 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 }}
Note
Alle include-Kombinationen werden nach exclude verarbeitet. So kannst du mit include wieder Kombinationen hinzufügen, die zuvor ausgeschlossen waren.
Beispiel: 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
Du kannst steuern, wie Auftragsfehler mit jobs.<job_id>.strategy.fail-fast und jobs.<job_id>.continue-on-error verarbeitet werden.
jobs.<job_id>.strategy.fail-fast gilt für die gesamte Matrix. Wenn jobs.<job_id>.strategy.fail-fast auf true festgelegt ist oder sein Ausdruck den Wert true annimmt, bricht GitHub alle in Verarbeitung oder in der Warteschlange befindlichen Aufträge in der Matrix ab, wenn bei einem Auftrag in der Matrix ein Fehler auftritt. Der Standardwert dieser Eigenschaft ist true.
jobs.<job_id>.continue-on-error gilt für einen einzelnen Auftrag. Wenn jobs.<job_id>.continue-on-error auf true festgelegt ist, werden andere Aufträge in der Matrix weiterhin ausgeführt, auch wenn bei dem Auftrag mit jobs.<job_id>.continue-on-error: true ein Fehler auftritt.
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
Definieren der maximalen Anzahl von gleichzeitigen Aufträgen
Standardmäßig maximiert GitHub die Anzahl der parallel ausgeführten Aufträge basierend auf der Runnerverfügbarkeit. 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]