Zum Inhalt springen

Was ist ein Matrix-Build in GitHub Actions?

Zuletzt aktualisiert am

Ein Matrix-Build ist eine GitHub-Actions-Strategie, die eine Job-Definition in viele parallele Jobs erweitert, und zwar für jede Kombination der Variablen, die Sie angeben, etwa Betriebssystem und Sprachversion.

So funktioniert es

Sie fügen strategy.matrix einem Job hinzu und listen Werte für einen oder mehrere Schlüssel auf. GitHub erstellt pro Kombination einen Job, jeweils auf einem eigenen Runner. Innerhalb des Jobs lesen Sie die aktuellen Werte mit ${{ matrix.<key> }} aus.

Zwei Listen mit je drei Werten ergeben neun Jobs. Die Anzahl wächst schnell, und jeder Job verbraucht CI-Minuten, weshalb eine breite Matrix teuer werden kann.

Beispiel

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [20, 22]
        include:
          - os: ubuntu-latest
            node: 24
        exclude:
          - os: windows-latest
            node: 20
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci && npm test

Nützliche Optionen

  • include fügt zusätzliche Kombinationen oder zusätzliche Variablen zu bestehenden Kombinationen hinzu.
  • exclude entfernt Kombinationen, die Sie nicht möchten.
  • fail-fast (Standard true) bricht die verbleibenden Jobs ab, sobald einer fehlschlägt. Setzen Sie den Wert auf false, wenn Sie das vollständige Bild benötigen.
  • max-parallel begrenzt, wie viele Matrix-Jobs gleichzeitig laufen.

Mit dem Matrix-Expander-Tool können Sie die Expansion vorab einsehen. Die vollständige Anleitung finden Sie unter GitHub Actions Matrix-Builds.

Häufige Fehler

  • Matrix, wo sie nicht nötig ist. Drei Node-Versionen für eine App zu testen, die nur auf einer ausgeliefert wird, verschwendet Minuten.
  • fail-fast beim Debuggen aktiviert lassen. Ein instabiler Zweig bricht die anderen ab und verdeckt echte Fehler.
  • Matrix für mehr Geschwindigkeit. Eine Matrix aus identischen Jobs verteilt keine Arbeit. Um eine Test-Suite auf mehrere Maschinen aufzuteilen, verwenden Sie Test-Sharding.
  • Zu viele erforderliche Checks. Jeder Matrix-Zweig ist ein eigener Check-Name, was den Branch-Schutz erschwert.
  • Überschreitung der Limits. Eine einzelne Matrix ist auf 256 Jobs pro Workflow-Lauf begrenzt.

FAQ

Worin unterscheiden sich Matrix und Test-Sharding?

Eine Matrix führt den gesamten Job mit unterschiedlichen Konfigurationen aus. Sharding teilt die Tests einer Konfiguration in Abschnitte auf. Beides lässt sich kombinieren, indem Sie einen Shard-Index als Matrix-Variable verwenden.

Führt eine Matrix Jobs parallel aus?

Ja, soweit es die Runner-Kapazität und die Concurrency-Limits zulassen. Mit max-parallel drosseln Sie die Parallelität.

Lässt sich die Matrix dynamisch erzeugen?

Ja. Ein Job kann JSON ausgeben, und ein späterer Job liest es mit fromJSON in strategy.matrix ein.