buf-action/MIGRATION.md

Migration Guide

This guide explains what changed when migrating from the individual Buf actions (buf-setup-action, buf-breaking-action, buf-lint-action, buf-push-action) to the new consolidated buf-action.

buf-setup-action

To migrate from buf-setup-action to buf-action, refer to the table below for the necessary changes:

Old Parameter	New Parameter	Description
version	version	Unchanged. Version of buf CLI to install.
buf_user	N/A	Removed. The username is not required for login.
buf_api_token	token	Renamed. Buf API token for BSR requests.
buf_domain	domain	Renamed. Buf domain for BSR requests. Enterprise only.
N/A	setup_only	Added. Installs buf and optionally login to the BSR but no additional commands will be run. Set to true to make buf-action behave like buf-setup-action. Defaults to false. For more details, refer to the setup-only example in the README
N/A	github_action	Added. Github actor for API requests. Defaults to the current actor in the Github context.
github_token	github_token	Unchanged. GitHub token for API requests. Defaults to token in the Github Context.

Example migration:

 steps:
   - uses: actions/checkout@v4
-  - uses: bufbuild/buf-setup-action@v1.45.0
+  - uses: bufbuild/buf-action@v1
     with:
-      buf_user: ${{ secrets.buf_user }}
-      buf_api_token: ${{ secrets.buf_api_token }}
+      version: '1.45.0' # Optional. Defaults to the latest release.
+      token: ${{ secrets.buf_api_token }}
+      setup_only: true
   - run: buf --version

Note

The buf CLI version is no longer dependent on the action version.

buf-breaking-action

To migrate from buf-breaking-action to buf-action, refer to the table below for the necessary changes:

Old Parameter	New Parameter	Description
input	input	Unchanged. The input directory to build. Defaults to the current directory. See the README for more details on specifying inputs.
against	breaking_against	Renamed. Specifies the reference to check breaking changes against. We recommend not setting this parameter and instead relying on the default behavior.
buf_input_https_username	N/A	Removed. The username is not required for login.
buf_input_https_password	N/A	Removed. To support multiple registries use the mulitple format of BUF_TOKEN as an enviornemt variable. See the buf token formats documentation for more details.
buf_token	token	Renamed. Buf API token for BSR requests.

Example migration:

 steps:
   - uses: actions/checkout@v4
-  - uses: bufbuild/buf-setup-action@v1
-  - uses: bufbuild/buf-breaking-action@v1
+  - uses: bufbuild/buf-action@v1
     with:
-      buf_token: ${{ secrets.BUF_TOKEN }}
+      token: ${{ secrets.BUF_TOKEN }}
-      against: 'https://github.com/acme/weather.git#branch=main'
+      # This example shows how to maintain behavior when migrating, but we recommend unsetting this parameter and relying on the default behavior instead.
+      breaking_against: 'https://github.com/acme/weather.git#branch=main'

buf-lint-action

To migrate from buf-lint-action to buf-action, refer to the table below for the necessary changes.

Old Parameter	New Parameter	Description
input	input	Unchanged. The input directory to lint. Defaults to the current directory. See the README for more details on specifying inputs.
buf_token	token	Renamed. Buf API token for BSR requests.

Example migration:

 steps:
   - uses: actions/checkout@v4
-  - uses: bufbuild/buf-setup-action@v1
-  - uses: bufbuild/buf-lint-action@v1
+  - uses: bufbuild/buf-action@v1
     with:
       input: proto
-      buf_token: ${{ secrets.BUF_TOKEN }}
+      token: ${{ secrets.BUF_TOKEN }}

buf-push-action

To migrate from buf-push-action to buf-action, refer to the table below for the necessary changes:

Old Parameter	New Parameter	Description
input	input	Unchanged. The input directory to push. Defaults to the current directory. See the README for more details on specifying inputs.
buf_token	token	Renamed. Buf API token for BSR requests.
draft	N/A	Removed. Drafts are deprecated in favor of labels. Labels are set using git metadata.
create_visibility	N/A	Removed. Repositories will always be created with private visibility if they do not exist.
N/A	push_disable_create	Added. Disables automatic creation of repositories. Defaults to false.

Example migration:

 steps:
   - uses: actions/checkout@v4
-  - uses: bufbuild/buf-setup-action@v1
-  - uses: bufbuild/buf-push-action@v1
+  - uses: bufbuild/buf-action@v1
     with:
-      buf_token: ${{ secrets.BUF_TOKEN }}
+      token: ${{ secrets.BUF_TOKEN }}
-      create_visibility: private
-      draft: ${{ github.ref_name != 'main'}}

To further customize the push action call the buf push command directly. For example:

 steps:
   - uses: actions/checkout@v4
   - uses: bufbuild/buf-action@v1
      with:
        token: ${{ secrets.BUF_TOKEN }}
+       setup_only: true # Disables default behavior.
+  - if: ${{ github.event_name == 'push' }}
+    run: buf push --error-format github-actions --create --git-metadata

Note

Labels are a new feature in the buf CLI. For more information, see the commits and labels documentation.