Zum Inhalt springen

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:

  1. Mehr Kerne. Oft die günstigste Lösung. --concurrency lässt sich auf größeren Runnern erhöhen.
  2. 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.
  3. Matrix nach Package-Gruppe. Verwenden Sie --filter pro 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

  1. Shallow Clone. Ein fehlender Merge-Base-Commit führt dazu, dass Turborepo viele Packages als geändert behandelt.
  2. 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.
  3. Nicht deklarierte Umgebungsvariablen. Liest ein Task eine Umgebungsvariable, die nicht in env oder globalEnv steht, können Cache-Einträge fälschlich geteilt oder fälschlich verfehlt werden.
  4. Unterschiedliche TURBO_TEAM zwischen Jobs. Die Jobs verwenden dann unterschiedliche Caches.
  5. 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.

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

Kostenlos testen