Monorepo-CI mit Nx oder Turborepo: Affected Builds
Zuletzt aktualisiert am
In einem Monorepo sollte eine einzeilige Änderung nicht alles neu bauen und erneut testen. Zwei Ideen machen das möglich: Tasks nur für die von der Änderung betroffenen Projekte ausführen und Ergebnisse früherer Runs über einen Cache wiederverwenden. Nx und Turborepo bieten beides. Dieser Guide zeigt das GitHub Actions Setup für beide sowie die Fehler, die betroffene Builds unbemerkt wieder zu vollständigen Builds machen.
Die drei Ebenen von "nur das, was sich geändert hat"
- Workflow-Trigger.
paths-Filter entscheiden, ob ein Workflow überhaupt startet. - Erkennung betroffener Projekte. Das Tool vergleicht die Änderung mit einem Basis-Commit und dem Projektgraphen und wählt die Projekte aus, die von geänderten Dateien abhängen.
- Task-Caching. Für ausgewählte Tasks hasht das Tool die Eingaben und spielt Ergebnisse erneut ab, wenn es sie bereits gesehen hat. Ein Remote-Cache teilt diese Ergebnisse zwischen CI-Läufen und Entwicklerinnen und Entwicklern.
Nutzen Sie alle drei. Jede deckt einen anderen Fall ab.
Den Basis-Commit richtig setzen
Die Erkennung betroffener Projekte braucht die Historie. Das Standard-actions/checkout holt nur einen einzelnen Commit, dem Tool fehlt also der Vergleichspunkt. Holen Sie entweder die vollständige Historie oder genug davon:
- uses: actions/checkout@v4
with:
fetch-depth: 0
Die vollständige Historie ist einfach und für die meisten Repositories geeignet. Bei sehr großen Repositories funktioniert ein tieferer Shallow-Fetch (zum Beispiel fetch-depth: 50), solange der Merge-Base darin liegt.
Bei Pull Requests vergleichen Sie mit dem Zielbranch (origin/main). Bei Pushes auf main vergleichen Sie mit dem letzten erfolgreichen Commit und nicht mit dem vorherigen Commit, damit ein fehlgeschlagener Lauf keine Änderungen verdeckt. Nx stellt dafür eine Action bereit:
- uses: nrwl/nx-set-shas@v4
Sie setzt NX_BASE und NX_HEAD auf den letzten erfolgreichen Lauf auf dem Hauptbranch bzw. den aktuellen Commit.
Nx-Einrichtung
name: ci
on:
pull_request:
push:
branches: [main]
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: nrwl/nx-set-shas@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx nx affected -t lint test build
nx affected -t lint test build führt diese Targets nur für betroffene Projekte aus, in Abhängigkeitsreihenfolge und mit lokalem Caching. Es liest NX_BASE und NX_HEAD. Fügen Sie --parallel=3 hinzu, um die Parallelität auf einem kleinen Runner zu steuern. Um Ergebnisse über Läufe hinweg wiederzuverwenden, verbinden Sie Nx Cloud oder einen anderen Remote-Cache; ohne einen solchen beginnt jeder CI-Lauf mit einem leeren lokalen Cache.
Turborepo-Einrichtung
Die Filtersyntax von Turborepo wählt anhand von Git-Änderungen aus:
- run: npx turbo run lint test build --filter="...[origin/main]"
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ vars.TURBO_TEAM }}
...[origin/main] bedeutet "Pakete, die seit origin/main geändert wurden, plus alles, was von ihnen abhängt". Sind TURBO_TOKEN und TURBO_TEAM gesetzt, nutzt Turborepo einen Remote-Cache (den von Vercel oder einen selbst gehosteten Server, der dessen API implementiert). Ohne Remote-Cache können Sie das lokale .turbo-Verzeichnis mit actions/cache und einem rollierenden Schlüssel speichern. Siehe den Caching-Leitfaden.
Definieren Sie Task-Eingaben und -Ausgaben in turbo.json präzise. Ist inputs zu breit (etwa wenn eine Datei enthalten ist, die sich bei jedem Commit ändert), verfehlen Tasks immer den Cache; fehlt in outputs ein Ordner, sind die wiedergegebenen Ergebnisse unvollständig.
Remote-Caching: was Sie gewinnen
Ein Cache-Treffer überspringt die Arbeit vollständig und spielt Logs und Dateien ab. In einem typischen PR, der ein Paket ändert, werden die davon abhängigen Pakete neu gebaut, alles andere ist ein Treffer. Die Wirkung ist am größten, wenn:
- mehrere PRs dieselben Codepfade berühren, sodass Ergebnisse geteilt werden.
- Entwickler und CI einen Cache teilen, sodass die CI wiedergibt, was ein Laptop gebaut hat.
- Tasks deterministisch sind. Tasks, die die Uhr, das Netzwerk oder Zufalls-Seeds lesen, lassen sich nicht sicher cachen.
Behandeln Sie Zugangsdaten des Remote-Caches als Geheimnisse und beschränken Sie Schreibzugriffe auf vertrauenswürdige Branches. Ein manipulierter Cache ist ein Risiko für die Lieferkette, daher sollten Pull Requests aus Forks nicht in ihn schreiben dürfen. Siehe Sicherung von GitHub Actions.
Trigger-Filter obendrauf
Günstiges Filtern auf Workflow-Ebene hilft, wenn Teile des Repositorys unabhängig sind, etwa eine Dokumentationsseite oder Infrastrukturcode:
on:
pull_request:
paths:
- "apps/**"
- "packages/**"
- "package-lock.json"
- ".github/workflows/ci.yml"
Nehmen Sie die Workflow-Datei selbst und Lockfiles mit auf. Ist der Workflow eine erforderliche Prüfung, bleibt eine übersprungene Ausführung dauerhaft auf "Erwartet" stehen; lösen Sie das mit einem immer laufenden Zusammenfassungs-Job oder mit einer Pfaderkennung innerhalb des Workflows.
Fallstricke
- Shallow Clone macht die Menge der betroffenen Projekte je nach Tool leer oder vollständig.
- Globale Dateien wie das Root-
package.json, das Lockfile oder die tsconfig ändern den Hash jedes Projekts. Das ist korrekt, aber achten Sie darauf, dass keine unabhängigen Dateien als globale Eingaben gelistet sind. - Implizite Abhängigkeiten, etwa ein Dienst, der eine Schema-Datei aus einem anderen Paket liest, ohne die Abhängigkeit zu deklarieren. Die Erkennung betroffener Projekte übersieht diese. Deklarieren Sie sie in der Projektkonfiguration.
- Deployments sollten sich nicht allein auf Builds betroffener Projekte verlassen, ohne ein Sicherheitsnetz mit vollständigem Build auf
mainoder nachts. - Cache-Größe: Ein Remote-Cache wächst ohne Grenze, sofern Sie keine Aufbewahrungsdauer festlegen.
Den Nutzen messen
Erfassen Sie die mediane CI-Dauer und das 90.-Perzentil für PRs vorher und nachher. Verfolgen Sie außerdem den Anteil der aus dem Cache bedienten Tasks. Bleibt er nach einer Woche unter etwa der Hälfte, prüfen Sie Eingaben und Basis-Commit-Einstellungen. Nutzen Sie den CI-Minuten-Prognoserechner, um eingesparte Minuten in einen Monatswert umzurechnen, und den Planer für Test-Sharding, falls betroffene Projekte weiterhin lange Testsuiten ausführen.
FAQ
Nx oder Turborepo?
Beide können betroffene Läufe und Caching. Nx bietet einen umfangreicheren Projektgraphen, Generatoren und verteilte Task-Ausführung; Turborepo ist schlanker und lässt sich einfacher zu einem bestehenden npm-Workspace hinzufügen. Wählen Sie nach dem, was Sie über Caching hinaus brauchen.
Brauche ich noch Pfadfilter?
Ja, für günstige Fälle: Sie verhindern, dass überhaupt ein Runner startet. Die feineren Entscheidungen übernehmen dann die Tools.
Funktioniert das auch für Repositories ohne JavaScript?
Nx hat Plugins für mehrere Sprachen, und Werkzeuge wie Bazel, Pants und Gradle bringen eigene Logik für Caching und betroffene Projekte mit. Die Grundprinzipien (Basis-Commit, Graph, Cache) sind dieselben.
Warum sind bei jedem PR alle Projekte betroffen?
Meist liegt es an einer geänderten globalen Datei, einem Shallow-Checkout oder einem falschen Base-SHA. Lassen Sie sich die betroffene Liste mit nx show projects --affected ausgeben, um den Fehler einzugrenzen.
Wo compiler.dev passt
Affected-Builds reduzieren die Anzahl der Jobs, die laufen; schnellere Runner verkürzen die Dauer jedes einzelnen. Der Vergleichsmodus von compiler.dev führt Ihren bestehenden Workflow auf schnelleren Maschinen aus, sodass Sie den zweiten Effekt in Ihrem eigenen Repository messen können.
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 Nx-Monorepos mit GitHub ActionsMachen Sie Nx-CI auf GitHub Actions schnell. nx affected mit nx-set-shas, Nx-Remote-Cache, Task-Verteilung, fetch-depth und ein vollständiger Workflow.