Verwenden von Matrizen für deine Aufträge

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 objecten 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ü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.

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

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]