> ## Documentation Index
> Fetch the complete documentation index at: https://bazel-pr-30012.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Bazel registries

Bzlmod discovers dependencies by requesting their information from Bazel
*registries*: databases of Bazel modules. Currently, Bzlmod only supports
[*index registries*](#index_registry) — local directories or static HTTP servers
following a specific format.

## Index registry

An index registry is a local directory or a static HTTP server containing
information about a list of modules — including their homepage, maintainers, the
`MODULE.bazel` file of each version, and how to fetch the source of each
version. Notably, it does *not* need to serve the source archives itself.

An index registry must follow the format below:

* `/bazel_registry.json`: A JSON file containing metadata for the registry
  like:
  * `mirrors`: specifying the list of mirrors to use for source archives.
    The mirrored URL is a concatenation of the mirror itself, and the
    source URL of the module specified by its `source.json` file sans the
    protocol. For example, if a module's source URL is
    `https://foo.com/bar/baz`, and `mirrors` contains
    `["https://mirror1.com/", "https://example.com/mirror2/"]`, then the
    URLs Bazel will try in order are `https://mirror1.com/foo.com/bar/baz`,
    `https://example.com/mirror2/foo.com/bar/baz`, and finally the original
    source URL itself `https://foo.com/bar/baz`.
  * `module_base_path`: specifying the base path for modules with
    `local_repository` type in the `source.json` file
* `/modules`: A directory containing a subdirectory for each module in this
  registry
* `/modules/$MODULE`: A directory containing a subdirectory for each version
  of this module, as well as:
  * `metadata.json`: A JSON file containing information about the module,
    with the following fields:
    * `homepage`: The URL of the project's homepage
    * `maintainers`: A list of JSON objects, each of which corresponds to
      the information of a maintainer of the module *in the registry*.
      Note that this is not necessarily the same as the *authors* of the
      project
    * `versions`: A list of all the versions of this module to be found in
      this registry
    * `yanked_versions`: A map of [*yanked* versions](/versions/8.4.2/external/module#yanked_versions) of this module. The keys
      should be versions to yank and the values should be descriptions of
      why the version is yanked, ideally containing a link to more
      information
* `/modules/$MODULE/$VERSION`: A directory containing the following files:
  * `MODULE.bazel`: The `MODULE.bazel` file of this module version
  * `source.json`: A JSON file containing information on how to fetch the
    source of this module version
    * The default type is "archive", representing an `http_archive` repo,
      with the following fields:
      * `url`: The URL of the source archive
      * `mirror_urls`: A list of string, the mirror URLs of the source archive.
        The URLs are tried in order after `url` as backups.
      * `integrity`: The [Subresource Integrity](https://w3c.github.io/webappsec-subresource-integrity/#integrity-metadata-description)
        checksum of the archive
      * `strip_prefix`: A directory prefix to strip when extracting the
        source archive
      * `patches`: A map containing patch files to apply to the
        extracted archive. The patch files are located under the
        `/modules/$MODULE/$VERSION/patches` directory. The keys are the
        patch file names, and the values are the integrity checksum of
        the patch files
      * `patch_strip`: Same as the `--strip` argument of Unix `patch`.
      * `archive_type`: The archive type of the downloaded file (Same as `type` on `http_archive`).
        By default, the archive type is determined from the file extension of the URL. If the file has
        no extension, you can explicitly specify one of the following: `"zip"`, `"jar"`, `"war"`, `"aar"`,
        `"tar"`, `"tar.gz"`, `"tgz"`, `"tar.xz"`, `"txz"`, `"tar.zst"`, `"tzst"`, `tar.bz2`, `"ar"`, or `"deb"`.
    * The type can be changed to use a git repository, with these fields:
      * `type`: `git_repository`
      * The following fields as described at [https://bazel.build/rules/lib/repo/git](https://bazel.build/rules/lib/repo/git):
        * `remote`
        * `commit`
        * `shallow_since`
        * `tag`
        * `init_submodules`
        * `verbose`
        * `strip_prefix`
    * The type can be changed to use a local path, representing a
      `local_repository` repo, with these fields:
      * `type`: `local_path`
      * `path`: The local path to the repo, calculated as following:
        * If `path` is an absolute path, it stays as it is
        * If `path` is a relative path and `module_base_path` is an
          absolute path, it resolves to `<module_base_path>/<path>`
        * If `path` and `module_base_path` are both relative paths, it
          resolves to `<registry_path>/<module_base_path>/<path>`.
          Registry must be hosted locally and used by
          `--registry=file://<registry_path>`. Otherwise, Bazel will
          throw an error
  * `patches/`: An optional directory containing patch files, only used when
    `source.json` has "archive" type

<h2 id="bazel-central-registry">
  Bazel Central Registry
</h2>

The Bazel Central Registry (BCR) at [https://bcr.bazel.build/](https://bcr.bazel.build/) is an index
registry with contents backed by the GitHub repo
[`bazelbuild/bazel-central-registry`](https://github.com/bazelbuild/bazel-central-registry).
You can browse its contents using the web frontend at
[https://registry.bazel.build/](https://registry.bazel.build/).

The Bazel community maintains the BCR, and contributors are welcome to submit
pull requests. See the [BCR contribution guidelines](https://github.com/bazelbuild/bazel-central-registry/blob/main/docs/README.md).

In addition to following the format of a normal index registry, the BCR requires
a `presubmit.yml` file for each module version
(`/modules/$MODULE/$VERSION/presubmit.yml`). This file specifies a few essential
build and test targets that you can use to check the validity of this module
version. The BCR's CI pipelines also uses this to ensure interoperability
between modules.

## Selecting registries

The repeatable Bazel flag `--registry` can be used to specify the list of
registries to request modules from, so you can set up your project to fetch
dependencies from a third-party or internal registry. Earlier registries take
precedence. For convenience, you can put a list of `--registry` flags in the
`.bazelrc` file of your project.

If your registry is hosted on GitHub (for example, as a fork of
`bazelbuild/bazel-central-registry`) then your `--registry` value needs a raw
GitHub address under `raw.githubusercontent.com`. For example, on the `main`
branch of the `my-org` fork, you would set
`--registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/`.

Using the `--registry` flag stops the Bazel Central Registry from being used by
default, but you can add it back by adding `--registry=https://bcr.bazel.build`.