Skip to main content

7 Push a Module

Now that you've authenticated with the BSR, you can create a repository and push a module that defines the PetStoreService API.

7.1 Terminology#

Before we continue, it's important that we cover some basic terminology.

7.1.1 Modules#

The module is the core primitive of Buf and the BSR. A module is a collection of Protobuf files that are configured, built, and versioned as a logical unit. You created a module when you initialized a buf.yaml in the beginning of the tour.

7.1.2 Repositories#

A module is stored in a repository. A repository stores all versions of a module, where each version is identified by a commit and (optionally) a tag.

While roughly analogous to Git repositories, a BSR repository is only a remote location - there is no concept of a repository "clone". In other words, repositories do not exist in multiple locations.

7.1.3 Module Names#

A module has a name, and has three components:

  • Remote: The DNS name for the server hosting the BSR, i.e. buf.build.
  • Owner: The user or organization that owns the repository.
  • Repository: The repository's name.

For example:

  • The module buf.build/alice/tools has a remote buf.build, owner alice, and repository tools.
  • The module buf.build/acme/weather has a remote buf.build, owner acme, and repository weather.

7.2 Create a Repository#

Create a petapis repository with the following command:

$ buf beta registry repository create buf.build/$BUF_USER/petapis --visibility publicFull name                    Createdbuf.build/$BUF_USER/petapis  ...

7.3 Configure a name#

Move back into the petapis directory:

$ cd petapis

Update your buf.yaml so that its name matches the repository you just created:

buf.yaml
 version: v1+name: buf.build/$BUF_USER/petapis lint:   use:     - DEFAULT breaking:   use:     - FILE

7.4 Push the Module#

Push the module to the buf.build/$BUF_USER/petapis repository with the following command (in the petapis directory containing the buf.yaml):

$ buf push19bcefa1a736428d9e64d21c9191b213

Behind the scenes, buf recognizes the name in your buf.yaml and pushes the module to the buf.build/$BUF_USER/petapis repository. If successful, the generated commit identifies this current version of your module.

The commit you see will differ from the one shown here.