buf-breaking-action

Note

This action has been deprecated in favor of the buf-action which combines the functionality of buf-breaking-action with the ability to run Buf commands in the same step. Please see the buf-action documentation for more information.

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.

Usage

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.

Prerequisites

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).

Configuration

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.

Output

Parameter	Description
results	The generated breaking change messages with the file annotations.

Constraints

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 configurations

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

Common tasks

Run on push

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'

Run against input in sub-directory

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.yaml

In that case, you can target the proto sub-directory by setting

• input to proto, and
• subdir to proto in the against reference.

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'