Skip to main content

Github App

Overview#

While our open source Github Actions provide a robust experience for smaller teams, if your organization has many repositories then it can become laborious to repeatedly configure these actions.

The Buf Github App offers an easy way to seamlessly synchronize source control and the Buf Schema Registry (BSR). Once enabled, the app will discover repositories that have buf.yaml files inside and will react to pull requests against those modules with a variety of checks:

Breaking#

The breaking check performs breaking changes detection between the current branch and the latest BSR commit to main. Breaking changes will be displayed as file annotations on the pull request.

Format#

The format check displays formatting violations as file annotations on the pull request, and recommends running buf format -w to resolve them.

Lint#

The lint check performs linting of proto files and displays lint violations as file annotations on the pull request.

Push#

The push check will buf push a draft commit to the BSR and add a comment to the pull request informing readers of how to consume generated code.

The app will also perform a push to the BSR main branch when pull requests are merged in Github, tagging the commit with the Git SHA.

Authorizing the App#

The app will use the BSR credentials of the developer that has created the pull request, requiring them to sign into the BSR, which they will be prompted to do via a comment:

Hey @example-dev! You're not connected to the Buf Schema Registry (BSR). Please click here to connect.

Configuration#

The github app configures the behaviour of both the lint and breaking checks from the buf.yaml in each module. But each check can be customised further by providing a .github/buf.github.yaml file in the repository:

Default Values#

The buf.github.yaml config file below demonstrates all default values being explicitly set, this file is the equivalent of no buf.github.yaml being present in your repository at all.

buf.github.yaml
version: v1beta1checks:  format:    ignore: []    skip: false  breaking:    ignore: []    skip: false  lint:    ignore: []    skip: falsepush:    branches: []

Fields#

version#

The version key is required, and defines the current configuration version. The only accepted value is v1beta1.

checks#

The checks key is a map of checks, the accepted values are format, lint and breaking.

Check Configuration#

ignore#

The ignore key is a list of file paths within the repository that this check should ignore. If a directory is ignored, then all files and subfolders of the directory will also be ignored. The specified directory or file paths must be relative to the root of the repository.

skip#

The skip key is a boolean flag, if true then this check will be skipped entirely and will not run in this repository.

Push Configuration#

branches#

The branches key is a list of branch names or github branch selection patterns. For example both main and releases/* are valid. If empty then the app defaults to the default branch.

Setup#

You can use the following URL to skip most of the configuration steps (Only steps 7, 10-13 will be needed). Note, we use example-org and buf.example.com as placeholder values, but they should be substituted with your Github organization and BSR instance. 

https://github.com/organizations/example-org/settings/apps/new?name=buf&url=https%3A%2F%2Fbuf.example.com&callback_url=https%3A%2F%2Fbuf.example.com%2Fapp%2Fgithub%2Fcallback&webhook_url=https%3A%2F%2Fbuf.example.com%2Fapp%2Fgithub%2Fwebhook&webhook_active=true&events[]=check_run&events[]=check_suite&events[]=deployment&events[]=deployment_status&events[]=pull_request&events[]=push&checks=write&statuses=write&deployments=write&pull_requests=write&issues=write&contents=read

  1. Navigate to https://github.com/organizations/example-org/settings/apps/new

  2. Set the GitHub App name, we recommend buf

  3. Set the Homepage URL to your BSR address https://buf.example.com

  4. Set the Callback URL to https://buf.example.com/app/github/callback

  5. Under Webook tick Active

  6. Set the Webhook URL to https://buf.example.com/app/github/webhook

  7. Set the Webhook secret to a random generated value, and store for later use

  8. Under Repository Permissions configure the following:

  • Checks - Read and write
  • Commit statuses - Read and write
  • Contents - Read-only
  • Deployments - Read and write
  • Issues - Read and write
  • Metadata - Read-only
  • Pull requests - Read and write
  1. Subscribe to the following events
  • Check run
  • Check Suite
  • Deployment
  • Deployment Status
  • Pull Request
  • Push

  1. If your organization is hosted on https://github.com then make sure Where can this GitHub App be installed? is set to Only on this account. For private instances Any Account can be selected.

  2. Click on Create GitHub App

  3. Once the app is created, from the app’s setting page click on Generate a new client secret and store for later use

  4. Click on Generate a private key and store for later use

Share the App ID, Client ID, Client Secret, Private Key and Webhook Secret with your Buf representative.