Manage repositories

A Buf Schema Registry (BSR) repository represents a module’s commits, labels, and label histories, and can be owned by either users or organizations. 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, nor can you change the owner.
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

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

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.

Add a member

Managing members is only allowed for repositories that are owned by a BSR organization. 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 user's access level or remove their access to the repository:

Go to the repository's Settings page at https://buf.build/ORGANIZATION/REPOSITORY/settings
In the Direct 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.
Confirm the operation.

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