Zum Inhalt springen

Schnellste CI für pnpm-Workspaces mit GitHub Actions

Zuletzt aktualisiert · Erstmals veröffentlicht

In einem pnpm-Workspace erreichen Sie den Großteil der Geschwindigkeit eines Build-Systems ganz ohne zusätzliches Tool: Den pnpm-Store cachen, einmal installieren und Skripte nur für geänderte Pakete mit pnpm --filter "...[origin/main]" ausführen. Dieser Leitfaden behandelt die Filter, die dafür nötigen Checkout-Einstellungen und wann Sie Turborepo oder Nx ergänzen sollten.

Einmal installieren, Store cachen

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

Installieren Sie im Root des Repositorys. pnpm installiert alle Workspace-Pakete in einem Durchgang und verknüpft sie. Details zu Store-Pfaden und Keys finden Sie unter pnpm in GitHub Actions cachen.

Nur geänderte Pakete ausführen

Der Parameter --filter von pnpm akzeptiert einen Selektor für Änderungen seit einem Referenzpunkt. Aus der pnpm-Filterdokumentation (geprüft im Oktober 2026):

# packages changed since origin/main
pnpm --filter "[origin/main]" test

# changed packages plus everything that depends on them
pnpm --filter "...[origin/main]" test

# changed packages plus their dependencies
pnpm --filter "[origin/main]..." build

Verwenden Sie "...[origin/main]" für Test und Build in der CI. Eine Änderung an packages/ui muss apps/web erneut testen, da das Paket davon abhängt. Das ... vor dem Selektor nimmt die abhängigen Pakete mit auf.

Zwei nützliche Optionen aus derselben Dokumentation:

  • --test-pattern="test/*" verhindert, dass abhängige Pakete hinzugefügt werden, wenn nur Testdateien geändert wurden, sodass eine Teständerung nicht alles neu testet.
  • --changed-files-ignore-pattern="**/README.md" ignoriert Änderungen, die keine Rolle spielen, etwa Dokumentation.
pnpm --filter "...[origin/main]" \
  --changed-files-ignore-pattern="**/*.md" \
  run test

Laut Dokumentation wird die Referenz mit dem Merge-Base verglichen, also dem Commit, an dem Ihr Branch abzweigt. Fehlt in einem Shallow-Clone die Merge-Base, vergleicht pnpm direkt mit der Referenz. Der Selektor benötigt Git 2.24 oder neuer. Die Images von GitHub-Hosted Runners und compiler.dev enthalten ein neueres Git.

Fetch-Tiefe

origin/main muss lokal vorhanden sein. Der Checkout holt nur den Merge-Commit des PRs, daher fehlt die Basis-Branch-Referenz möglicherweise. Zwei Lösungen:

- uses: actions/checkout@v6
  with:
    fetch-depth: 0

oder holen Sie nur das Nötige:

- uses: actions/checkout@v6
  with:
    fetch-depth: 1
- run: git fetch --no-tags --depth=200 origin ${{ github.base_ref }}

Ein Shallow-Fetch genügt, wenn 200 Commits die Merge-Base abdecken; andernfalls werden die Ergebnisse ungenauer. Die vollständige Historie ist einfacher und mit filter: tree:0 beim Checkout trotzdem schnell.

Bei Push-Events auf main ist origin/main der aktuelle Commit, der Filter wählt also nichts aus. Verwenden Sie entweder "...[HEAD^1]" für Pushes oder führen Sie die vollständige Suite auf main aus und gefilterte Läufe nur bei PRs.

Parallelität in pnpm

pnpm führt Skripte in topologischer Reihenfolge aus und kann parallelisieren. Mit -r:

pnpm -r --workspace-concurrency=8 run test

--workspace-concurrency ist standardmäßig 4. Auf einer Maschine mit 8 Kernen ist 8 ein sinnvoller Startwert. Kombinieren Sie es mit Filtern:

pnpm --filter "...[origin/main]" --workspace-concurrency=8 run test

Führen Sie mit --if-present aus, damit Pakete ohne das Skript übersprungen werden statt zu scheitern. Verwenden Sie --workspace-concurrency=1 nur zur Fehlersuche bei Problemen mit der Reihenfolge.

Aufteilung auf mehrere Jobs

pnpm verteilt die Arbeit nicht auf mehrere Maschinen. Verwenden Sie eine GitHub-Matrix nach Paket oder Aufgabengruppe:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        package: [web, api, worker]
    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 --filter "${{ matrix.package }}..."
      - run: pnpm --filter "${{ matrix.package }}" test

pnpm install --filter mit name... installiert nur dieses Paket und seine Abhängigkeiten, was jeden Job verkürzt. Die Punkte nach dem Namen bedeuten Abhängigkeiten; Punkte davor (...name) bedeuten abhängige Pakete, also solche, die von ihm abhängen. Verteilen Sie die Matrix so, dass kein Job dominiert; zum Aufteilen einer großen Suite siehe Test-Sharding, und der Shard-Rechner zeigt, ab wann sich weitere Shards lohnen.

Wann Turborepo oder Nx ergänzen

Die pnpm-Filter zeigen, welche Pakete sich geändert haben. Sie cachen aber keine Task-Ausgaben. Wird dasselbe Paket bei jedem PR von Grund auf neu gebaut, hilft ein Task-Cache: Turborepo und Nx hashen Eingaben und spielen Ausgaben erneut ab, lokal und remote. Siehe schnellste CI für Turborepo und schnellste CI für Nx. Beide funktionieren problemlos auf pnpm-Workspaces und verwenden dieselben packages-Globs aus pnpm-workspace.yaml.

Ein vollständiger Workflow

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

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  check:
    runs-on: [self-hosted, Linux, compiler-ci]   # or ubuntu-latest
    timeout-minutes: 20
    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: PR: changed packages only
        if: github.event_name == 'pull_request'
        run: |
          pnpm --filter "...[origin/${{ github.base_ref }}]" \
            --workspace-concurrency=8 run --if-present lint test build
      - name: main: everything
        if: github.event_name == 'push'
        run: pnpm -r --workspace-concurrency=8 run --if-present lint test build

Der concurrency-Block bricht überholte Runs auf demselben Branch ab, was ebenfalls Minuten spart; siehe GitHub Actions-Kosten senken. Auf compiler.dev legt die Zeile runs-on den Job auf einer Maschine mit 8 vCPU ab $0.008 pro Minute mit bereitgestellten Dependency-Caches ab; siehe Preise.

Typprüfung und Linting sind in einem TypeScript-Monorepo oft der langsamste Teil; Caching dafür beschreibt TypeScript-Monorepo beschleunigen.

Häufige Fehler

  1. Keine origin/main-Referenz. Der Filter findet nichts oder alles.
  2. Abhängige vergessen. [origin/main] ohne ... überspringt Pakete, die über Abhängigkeiten betroffen sind.
  3. Install mit Filter. Filtern Sie die Installation nur, wenn Sie sicher sind, dass jeder Job eine Teilmenge braucht; eine fehlende Abhängigkeit zeigt sich als verwirrende Fehlermeldung.
  4. Änderungen auf Root-Ebene. Eine Änderung an pnpm-lock.yaml oder der Root-Konfiguration betrifft jedes Paket. Erwägen Sie, dann die vollständige Suite auszuführen.

FAQ

Wie entscheidet pnpm, dass sich ein Paket geändert hat?

Über git diff seit dem Referenzpunkt, zugeordnet zu Paketverzeichnissen. pnpm zählt ein Paket außerdem als geändert, wenn sich eine Katalogversion ändert, die es in pnpm-workspace.yaml verwendet.

Kann ich pnpm-Filter mit Turborepo verwenden?

Ja, aber Turborepo hat eine eigene Option --filter mit ähnlicher Syntax. Verwenden Sie pro Befehl nur eine davon.

Ist pnpm install --filter sicher?

Für gezielte Matrix-Jobs ja. Installieren Sie im Zweifel alles; der gecachte Store macht es günstig.

Welche fetch-depth sollte ich verwenden?

0 ist sicher. Ein Shallow-Fetch des Basis-Branches funktioniert, wenn er die Merge-Base abdeckt.

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

Kostenlos testen