3.1.6 BCR Infrastructure

Bzlmod in 3.1.1 Bzlmod (MODULE.bazel) makes external dependencies feel simple, but production reliability depends on infrastructure below that friendly bazel_dep() surface. The Bazel Central Registry is only the metadata layer: Bazel asks a registry for module files and fetch instructions, then downloads source archives from whatever URLs those registry entries point at. If either layer fails, the build fails for a different reason, and the mitigation is different too.^1,2

What the registry actually serves

An index registry is just a directory tree or static HTTP server. For each module version it serves the registry copy of MODULE.bazel, a source.json file describing how to fetch the source, and optional patches or overlay files.¹ The source archive itself usually lives somewhere else.

That separation matters operationally. A healthy bcr.bazel.build endpoint does not guarantee that the archive URL in source.json is healthy, stable, or even still available.^1,2 Conversely, mirroring source archives does not help if Bazel cannot fetch registry files in the first place. The full registry layout and custom hosting model are covered in 3.1.8 Registry Structure & Custom Registries.

Registry outages and archive outages are different failures

When the hosted BCR endpoint is unavailable, module resolution can fail before Bazel even starts downloading dependency sources. Hosted-registry incidents have a different recovery shape from archive outages: users can often get unstuck by pointing --registry at a mirrored or raw copy of bazelbuild/bazel-central-registry, because Bazel only needs static registry files at that stage.^3,1

common --registry=https://raw.githubusercontent.com/bazelbuild/bazel-central-registry/main/

Archive failures are a separate problem. Many module entries still point at upstream release artifacts or GitHub archive endpoints. Archive checksum churn is the cautionary story here: GitHub-generated /archive/refs/... tarballs are not a stable byte-level API, so a server-side Git upgrade can change the SHA-256 of the downloaded archive even when the extracted source tree is effectively the same.² That is why "it builds from BCR" is not the same thing as "it is insulated from upstream archive churn."

The safe default is to prefer static release artifacts that maintainers publish intentionally, then mirror those artifacts so Bazel has a second place to fetch from.² mirror.bazel.build is the ecosystem's shared version of that pattern. Large organizations usually add their own mirror in front of the same artifacts.²

The knobs maintainers actually use

There are several layers where you can add resilience:

• Registry authors can declare registry-wide source mirrors in bazel_registry.json. Bazel prefixes the original source URL with each mirror base and tries those before the original URL.¹
• Individual module versions can add mirror_urls in source.json as explicit backups for a single archive.¹
• Consumers can replace the default registry entirely with repeated --registry flags, for example to prefer an internal registry or a mirrored BCR endpoint.¹
• Consumers can steer archive downloads with --downloader_config or --module_mirrors, which is especially useful in CI or during temporary infrastructure incidents.⁴

The local-registry-chain snippet isolates the consumer-side registry knob: its assertion script runs bazel mod graph and bazel build with a file:// registry first and https://bcr.bazel.build configured second. The demo module exists only in the local registry, while the command keeps the public registry as an explicit fallback for other modules.

One practical pattern is to keep a small downloader config ready so Bazel can rewrite known URLs toward internal storage during an outage or controlled migration:³

# .bazel_downloader.cfg
rewrite mirror.bazel.build/(.*) storage.googleapis.com/example_bucket/$1

These knobs provide alternate routes while Bazel is still fetching dependencies. They are not the offline-build mechanism: prefetching, repository-cache reuse, and vendoring belong to 3.1.9 Offline / Air-Gapped Builds, while CI air-gap operations belong to 6.7.2 Operating Bazel Builds in Air-Gapped Environments.⁴

Keep the concerns separated

It helps to keep three distinct questions separate:

1. Can Bazel reach registry metadata at all?
2. Are the source archives behind those metadata entries byte-stable and mirrored?
3. Do we trust the artifact we downloaded to match the reviewed source?

This article is about the first two. The immutability rules for registry contents themselves are the next topic in 3.1.7 Registry Immutability. The trust/provenance side is improving through BCR attestation work, but that is a security story more than an availability story. The deeper model lives in 6.7.6 Build Provenance and Attestations.⁵