buf-setup-action

This Action installs the buf CLI in your GitHub Actions pipelines so that it can be used by other Buf Actions:

• buf-breaking-action
• buf-lint-action
• buf-push-action

After buf-setup-action is run, the buf command is available to other Actions in the pipeline's PATH. You can also use the buf command directly inside of workflow steps.

Usage

Here's an example usage of buf-setup-action:

steps:
  # Run `git checkout`
  - uses: actions/checkout@v2
  # Install the `buf` CLI
  - uses: bufbuild/buf-setup-action@v1.8.0
  # Ensure that `buf` is installed
  - run: buf --version

Configuration

You can configure buf-setup-action with these parameters:

Parameter	Description	Default
version	The version of the buf CLI to install	1.8.0
github_token	The GitHub token to use when making API requests

These parameters are derived from action.yml.

Version

If version is unspecified, the latest version of buf is installed:

steps:
  - uses: actions/checkout@v2
  # Installs latest
  - uses: bufbuild/buf-setup-action@v1.8.0
  - run: buf --version

Use the version parameter to pin to a specific version:

steps:
  - uses: actions/checkout@v2
  # Installs version 1.8.0
  - uses: bufbuild/buf-setup-action@v1.8.0
    with:
      version: 1.8.0
  # Should output 1.8.0
  - run: buf --version

To resolve the latest release from GitHub, you can specify latest, but this is not recommended:

steps:
  - uses: actions/checkout@v2
  - uses: bufbuild/buf-setup-action@v1.8.0
    with:
      version: latest
  - run: buf --version

GitHub token

Optionally, you can supply a github_token input so that any GitHub API requests are authenticated. This may prevent rate limit issues when running on GitHub hosted runners:

steps:
  - uses: bufbuild/buf-setup-action@v1.8.0
    with:
      github_token: ${{ github.token }}

Buf token

When calling the buf command directly from a workflow step, you may need to authenticate with the Buf Schema Registry (BSR). You can authenticate by setting the BUF_TOKEN environment variable. If you have a GitHub secret called BUF_TOKEN, for example, you can set the BUF_TOKEN environment variable like this:

env:
  BUF_TOKEN: ${{ secrets.BUF_TOKEN }}

Installing protoc

In most cases, you don't need to install protoc for Buf's GitHub Actions, but some protoc plugins are built into the compiler itself. If you need to execute one of these plugins, you do need to install protoc alongside buf:

• protoc-gen-cpp (C++)
• protoc-gen-csharp (C#)
• protoc-gen-java (Java)
• protoc-gen-js (JavaScript)
• protoc-gen-objc (Objective-C)
• protoc-gen-php (PHP)
• protoc-gen-python (Python)
• protoc-gen-ruby (Ruby)
• protoc-gen-kotlin (Kotlin)

In these cases, buf executes protoc as a plugin but continues to use its own internal compiler.

The buf-setup-action doesn't install protoc for you, but there are other options you can use, such as setup-protoc. To configure it alongside buf:

steps:
  # Run `git checkout`
  - uses: actions/checkout@v2
  # Install the `buf` CLI
  - uses: bufbuild/buf-setup-action@v1.8.0
  # Install `protoc`
  - uses: arduino/setup-protoc@v1