GitHub Action
buf-breaking
This Action enables you to run breaking change detection with
Buf in your GitHub Actions pipelines. If it detects breaking changes in a pull request, it
automatically creates inline comments under specific lines in your .proto files.
buf-breaking-action is also commonly used alongside other buf Actions, such as
buf-lint, which lints Protobuf sources, and buf-push,
which pushes Buf modules to the Buf Schema Registry (BSR). See example
configurations for more.
Here's an example usage of the buf-breaking Action:
on: pull_request # Apply to all pull requests
jobs:
validate-protos:
steps:
# Run `git checkout`
- uses: actions/checkout@v2
# Install the `buf` CLI
- uses: bufbuild/buf-setup-action@v1
# Run breaking change detection against the `main` branch
- uses: bufbuild/buf-breaking-action@v1
with:
against: 'https://github.com/acme/weather.git#branch=main'With this configuration, the buf CLI detects breaking changes between the Protobuf sources in the
current branch against the main branch of the repository.
For the buf-breaking Action to run, you need to install the buf CLI in the GitHub Actions Runner
first. We recommend using the buf-setup Action to install it (as in the example
above).
You can configure buf-breaking-action with these parameters:
| Parameter | Description | Required | Default |
|---|---|---|---|
input |
The path of the Buf input you want to compare with against |
. |
|
against |
The reference to check compatibility against | ✅ | |
buf_input_https_username |
The username for the repository to check compatibility against. | ${{github.actor}} |
|
buf_input_https_password |
The password for the repository to check compatibility against. | ${{github.token}} |
|
buf_token |
The Buf authentication token used for private inputs. |
These parameters are derived from
action.yml.
| Parameter | Description |
|---|---|
results |
The generated breaking change messages with the file annotations. |
For the buf-breaking-action to detect changes successfully, both the input and the against
need to be properly formed inputs, that is, buf needs to be able to build both into
a Buf image. You can verify this locally using the buf build command on both inputs.
Some examples:
# Build the `main` branch
buf build .git#branch=main
# Build the v0.1.0 feature tag
buf build .git#ref=v0.1.0
# Build the Protobuf sources in a sub-directory
buf build ./proto| Example | Config file |
|---|---|
| Simple breaking change detection | examples/simple-change-detection.yaml |
| Detect breaking changes, then push | examples/detect-and-push.yaml |
| Detect breaking changes in a sub-directory | examples/detect-in-directory.yaml |
A common Buf workflow in GitHub Actions is to push the Protobuf sources in the current branch to the
Buf Schema Registry if no breaking changes are detected against the previous commit (where
ref is HEAD~1).
on: # Apply to all pushes to `main`
push:
branches:
- main
jobs:
validate-protos:
steps:
# Run `git checkout`
- uses: actions/checkout@v2
# Install the `buf` CLI
- uses: bufbuild/buf-setup-action@v1
# Run breaking change detection against the last commit
- uses: bufbuild/buf-breaking-action@v1
with:
against: 'https://github.com/acme/weather.git#branch=main,ref=HEAD~1'Some repositories are structured in such a way that their buf.yaml is defined in a
sub-directory alongside their Protobuf sources, such as a proto/ directory. Here's an example:
$ tree
.
└── proto
├── acme
│ └── weather
│ └── v1
│ └── weather.proto
└── buf.yamlIn that case, you can target the proto sub-directory by setting
inputtoproto, andsubdirtoprotoin theagainstreference.
steps:
- uses: actions/checkout@v2
- uses: bufbuild/buf-setup-action@v1
# Run breaking change detection against the last commit
- uses: bufbuild/buf-breaking-action@v1
with:
input: 'proto'
against: 'https://github.com/acme/weather.git#branch=main,ref=HEAD~1,subdir=proto'