Optimizing your Bazel build

Try these when CI builds are slower or more expensive than they should be. They’re independent: start with whichever matches what you see. For the CI runners themselves, see Optimizing CI runners.

Enable Build without the Bytes (BWOB)

Bazel 7 defaults to --remote_download_toplevel. On CI, --remote_download_minimal downloads less; set it under build:ci on any version. Build without the Bytes has the flag and where to put it. Then turn --config=ci on for CI: pass --config=ci in the job’s bazel calls, or add it automatically for Aspect CLI tasks in .aspect/config.axl:

.aspect/config.axl

load("@aspect//traits.axl", "BazelTrait")

def config(ctx: ConfigContext):
    is_ci = bool(ctx.std.env.var("CI"))
    if is_ci:
        ctx.traits[BazelTrait].extra_flags.extend([
            "--config=ci",
        ])

Diagnose non-determinism and improve cache hit rate

A cache hit rate below 95% usually signals non-determinism: an action produces different outputs from the same inputs, so the actions that depend on it miss the cache.

Check the cache hit rate on the build’s Cache tab in the Build Results UI. Target above 95%. The same tab lists the misses and their reasons. On a self-hosted deployment, the Grafana dashboards also chart the hit rate across builds.
Run aspect cache diff on a commit CI has already built. It lists the actions that missed the cache and the tests they affect, without running any tests.
To find what makes a missed action non-deterministic, collect two execution logs on the same commit:
- Pass --execution_log_compact_file=/tmp/exec.log to your aspect build or aspect test invocation.
- For the second run, ensure a different runner handles the job: stop all runners and wait for the runner group to scale to zero (hosted by Aspect, ask Aspect to recycle the group), or retry from a previous day’s commit to eliminate legitimate source-change misses.
- Download the resulting log artifacts from each CI run.
Compare the two logs using Bazel’s guide to debugging remote cache hits to identify the non-deterministic actions.

Execution log files are often large. Use a commit with no source changes for the second run to eliminate legitimate cache misses as a variable.

​Enable Build without the Bytes (BWOB)

​Diagnose non-determinism and improve cache hit rate

Enable Build without the Bytes (BWOB)

Diagnose non-determinism and improve cache hit rate