GitHub Actions Matrix-Builds richtig umgesetzt
Zuletzt aktualisiert am
Ein Build-Matrix führt denselben Job über Kombinationen aus Betriebssystem, Sprachversion oder anderen Variablen aus. Das ist die übliche Methode, eine Bibliothek auf mehreren Laufzeitumgebungen zu testen, und zugleich ein einfacher Weg, die Kosten unbemerkt zu verdreifachen. Dieser Leitfaden behandelt die Syntax, die wichtigen Optionen und die Kostenkontrolle.
Die Grundlagen
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest]
node: [20, 22]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
cache: npm
- run: npm ci
- run: npm test
Das erzeugt 2 x 2 = 4 Jobs. GitHub begrenzt eine Matrix auf 256 Jobs pro Workflow-Lauf. Fügen Sie Ihre Konfiguration in den Matrix-Expander ein, um vor dem Push jede Kombination und deren Kosten zu sehen.
include und exclude
exclude entfernt Kombinationen; include fügt Kombinationen hinzu oder erweitert sie.
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
node: [20, 22]
exclude:
- os: macos-latest
node: 20
include:
- os: ubuntu-latest
node: 24
experimental: true
Zwei Regeln führen häufig zu Fehlern. Erstens werden include-Einträge nach exclude verarbeitet. Zweitens fügt ein include-Eintrag, dessen Schlüssel zu einer bestehenden Kombination passen, dieser zusätzliche Werte hinzu (ohne ursprüngliche Werte zu überschreiben); passt er zu keiner, wird ein neuer Job erstellt. Fügen Sie einen eigenen Schlüssel hinzu (wie experimental oben) und lesen Sie ihn mit ${{ matrix.experimental }} aus.
fail-fast und max-parallel
Standardmäßig ist fail-fast auf true gesetzt: Schlägt ein Job fehl, bricht GitHub die noch laufenden anderen ab. Das spart Minuten, verbirgt aber Informationen, da Sie nur von einer fehlgeschlagenen Kombination erfahren. Verwenden Sie:
fail-fast: falsefür Bibliotheken und Kompatibilitätsmatrizen, bei denen Sie das vollständige Bild benötigen.fail-fast: true(der Standard) für Matrizen mit Shards einer Test-Suite, bei denen ein Fehler ohnehin den gesamten Lauf entwertet.
strategy:
fail-fast: false
max-parallel: 4
max-parallel begrenzt die gleichzeitig laufenden Jobs einer Matrix. Das ist nützlich, wenn Jobs eine gemeinsame Ressource nutzen, etwa eine Test-Datenbank oder ein API-Rate-Limit, oder wenn Parallelität für andere Workflows frei bleiben soll. Standardmäßig laufen so viele Jobs wie der Tarif erlaubt.
Markieren Sie eine Kombination als fehlschlagen dürfen mit continue-on-error: ${{ matrix.experimental == true }} auf Job-Ebene.
Die Kosten im Griff behalten
Die Größe der Matrix multipliziert die abgerechneten Minuten, und das gewählte Betriebssystem multipliziert den Preis. Laut der Runner-Preisgestaltung von GitHub kostet eine Windows-Minute $0.010 und eine macOS-Minute $0.062, gegenüber $0.006 für Linux. Bei den inkludierten Minuten zählt Windows doppelt und macOS zehnfach. Vergleichen Sie diese beiden Matrizen mit jeweils 10 Minuten pro Job:
| Matrix | Jobs | Kosten pro Lauf |
|---|---|---|
| 3 Betriebssysteme x 4 Node-Versionen, alle Kombinationen | 12 | 4 x (10 x 0.006 + 10 x 0.010 + 10 x 0.062) = $3.12 |
| Linux x 4 Versionen, dazu Windows und macOS nur auf latest | 6 | 4 x 0.06 + 0.10 + 0.62 = $0.96 |
Testen Sie Ihre eigenen Werte mit dem Actions-Kostenrechner. So verkleinern Sie eine Matrix, ohne echte Abdeckung zu verlieren:
- Testen Sie die Ränder, nicht jede Zelle. Die älteste und die neueste unterstützte Version fangen die meisten Kompatibilitätsfehler ab. Testen Sie die volle Kombination nach einem Zeitplan statt bei jedem Push.
- Aufwendige Betriebssysteme nur einmal. Führen Sie Windows und macOS nur mit einer Sprachversion aus.
- Zwei Stufen. Eine kleine Matrix für PRs; die volle Matrix auf
mainund nachts. - Überspringen Sie Läufe anhand geänderter Pfade, damit eine Dokumentationsänderung nichts ausführt.
- Brechen Sie überholte Läufe ab mit
concurrency. Das wird mit wachsender Matrix wichtiger.
Dynamische Matrizen
Erzeugen Sie die Matrix in einem ersten Job, wenn sie vom Zustand des Repositorys abhängt, etwa nur die geänderten Pakete in einem Monorepo:
jobs:
plan:
runs-on: ubuntu-latest
outputs:
matrix: ${{ steps.set.outputs.matrix }}
steps:
- uses: actions/checkout@v4
- id: set
run: echo "matrix=$(node scripts/affected.mjs)" >> "$GITHUB_OUTPUT"
build:
needs: plan
if: ${{ needs.plan.outputs.matrix != '[]' }}
runs-on: ubuntu-latest
strategy:
matrix:
package: ${{ fromJSON(needs.plan.outputs.matrix) }}
steps:
- run: npm run build -w ${{ matrix.package }}
Ist die erzeugte Matrix leer, schlägt der Job mit einem Fehler fehl; deshalb ist die if-Bedingung vorhanden. Siehe auch Monorepo-CI mit Nx oder Turborepo.
Erforderliche Prüfungen und Matrizen
Branch-Schutzregeln gleichen Prüfnamen ab. Matrix-Jobs erhalten Namen wie test (ubuntu-latest, 20), und jede Änderung an der Matrix ändert diese Namen, wodurch erforderliche Prüfungen auf „Expected“ hängen bleiben. Benennen Sie die Matrix-Jobs explizit, wenn Sie sie verlangen müssen, oder fügen Sie besser einen zusammenfassenden Job hinzu, der von der gesamten Matrix abhängt, und verlangen Sie nur diesen:
all-tests:
if: always()
needs: test
runs-on: ubuntu-latest
steps:
- run: test "${{ needs.test.result }}" = "success"
Verwenden Sie if: always(), damit der zusammenfassende Job läuft und fehlschlägt, wenn die Matrix fehlschlägt. Andernfalls wird er übersprungen, und ein übersprungener Job kann eine erforderliche Prüfung erfüllen. Mehr dazu in GitHub-Merge-Queues.
Matrixwerte sicher verwenden
Auch Matrixwerte sind Ausdrücke. Stammen einige aus nicht vertrauenswürdiger Eingabe, etwa einem PR-Label, leiten Sie diese über env weiter statt direkt in Skripte. Siehe GitHub Actions absichern. Setzen Sie Versionen in YAML außerdem in Anführungszeichen: python: [3.9, 3.10] liest 3.10 als die Zahl 3.1. Schreiben Sie ["3.9", "3.10"].
Cache-Schlüssel pro Zelle
Nehmen Sie Matrixwerte in Cache-Schlüssel auf, damit sich Zellen nicht gegenseitig überschreiben:
key: npm-${{ matrix.os }}-node${{ matrix.node }}-${{ hashFiles('package-lock.json') }}
Viele Zellen, die große Caches schreiben, können das Limit von 10 GB pro Repository füllen. Siehe den Leitfaden zum Caching.
FAQ
Wie groß darf eine Matrix maximal sein?
256 Jobs pro Workflow-Lauf, laut den Nutzungslimits von GitHub.
Kann eine Matrix Jobs auf unterschiedlichen Runnern enthalten?
Ja, setzen Sie runs-on: ${{ matrix.os }} oder fügen Sie jedem Eintrag einen runner-Schlüssel hinzu. Labels für größere Runner funktionieren ebenfalls.
Wie benenne ich Matrix-Jobs?
Setzen Sie name: test (${{ matrix.os }}, node ${{ matrix.node }}) auf Job-Ebene, damit die Check-Namen lesbar bleiben.
Warum erzeugt mein include-Eintrag einen neuen Job?
Weil er bei allen ursprünglichen Schlüsseln nicht mit einer bestehenden Kombination übereinstimmt. Prüfen Sie auf Tippfehler und Typunterschiede wie 20 gegenüber "20".
Testen Sie es an Ihrer Matrix
Wenn eine Matrix lange läuft, ist die Geschwindigkeit jeder einzelnen Zelle genauso wichtig wie ihre Anzahl. Der Vergleichsmodus von compiler.dev führt eine Zelle auf schnelleren Maschinen aus, sodass Sie Laufzeit und Kosten pro Zelle sehen, bevor Sie etwas ändern.
Verwandt
- Xcode-Builds in der CI beschleunigenSchnellere xcodebuild-Läufe auf GitHub Actions: SPM- und CocoaPods-Caching, build-for-testing, Simulator-Setup und was nicht in DerivedData-Caches gehört.
- Was ist ein Matrix-Build in GitHub Actions?Ein Matrix-Build führt einen Job mehrfach mit unterschiedlichen Eingaben aus, etwa OS oder Sprachversion. Syntax, include/exclude und typische Fehler.
- TypeScript-Monorepo in GitHub Actions beschleunigenTypprüfung und Linting in TypeScript-Monorepos auf GitHub Actions beschleunigen: inkrementelles tsc, Projektreferenzen, Lint-Caches und parallele Jobs.
- Playwright im Monorepo mit GitHub Actions beschleunigenPlaywright-E2E-Tests in einem Node-Monorepo auf GitHub Actions beschleunigen: App einmal bauen, E2E überspringen, wenn sich die Web-App nicht ändert.