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
includefügt zusätzliche Kombinationen oder zusätzliche Variablen zu bestehenden Kombinationen hinzu.excludeentfernt Kombinationen, die Sie nicht möchten.fail-fast(Standardtrue) bricht die verbleibenden Jobs ab, sobald einer fehlschlägt. Setzen Sie den Wert auffalse, wenn Sie das vollständige Bild benötigen.max-parallelbegrenzt, 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-fastbeim 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.
Verwandte Begriffe
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.
Verwandt
- Docker-Build in der CI langsam? Ursache finden und behebenDocker-Build in CI zu langsam? Build-Kontext, .dockerignore, Layer-Reihenfolge, Cache-Misses und BuildKit prüfen und zuerst das größte Problem beheben.
- GitHub Actions Matrix-Builds richtig umgesetztstrategy.matrix mit include, exclude, fail-fast und max-parallel nutzen, Job-Anzahl und Kosten im Blick behalten und Pflicht-Checks korrekt einrichten.
- Was ist ein Remote-Build-Cache?Ein Remote-Build-Cache speichert Task-Ergebnisse von Tools wie Nx, Turborepo, Gradle und Bazel, damit CI und Team bereits erledigte Arbeit überspringen.
- Was sind CI-Minuten? GitHub Actions Abrechnung erklärtCI-Minuten sind die abgerechnete Rechenzeit Ihrer Pipelines. So zählt GitHub Actions Minuten, Rundung und Multiplikatoren, und so senken Sie den Verbrauch.