Skip to content
alert-triangle

GitHub Action

buf-breaking

v1.1.4 Latest version

buf-breaking

alert-triangle

buf-breaking

Check that the Input location has no breaking changes compared to the "against" location.

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: buf-breaking

              
  uses: bufbuild/buf-breaking-action@v1.1.4
Learn more about this action in bufbuild/buf-breaking-action

Choose a version

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.

image

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'