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.

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:
    runs-on: ubuntu-latest
    steps:
      - name: Install cargo-release
        uses: taiki-e/install-action@v1
        with:
          tool: cargo-release

      - uses: actions/checkout@v3
        with:
          ref: main

      - uses: cargo-bins/release-pr@v1
        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:
    runs-on: ubuntu-latest
    steps:
      - name: Install cargo-release
        uses: taiki-e/install-action@v1
        with:
          tool: cargo-release

      - uses: actions/checkout@v3
        with:
          ref: main

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

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.

The action runs cargo-release with these CLI options:

• --verbose
• --dependent-version upgrade
• --execute, --no-confirm (no dry run)
• --no-push, --no-tag (only commit)
• --no-publish (no publishing to crates.io yet)
• --allow-branch release/1.2.3 (so that cargo-release doesn't refuse to work)
• with working directory set to the root of the crate being released

Otherwise, cargo-release will behave as normal. Notably, it will read release.toml files where present, which can provide further configuration. There are two additional restrictions:

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
  };
  crate: {
    name: string; // the name of the crate being released
    path: string; // the full/absolute path to the crate
  };
  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

This action pairs with two other actions:

• cargo-bins/pr-release-notes: extract release notes from a PR, such as the one created by this action
• cargo-bins/tag-on-merge: publish a tag when a commit with a particular message is merged