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
- Keine
origin/main-Referenz. Der Filter findet nichts oder alles. - Abhängige vergessen.
[origin/main]ohne...überspringt Pakete, die über Abhängigkeiten betroffen sind. - 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.
- Änderungen auf Root-Ebene. Eine Änderung an
pnpm-lock.yamloder 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.
Verwandt
- pnpm-Abhängigkeiten in GitHub Actions cachenPnpm-Store in GitHub Actions cachen mit pnpm/action-setup, setup-node oder actions/cache. Store-Pfad, Schlüssel, Workspaces und Cache-Treffer prüfen.
- 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 Turborepo-Monorepos mit GitHub ActionsTurborepo-CI auf GitHub Actions beschleunigen: --filter für geänderte Pakete, Remote Cache mit TURBO_TOKEN, fetch-depth, Sharding und ein Workflow.