Manage repositories

A Buf Schema Registry (BSR) repository represents a module’s commits, labels, and label histories. This page shows how to create and manage your repositories and their properties. All instructions assume that you have a Buf account and are logged in to the BSR.

Create a repository

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

You can't rename a Buf Schema Registry repository once it's created.
The repository name must be unique within the owner's namespace (either a user or organization), and meet these format requirements:
- must be between 2 and 100 characters
- must only contain lowercase letters, digits, or hyphens
- must begin with a lowercase letter
- can't end with a hyphen
- can't 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 Repository concepts page for more detail about visibility settings.
Click Create.

Change repository settings

Within a BSR organization, only users with an Admin or Owner role or Admin permissions on the repository can perform the following operations.

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.

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.

Note

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

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. When you create one, you get to choose which one you want.

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 moduldes.
A private repository is only viewable by you and the people you give permission to.

Manage contributor access

Managing contributors is only allowed for repositories that are owned by a BSR organization. Organization members inherit the organization's base resource role, which defaults to Write. Contributors outside of the organization can be added from the repository's Settings page.

To add a contributor:

Go to the repository Settings page: https://{remote}/{organization}/{repository}
In the Manage access section, click Add user.
Use the search box to find the user you want to add, set their access to the level you want, and click Add.

To change a user's access level or remove their access to the repository:

Go to the repository Settings page: https://{remote}/{organization}/{repository}
In the Manage access section, select the user whose access you want to change or remove.
Click the settings icon at the right of the user's row and choose which operation to perform from the dropdown.

Deprecate or undeprecate

You can deprecate BSR repositories to indicate to others that depending on this repository 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 beta registry repository deprecate <{REMOTE}/{OWNER}/{REPOSITORY}> [--message <deprecation message>]

Undeprecate a repository

$ buf beta registry repository 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

Learn more about repositories and their properties.
Read Manage organizations and Manage members and roles