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

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

With a single crate (no workspace):

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:

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:

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.

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

interface TemplateVars {
  pr: {
    title: string; // value of the `pr-title` input
    label?: string; // value of the `pr-label` input
    draft: boolean; // value of the `pr-draft` input
    modifiable: boolean; // value of the `pr-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
}

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

• 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