Schnellste CI für Turborepo-Monorepos mit GitHub Actions
Zuletzt aktualisiert am
Schnelle Turborepo-CI entsteht aus zwei Dingen: dem Ausführen nur geänderter Packages und dem Wiederverwenden gecachter Task-Ausgaben aus einem Remote Cache. Turborepo bietet dafür --filter und einen Remote Cache. Dieser Leitfaden zeigt, wie Sie beides in GitHub Actions einrichten und welche Git-Einstellungen darüber entscheiden, ob es funktioniert. Den Vergleich mit Nx finden Sie in der Übersicht zu Nx und Turborepo.
Schritt 1: Nur geänderte Packages ausführen
turbo run build test lint --filter="...[origin/main]"
Der Teil [origin/main] wählt Packages mit Änderungen seit origin/main aus. Das führende ... nimmt außerdem alles hinzu, was von ihnen abhängt. Das ist in der CI sinnvoll: Eine Änderung in einer gemeinsam genutzten Bibliothek muss auch deren Verbraucher testen. Ohne ... erhalten Sie nur Packages, deren eigene Dateien sich geändert haben.
pnpm verwendet dieselbe Selektor-Syntax; siehe pnpm-Workspaces. Neuere Turborepo-Versionen haben außerdem ein Flag --affected, das die Basis selbst wählt. Prüfen Sie die Turborepo-Dokumentation für Ihre installierte Version.
Fetch-Tiefe
Ein Filter gegen origin/main benötigt diese Referenz und genug Historie, um den Merge-Base-Commit zu finden. actions/checkout holt standardmäßig nur einen Commit, daher verwenden Sie eine der folgenden Optionen:
- uses: actions/checkout@v6
with:
fetch-depth: 0 # full history: safest
Der Turborepo-Leitfaden für GitHub Actions (Stand Oktober 2026) verwendet in seinen Beispielen fetch-depth: 2. Das reicht für einen Vergleich mit dem vorherigen Commit auf main, nicht aber für einen langlebigen PR-Branch im Vergleich mit origin/main. Bei PRs ist die sichere Wahl die vollständige Historie oder filter: tree:0 zusammen mit fetch-depth: 0. Bei Pushes auf main ist der Vergleich mit dem vorherigen Commit üblich:
- run: turbo run build test --filter="...[HEAD^1]"
Bei Pull Requests können Sie dynamisch mit dem Basis-Branch vergleichen:
- run: turbo run build test --filter="...[origin/${{ github.base_ref }}]"
if: github.event_name == 'pull_request'
Schritt 2: Remote Cache
Der lokale Cache von Turborepo liegt in node_modules/.cache/turbo und verschwindet mit jedem frischen Runner. Ein Remote Cache speichert Ausgaben anhand ihres Hashes, sodass ein anderer Runner, Branch oder Teammitglied das Ergebnis erhält, ohne den Task auszuführen.
Die Turborepo-Dokumentation beschreibt zwei Authentifizierungswege in GitHub Actions. Mit einem Token setzen Sie TURBO_TOKEN als Secret und TURBO_TEAM als Variable:
jobs:
build:
runs-on: ubuntu-latest
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ vars.TURBO_TEAM }}
Ihr Leitfaden beschreibt außerdem eine OIDC-Einrichtung mit vercel/setup-turborepo-remote-cache-action. Sie benötigt die Berechtigung id-token: write und tauscht ein kurzlebiges GitHub-Token gegen ein Cache-Token. Der Schritt muss vor jedem Schritt laufen, der turbo aufruft. Verwenden Sie nach Möglichkeit OIDC, denn dann gibt es kein langlebiges Secret, das abfließen könnte.
Ein Cache-Treffer erscheint in der Ausgabe als cache hit, replaying logs mit einem Hash, und die Zusammenfassung meldet Cached: N cached, M total. Ein vollständig gecachter Lauf zeigt FULL TURBO.
Wenn Sie keinen gehosteten Cache möchten, können Sie einen selbst gehosteten Cache-Server betreiben, der die Remote-Cache-API von Turborepo implementiert, oder stattdessen actions/cache auf .turbo verwenden:
- uses: actions/cache@v6
with:
path: .turbo
key: turbo-${{ runner.os }}-${{ github.sha }}
restore-keys: |
turbo-${{ runner.os }}-
Dies ist das rollierende Cache-Muster aus Caching in GitHub Actions. Es funktioniert, wenn Sie das Cache-Verzeichnis von Turborepo auf .turbo setzen. Es ist durch die Obergrenze von 10 GB und den Branch-Geltungsbereich begrenzt; siehe Cache-Limits.
Schritt 3: Sharding und Parallelisierung
Turborepo führt Tasks auf einer Maschine parallel aus, begrenzt durch --concurrency (Standard: 10). Auf mehrere Maschinen verteilt Turborepo die Tasks nicht selbst. Ihre Optionen:
- Mehr Kerne. Oft die günstigste Lösung.
--concurrencylässt sich auf größeren Runnern erhöhen. - Matrix nach Task. Führen Sie Lint, Tests und Build als getrennte Jobs aus, die jeweils den Remote Cache nutzen, sodass bereits von einem Job erledigte Arbeit in einem anderen Job wiederverwendet wird.
- Matrix nach Package-Gruppe. Verwenden Sie
--filterpro App. Kombinieren Sie dies mit Test-Sharding bei großen Test-Suiten.
strategy:
fail-fast: false
matrix:
task: [lint, test, build]
steps:
- run: turbo run ${{ matrix.task }} --filter="...[origin/main]"
Jeder Matrix-Job verursacht Kosten für Checkout und Installation, daher sollten Sie Abhängigkeiten gut cachen; siehe pnpm-Caching und npm-Caching.
Ein vollständiger Workflow
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
ci:
runs-on: [self-hosted, Linux, compiler-ci] # or ubuntu-latest
timeout-minutes: 20
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ vars.TURBO_TEAM }}
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
- uses: pnpm/action-setup@v6
- uses: actions/setup-node@v7
with:
node-version: 22
cache: pnpm
- run: pnpm install --frozen-lockfile
- name: Run changed packages
run: pnpm turbo run lint test build --filter="...[origin/${{ github.base_ref || 'main' }}]"
Bei einem Push ist github.base_ref leer, daher fällt der Ausdruck auf main zurück. Auf main selbst vergleicht dies main mit main und wählt nichts aus. Verwenden Sie bei Pushes deshalb --filter="...[HEAD^1]" oder führen Sie einfach alles aus und lassen den Cache wiedergeben.
Auf compiler.dev genügt eine Zeile runs-on, und Sie erhalten eine Maschine mit 8 vCPU für $0.008 pro Minute, mit bereits bereitstehenden Dependency-Caches. Zum Zurücksetzen ändern Sie die Zeile einfach wieder. In unserem gemessenen Lauf eines Projekts mit Turborepo, Next.js, tRPC und MySQL sank die CI-Laufzeit von 3m29s auf GitHub-gehosteten Runnern auf 1m53s (siehe Benchmarks).
Fehler, die das Filtern unwirksam machen
- Shallow Clone. Ein fehlender Merge-Base-Commit führt dazu, dass Turborepo viele Packages als geändert behandelt.
- Zu breite Cache-Schlüssel-Eingaben. Dateien außerhalb des Packages, die in einen Task einfließen (globale Abhängigkeiten in
turbo.json), machen bei Änderungen alles ungültig. - Nicht deklarierte Umgebungsvariablen. Liest ein Task eine Umgebungsvariable, die nicht in
envoderglobalEnvsteht, können Cache-Einträge fälschlich geteilt oder fälschlich verfehlt werden. - Unterschiedliche
TURBO_TEAMzwischen Jobs. Die Jobs verwenden dann unterschiedliche Caches. - Nicht vertrauenswürdige PRs schreiben in den Cache. Beschränken Sie Schreibzugriffe auf vertrauenswürdige Branches.
FAQ
Was bedeutet ...[origin/main] in turbo --filter?
Packages, die sich seit origin/main geändert haben, plus deren Abhängige, wegen des führenden ....
Brauche ich Vercel für den Remote Cache?
Die dokumentierte gehostete Option ist die von Vercel. Sie können auch einen kompatiblen, selbst gehosteten Cache-Server betreiben.
Warum baut die CI auf main alles neu?
Bei Pushes gibt es keine PR-Basis. Vergleichen Sie mit dem vorherigen oder dem letzten erfolgreichen Commit oder verlassen Sie sich darauf, dass der Remote Cache die Ergebnisse wiedergibt.
Verteilt Turborepo Tasks auf mehrere Maschinen?
Nicht von sich aus. Verwenden Sie eine Matrix oder größere Runner, wie oben beschrieben.
Verwandt
- 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.
- 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.
- Monorepo-CI mit Nx oder Turborepo: Affected BuildsNur geänderte Teile eines Monorepos auf GitHub Actions bauen. Nx affected, Turborepo-Filter, Remote-Caching, Pfadfilter und die wichtigen Checkout-Einstellungen.