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/[email protected]
  # Ensure that `buf` is installed
  - run: buf --version

Configuration

Input

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

Parameter	Description	Default
version	The version of the buf CLI to install	v1.27.1
github_token	The GitHub token to use when making API requests
buf_user	The username to use for logging into Buf Schema registry.
buf_api_token	The API token to use for logging into Buf Schema registry.
buf_domain	The domain of the Buf Schema Registry to login to.	buf.build

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/[email protected]
  - run: buf --version

Use the version parameter to pin to a specific version:

steps:
  - uses: actions/checkout@v2
  # Installs version 1.27.1
  - uses: bufbuild/[email protected]
    with:
      version: 1.27.1
  # Should output 1.27.1
  - 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/[email protected]
    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/[email protected]
    with:
      github_token: ${{ github.token }}

The token will need the contents:read permission to be able to read the latest release and tag of buf. This permission is granted by default to the GITHUB_TOKEN that is created for every workflow run of a Github Action, so it is not necessary to explicitly specify the permission. However, you must still pass the token to the action:

steps:
  - uses: bufbuild/[email protected]
    with:
      github_token: ${{ secrets.GITHUB_TOKEN }}

Buf username and Buf API token

If you are using Private Remote Packages you may need to authenticate the entire system to successfully communicate with the Buf Schema Registry. To achieve this, supply both buf_user and buf_api_token. This will add your auth credentials to the .netrc and allow you to access the BSR from anything in your PATH.

steps:
  - uses: bufbuild/[email protected]
    with:
      buf_user: ${{ secrets.buf_user }}
      buf_api_token: ${{ secrets.buf_api_token }}

Other Configurations

Buf token

When calling the buf command directly from a workflow step, you may need to authenticate with the 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 }}

Note that this only authenticate you with the buf cli. You cannot access your private remote packages in BSR. If you need to access your private remote packages, supply the username and Buf API Token as parameters.

Buf domain

If you are working with a private BSR then you can set the buf_domain input to the domain of your instance. Please ensure that you are using a token created on your instance (e.g. https://buf.example.com/settings/user) and not from the public BSR at https://buf.build.

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/[email protected]
  # Install `protoc`
  - uses: arduino/setup-protoc@v1