The Buf Schema Registry (BSR) stores and manages Protobuf files as versioned modules so that individuals and organizations can publish and consume their APIs without friction. However, having only a main commit history in the BSR makes it difficult for engineers to push work-in-progress modules for testing or validation in the same way that they would push commits to a git feature branch. To enable engineers to begin iterating quickly using generated code without the need to merge Protobuf schemas to main, we support BSR drafts.

Drafts are not included in the main commit history, can be deleted or overwritten, and work seamlessly with:

• GitHub branches: Drafts can be automatically deployed to the BSR when a change is pushed to a GitHub branch/PR by configuring a GitHub action.
• The buf CLI: Drafts can be used locally with the buf CLI and commands like buf build and buf generate.
• Generated SDKs: Any draft can be used with generated SDKs, enabling in-progress changes to be integrated using tools like npm and go get.

Creating drafts

Users can manually push drafts with a simple buf CLI command:

$ buf push --draft <DRAFT_NAME>

When the draft is pushed, it becomes available on the BSR, along with its documentation. A link at the top of the repository page will show the number of drafts that were pushed to that repository and provide the ability to navigate to them:

Users can also integrate drafts by adding the buf-push-action to their GitHub workflows. With this integration, engineers can automatically deploy drafts with their Protobuf definitions to the BSR whenever they push to a GitHub branch or pull request!

To illustrate, consider this example:

name: buf-push
on: push # Apply to all pushes
jobs:
  push-module:
    # Run `git checkout`
    - uses: actions/checkout@v3
    # Install the `buf` CLI
    - uses: bufbuild/buf-setup-action@v1
    # Push the module to the BSR
    - uses: bufbuild/buf-push-action@v1
      with:
        buf_token: ${{ secrets.BUF_TOKEN }}
        # Push as a draft when not pushing to `main`
        draft: ${{ github.ref_name != 'main' }}

The draft flag indicates whether the module should be pushed as a draft. In the above example, the module will be pushed to the BSR as a draft if the GitHub push did not occur on the main git branch. The name of the BSR draft will be the short ref name of the git branch or git tag that triggered the workflow run. For more details on buf-push-action, check out the GitHub repository and the Buf documentation.

Using drafts with the Buf CLI

To consume a draft with the buf CLI, use the name of the draft as a module reference. For example, assuming a buf.gen.yaml file exists in the current directory, code can be generated for a draft with the name add-pet-type-fish using:

$ buf generate buf.build/tommyma/petapis:add-pet-type-fish

The :<DRAFT_NAME> reference can also be used in other buf CLI commands including buf build, buf breaking, buf export, buf curl, or as a dependency in the buf.yaml:

version: v1
deps:
  - buf.build/tommyma/petapis:add-pet-type-fish
breaking:
  use:
    - FILE
lint:
  use:
    - DEFAULT

Please be aware that since drafts are able to be deleted and overwritten, they can only be used as dependencies locally. A module that has a dependency on a draft cannot be pushed to the BSR.

Using drafts with generated SDKs

In addition to using drafts with the buf CLI, engineers can also consume them with generated SDKs.

To reference a draft in generated SDKs, add a @<DRAFT_NAME> reference to the go get or npm install command. The package will be generated with the latest plugin version available when referencing the name of the draft for the remote package.

To get a remote package with generated Go code using protocolbuffers/go for the draft shown above:

$ go get buf.build/gen/go/tommyma/petapis/protocolbuffers/go@add-pet-type-fish

To get a remote package that includes generated TypeScript code with protobuf-es:

$ npm install @buf/tommyma_petapis.bufbuild_es@add-pet-type-fish

Get started with BSR drafts

Drafts are a powerful tool to boost developer productivity by making it easier to push work-in-progress Protobuf definitions to the BSR. This workflow unblocks engineers and enables them to begin iterating quickly using generated code without the need to merge Protobuf schemas to main. Check out buf.build to start developing with drafts now!

For any questions or concerns, check out the BSR docs, and don't hesitate to reach out to us on Slack - we’d love to hear your feedback!