Publish to BCR

Release automation that mirrors releases of your Bazel ruleset to the Bazel Central Registry.

Prerequisites

Prepare your ruleset for bzlmod by following the Bzlmod User Guide.

Then, include these template files in your ruleset repository.

Setup

Create a GitHub Actions workflow in your ruleset repository by creating a file, typically named .github/workflows/publish.yaml.

This repository provides a reusable workflow that contains all the boilerplate. See complete documentation in the reusable workflow file.

1. Decide how your workflow will be invoked

Use an on block, and provide at least the tag_name as an input.

For example, if you have a release automation using GitHub Actions, you might call this publish workflow upon successful completion. A recommended setup for release automation, including generating attestations to prove the provenance of release artifacts, may be found at https://github.com/bazel-contrib/.github/blob/master/.github/workflows/

As another example, you might use workflow_dispatch to manually run the publish workflow from the GitHub web UI or the CLI (documentation)

It's also useful to permit both of these, for example:

on:
  # Run the publish workflow after a successful release
  # Will be triggered from the release.yaml workflow
  workflow_call:
    inputs:
      tag_name:
        required: true
        type: string
  # In case of problems, let release engineers retry by manually dispatching
  # the workflow from the GitHub UI
  workflow_dispatch:
    inputs:
      tag_name:
        required: true
        type: string

2. Reference the reusable workflow in your publish job (replacing the [version] placeholder).

jobs:
  publish:
    uses: bazel-contrib/publish-to-bcr/.github/workflows/publish.yaml@[version]
    with:
      tag_name: ${{ inputs.tag_name }}
      # GitHub repository which is a fork of the upstream where the Pull Request will be opened.
      registry_fork: my-org/bazel-central-registry
      # see note on Attestation Support
      attest: true
    permissions:
      contents: write
      # Necessary if attest:true
      id-token: write
      # Necessary if attest:true
      attestations: write
    secrets:
      # Necessary to push to the BCR fork, and to open a pull request against a registry
      publish_token: ${{ secrets.BCR_PUBLISH_TOKEN }}

3. Create a Personal Access Token

Create a "Classic" PAT, see documentation

It requires "workflow" and "repo" permissions.

Note

At the moment, fine-grained PATs are not fully supported because they cannot open pull requests against public repositories, although this is on GitHub's roadmap: github/roadmap#600. To use a fine-grained PAT without opening a pull request, set open_pull_request to false. This will run a step outputting a URL to create the pull request manually. The fine-grained PAT should be created for the owner of the registry fork.

Save it as BCR_PUBLISH_TOKEN in your repository or org, under Settings > Secrets and variables > Actions.

Tip

See an example of release and publish workflows working together in rules_lint.

Publishing multiple modules in the same repo

Multple modules that are versioned together in the same git repository can be published by configuring moduleRoots.

Including patches

Include patches in the BCR entry by adding them under .bcr/patches in your ruleset repository. All patches must have the .patch extension and be in the -p1 format.

For example, a patch in .bcr/patches/remove_dev_deps.patch will be included in the entry's pull request and will be referenced in the corresponding source.json file:

{
    ...
    "patch_strip": 0,
    "patches": {
        "remove_dev_deps.patch": "sha256-DXvBJbXZWf3hITOIjeJbgER6UOXIB6ogpgullT+oP4k="
    }
}

To patch in a submodule, add the patch to a patches folder under the submodule path .bcr/[sub/module]/patches where sub/module is the path to the WORKSPACE folder relative to the repository root.

Attesation support

BCR supports the upload of attestations with your build. This workflow will produce them by default but BCR requires that you also release your ruleset using the bazel-contrib release_ruleset workflow. Source archive attestations produced in other ways will currently be rejected by BCR. If you are not using the release_ruleset, you will want to set attest: false

Reporting issues

Create an issue in this repository for support.

LEGACY GitHub App

Prior to the introduction of the attestation feature in March 2025, this functionality was provided by a GitHub App.

This documentation remains for users of that method to reference before upgrading.

Configure the app for two repositories:

• Your ruleset repository.
• A fork of bazelbuild/bazel-central-registry. The fork can be in the same GitHub account as your ruleset or in the release author's personal account. If you use release automation and the release author is the github-actions bot, then the fork must be in ruleset's account unless you override the releaser.

Note: Authors of rulesets under the bazelbuild org should add the app to their personal fork of bazelbuild/bazel-central-registry.