Bazel & Buildbarn guides

Foundations · Reviewed November 19, 2026

Try Bazel on one useful workload before migrating.

Pick a service or library your team changes often. Build it, test it, and run it in CI with Bazel before deciding what else to move. The pilot should expose the work the migration requires, not just produce a successful hello world.

Decide what the pilot needs to prove

Write down the problem first: repeated compilation in CI, inconsistent developer environments, a difficult dependency graph, or build capacity. Record the current build and test commands and the artifacts they produce. Keep the same workload for the comparison.

Bazel describes dependencies and tools in a build graph and can reuse action results. It still needs suitable language rules, declared inputs, and working toolchains. Remote caching and remote execution are additional choices; installing Bazel does not provision either service.

QuestionWhat to verify
Repeated workCan a second build reuse results, and does a small source edit rebuild only the work you expect?
ReproducibilityCan a teammate and CI build the target without relying on tools or files that exist only on your laptop?
Integration effortCan the language rules handle code generation, test data, packaging, and the dependencies used by this workload?
MaintenanceWho will maintain BUILD files, rule updates, toolchains, and the CI configuration?

Make one target work locally

Choose a supported Bazel release and pin it in .bazelversion when using Bazelisk. Select language rules compatible with that release and follow their own setup instructions. A repository needs Bazel configuration and BUILD targets; pointing Bazel at an existing Makefile or package manifest is not a complete migration.

Include a real test and its data. Declare tools and generated inputs explicitly. Run the workload from another checkout or machine before interpreting a successful local build as a reproducible setup.

  • Record the Bazel version, language-rule versions, compiler or runtime, and target platform.
  • Check external dependency resolution and private-registry access in CI as well as locally.
  • Compare the artifact and test behavior with the existing build. A faster command that omits required work is not an improvement.

Put the pilot in CI before adding remote execution

Keep the existing CI path while the pilot is evaluated. Use the same source revision and an explicit Bazel configuration. Save Build Event Protocol (BEP) events for build and test outcomes and a profile for timing. The commands below assume the targets already exist; replace the example labels with your own.

bazel version
bazel build //your/package:target \
  --build_event_json_file=/tmp/bazel-pilot.bep.json \
  --profile=/tmp/bazel-pilot.profile.gz
bazel test //your/package:tests --test_output=errors

Compare cold, unchanged, and small-edit builds separately. A new runner and a warm developer checkout have different local state. Record the configuration and what work ran in each case rather than reporting a single speedup percentage.

Choose cache and execution services separately

A remote cache lets clients reuse stored action results. Remote execution runs eligible actions on workers as well. Try cache reuse on a representative workload; then evaluate remote execution if execution capacity or environment consistency is the problem.

Before moving actions off the developer machine, verify toolchains, declared inputs, execution-platform properties, network assumptions, and required credentials. A build that works locally may still depend on a host tool or undeclared file. Adding workers will not correct those dependencies.

Run a small target on Hermetiq Cloud

Use this public fixture to check the connection before moving a representative workload. It needs a POSIX shell rather than a downloaded language toolchain. Success here is a setup check; your own pilot must still exercise its compilers, tests and dependencies.

Recorded November 19, 2026 · Bazel 9.2.0 · macOS arm64 client · Hermetiq Cloud shared Buildbarn workers

We ran a shell-only target that writes a mode and copies a declared input into a manifest. The first command disabled remote cache reads. The second used a fresh Bazel output base, so it could not reuse the first client’s local action cache.

StepRecorded outcomeEvidence
Force remote execution1 remote execution; 0 remote cache hits
Bazel exit code 0
Action records
Bazel event excerpt
Repeat unchanged1 remote cache hit; 0 remote executions
Bazel exit code 0
Action records
Bazel event excerpt

This small fixture verifies a setup and investigation workflow. It does not measure production performance, migration effort, flake-detection accuracy, or every toolchain’s compatibility. The downloadable JSON includes selected evidence fields, with local paths and project identifiers removed where noted.

Download source and recorded evidence · Reproduction steps and scope · Offline verifier

Try the shared-worker setup in your own project · Follow the cache-miss investigation

Expand only after the pilot has an owner

Review correctness, elapsed time, reliability, and maintenance work together. Include the cost of adapting rules and developer workflows. Agree which targets move next and how to roll back if CI or packaging regresses.

Hermetiq can discuss Bazel readiness, toolchains, dependencies, and migration scope before onboarding. Build Analytics & AI connects a supported Bazel build to investigation tools. Managed Cache & Execution adds Hermetiq-provided cache and execution under an agreed workload and operating scope. Neither purchase automatically converts an arbitrary repository to Bazel.

Sources and review

Reviewed against the primary references below and Hermetiq's setup and deployment documentation on November 19, 2026. Check flags and requirements against the versions you run. The adoption and operating checklists are engineering guidance, not measured performance claims.