Action: (Cargo) release-pr

A GitHub Action for creating "Release PRs" for Cargo projects.

Purpose

This action uses cargo-release to perform a release of a Cargo project or a crate, but commits the result to a new branch, and submits that branch as a Pull Request on the repo.

It is meant to be invoked as a "manual" action (via workflow_dispatch).

The result is a PR which can be reviewed, approved, and merged with the same protocol as normal PRs, avoiding the need for special push permissions for people doing releases. This also provides a staging ground for drafting release notes, and serves as a kind of pre-release announcement, or an "intent to release" declaration.

The body and title of the PR can be customised via inputs, or completely overriden using custom templates.

See the various PRs in the test repo for examples: https://github.com/passcod/cargo-release-pr-test/pulls?q=is%3Apr

Usage

With a single crate (no workspace):

```yaml name: Open a release PR on: workflow_dispatch: inputs: version: description: Version to release required: true type: string

jobs: make-release-pr: permissions: id-token: write # Enable OIDC pull-requests: write contents: write runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: chainguard-dev/actions/setup-gitsign@main - name: Install cargo-release uses: taiki-e/install-action@v1 with: tool: cargo-release

  - uses: cargo-bins/release-pr@v2
    with:
      github-token: ${{ secrets.GITHUB_TOKEN }}
      version: ${{ inputs.version }}

```

With a workspace:

```yaml name: Open a release PR on: workflow_dispatch: inputs: crate: description: Crate to release required: true type: choice options: - widget - gadget - budget - fidget - nugget version: description: Version to release required: true type: string

jobs: make-release-pr: permissions: id-token: write # Enable OIDC pull-requests: write contents: write runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: chainguard-dev/actions/setup-gitsign@main - name: Install cargo-release uses: taiki-e/install-action@v1 with: tool: cargo-release

  - uses: cargo-bins/release-pr@v2
    with:
      github-token: ${{ secrets.GITHUB_TOKEN }}
      version: ${{ inputs.version }}
      crate-name: ${{ inputs.crate }}

```

Your repository must be configured (Settings > Actions > General) to allow actions to create Pull Requests:

Release configuration

The action does not include a build of cargo-release itself. Instead, it's expected that cargo-release be installed into the workflow prior to this action running, as with the usage examples above. If cargo-release is not present when the action runs, it will attempt to install it with cargo install (which can be very slow!). If cargo-binstall is available in the workflow, it will instead attempt to use that to install cargo-release.

If 0.23 is available, the action runs only the cargo-release steps it needs. If an older version is present, the simple interface is used, with flags to disable tagging and publishing.

Otherwise, cargo-release will behave as normal. Notably, it will read release.toml files where present, which can provide further configuration. For example, you may want to customise the dependent-version behaviour: you should do so by providing a cargo-release config.

If using cargo-release before 0.23, you must not disable commit creation, and you must not enable post-release version bumps. Doing so will break this action.

Inputs

| Name | Type | Default | Description | |:-|:-:|:-:|:-| | github-token | String | required | Should be set to ${{ secrets.GITHUB_TOKEN }}. | | version | String | required | The exact version to release, or any of the bump levels cargo-release supports. It's recommended to use an exact version. | | crate-name | String | (discovered) | The name of the crate to publish. This is required if there is more than one crate in the repo, e.g. for workspaces, unless crate-path is provided. | | crate-path | String | (discovered) | The relative (from the repo root) path to the crate to publish. This is required if there is more than one crate in the repo, e.g. for workspaces, unless crate-name is provided. | | crate-release-all | Boolean | false | Flag to release all crates in the workspace. This option implicitly requires all found crates to have the same version. Exclusive against crate-name and crate-path. | | pr-title | String | release: <%= crates.length === 1 ? crates[0].name : '' %> v<%= version.actual %> | An EJS template string (or a literal string, so long as no EJS tags are present) for the title of the PR. | | pr-label | String | optional | The name of a label to add to the PR. | | pr-draft | Boolean | false | Set to true to create the PR as Draft. | | pr-modifiable | Boolean | true | Set to false to disallow maintainers from editing the PR. Note that this is rarely enforceable, as the branch is created in the same repo. | | pr-template | String | optional | An EJS template string for the body of the PR. This is mutually exclusive with pr-template-file. If neither is provided, the default template is used. | | pr-template-file | String | optional | The path to an EJS template file for the body of the PR. This is mutually exclusive with pr-template. If neither is provided, the default template is used. | | pr-merge-strategy | String | squash | The merge strategy that should be used to merge the release PR. Note that this action is not involved in merging the PR; this input is only a hint which is rendered by the (default) template. May be either of: squash, merge, rebase, bors. | | pr-release-notes | Boolean | false | Includes a section in the PR body (with the default template) which can be used to fill in release notes. | | pr-meta-comment | Boolean | true | Includes a comment containing some JSON metadata about the release (with the default template) in the PR body, for other actions to consume later. | | check-semver | Boolean | false | Use cargo-semver-checks to check the release before pushing it. For this to work, the current version of the crate must be published to the registry. | | git-user-name | String | github-actions | The git user name, which will be used for the release commit. | | git-user-email | String | github-actions@github.com | The git user email, which will be used for the release commit. | | base-branch | String | (discovered) | The branch which the release PR will target. Note that the action does not checkout this branch, so mismatches could cause odd behaviour. Defaults to the repo's configured default branch. | | branch-prefix | String | release | The prefix to use to name the branch used for the PR. This will be joined onto the version input with /. |

Templates

PR title and body templates are EJS. The following variables are available:

``typescript interface TemplateVars { pr: { title: string; // value of thepr-titleinput label?: string; // value of thepr-labelinput draft: boolean; // value of thepr-draftinput modifiable: boolean; // value of thepr-modifiable` input

template?: string; // value of the `pr-template` input
templateFile?: string; // value of the `pr-template-file` input

mergeStrategy: string; // value of the `pr-merge-strategy` input
releaseNotes: boolean; // value of the `pr-release-notes` input
metaComment: boolean; // value of the `pr-meta-comment` input

};

// if multiple crates are released, crate will have the "first" crate: { name: string; // the name of the crate being released path: string; // the full/absolute path to the crate }; crates: { name: string; path: string; }[];

version: { previous: string; // the version of the crate prior to any changes actual: string; // the version of the crate after being released desired: string; // the value of the version input };

branchName: string; // the name of the branch used for the PR title?: string; // the rendered title of the PR // this is only available to the PR body template } ```

Outputs

The action sets the following:

• pr-branch (String) The name of the branch used for the PR
• pr-url (String) The URL to the newly-created PR
• version (String) The version of the crate after release

Pairs well with

• taiki-e/install-action install tooling (such as cargo-release) from binaries

• chainguard-dev/actions/setup-gitsign enable commit signatures in actions with gitsign

• cargo-semver-checks check semver compatibility before publishing a release