Bazel Central Registry

Use this skill to inspect live BCR metadata, answer repo-local Bzlmod version questions, and update module pins.

Quick start

Resolve the helper CLI from this skill directory first. Do not assume the current repo has a scripts/ or tools/ copy of bcr_tool.py.

• Canonical helper path:

- SKILLDIR="${BCRSKILLDIR:-<path-to-this-skill>}" - BCRTOOL="$SKILLDIR/scripts/bcrtool.py"

• Check which direct deps in a repo can be upgraded:

- python3 "$BCR_TOOL" check-upgrades --module-file /path/to/MODULE.bazel

• Check one included file only:

- python3 "$BCRTOOL" check-upgrades --module-file /path/to/deps/bazeldep.MODULE.bazel --workspace-root /path/to/workspace

• List direct deps from a workspace (follows include() chains):

- python3 "$BCR_TOOL" list-deps --module-file /path/to/MODULE.bazel

• Check latest versions from BCR:

- python3 "$BCRTOOL" latest --module rulesgo --module rules_python

• Dry-run upgrade (print diffs only):

- python3 "$BCR_TOOL" upgrade --module-file /path/to/MODULE.bazel

• Apply upgrade edits:

- python3 "$BCR_TOOL" upgrade --module-file /path/to/MODULE.bazel --write

• Best-effort dependency tree (bounded depth):

- python3 "$BCR_TOOL" deps-tree --module-file /path/to/MODULE.bazel --max-depth 2

Tasks

Check which modules can be upgraded

1. Use check-upgrades first for questions like "which modules in the current repo can be upgraded?"
2. Point --module-file at the root MODULE.bazel when the repo uses include().
3. Point --module-file at an included file when the user wants a scoped answer for one file such as deps/bazel_dep.MODULE.bazel; pass --workspace-root if that file contains labels that should resolve from the repo root.
4. Treat singleversionoverride(..., version = "...") as the effective version when comparing to BCR.
5. Treat archive_override and versionless deps as custom pins. Report them separately instead of claiming they can be upgraded by a simple BCR version bump.
6. Cite exact file and line numbers from the tool output in the answer.

Find modules / versions (local registry clone)

1. Clone or point at a local bazel-central-registry checkout.
2. Search by substring:

- python3 "$BCRTOOL" find --registry-path /path/to/bazel-central-registry --query rules

1. List versions for a module:

- python3 "$BCRTOOL" list-versions --registry-path /path/to/bazel-central-registry --module rulesgo

Upgrade modules in MODULE.bazel

• Start with check-upgrades or a dry-run upgrade before editing files.
• upgrade reads the root MODULE.bazel, follows include() files, and updates bazel_dep(..., version = "...") entries to the latest BCR version.
• Use --module to target a subset and --include-overrides to update singleversionoverride entries.
• By default, live lookups choose the latest non-yanked stable release. Add --include-prerelease only when the user explicitly wants release candidates or betas.
• Always start with a dry-run, then re-run with --write when the diff looks correct.
• After bumps, check whether the repo also pins the same dependency on another surface such as go.mod, lockfiles, or generated manifests.

Analyze dependency tree

• list-deps shows direct deps (names + versions) from all included module files.
• deps-tree fetches MODULE.bazel files from BCR for a best-effort transitive tree (bounded by --max-depth).
• For a fully resolved graph (including overrides/extensions), run Bazel directly:

- bazel mod graph

Resources

scripts/

• bcr_tool.py: primary CLI for module search, live metadata lookup, upgrade checks, upgrades, and dependency inspection.
• registry.py: upstream BCR reference helper kept for comparison and reuse when needed.