Skip to content

GitHub Action

The buf-action GitHub Action makes it easy to run the Buf CLI within a workflow to check for build, lint, format, and breaking change errors, and automatically publish schema changes to the Buf Schema Registry (BSR).

Annotations example for lint and breaking changes

Prerequisites

If you're publishing schema changes, the Buf GitHub Action requires a BSR authentication token. Authenticating with the BSR is required for both the "push" and "archive label" steps.

To authenticate with the BSR, set the token parameter to the BSR token. We recommend storing the token value as a GitHub secret.

Setup

To use the Buf GitHub Action, create a new .github/workflows/buf-ci.yaml file in your repository with the following content:

.github/workflows/buf-ci.yaml
name: Buf CI
on:
  push:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
  delete:
permissions:
  contents: read
  pull-requests: write
jobs:
  buf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: bufbuild/buf-action@v1
        with:
          token: ${{ secrets.BUF_TOKEN }}
          # Change setup_only to true if you only want to set up the Action and not execute other commands.
          # Otherwise, you can delete this line--the default is false.
          setup_only: false
          # Optional GitHub token for API requests. Ensures requests aren't rate limited.
          github_token: ${{ secrets.GITHUB_TOKEN }}

Default behavior

With the default configuration above, the Action does the following:

  • On a pull request, it runs all checks (buf build, buf lint, buf format, and buf breaking) and posts a summary comment on the PR.
  • When you push a Git commit, tag, or branch to GitHub, it pushes named modules to the BSR using buf push.
  • When you delete a Git branch or tag, it archives the corresponding label on the BSR.

Summary comment

The Action reports the status of the most recent checks in a comment on each pull request.

Comment example showing the GitHub summary

To disable the comment, set the comment parameter to false and remove the pull_request: write permission because it's no longer required.

name: Buf CI
on:
  push:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
  delete:
permissions:
  contents: read
- pull-requests: write
jobs:
  buf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: bufbuild/buf-action@v1
        with:
          token: ${{ secrets.BUF_TOKEN }}
+         pr_comment: false

Configuration

You can further configure the Action (including skipping checks, pointing to a custom BSR domain, pinning to a specific Buf CLI version, and more) by adding additional parameters to the buf-ci.yaml file:

- uses: bufbuild/buf-action@v1
  with:
      <Parameter>: <value>

See the unified Action's GitHub Repository for the complete list of parameters and example files for the most common use cases.