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 maintained by Buf. These include:

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.

Create repo

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.

You can't rename a Buf Schema Registry repository once it's created.

Setting page for creating a repo

Creating a private repository

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

To update your public repository to private, navigate to your repository, select Settings and Change Visibility.

Create a private repo

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.

Deleting a repository deletes all the images it contains and its build settings. This action cannot be undone.

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

User settings

https://buf.build/settings/user

User profile

https://buf.build/{user}

Organization profile

https://buf.build/{organization}

Members of an organization

https://buf.build/{organization}/members

Organizations a user belongs to

https://buf.build/{user}/organizations

Module repository

https://buf.build/{owner}/{repository}

Repository documentation

https://buf.build/{owner}/{repository}/docs

Repository code

https://buf.build/{owner}/{repository}/tree

Generated respository assets

https://buf.build/{owner}/{repository}/assets

Repository history

https://buf.build/{owner}/{repository}/history

Hosted templates associated with an owner

https://buf.build/{owner}/templates

Hosted template

https://buf.build/{owner}/templates/{template}

Remote plugins associated with an owner

https://buf.build/{owner}/plugins

Remote plugin

https://buf.build/{owner}/plugins/{plugin}

Generated documentation for a specific reference

https://buf.build/{owner}/{repository}/docs/{reference}

Generated assets for a specific reference

https://buf.build/{owner}/{repository}/assets/{reference}