3.1.8 Registry Structure & Custom Registries

An index registry is the metadata store Bazel consults during module resolution. The Bazel Central Registry is just the public instance of that format. A private or forked registry uses the same layout, so once you understand the files Bazel reads and how --registry chooses among them, you understand both public and internal module hosting.^1,2 If 3.1.1 Bzlmod (MODULE.bazel) explained that Bazel resolves modules through registries, this article is the file-format view of that statement.

An index registry is a small filesystem tree

Bazel only supports index registries: either a local directory or a static HTTP server with a fixed layout.¹ At the top level you may have an optional bazel_registry.json, then a modules/ directory, and under that one directory per module.¹ The registry-wide file is where shared archive mirrors and module_base_path for local_path entries live.¹

my-registry/
  bazel_registry.json
  modules/
    rules_foo/
      metadata.json
      1.2.3/
        MODULE.bazel
        source.json
        patches/
        overlay/
        presubmit.yml   # BCR only

Two details are easy to miss. metadata.json is per module, not per version, and it mainly lists available versions plus optional yanked-version metadata.¹ The version directory then contains the registry-owned MODULE.bazel used during resolution and the source.json that tells Bazel how to fetch the actual source tree.^1,2

The registry copy of MODULE.bazel is the important one

During Bzlmod resolution, Bazel asks the registry for dependency MODULE.bazel files first, resolves the graph, and only then consults the registry again to learn how to define the backing repositories.² That is why the MODULE.bazel inside a registry entry is not just a mirror of whatever happens to be in the source archive.^1,2

For released modules, the safest pattern is to treat the registry copy as the source of truth for the release version and keep the source archive MODULE.bazel free of version hard-coding when possible.^1,3 That avoids awkward behavior when users switch to non-registry overrides during local development, because the source tree may no longer represent the published release exactly.³

source.json chooses how Bazel gets the source

source.json is required for each published version, and its schema depends on the source type.¹ The default archive type points at a versioned archive URL and can also carry mirror_urls, integrity, strip_prefix, plus optional overlay/ and patches/ directories that Bazel applies when materializing the repo.¹ git_repository entries forward the expected Git attributes such as remote, commit, or tag, and can also carry patch metadata (patches plus patch_strip) for registry-owned changes to the cloned checkout. local_path entries symlink to a local checkout instead of downloading anything.¹

The subtle part is local_path: if the path is relative, Bazel resolves it through module_base_path from bazel_registry.json, and a relative-on-relative setup only works when the registry itself is local and used via file://....¹ That makes local_path useful for private, locally hosted registries, but not something you can publish to a generic static HTTP host and expect every consumer to use unchanged.¹

BCR adds policy on top of the base format

The BCR is an index registry backed by the bazelbuild/bazel-central-registry repository and browsed through registry.bazel.build.¹ What makes it special is not a different protocol, but extra policy. In addition to the normal registry layout, each published version needs a presubmit.yml file so BCR CI can run interoperability checks across platforms and dependency combinations.¹

That distinction matters because a custom registry can be much smaller. If your company needs to host proprietary modules or a curated fork, you do not need a second dependency mechanism. You need the same index-registry shape and stable source metadata.¹

You can inspect that split in the live BCR repository: a module directory such as modules/rules_cc/ keeps module-wide metadata beside immutable version directories, while docs/README.md documents the BCR-only validation and presubmit.yml layer.⁴ Treat the live tree as a concrete format example. The base registry contract remains the Bazel registry specification.

--registry is how you build a registry chain

The repeatable --registry flag controls where Bazel looks for modules.¹ Earlier entries take precedence, which lets you put an internal registry or fork ahead of the public BCR.¹ The easy-to-miss behavior is that once you start passing --registry, Bazel stops using the default BCR automatically, so you must add https://bcr.bazel.build back explicitly if you still want it as a fallback.¹

common --registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/
common --registry=https://bcr.bazel.build

If the registry is a GitHub fork, the URL has to point at the raw content host, not the normal repository web UI.¹ If the registry is local, a directory on disk is enough, which is why local BCR clones are one practical building block for restricted-network setups alongside the broader strategies in 3.1.9 Offline / Air-Gapped Builds.^1,5 The local-registry-chain snippet keeps that shape runnable: a root module depends on the local-only registry_dep@1.0.0, the registry-side MODULE.bazel supplies the published version, and the assertion script runs with the local registry first and BCR explicitly configured as fallback.

Start with overrides, then promote to a registry

Before publishing, get the dependency working with overrides. 3.1.7 Registry Immutability explains why the registry must not become the iteration surface. The registry-layout concern begins when that working dependency is promoted into the index and placed in an explicit --registry chain.^3,6 See 3.1.6 BCR Infrastructure for download reliability and failover policy.