logo

Bazel integration

Bazel is a popular build system optimized for polyglot, large monorepos.

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 but produce relatively small outputs
  • 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 using the CLI:

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 cache dialog

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

Remote Build Execution

Remote Build Execution is in early access. Reach out to join the waitlist.

Beyond remote caching, Namespace can execute your Bazel actions remotely on Namespace compute. This horizontally scales your builds with high parallelism, while keeping low-latency access to the Bazel cache. We're onboarding new workspaces gradually — reach out to join the early-access waitlist.

Learn more about Bazel Remote Execution →

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 Federation — From GitHub Runners.

Last updated