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
- Flacher Checkout. Der häufigste Fehler. Verwenden Sie
fetch-depth: 0. - Eine Root-Datei wird geändert. Änderungen an
package-lock.json,nx.jsonoder einer gemeinsamen tsconfig machen alles betroffen. DienamedInputsvon Nx erlauben es, enger zu festzulegen, wovon jedes Target abhängt. - Die Basis ist ein roter Commit.
HEAD~1nach einem fehlgeschlagenen Lauf verdeckt Fehler. nx-set-shas wählt den letzten grünen Commit. - Skripte außerhalb von Nx. Tasks außerhalb von
nxumgehen Cache und die Logik für betroffene Projekte. - 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.
Verwandt
- 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.
- Schnellste CI für Bazel-Monorepos mit GitHub ActionsSchnelle Bazel-CI auf GitHub Actions: Zieltyp-Ermittlung für betroffene Builds, Remote-Cache-Flags, schreibgeschützte PR-Uploads und Sharding.
- Schnellste CI für pnpm-Workspaces mit GitHub ActionsSchnelle CI für pnpm-Workspaces auf GitHub Actions. Filter für geänderte Pakete, Store-Caching, fetch-depth, Matrix-Sharding und ein kopierbarer Workflow.