Repositories: module storage

Buf Schema Registry repositories provide a platform for sharing your Protobuf schemas with your team, customers, or the wider Buf community.

While roughly analogous to Git repositories, a Buf repository is only a remote location—there is no concept of a repository "clone" or "fork". Repositories do not exist in multiple locations.

Every repository is identified by its module name, allowing it to be imported by other modules and uniquely identified within the BSR.

Many organizations with public Protobuf files are already using the BSR, and some bigger ones are officially synced from its source by Buf. These include envoyproxy/envoy, envoyproxy/protoc-gen-validate, googleapis/googleapis, among others. See all supported managed modules in Buf's modules repository.

To push Buf modules to the Buf Schema Registry, you can use the buf push command. A single Buf Schema Registry repository is capable of containing multiple versions of Buf modules, which are stored as commits and tags.

Creating a repository

To create a new repository, you can log in to the Buf Schema Registry, click on Show all under the "Your repositories" section, and then select Create Repository.

When setting up a new repository, there are a few important things to keep in mind:

• The repository name must be unique within its namespace and can be between 2 and 255 characters in length. It can only contain lowercase letters, numbers, or hyphens (-).
• Once you have created the repository, you can use the buf push command to begin pushing modules to it.
• You have the option to link a source code URL later in the repository settings.
• Additionally, you can also provide a description of the repository, which can be up to 350 characters in length.

Creating a private repository

To create a private repository, navigate to Buf Schema Registry and select Repositories and Private.

Deleting a repository

1. Navigate to Buf Schema Registry and select Show all under "Your repositories".

2. Select a repository from the list, select Settings, and then Delete Repository.

Pushing a Buf module to Buf Schema Registry

Before you can push a module to the Buf Schema Registry, you need to assign a name to your local module that corresponds with the name of the repository you created on the Buf Schema Registry website.

Name your local modules using one of these methods:

• When you create them, using buf mod init <remote>/<owner>/<repository_name>
• By re-naming an existing local module
  buf.yaml

  version: v1
  name: <remote>/<owner>/<repository_name>
  

Now you can push this repository to the registry.

$ buf push

Once the module is uploaded, it will be readily available for your team or community to use.

Deprecate or undeprecate a repository

BSR repositories can be deprecated. buf warns you when you run buf mod update on a module that depends on a deprecated repository.

You can deprecate a repository with

$ buf beta registry repository deprecate <buf.build/owner/repository> [--message <deprecation message>]

Undeprecate a deprecated repository with

$ buf beta registry repository undeprecate <buf.build/owner/repository>

Update the visibility of a repository

The visibility of BSR repositories can be updated.

You can update the visibility with

$ buf beta registry repository update <buf.build/owner/repository> --visibility [public,private]

The --visibility flag must be one of: private or public.

Buf Schema Registry URLs