`buf-breaking-action`

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'

elide-tools / buf-breaking-action Goto Github PK