logo

Bazel cache

Reuse Bazel build artifacts across runs. The cache is shared between your CI workflows and local builds.

Namespace provides high-performance Bazel caching with very low network latency between runners and the cache storage. This allows your Bazel workflows to reuse build artifacts across runs, irrespective of your chosen granularity, significantly reducing build times.

Bazel caching is particularly effective for:

  • Build steps that are time-consuming to execute
  • Projects where compilation is typically slow, such as Rust and C++ codebases
  • Workflows that can benefit from cross-invocation artifact reuse

Since the cache is shared, local builds can also benefit from artifacts already cached by CI, and vice versa.

Getting started

Bazel caching is a paid add-on. In order to enable it for your workspace contact our sales team. You can produce a ready-to-use configuration with nsc bazel setup:

Configure cache access

$
nsc bazel setup --remote=false --bazelrc /etc/bazel.bazelrc

This command generates short-term credentials and sets up a bazelrc configuration file.

Use the Bazel cache

$
bazel --bazelrc=/etc/bazel.bazelrc test //..

You can pass multiple configuration files by setting --bazelrc repeatedly, allowing you to combine your existing configuration with Namespace cache access. See Bazel's documentation for granularity control options.

GitHub Actions Example

Configure cache access

When using Namespace runners, you can enable Bazel caching directly in your profile configuration.

Bazel caching enabled in a Namespace runner profile

Use the Bazel cache

In your workflow, you only need to select the corresponding profile. Bazel is already configured to use the Namespace cache.

jobs:
  build:
    runs-on: namespace-profile-with-bazel
  steps:
    - name: Bazel test
      run: bazel test //..

How it works

The Bazel caching solution employs a tiered caching approach, where the hot cache lives as close to the consumer (e.g. your CI job runner) as possible. The cold caching tier is backed by our high-performance artifact storage and enables Bazel to retain a vast amount of cached artifacts.

Access to the Bazel cache is granted through short-lived secure credentials.

Usage

Namespace accounts Bazel cache usage in two categories:

  • Bazel cache storage
  • Bazel cache reads

For detailed billing information for each item as well as included amounts in your plans, visit the pricing page.

Remote Asset API

Namespace implements Bazel's Remote Asset API, which lets Bazel offload external downloads to the Namespace cache instead of fetching them directly from the origin.

Namespace's remote Bazel caches support:

  • Checksum-verified fetches using the checksum.sri qualifier (SHA-256). When Bazel provides an integrity hash, Namespace resolves the asset straight from cache without contacting the origin.
  • Custom HTTP headers via the http_header: and http_header_url: qualifiers, so authenticated or header-gated downloads work through the cache.
  • HTTP and HTTPS URIs.

Enabling

The remote Asset API is opt-in. When using Namespace runners, enable it in your profile configuration alongside Bazel caching. The generated .bazelrc will contain the necessary flags automatically, so you only need to select the profile:

jobs:
  build:
    runs-on: namespace-profile-with-bazel
  steps:
    - name: Bazel test
      run: bazel test //..

When configuring the cache with the CLI, pass the --enable_remote_asset_api flag to include the remote asset endpoint in the generated bazelrc:

$
nsc bazel setup --remote=false --enable_remote_asset_api --bazelrc /etc/bazel.bazelrc

Running Bazel from a Devbox

You can create a Devbox with Bazel caching already configured. Namespace runs the setup for you, so bazel uses the Namespace cache without any further steps.

Enable Bazel caching

Turn on caching when you create the Devbox, and select the repository holding your Bazel project at the same time. The Devbox then starts with the repository cloned and the cache configured, ready to build.

Create a new Devbox from the Devboxes page and select your repository. Expand the Advanced section and turn on Bazel cache.

Bazel cache toggle in the Advanced section of the Devbox create wizard

To add caching to a Devbox that was created without it, open a shell in the Devbox and run setup against the same path the toggle configures:

$
nsc bazel setup --bazelrc=/home/devbox/.bazelrc --remote=false

Run Bazel from the Devbox

Open a shell in the Devbox:

$
devbox ssh my-devbox

Then build as you normally would:

$
bazel build //...

You do not need a --bazelrc flag. Namespace writes the configuration to /home/devbox/.bazelrc, which is the devbox user's home bazelrc, so Bazel picks it up automatically.

The Devbox also sets a BAZELRC environment variable pointing at that file. Use it when you need to name the configuration explicitly, for example from a script or a Makefile that combines it with your own configuration:

$
bazel --bazelrc=$BAZELRC --bazelrc=tools/bazelrc/rbe.bazelrc build //...

The same applies to commands run with devbox exec, which is the usual way to drive builds from CI or from a coding agent:

$
devbox exec my-devbox -- bazel build //...

To also run the Bazel actions on Namespace compute, see Remote Execution from a Devbox.

Bazel cache from GitHub-hosted runners

You can use the Namespace Bazel cache from GitHub-hosted runners. This lets you validate your cache setup before migrating your runners to Namespace.

Performance in this setup is not representative of running your full workflow on Namespace.

From GitHub-hosted runners, cache reads and writes travel over the public internet, adding latency you won't see once your runners run on Namespace.

Use Identity Federation to grant GitHub Actions access to the Namespace Bazel cache and other resources.

Example
A minimal workflow that configures cache access looks like this:

name: Example workflow
permissions:
  id-token: write # This is required for federation using OpenID Connect
  contents: read # This is required for actions/checkout
jobs:
  test:
    name: Bazel test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure access to Namespace
        uses: namespacelabs/nscloud-setup@v0
      - run: |
          nsc bazel setup --remote=false --bazelrc /etc/bazel.bazelrc

For a full step-by-step walkthrough, see From GitHub Runners in the Federation documentation.

Observability

Namespace records the invocations that run through the cache. Inspect them from the Bazel invocations page or with nsc bazel invocation list. See Bazel observability.

Bazel Remote Execution

Beyond caching, Namespace can run your Bazel actions on Namespace compute, scaling builds horizontally with high parallelism. Remote Execution uses this cache, so remotely executed actions share artifacts with your CI and local builds.

Learn more about Bazel Remote Execution →

Last updated