Buf's new GitHub Actions make it easier than ever to instrument your CI/CD workflows with
Reduce friction and save developer time by automating these essential steps.
Buf recently published a collection of GitHub Actions that can be used to setup buf to build custom CI/CD workflows, automatically verify that your Protobuf files conform to lint rules, prevent backwards-incompatible changes, and push modules to the Buf Schema Registry (BSR) so that your GitHub repository is always in-sync with your published modules.
This guide will walk you through the steps required to create a GitHub workflow that runs buf-setup, buf-lint, buf-breaking, and buf-push for both pull requests and branch commits in general. Once you're done, your PRs will include in-line comments like the following:
- The buf-setup action installs
buffor use in other custom actions that require the
- The buf-lint and buf-breaking actions ensure that your Protobuf API changes always conform to
breakingconfigurations. Lint failures and breaking changes are written as in-line comments.
- The buf-push action automatically keeps your GitHub repository in-sync with the BSR.
- Write your workflow configuration once, and leave the rest to
buf-push actions require that
buf is installed in the
GitHub Action runner, so you can use the
buf-setup action to install it.
buf-setup action is easy - all you need to do is add the
job, and select a
buf version to install.
For example, consider the following GitHub workflow configured in
buf-breakingactions require that you use at least version
0.41.0, so make sure to configure a version the satisfies
With this, you can create custom workflows that depend on
buf without needing to worry about maintaing
buf installation yourself.
Now that you've installed
buf in setup, you can configure the
so that changes to your Protobuf APIs are validated with the lint configuration found in your
buf.yaml. We can configure the action so that
buf-lint comments in-line like so:
For example, consider a
buf.build/bufbuild/semver module that defines a
Version message in the
proto/bufbuild/semver/v1/semver.proto file shown below:
buf.yaml configuration contains the following (notice the
Suppose a developer mistakenly updates the
major field to
Major, such that it violates the
configuration (i.e. the updated field name doesn't conform to the
buf-lint action will detect the failure and comment in-line like so:
With this, the developer can quickly realize their mistake and update their change.
Much like the lint section above, you can use the
buf-breaking action to prevent breaking
changes in your APIs according to the breaking configuration found in your
buf.yaml. We can edit
the workflow configuration so that
buf-breaking comments in-line like so:
ifconditional is adapted so that both the
buf-breakingactions are run if the
buf-setupaction succeeds. The simple
success()check is insufficient here because a
buf-lintfailure would prevent the
buf-breakingaction from running (assuming the
buf-lintaction is configured before the
If the same scenario illustrated in the lint section above occurs, the
buf-breaking action will detect
the failure and comment in-line like so:
buf-pushaction requires that you have access to the BSR beta. If you haven't already signed up, add yourself to the waitlist here!
Now that you've configured
buf-breaking, you can adapt this workflow so that commits merged
main branch will automatically push module updates to the BSR.
First, you'll need to create a
buf API token so that you can write to the BSR. For details on creating a
buf API token,
please refer to the documentation. Once you've created a
buf API token, you'll need to create an encrypted
GitHub Secret for it. In the following example, the API token is set to
We don't want to push module updates to the BSR for every pull request commit, so you'll need to add a separate
.github/workflows/push.yaml file that exists alongside the
With this, the
buf-push action will only run if both the
buf-breaking jobs are successful, but both
buf-breaking will run as long as
buf-setup is successful. The module pushed to the BSR is tagged with the
git commit SHA
so that it's easy to associate the two with one another.
Now that you have all of the Buf GitHub Actions configured in your CI/CD pipeline, you'll never have to worry about manual Protobuf maintenance again. If you have any questions or feedback, please reach out in our public Slack channel!