Buf Schema Registry (BSR) repositories allow you to share your Protobuf schemas with your team, customers, or the
wider Buf community, and are the basis of all of the BSR's features and shareable artifacts. This page describes the relationship between repositories, modules, labels, and how repositories interact with the BSR's governance features.

A BSR repository is a remote location representing a module's commits, labels, and label histories. Repositories are similar to a version control system (VCS) in that you can see the commits, labels, and diffs for your modules, but they only exist in the BSR. You can't clone or fork them, and they're meant to be used alongside your VCS. Each repository has a 1:1 relationship with a Buf module, represented by the module's name key. The name shows the module's BSR location and ownership:

• Remote: The DNS name for the server hosting the BSR. This is the public BSR server at buf.build unless you're on the Pro or Enterprise plan, in which case it's your private BSR server's custom domain.

• Owner: Either a user or organization within the BSR ecosystem.

• Repository: Storage for all versions of a single module.

Access and ownership

Repositories can be owned by either users or organizations. Organizations often represent teams within a company that own the schemas contained in the repository and control access to them, both within the BSR and in their VCS. See Manage members and roles for more detail about access controls in the BSR.

Repositories can be updated by two types of users: admins and contributors. Contributors have write access and can push commits to the repository. Admins can additionally change the settings of the repository itself. See Manage repositories for more detail about these settings.

Visibility

Repositories are either public or private with respect to your BSR server (either the public BSR server at https://buf.build or a private server at a custom domain owned by your organization). Visibility maps out as follows:

Repository	Public BSR	Private BSR
Public	All users with access to buf.build can view and import this repository; only repo owners and contributors can edit.	All users with access to the private server can view and import this repository; only repo owners and contributors can edit.
Private	Only repo owners and contributors can view, import, and/or edit.	Only repo owners and contributors can view, import, and/or edit.

Metadata

Each repository has an optional source code URL and description that you can add from the settings page. Adding this information helps others understand the purpose of the repository and navigate to the source code in the VCS if needed. Both fields appear in a user's list of repositories they have access to:

Default label

Each BSR repository has a default label that is used by default in BSR web UI and CLI operations for a repository unless another label or commit is explicitly selected or specified.

• References to a module that don't specify a particular commit or label resolve to the latest commit on the default label.
• New commits pushed to the BSR are automatically assigned to the default label if no other label is provided; however, we recommend explicitly associating labels when pushing instead of relying on the default label.
• A commit made to a label that is the default label at the time of push will become the latest released commit for Generated SDKs.

The initial default label for a repository is main.

We recommend setting the default label name to match the name of the branch in your VCS that you release from. For companies doing continuous deployment, this is usually the default branch in your VCS. This is so that:

• Dependency references will resolve by default to what is released.
• Users browsing docs on the BSR will see what is released.
• Dependency automation tools (e.g. Dependabot, Renovate) will automatically keep clients updated with the latest released version of generated SDKs.

Name change restrictions

There are some restrictions on changing the default label.

• You can only change the default label to point to a label that exists and is not archived.
• You can't change the default label if policy checks are enabled.
• If Confluent Schema Registry (CSR) integration is enabled, you can't update the default label to another label if the latest commit on the other label does not pass CSR compatibility checks relative to the latest commit on the current default label.

Related docs

• Learn how to create and manage repositories.
• Find out how to push modules to the BSR.
• Read about how the BSR handles commits and labels.