Verify backwards compatibility for your Protobuf files with buf and comment in-line on pull requests.

Refer to the action.yml to see all of the action parameters.

The buf-breaking action requires that buf is installed in the Github Action runner, so we'll use the buf-setup action to install it.

In most cases, you'll only need to configure several variables which are referenced in the examples below. In these examples, we'll configure the action on the hypothetical https://github.com/acme/weather.git repository.

on: pull_request
jobs:
  validate-protos:
    steps:
      - uses: actions/checkout@v2
      - uses: bufbuild/buf-setup-action@v0.3.1
      - uses: bufbuild/buf-breaking-action@v0.4.0
        with:
          against: 'https://github.com/acme/weather.git#branch=main'

This configuration will compare against the main branch of the repository.

Please note that in order for the buf-breaking-action to run and detect changes successfully, both the input and the against must compile. This can be verified by running buf build in both inputs.

When we configure this action on push, we often need to update the reference to check compatibility against so that we don't accidentally verify against the same commit.

For example, if we want to run the buf-breaking action for all commits pushed to the main branch, we'll need to update our against reference to refer to the previous commit, i.e. HEAD~1.

on:
  push:
    branches:
      - main
jobs:
  validate-protos:
    steps:
      - uses: actions/checkout@v2
      - uses: bufbuild/buf-setup-action@v0.3.1
      - uses: bufbuild/buf-breaking-action@v0.4.0
        with:
          against: 'https://github.com/acme/weather.git#branch=main,ref=HEAD~1'

Some repositories are structured so that their buf.yaml is defined in a sub-directory alongside their Protobuf sources, such as a proto/ directory. In this case, you can specify the relative input path and the subdir option in the against reference (this is relevant for both pull_request and push).

$ tree
.
└── proto
    ├── acme
    │   └── weather
    │       └── v1
    │           └── weather.proto
    └── buf.yaml

steps:
  - uses: actions/checkout@v2
  - uses: bufbuild/buf-setup-action@v0.3.1
  - uses: bufbuild/buf-breaking-action@v0.4.0
    with:
      input: 'proto'
      against: 'https://github.com/acme/weather.git#branch=main,ref=HEAD~1,subdir=proto'

The buf-breaking action is also commonly used alongside other buf actions, such as buf-lint and buf-push.