Configuring Bazel Remote Caching to Speed Up Incremental Builds

Desired outcome

Enable Bazel remote caching so that build action outputs are stored on a shared server and reused in later builds. This reduces compile time and network bandwidth when multiple developers or CI agents rebuild the same targets.

Prerequisites

• Bazel version 0.23 or newer (the --remote_cache flag exists in these releases).
• Access to an HTTP/HTTPS remote cache endpoint. This can be a dedicated bazel-remote-cache instance, a simple Nginx proxy with WebDAV enabled, or any server that implements the Bazel Remote Cache API.
• If the endpoint requires authentication, have a valid token, username/password pair, or client certificate ready.
• A WORKSPACE file that either loads the remote_cache rule (optional) or relies on the command‑line flag.

Procedure

1. Choose where to store the cache URL. For persistent configuration, edit your workspace’s .bazelrc (or a user‑specific ~/.bazelrc) and add:

   build --remote_cache=https://cache.example.com

   Replace https://cache.example.com with the actual URL of your remote cache.

2. If authentication is needed, you can either:

   • Use a .netrc file in your home directory:

     machine cache.example.com login bazel-user password my-secret-token

   • Or pass headers directly via Bazel’s --remote_header flag (repeat for each header):

     build --remote_header="Authorization: Bearer my-secret-token"

3. Optional: upload locally built artifacts after a successful local build so they are immediately available to others:

   build --remote_upload_local_results=true

4. Start with a clean slate to avoid polluting the cache with stale local outputs:

   bazel clean --expunge

5. Run a full build to populate the cache:

   bazel build //... --remote_cache=https://cache.example.com

   If you placed the flag in .bazelrc, you can omit it on the command line.

6. Subsequent builds (with no source changes) should attempt to download matching actions from the remote cache.

Expected checks

• Watch Bazel’s console output for lines such as:

  Remote cache hit: //path/to:target

  or

  Remote cache upload: //path/to:target

• Inspect a build profile for cache metrics:

  bazel build --profile=profile.json //...

  Then examine profile.json for fields like cacheHitRatio, remoteCacheHitCount, or remoteCacheMissCount.

• Confirm the configured URL with:

  bazel info --remote_cache

  It should print the URL you set.

• If you have access to the remote cache server logs, verify that PUT (upload) and GET (download) requests correspond to your build actions.

Recovery options

• If the remote cache is unreachable or returns errors, Bazel automatically falls back to local execution. The build will continue, albeit slower.
• To temporarily disable remote caching without editing configuration files, invoke Bazel with:

  bazel build //... --noremote_cache

• If you suspect corrupted cache entries (e.g., after a server crash), you can clear them on the remote cache side. For a bazel-remote-cache instance, stop the service and delete its data directory, then restart.
• Check network connectivity, firewall rules, and TLS certificates if you see repeated connection failures.

Verification

1. Run a baseline build after a clean state and note the elapsed time:

   bazel clean --expunge
   bazel build //... --remote_cache=https://cache.example.com

2. Immediately run the same command again without changing any sources:

   bazel build //... --remote_cache=https://cache.example.com

   You should see a significantly shorter duration and multiple Remote cache hit lines.

3. Use bazel info --remote_cache to confirm the URL is correctly loaded.

4. Generate a profile and verify that cacheHitRatio is greater than zero:

   bazel build --profile=profile.json //...
   # inspect profile.json

Limitations and practical considerations

• Storage and bandwidth: The remote cache must have enough disk space to hold all action outputs you intend to share. High upload latency can offset the time saved by downloads, especially for large artifacts.
• Authentication freshness: Expired tokens or certificates cause Bazel to reject the connection and silently fall back to local caching, which can be confusing during debugging. Rotate credentials before they expire and monitor Bazel logs for authentication errors.
• Hermeticity requirement: Bazel’s correctness assumes that each action’s outputs are fully determined by its inputs. If a build rule incorrectly declares its outputs as unchanged, stale cache entries may produce incorrect binaries. Always validate custom rules for proper input/output declarations.
• Version compatibility: The --remote_cache flag is stable from Bazel 0.23 onward. Older releases lack this feature; upgrading is required.