Zum Inhalt springen

Schnellste CI für Nx-Monorepos mit GitHub Actions

Zuletzt aktualisiert am

Die schnellste Nx-CI erledigt drei Dinge: Sie führt nur betroffene Projekte aus (nx affected), nutzt Ergebnisse über einen Remote-Cache wieder und verteilt die verbleibende Arbeit auf mehrere Maschinen. Dieser Leitfaden geht tiefer auf Nx ein als der allgemeine Leitfaden zu Nx und Turborepo und behandelt auch die Git-Einstellungen, die betroffene Läufe unbemerkt brechen können.

Schritt 1: Nur betroffene Projekte ausführen

nx affected vergleicht zwei Commits und führt Tasks nur für Projekte aus, die sich geändert haben oder von geänderten Projekten abhängen. Dafür werden eine Basis und ein Head benötigt. Die Action nrwl/nx-set-shas ermittelt beides für Sie.

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
          filter: tree:0
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - uses: nrwl/nx-set-shas@v5
      - run: npx nx affected -t lint test build

Laut README von nx-set-shas (geprüft im Oktober 2026) exportiert die Action NX_BASE und NX_HEAD für den Job und stellt base und head zusätzlich als Step-Outputs bereit. Bei einem Pull Request ist die Basis der Merge-Base mit main. Bei einem Push auf main ist es der letzte Commit, dessen Workflow-Lauf erfolgreich war, sodass ein roter Commit seine Änderungen dem nächsten Lauf nicht vorenthält. Findet die Action keinen solchen Commit, greift sie auf HEAD~1 zurück, sofern Sie nicht error-on-no-successful-workflow: true setzen.

Die Anforderung an fetch-depth

actions/checkout holt standardmäßig nur einen Commit. Ohne weiteren Commit gibt es keine Basis zum Vergleich, und nx affected bricht ab oder behandelt alles als betroffen. Laut README von nx-set-shas benötigt Nx alle Branches und Commits, um eine Vergleichsbasis zu haben, weshalb der Workflow fetch-depth: 0 verwendet.

filter: tree:0 erzeugt einen Partial Clone im Stil eines blobless Clones. Die vollständige Historie bleibt so günstig: Commit-Metadaten werden vorab geladen, Dateiinhalte bei Bedarf. Bei sehr großen Repositories dauert das oft Sekunden statt einer Minute.

Standardbasis anpassen

Nx liest außerdem defaultBase in nx.json (meist main). Halten Sie den Wert synchron mit dem Namen Ihres Hauptbranches, sonst vergleichen betroffene Läufe gegen die falsche Referenz.

Schritt 2: Remote-Cache

Ein lokaler Cache hilft nur, wenn derselbe Runner dieselben Dateien sieht. Auf GitHub Actions startet jeder Job sauber, daher brauchen Sie einen Remote-Cache, um Task-Ergebnisse zwischen Läufen, Branches und Teammitgliedern wiederzuverwenden.

Die Nx-Dokumentation (geprüft im Oktober 2026) verbindet einen Workspace mit npx nx-cloud onboard connect-workspace, das nxCloudId in nx.json schreibt. Für die CI-Authentifizierung beschreibt sie schreibgeschützte und Lese-Schreib-Zugriffstoken in ihrem Leitfaden zu CI-Zugriffstoken. Verwenden Sie ein schreibgeschütztes Token für Pull Requests aus Forks und ein Lese-Schreib-Token für vertrauenswürdige Branches, damit ein nicht vertrauenswürdiger PR den Cache nicht verunreinigen kann.

Bestätigen Sie Cache-Treffer im Log. Ein gecachter Task gibt [local cache] oder [remote cache] aus und spielt die Ausgabe ab, statt den Befehl auszuführen. Eine Zusammenfassung am Ende zeigt, wie viele Tasks aus dem Cache gelesen wurden.

Ohne Nx Cloud können Sie andere Remote-Cache-Implementierungen über den Custom Task Runner und die Cache-Plugins von Nx nutzen oder das Verzeichnis .nx/cache mit actions/cache zwischenspeichern. Die Variante mit dem Actions-Cache ist am günstigsten zum Ausprobieren, hat aber zwei Grenzen: PR-Caches sind eingeschränkt, und das Limit von 10 GB pro Repository gilt. Siehe Cache-Limits.

- uses: actions/cache@v6
  with:
    path: .nx/cache
    key: nx-${{ runner.os }}-${{ github.sha }}
    restore-keys: |
      nx-${{ runner.os }}-

Schritt 3: Tasks verteilen

Nach affected und Caching kann ein großer PR trotzdem langsam sein. Nx kann Tasks auf mehrere Agenten verteilen. Die Einführung in Nx CI (geprüft im Oktober 2026) konfiguriert das in .nx/ci-config.yaml und startet die Agenten im Workflow vor der Installation:

# .nx/ci-config.yaml
dte:
  distribute-on: 3 linux-large-js
lifecycle:
  stop-after:
    - build
steps:
  - uses: actions/checkout@v6
    with:
      fetch-depth: 0
      filter: tree:0
  - run: npx nx-cloud start-workers
  - uses: actions/setup-node@v7
    with:
      node-version: 22
      cache: npm
  - run: npm ci
  - uses: nrwl/nx-set-shas@v5
  - run: npx nx affected -t lint test build

Wenn Sie die Worker zuerst starten, können sie hochfahren, während Ihr Hauptjob die Abhängigkeiten installiert. Nur Tasks, die über nx laufen, werden gecacht und verteilt. Achten Sie daher darauf, dass npm test nx test aufruft und nicht direkt den Test-Runner.

Wenn Sie lieber bei reinem GitHub Actions bleiben, können Sie selbst mit einer Matrix sharden. Nx unterstützt die Aufteilung nach Projekt, und bei einzelnen großen Testsuiten können Sie den Runner selbst sharden. Siehe Test-Sharding in GitHub Actions.

Alles zusammen

name: CI
on:
  push:
    branches: [main]
  pull_request:

permissions:
  actions: read
  contents: read

jobs:
  main:
    runs-on: [self-hosted, Linux, compiler-ci]   # or ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
          filter: tree:0
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - uses: nrwl/nx-set-shas@v5
      - run: npx nx affected -t lint test build --parallel=4

--parallel steuert, wie viele Tasks gleichzeitig auf derselben Maschine laufen. Mit mehr Kernen können Sie diesen Wert erhöhen. Die Zeile runs-on ist der einzige compiler.dev-spezifische Teil: Sie verschiebt den Job auf eine Maschine mit 8 vCPUs zu $0.008 pro Minute, und durch Zurücksetzen machen Sie das wieder rückgängig. Siehe Preise.

Fehler, durch die „betroffen“ zu „alles“ wird

  1. Flacher Checkout. Der häufigste Fehler. Verwenden Sie fetch-depth: 0.
  2. Eine Root-Datei wird geändert. Änderungen an package-lock.json, nx.json oder einer gemeinsamen tsconfig machen alles betroffen. Die namedInputs von Nx erlauben es, enger zu festzulegen, wovon jedes Target abhängt.
  3. Die Basis ist ein roter Commit. HEAD~1 nach einem fehlgeschlagenen Lauf verdeckt Fehler. nx-set-shas wählt den letzten grünen Commit.
  4. Skripte außerhalb von Nx. Tasks außerhalb von nx umgehen Cache und die Logik für betroffene Projekte.
  5. Ein Cache, der nie gespeichert wird. Stellen Sie sicher, dass ein vertrauenswürdiger Branch ihn schreibt.

Für langsame Installationen siehe npm-Caching oder pnpm-Caching. Für andere Monorepo-Tools siehe Turborepo und Bazel.

FAQ

Was vergleicht nx affected eigentlich?

Die Dateien, die sich zwischen NX_BASE und NX_HEAD geändert haben, abgebildet über den Projektgraphen auf Projekte und deren Abhängige.

Brauche ich Nx Cloud?

Für betroffene Läufe nicht. Für die Wiederverwendung über Läufe hinweg brauchen Sie einen Remote-Cache oder verteilte Ausführung. Nx Cloud ist der unterstützte Weg, und actions/cache auf .nx/cache ist eine eingeschränkte Alternative.

Warum führt nx affected auf meinem PR alles aus?

Prüfen Sie die fetch-Tiefe, prüfen Sie, ob NX_BASE auf unerwartete Weise ein Vorfahre von NX_HEAD ist, und ob eine Root-Konfigurationsdatei geändert wurde.

Funktioniert das mit einer Merge Queue?

nx-set-shas hat für Merge Groups eine Eingabe use-previous-merge-group-commit (Standard: true). Siehe GitHub Merge Queue.

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

Kostenlos testen