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.

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.47.2
  # Ensure that `buf` is installed
  - run: buf --version

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

These parameters are derived from action.yml.

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

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

Use the version parameter to pin to a specific version:

steps:
  - uses: actions/checkout@v2
  # Installs version 1.47.2
  - uses: bufbuild/buf-setup-action@v1.47.2
    with:
      version: 1.47.2
  # Should output 1.47.2
  - 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.47.2
    with:
      version: latest
  - run: buf --version

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.47.2
    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/buf-setup-action@v1.47.2
    with:
      github_token: ${{ secrets.GITHUB_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/buf-setup-action@v1.47.2
    with:
      buf_user: ${{ secrets.buf_user }}
      buf_api_token: ${{ secrets.buf_api_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.

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.

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.47.2
  # Install `protoc`
  - uses: arduino/setup-protoc@v1