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
steps:
  - uses: actions/checkout@v2
  - uses: bufbuild/[email protected]
  - uses: bufbuild/[email protected]
    env:
      BUF_INPUT_HTTPS_USERNAME: ${{ github.actor }}
      BUF_INPUT_HTTPS_PASSWORD: ${{ github.token }}
    with:
      against: 'https://github.com/acme/weather.git#branch=main'

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
steps:
  - uses: actions/checkout@v2
  - uses: bufbuild/[email protected]
  - uses: bufbuild/[email protected]
    env:
      BUF_INPUT_HTTPS_USERNAME: ${{ github.actor }}
      BUF_INPUT_HTTPS_PASSWORD: ${{ github.token }}
    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

on:
  push:
    branches:
      - main
steps:
  - uses: actions/checkout@v2
  - uses: bufbuild/[email protected]
  - uses: bufbuild/[email protected]
    env:
      BUF_INPUT_HTTPS_USERNAME: ${{ github.actor }}
      BUF_INPUT_HTTPS_PASSWORD: ${{ github.token }}
    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.