The following section contains step-by-step instructions on how to easily get started with Buf Schema Registry.

Step 1: Sign up for a Buf account

Let's start by creating a Buf Account.

A Buf Account grants you access to Buf Schema Registry repositories and allows you to explore modules that are available from the community and verified publishers. You'll also need a Buf Account to share modules on the Buf Schema Registry.

Step 2: Create your first repository

To create a repository:

  1. Sign in to Buf Schema Registry.

  2. Click Create a Repository on the Buf Schema Registry welcome page.

  3. Name it <USERNAME>/my-private-repo.

  4. Set the visibility to Private.

  5. Click Create.

    You've created your first repository. You should see:

    Repository created

Step 3: Download and install Buf CLI

You'll need to download Buf CLI to build, push, and pull container modules.

  1. Download and install Buf CLI.

  2. To execute buf commands below make sure you are authenticated. Obtain a token from the BSR and sign in to the Buf CLI application using the Buf Account you've just created.:

    $ buf registry login

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

Step 4: Build a module

  1. Start by creating a .proto file to specify your application as shown below:

    syntax = "proto3";
    package helloworld;
    // The greeting service definition.
    service Greeter {
     // Sends a greeting
     rpc SayHello (HelloRequest) returns (HelloReply) {}
    // The request message containing the user's name.
    message HelloRequest {
     string name = 1;
    // The response message containing the greetings
    message HelloReply {
     string message = 1;
  2. Run buf mod init<your_username>/my-private-repo to configure your buf module.

  3. Run buf build to build and test your Buf module locally.

Step 5: Push the module to Buf Schema Registry from your computer

  1. Run buf push to push your Buf module to Buf Schema Registry. You should see output similar to:

    $ buf push

    You must be signed in to Buf Schema Registry through Buf CLI, and you must also name your modules correctly, as per the above steps.

  2. Your repository in Buf Schema Registry should now display a new latest tag under Tags.

Congratulations! You've successfully:

  • Signed up for a Buf account
  • Created your first repository
  • Built your own buf module on your computer
  • Pushed it successfully to Buf Schema Registry

Next steps