Skip to content
Documentation

Docs / Adapter commands / Bazel

Bazel adapter

Give Bazel a shared HTTP action cache and content-addressable store without replacing Bazel's action keys or build graph.

Command
boringcache bazel
Protocol
Bazel HTTP remote cache over /ac/* and /cas/*
Action
mode: bazel

How the adapter works

Native action cache and CAS

BoringCache speaks the HTTP cache paths Bazel expects instead of turning Bazel outputs into generic archives.

One workspace for CI and local builds

Use the same cache from a developer laptop, GitHub Actions, or another CI runner.

Clear write control

Restore-only tokens can read remote cache while trusted jobs publish action outputs.

Set up Bazel

Keep the command and cache tag in .boringcache.toml, then use the same boringcache bazel entrypoint locally and in CI. The action cache and CAS stay Bazel-native. The adapter downloads top-level outputs by default; download-outputs and remote-max-connections are configured under [adapters.bazel.options]. The separate bazel-reapi command uses gRPC and a separate cache namespace.

[adapters.bazel]
tag = "bazel-cache"
command = ["bazel", "build", "//..."]

# Run: boringcache bazel

Before the first run

  • Install Bazel or Bazelisk before the direct CLI command.
  • Keep Bazel platform and toolchain configuration stable across the jobs expected to share action results.
  • Use dry-run output to review generated cache flags before adding extra bazelrc lines.

Bazel actions

What is recorded

With Bazel 7.4 or later, the CLI adds --execution_log_compact_file after bazel build, bazel test, bazel run and bazel coverage. Bazel writes a compressed record of each action it ran or served from a cache to a temporary file, and the CLI reads it after the command and removes it. The flag does not change action keys, and Bazel keeps its analysis cache between builds.

The run page and the run API list every action: its target and mnemonic, where it ran, whether the remote cache or a disk cache served it, its exit code, and when it started and how long it took. Command lines, environment variables and input files are not recorded.

Every request Bazel makes to the cache is recorded too, with its result, size and time, so a run shows both what Bazel ran and what the cache served.

Commands without actions

A command that passes its own --execution_log_json_file, --execution_log_binary_file or --execution_log_compact_file keeps its log, and the CLI records no actions. The same applies when any line of a bazelrc file the command loads contains an execution log option, including a line for a config the command does not use, because Bazel accepts only one execution log. Before it adds the flag, the CLI runs bazel --version with the command's environment; when Bazel is older than 7.4 or reports no version within 10 seconds, the command runs unchanged and the CLI records no actions. Commands that run no actions, such as bazel query, and commands run through another program record only the cache requests.

Use the same adapter in GitHub Actions

The Action starts the Bazel adapter and gives the later Bazel step its remote-cache settings.

.github/workflows/ci.yml
- uses: boringcache/one@1781572d7b3ec5aef652f8ba479b981439b2776b # v1.48.2
  with:
    trust-policy: auto
    mode: bazel

- run: bazel build //...

Approve the repository through Connect CI and grant the job contents: read and id-token: write. The Action uses that Machine connection. Pull requests restore by default; trusted jobs may publish. See the authentication example in the GitHub Actions reference for scoped credentials when OIDC is unavailable.

GitHub Actions reference

Benchmarks

gRPC builds the same upstream commits with BoringCache, Bitrise Build Cache, BuildBuddy, Depot Cache, GHA Cache and NativeLink on the same runner classes.

gRPC

Bazel

Benchmark →

RPC framework. The C++ library and its CSM greeter client and server, built with Bazel.

Average restore, build and save · lower is better

GitHub runner

4 vCPU · 16 GB · Ubuntu 24.04 x86-64

BoringCache
2 min 51 s 9 builds
BuildBuddy
4 min 14 s 9 builds
Depot Cache
7 min 47 s 9 builds
GHA Cache
3 min 4 s 9 builds
Same CPU model

Builds of one commit can land on different CPU models. These ratios use only the build pairs where both caches ran on the same model; above 1.00× means BoringCache's total time over those pairs was lower.

BuildBuddy vs BoringCache
1.33× · 1 of 9
Depot Cache vs BoringCache
1.75× · 1 of 9
GHA Cache vs BoringCache
No same-CPU pair
NativeLink vs BoringCache
3.28× · 3 of 9
6 CPU models recorded
BoringCache · Remote cache
AMD EPYC 7763 (4 builds) · AMD EPYC 9V45 (2 builds) · Intel Xeon Platinum 8573C (1 build) · Intel Xeon 6973P-C (1 build) · AMD EPYC 9V74 (1 build)
BuildBuddy
AMD EPYC 7763 (5 builds) · AMD EPYC 9V45 (2 builds) · Intel Xeon 6973P-C (1 build) · AMD EPYC 9V74 (1 build)
Depot Cache
AMD EPYC 7763 (3 builds) · AMD EPYC 9V45 (3 builds) · AMD EPYC 9V74 (2 builds) · Intel Xeon Platinum 8573C (1 build)
GHA Cache · Bazel --disk_cache restored and saved by actions/cache
AMD EPYC 7763 (2 builds) · Intel Xeon Platinum 8573C (2 builds) · AMD EPYC 9V45 (2 builds) · Intel Xeon 6973P-C (1 build) · Intel Xeon Platinum 8370C (1 build) · AMD EPYC 9V74 (1 build)
NativeLink · NativeLink server on the runner
AMD EPYC 7763 (5 builds) · AMD EPYC 9V74 (2 builds) · AMD EPYC 9V45 (1 build) · Intel Xeon Platinum 8573C (1 build)
Cold and warm builds

Each table is one workflow run with one build per cache. A row marked Different CPU ran on another CPU model than BoringCache at the same level, so part of its time difference can come from the hardware.

One cold and warm build per cache
Cache Cold Warm CPU
BoringCache Remote cache 28 min 3 s 1 min 46 s Cold: Intel Xeon 6973P-C · Warm: AMD EPYC 7763
BuildBuddy 26 min 52 s 1 min 51 s AMD EPYC 9V45 Different CPU
Depot Cache 54 min 20 s 2 min 26 s Cold: AMD EPYC 7763 · Warm: AMD EPYC 9V74 Different CPU
GHA Cache Bazel --disk_cache restored and saved by actions/cache 27 min 2 s 73.7 s Cold: Intel Xeon 6973P-C · Warm: Intel Xeon Platinum 8573C Different CPU

Cache hits

BoringCache · GitHub runner · 4 vCPU

99.5% of 82,319 lookups over 9 builds

Served from the runner
Under 1 ms per read
Read from cache
1.46 GB

Tool reference

Check the tool's own reference when you need cache-key rules, build settings, or version-specific behavior.

All adapter commands

Compare every supported command, protocol, and Action mode in one place.

Adapter command index →

Need help or found something unclear? Open an issue or browse the CLI repo.