Repositories#

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, and 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:

Module/repository name syntax

https://BSR_INSTANCE/OWNER/REPOSITORY

# Examples
https://buf.build/acme/petapis       # Teams or community member on the public BSR
https://example.buf.dev/acme/petapis # Pro subscription with custom subdomain on 'buf.dev'
https://buf.example.com/acme/petapis # Enterprise subscription with custom domain

The URL contains these elements:

BSR_INSTANCE is the DNS name for the server hosting the BSR. This is the public BSR instance at buf.build unless you're on the Pro or Enterprise plan, in which case it's your private BSR instance's custom domain.
OWNER is either a user or organization within the BSR ecosystem.
REPOSITORY is storage for all versions of a single module.

To create or manage repositories, you'll need a Buf account to log in to the BSR.

Create a repository#

When setting up a new repository, keep the following in mind:

Repository names and owners can't be changed after creation.
The repository name must be unique within the owner's namespace (either a user or organization), and must:
- be between 2 and 100 characters.
- only contain lowercase letters, digits, or hyphens.
- begin with a lowercase letter.
- can't end with a hyphen.
- not include profanity or a reserved name.

Once you've created the repository, you can begin pushing to it. To create a new repository:

Go to the user dropdown and click Repositories.
Click Create repository.
In the popup that appears, give the repository a name and set its visibility. See the Visibility section below for more detail about visibility settings.
Click Create.

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 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.

You must have the Admin or Owner role for the repository to perform repository management operations. If the repository is owned by an organization, you may inherit these roles from the organization.

Add a member#

Managing members is only allowed for repositories that are owned by a BSR organization.

This section describes how to manage repository members using the BSR web app. See Manage user access with IdP groups if you're using IdP groups to manage repository membership.

To add a direct access member (one who doesn't belong to the parent organization):

Go to the repository's Settings page at https://buf.build/ORGANIZATION/REPOSITORY/settings
In the Manage access section, click Add direct access members.
Use the search box to find the user you want to add, set their access to the resource role you want, and click Add.

Change member access#

To change a member's access level:

Go to the repository's Settings page at https://buf.build/ORGANIZATION/REPOSITORY/settings
In the Direct access section, go to the member whose access you want to change.
Choose the member's new role from the Role dropdown.
Confirm the role change.

Remove a member#

To remove a member from the repository:

Go to the repository's Settings page at https://buf.build/ORGANIZATION/REPOSITORY/settings
In the Direct access section, select the member you want to remove.
Click the trash can at the right of the member's row.
Confirm the removal.

Visibility#

Repositories are either public or private with respect to your BSR instance (either the public BSR instance 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.

If you want to share modules with the wider Buf community, push them to the public BSR with public visibility.

Change visibility#

You can change the visibility of BSR repositories.

In the BSR, navigate to your repository, select Settings, then Change Visibility.
From the command line (you must be logged in from your terminal):
Change a repository's visibility
```
$ buf beta registry repository update <{REMOTE}/{OWNER}/{REPOSITORY}> --visibility [public,private]
```
The --visibility flag must be either private or public.

You can decide who gets to see your repository by picking whether it's public or private.

A public repository can be seen by anyone who has access to the instance. For repositories on https://buf.build, this means it can be seen by anyone on the internet. For private customer instances, it means it can only be seen by anyone authenticated on the instance unless you disable authentication for public modules.
A private repository is only viewable by you and the people you give permission to.

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:

Add metadata#

You can add metadata to your repository that displays in the repository list of any user who has access:

a source URL that links your BSR repository to its corresponding repository in your version control system (helpful for tracing the origin of changes if you're pushing to the BSR using CI/CD workflows)
a description of up to 350 characters

To add metadata:

Go to the repository Settings page: https://buf.build/{organization}/{repository}/settings
In the General section, add the source URL and/or the description and click Save.

Default label#

Each BSR repository has a default label that's used by default in BSR web UI and CLI operations 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's the default label at the time of push becomes 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 resolve by default to what's released.
Users browsing docs on the BSR see what's released.
Dependency automation tools (for example Dependabot, Renovate) automatically keep clients updated with the latest released version of generated SDKs.

Change default label#

When you create a repository, it has a default label of main, for parity with most version control systems. Subject to certain restrictions, you can change the default to point to a different label.

To change the default label pointer:

In the BSR, navigate to your repository, select Settings, then go to the Change default label section.
Start typing in the Select new label box—it provides type-ahead results to help you filter all of the available labels.
Select the label you want to use and press Enter. If none of the restrictions apply, the default label changes.

If the label you want to switch to is archived, you must first unarchive it by pushing again with that label.

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 isn't archived.
You can't change the default label if 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 doesn't pass CSR compatibility checks relative to the latest commit on the current default label.

Repository management#

Deprecate or undeprecate#

You can deprecate BSR repositories to indicate to others that depending on the underlying module is no longer recommended. The Buf CLI warns any user who runs buf dep update on a module that depends on a deprecated repository.

In the BSR, deprecate or undeprecate a repository from its Settings page.

From the command line (you must be logged in from your terminal):

Deprecate a repository

$ buf registry module deprecate <{REMOTE}/{OWNER}/{REPOSITORY}> [--message <deprecation message>]

Undeprecate a repository

$ buf registry module undeprecate <{REMOTE}/{OWNER}/{REPOSITORY}>

Delete a repository#

Warning

Deleting a repository will immediately and permanently break the build of all modules that depend on it. This action can't be undone.

To delete a repository, go to the repository's Settings page, then click Delete repository.

Reserved names#

The following names are reserved terms and can't be used as repository names:

curated-plugin
curated-plugins
member
members
module
modules
organisation
organisations
organization
organizations
plugin-set
plugin-sets
plugin
plugins
pluginset
pluginsets
pro-settings
registries
repositories
repository
setting
settings
team
teams
template
templates
user
users