Zum Inhalt springen

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:

OrtBleibt über Läufe erhaltenÜber Runner hinweg geteiltHinweise
Runner-FestplatteNeinNeinNein, frische VM pro Job
actions/cache des Disk-CacheJaJa, mit Einschränkungen des GeltungsbereichsBegrenzt durch 10 GB und Branch-Geltungsbereich
Remote-Cache-ServerJaJaDie 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:

  1. 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.
  2. 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

  1. 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.
  2. Alle schreiben in den Cache. Ein fehlerhafter Eintrag verbreitet sich. Beschränken Sie Schreibzugriffe.
  3. Shallow Clone mit Target Determination. Der Basis-Commit fehlt.
  4. Unbegrenzter Disk-Cache. Er verdrängt Ihre anderen Caches.
  5. Unterschiedliche Toolchains pro Runner. Fixieren Sie Bazel mit .bazelversion und die Toolchains in MODULE.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.

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

Kostenlos testen