Hinweis: GitHub-gehostete Runner werden auf GitHub Enterprise Server derzeit nicht unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.
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 Enterprise Server 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 Enterprise Server 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 Kontexte.
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
os
angegeben sind - Drei Node.js-Versionen, die in der Variable
version
angegeben 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 object
en sein.
matrix:
os:
- ubuntu-latest
- macos-latest
node:
- version: 14
- version: 16
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: 16
matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider
- matrix.os: macos-latest
matrix.node.version: 14
- matrix.os: macos-latest
matrix.node.version: 16
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 Kontexte.
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: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.
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 }}
Hinweis: 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@v3 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@v3 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@v3
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@v3
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 Enterprise Server 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 Enterprise Server 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]