Schnellste CI für Bazel-Monorepos mit GitHub Actions
Zuletzt aktualisiert am
Bazel ist bereits inkrementell. Schnelle CI hängt daher vor allem von zwei Dingen ab: einem gemeinsamen Remote-Cache, damit ein frischer Runner nicht neu baut, was ein anderer Lauf bereits gebaut hat, und – bei großen Repositories – dem Ausführen nur der Targets, die eine Änderung betreffen kann. Bazels Cache ist per Design korrekt und lässt sich daher sicher teilen. Die eigentliche Arbeit besteht darin, ihn in GitHub Actions einzubinden.
Warum CI auch mit Bazel langsam ist
Ein frischer GitHub Actions Runner hat ein leeres Output-Base-Verzeichnis und einen leeren Disk-Cache. Bazel baut daher beim ersten Durchlauf jedes Target neu. Inkrementalität hilft nur, wenn der Zustand zwischen den Runs erhalten bleibt. Dafür stehen Ihnen drei Orte zur Verfügung:
| Ort | Bleibt über Läufe erhalten | Über Runner hinweg geteilt | Hinweise |
|---|---|---|---|
| Runner-Festplatte | Nein | Nein | Nein, frische VM pro Job |
actions/cache des Disk-Cache | Ja | Ja, mit Einschränkungen des Geltungsbereichs | Begrenzt durch 10 GB und Branch-Geltungsbereich |
| Remote-Cache-Server | Ja | Ja | Die richtige Wahl im großen Maßstab |
Remote-Cache
Laut der Dokumentation zum Bazel-Remote-Caching (geprüft im Oktober 2026) legt --remote_cache den Endpunkt fest (HTTP, HTTPS, gRPC oder gRPCS). Für einfache Setups werden Zugangsdaten in der URL beschrieben, was nur über HTTPS sicher ist. Legen Sie die Flags in .bazelrc unter einer ci-Konfiguration ab, damit Entwickler und CI dieselbe Definition nutzen:
# .bazelrc
build:ci --remote_cache=https://cache.example.com
build:ci --remote_upload_local_results=false
Die Dokumentation beschreibt --remote_upload_local_results=false so, dass der Build in Bezug auf den Remote-Cache nur lesend arbeitet, und empfiehlt, dass nur das CI-System Schreibzugriff hat. Gehen Sie einen Schritt weiter: Lassen Sie nur vertrauenswürdige Builds auf main schreiben.
# passed from the workflow for main only
build:ci-write --config=ci
build:ci-write --remote_upload_local_results=true
Pull Requests lesen dann, was main gebaut hat, und können den Cache nicht verfälschen. Es gibt gehostete und selbst betriebene Cache-Server; wählen Sie den, der zu Ihren Sicherheitsanforderungen passt. Einen Anbieter empfehle ich hier nicht, da die Wahl vom Speicherort Ihrer Daten und von Ihrer Größe abhängt.
Disk-Cache als Ausweichlösung
Wenn Sie noch keinen Server haben, verweist --disk_cache Bazel auf ein lokales Verzeichnis. Speichern Sie es mit actions/cache:
- uses: actions/cache@v6
with:
path: ~/.cache/bazel-disk
key: bazel-${{ runner.os }}-${{ hashFiles('MODULE.bazel', 'MODULE.bazel.lock', '.bazelversion') }}-${{ github.sha }}
restore-keys: |
bazel-${{ runner.os }}-${{ hashFiles('MODULE.bazel', 'MODULE.bazel.lock', '.bazelversion') }}-
- run: bazel build --disk_cache=~/.cache/bazel-disk //...
Der Disk-Cache wächst standardmäßig ohne Grenze. Die Bazel-Dokumentation nennt ab Bazel 7.4 die Garbage-Collection-Flags --experimental_disk_cache_gc_max_size und --experimental_disk_cache_gc_max_age. Setzen Sie eines davon, sonst erreichen Sie das 10-GB-Limit des Repositories und es kommt zu Verdrängungen; siehe Cache-Limits.
Nur betroffene Targets ausführen: Target Determination
Bei einem großen Monorepo verschwendet bazel test //... auf jedem PR Zeit, selbst mit Caching, weil sich Analyse und Cache-Abfragen für Tausende Targets summieren. Target Determination ermittelt, welche Targets sich zwischen zwei Commits geändert haben.
Der Open-Source-Target-Determinator (bazel-contrib/target-determinator, geprüft im Oktober 2026) nimmt eine Vorgänger-Revision entgegen und gibt die betroffenen Targets zeilenweise auf stdout aus, bezogen auf die aktuell ausgecheckte Revision. Er wird als Release-Binary bereitgestellt. Laut README gibt es außerdem ein driver-Binary, das Tests der betroffenen Targets direkt ausführt und betroffene Tests mit dem Tag manual standardmäßig überspringt.
- uses: actions/checkout@v6
with:
fetch-depth: 0
- name: Find affected targets
run: |
BASE=$(git merge-base origin/${{ github.base_ref }} HEAD)
./tools/target-determinator -bazel bazel "$BASE" > affected.txt
- name: Test affected
run: |
if [ -s affected.txt ]; then
bazel test --config=ci --target_pattern_file=affected.txt
fi
Prüfen Sie im README den genauen Befehl für Ihre heruntergeladene Version: Die Flag-Liste (-bazel, -bazel-opts, -targets, -working-directory) und das positionale Argument für die Vorgänger-Revision sind dort dokumentiert. Fixieren Sie die Version, die Sie herunterladen, und prüfen Sie die Checksumme.
Da das Tool zwei Revisionen vergleicht, muss der Basis-Commit lokal vorhanden sein. Verwenden Sie deshalb fetch-depth: 0. Beachten Sie, dass es nur so genau sein kann wie Ihr Build-Graph. Eine Änderung an MODULE.bazel, .bazelrc oder einer Toolchain wirkt zu Recht auf alles.
Lohnt sich der Modus nur betroffener Targets? Bei einem warmen Remote-Cache sind nicht betroffene Targets Cache-Treffer und kosten nur Sekunden. Bei kleinen und mittleren Repositories ist daher das einfache bazel test //... genauso schnell und unkomplizierter. Ergänzen Sie Target Determination, wenn gerade die Analysezeit das Problem ist.
Sharding und Parallelität
Bazel parallelisiert Actions über Kerne hinweg mit --jobs, dessen Standardwert von der CPU-Anzahl abhängt. Eine größere Maschine beschleunigt kalte Builds direkt. Für Test-Sharding innerhalb von Bazel verwenden Sie shard_count in den Test-Regeln. Um auf mehrere Maschinen zu verteilen:
- Matrix über Target-Gruppen. Testtargets abfragen, die Liste aufteilen und jeden Abschnitt in einem eigenen Job ausführen. Alle Jobs teilen sich den Remote-Cache.
- Remote Execution. Bazel kann Actions auf einem entfernten Cluster ausführen (
--remote_executor). Das skaliert über eine einzelne Maschine hinaus, erfordert aber Infrastruktur und hermetische Builds.
strategy:
matrix:
slice: [0, 1, 2, 3]
steps:
- run: |
bazel query 'kind(".*_test", //...)' --output=label | sort > all.txt
split -n l/4 -d all.txt part-
bazel test --config=ci --target_pattern_file=part-0${{ matrix.slice }}
Siehe Test-Sharding in GitHub Actions, um Abschnitte nach Laufzeit auszubalancieren.
Ein vollständiger Workflow
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
bazel:
runs-on: [self-hosted, Linux, compiler-ci] # or ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
- name: Build and test (PR, read-only cache)
if: github.event_name == 'pull_request'
run: bazel test --config=ci //...
- name: Build and test (main, writes cache)
if: github.event_name == 'push'
run: bazel test --config=ci-write //...
Bazel benötigt viel CPU und Arbeitsspeicher. Die Zeile runs-on ist die einzige compiler.dev-spezifische Änderung: Sie führt denselben Workflow auf einer Maschine mit 8 vCPU und 16 GB aus, für $0.008 pro Minute, wobei die Bazel-Jobs auf alle Kerne skalieren. Größere Varianten (16 und 32 vCPU) sind verfügbar; siehe Preise und den Auswahlassistenten für Runner-Größen.
Häufige Fehler
- Nicht hermetische Actions. Actions, die die Uhr, das Netzwerk oder die Host-Umgebung lesen, liefern auf jeder Maschine unterschiedliche Ergebnisse und verhindern die gemeinsame Nutzung. Beheben Sie die Action, nicht den Cache.
- Alle schreiben in den Cache. Ein fehlerhafter Eintrag verbreitet sich. Beschränken Sie Schreibzugriffe.
- Shallow Clone mit Target Determination. Der Basis-Commit fehlt.
- Unbegrenzter Disk-Cache. Er verdrängt Ihre anderen Caches.
- Unterschiedliche Toolchains pro Runner. Fixieren Sie Bazel mit
.bazelversionund die Toolchains inMODULE.bazel.
Vergleichen Sie mit Nx und Turborepo, falls Teile Ihres Repositories in JavaScript geschrieben sind.
FAQ
Brauche ich für Bazel in CI einen Remote-Cache?
Praktisch ja. Ohne einen solchen Cache baut jeder neue Runner von Grund auf neu. Ein Disk-Cache mit actions/cache ist nur eine Übergangslösung.
Ist eine Target-Bestimmung erforderlich?
Nein. Mit einem warmen Remote-Cache sind die Treffer bei //... größtenteils Cache-Hits. Der Aufwand lohnt sich, wenn die Analyse eines sehr großen Target-Graphen langsam ist.
Sollten PRs in den Remote-Cache hochladen?
Besser nicht. Lassen Sie vertrauenswürdige main-Builds schreiben und PRs nur lesen.
Wie groß sollte die CI-Maschine sein?
Bazel nutzt alle ihm zugewiesenen Kerne. Mehr Kerne beschleunigen kalte Builds nahezu linear, bis Arbeitsspeicher oder I/O zum Engpass werden. Messen Sie das in Ihrem Repo.
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 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.