diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..09ed33d --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,144 @@ +# Migration Guide + +This guide explains what changed when migrating from the individual Buf actions +([buf-setup-action][buf-setup], [buf-breaking-action][buf-breaking], +[buf-lint-action][buf-lint], [buf-push-action][buf-push]) to the new +consolidated `buf-action`. + +## [buf-setup-action][buf-setup] + +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](./README.md#setup-only) | +| 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: + +```diff + 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][buf-breaking] + +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](./README.md#specify-the-input-directory) 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][buf-token-formats] for more details. | +| `buf_token` | `token` | Renamed. Buf API token for BSR requests. | + +Example migration: + +```diff + 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][buf-lint] + +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](./README.md#specify-the-input-directory) for more details on specifying inputs. | +| `buf_token` | `token` | Renamed. Buf API token for BSR requests. | + +Example migration: + +```diff + 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][buf-push] + +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](./README.md#specify-the-input-directory) 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][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: + +```diff + 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: + +```diff + 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][commits-labels] documentation. + +[buf]: https://buf.build +[buf-setup]: https://github.com/marketplace/actions/buf-setup +[buf-breaking]: https://github.com/marketplace/actions/buf-breaking +[buf-cli]: https://github.com/bufbuild/buf +[buf-lint]: https://github.com/marketplace/actions/buf-lint +[buf-push]: https://github.com/marketplace/actions/buf-push +[git-metadata]: https://buf.build/docs/reference/cli/buf/push/?h=git+metadata#git-metadata +[buf-token-formats]: https://buf.build/docs/bsr/authentication/#buf_token-formats +[commits-labels]: https://buf.build/docs/concepts/commits-labels/ diff --git a/README.md b/README.md index 54195da..fb3c7ec 100644 --- a/README.md +++ b/README.md @@ -168,7 +168,7 @@ jobs: ### Specify the input directory -To run the action for parameters not declared at the root of the repository, +To run the action for inputs not declared at the root of the repository, set the parameter `input` to the directory of your `buf.yaml` file. ```yaml @@ -281,6 +281,8 @@ we recommend migrating to this consolidated action that has additional capabilit - Status comments on pull requests. - Easy configuration for custom behavior. +See the [migration guide](MIGRATION.md) for more information. + ## Feedback and support If you have any feedback or need support, please reach out to us on the [Buf Slack][slack],