Zum Inhalt springen

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: false fü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:

MatrixJobsKosten pro Lauf
3 Betriebssysteme x 4 Node-Versionen, alle Kombinationen124 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 latest64 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 main und 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.

Diesen Workflow auf compiler.dev ausführen Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen