Mirror BCR

This guide shows you how to create a local mirror of the Bazel Central Registry (BCR) using bz.

Why Mirror BCR?

Faster builds - Avoid network latency for module resolution
Reliability - Builds don’t fail when BCR is slow or down
Compliance - Keep a copy of all dependencies for auditing
Offline builds - Enable builds without internet access

Setup

Create a configuration file

Create bz.star in your project:

# bz.star - BCR Mirror Configuration

# Source: Bazel Central Registry
bcr = registry.http("https://bcr.bazel.build")

# Destination: Local filesystem
mirror = registry.file("/var/bazel-registry")

# Modules to mirror (add your dependencies here)
modules = [
    "bazel_skylib",
    "platforms",
    "rules_cc",
    "rules_go",
    "rules_python",
    "gazelle",
    "protobuf",
]

# Sync workflow
sync.workflow(
    name = "mirror",
    origin = bcr,
    destination = mirror,
    modules = modules,
    versions = sync.latest(count = 5),  # Keep last 5 versions
    transforms = [
        sync.skip_yanked(),
    ],
)

Run the sync
Terminal window
```
bz mod sync --workflow mirror
```
Configure Bazel to use the mirror

Add to your .bazelrc:
Terminal window
```
common --registry=file:///var/bazel-registry
common --registry=https://bcr.bazel.build
```
List your local mirror first so Bazel checks it before BCR.
Set up regular syncing

Create a cron job or CI pipeline to keep the mirror updated:
Terminal window
```
# Run daily at 2 AM
0 2 * * * cd /path/to/project && bz mod sync --workflow mirror
```

Advanced Configuration

Mirror All Versions

For a complete mirror of all versions:

sync.workflow(
    name = "full-mirror",
    origin = bcr,
    destination = mirror,
    modules = modules,
    versions = sync.all(),  # All versions
    transforms = [
        sync.skip_yanked(),
    ],
)

Multiple Workflows

Separate workflows for different environments:

# Development: just latest versions
sync.workflow(
    name = "dev",
    origin = bcr,
    destination = registry.file("./local-registry"),
    modules = modules,
    versions = sync.latest(count = 1),
)

# CI: last few versions for compatibility testing
sync.workflow(
    name = "ci",
    origin = bcr,
    destination = registry.file("/opt/ci-registry"),
    modules = modules,
    versions = sync.latest(count = 3),
)

# Archive: full history
sync.workflow(
    name = "archive",
    origin = bcr,
    destination = registry.file("/mnt/archive/bazel-registry"),
    modules = modules,
    versions = sync.all(),
)

Rewrite URLs for Internal Proxy

If you have a GitHub proxy:

sync.workflow(
    name = "mirror",
    origin = bcr,
    destination = mirror,
    modules = modules,
    transforms = [
        sync.skip_yanked(),
        sync.rewrite_source_urls(
            pattern = "https://github.com",
            replacement = "https://github-proxy.internal.example.com",
        ),
    ],
)

Serving the Mirror

HTTP Server

Serve your mirror via HTTP using any web server:

# Using Python
cd /var/bazel-registry
python -m http.server 8080

# Using nginx
# Add to nginx.conf:
# server {
#     listen 8080;
#     root /var/bazel-registry;
#     autoindex on;
# }

Then configure Bazel:

common --registry=http://localhost:8080

Git Repository

Push the mirror to a git repository:

team_mirror = registry.git(
    url = "https://github.com/myorg/bazel-registry.git",
    branch = "main",
)

sync.workflow(
    name = "git-mirror",
    origin = bcr,
    destination = team_mirror,
    modules = modules,
)

Troubleshooting

Module Not Found

If Bazel can’t find a module:

Verify the module exists in your mirror:
Terminal window
```
ls /var/bazel-registry/modules/
```
Check you’ve synced the required version:
Terminal window
```
ls /var/bazel-registry/modules/rules_go/
```
Run sync again with verbose output:
Terminal window
```
bz mod sync --workflow mirror --verbose
```

Stale Mirror

If your mirror is out of date:

# Check what would be updated
bz mod sync --workflow mirror --dry-run

# Run the sync
bz mod sync --workflow mirror