Publish modules to the BSR

When you want to make a module available for other developers, you push it to the Buf Schema Registry (BSR). Once the module is in the BSR, its code, documentation, and generated SDKs can be accessed by anyone with the correct permissions for your repository. This page describes how to push locally, how to archive and unarchive labels, and how pushing works in CI/CD environments.

Pushing to the BSR also interacts with the BSR's policy checks and Confluent Schema Registry integration features. See their documentation and Commits and labels for more details.

Module and repository setup

Before you can push to a BSR repository, you need to create the repository and then connect it to your module by specifying the repository in the modules.name key of the buf.yaml file:

buf.yaml

version: v2
modules:
  - path: path/to/local/directory
    name: buf.build/exampleco/payments

See Manage repositories to learn how to create a repository.

Pushing from a local workspace

When you push from your workspace, the Buf CLI automatically resolves the internal and external dependencies of the workspace and pushes each of the modules in dependency order. Generally, pushing to the BSR is done via CI/CD integration with your version control system (VCS), but you can also push a workspace manually using these steps:

Open a command prompt and change to your workspace root directory.
Run buf dep update to fetch the latest digests for the specified deps references in the buf.yaml file, and write them and any transitive dependencies to the buf.lock file.
```
$ buf dep update
```
Run buf build to make sure everything is working. This builds the Protobuf files into a Buf image, which is necessary for the modules in the workspace to be accepted into the registry.
```
$ buf build
```
Push your workspace to the BSR. If successful, the Buf CLI outputs the BSR commit hashes for each module in the workspace.
```
$ buf push
Outputbuf.build/example/module:280bdcbf4b0341d6aefd8bfcafc018eb
```

Pushing with labels

Labels allow you to add a commit to the history of a specific stream of development like a release or a feature, similar to branches and tags in a VCS. If no other label is applied, the commit will be added to the history of the default label, which is similar to the default branch in a VCS (e.g. main in Git). As a best practice, we recommend always explicitly specifying the labels you want to push to rather than relying on the current default label in the BSR. See Commits and labels for more details about label properties and behavior.

To apply a label to a commit, add the --label flag:

Apply the 'v1.0.1' label to the commit

$ buf push --label v1.0.1

When a commit is pushed to the BSR, it is appended to the history of each label it was pushed with. Each of these labels will begin resolving to this latest commit as long as policy checks are either passing or not enabled. All BSR artifacts for the modules in a commit can be referenced by any of their labels, which are available via a dropdown selector in the BSR UI:

This repository has two labels, 'main' and 'demos'. 'main' is the default label

Archiving and unarchiving labels

You can archive labels if you no longer need them, so that it's easier to find labels in the label dropdown and "all labels" list. Archiving removes labels from the list but doesn't delete them, and you can unarchive them later if necessary.

To archive a label:

In your repository, choose View all labels from the label dropdown, or go directly in the browser:
```
https://{REMOTE}/{OWNER}/{REPOSITORY}/commits/labels
```
Find the label you want to archive and click the icon at the right:

To unarchive a label:

In your repository, choose View all labels from the label dropdown and click on Archived, or go directly in the browser:
```
https://{REMOTE}/{OWNER}/{REPOSITORY}/commits/labels/archived
```
Find the label you want to unarchive and click the icon at the right:

You can also make a commit with the label applied and it automatically unarchives.

Pushing with CI/CD

As mentioned above, generally you won't be pushing to the BSR directly from a local environment. Instead, most organizations use GitHub Actions or other automation to push to the BSR automatically from their VCS, so that there's a single source of truth and the BSR commit can link back to the context of the original code commit.

For more information about CI/CD, see the General CI/CD setup and GitHub Actions setup pages.