Skip to main content

Usage

To execute buf commands below make sure you are authenticated. Obtain a token from the BSR and run:

$ buf registry login

Follow the prompts to enter your username and password (API Token). This will add an entry into your $HOME/.netrc (Linux or macOS) or %HOME%/_netrc (Windows).

Push a Module#

The only requirement to push to the BSR is to have a module that builds successfully, i.e., you should be able to run buf build successfully on your module.

Before you can push a module into the BSR there needs to exist a repository, owned by either a user or an organization, the user has access to. A repository can be created either through the UI or from the command line with buf.

If you want to collaborate with other users on a module, select an organization as the owner of the repository.

1. Create a Repository

Through the UI log in at https://buf.build/login and navigate to Your repositories and click Create Repository. Select an owner for the repository and give it a repository name. The visibility can be either public or private.

Alternatively, use the CLI run the following command:

$ buf beta registry repository create <MODULE_NAME> --visibility [public,private]

The module name takes the form <remote>/<owner>/<repository_name> (e.g. buf.build/acme/weather).
The --visibility flag is required and must be one of: private or public.

2. Configure a name

You'll need to configure your buf.yaml file to match the BSR repository. To do so, add the module name as a name key:

buf.yaml
version: v1name: buf.build/acme/weather

3. Push to the Repository

Push your module to the BSR by running the following command:

$ buf push

This command will return the commit reference.

One of the main benefits of a centralized, Protobuf-aware, registry is the guarantees afforded from pushing broken modules. This means consumers have confidence modules hosted on the BSR will correctly compile.

Suppose we mistyped an identifier:

syntax = "proto3";
package units.v1;
messag Metric {    int64 other = 1;}

If we try to buf push to the BSR we'll get an immediate error:

Failure: units/v1/metric.proto:5:1:syntax error: unexpected identifier.

Sure you can have CI workflows to automatically catch compilation errors, but by using the BSR these gaurantees are made available to everyone out-of-the-box.

That's it. This module can now be consumed as a first class dependency and its autogenerated documentation can be viewed on the BSR.

Add a Dependency#

If, for example, you are using one of the files from the googleapis repository in your Protobuf files, and you're having to copy files into your local Protobuf generation tree, you can instead use buf to manage this dependency for you.

To include dependencies in your build add the deps key to your buf.yaml file and list the modules your build depends on. Example:

buf.yaml
version: v1deps:    - buf.build/googleapis/googleapislint:  use:    - DEFAULTbreaking:  use:    - FILE

After adding dependencies in buf.yaml run the following command:

$ buf mod update

This updates all your deps to their latest version and gets captured in a buf.lock file. You do not need to make any changes to this file and if using a version control system, commit it along with your Protobuf files.

buf.lock
# Generated by buf. DO NOT EDIT.version: v1deps:  - remote: buf.build    owner: googleapis    repository: googleapis    branch: main    commit: 1c473ad9220a49bca9320f4cc690eba5    digest: b1-unlhrcI3tnJd0JEGuOb692LZ_tY_gCGq6mK1bgCn1Pg=    create_time: ...

Once your dependencies are updated, you can run buf build and the buf CLI will resolve hosted module dependencies by leveraging the BSR.

For a more in-depth example see the Tour - Add a Dependency

Code generation#

The BSR facilitates both local and remote code generation, simplifying how module consumers get access to generated code. This is especially useful for clients that need to generate an SDK to consume a Protobuf-based API in their language of choice.

Local code generation#

The buf generate command allows you to run local plugins to generate code from remote modules hosted on the BSR. If you already have a workflow that invokes plugins with protoc then adopting buf generate should be straightforward.

Add a buf.gen.yaml file and list all the plugins as well as their options. Here is a quick example that will generate C++ and Java code.

buf.gen.yaml
version: v1plugins:  - name: cpp    out: gen/proto/cpp  - name: java    out: gen/proto/java

The buf CLI infers the protoc-gen-{name} prefix for each plugin specified by the name key, similar to protoc behaviour.

Once you seup a buf.gen.yaml file run the following command and specify a module hosted on the BSR. That's right, you can reference a hosted BSR module without having the Protobuf files locally!

$ buf generate <MODULE_NAME>

This will generate C++ and Java code in the local /gen/proto/{cpp,java} directories

For a more advanced example, check out the Tour - Generate Go Code

Remote code generation#

If you don't want to manage plugins and generate code manually, and instead would prefer to simply consume generated code, check out the experimental Remote Code Generation section.