Quickstart
By default, every time you merge a commit to the main branch, the GitHub Action runs two commands, one after the other:
release-plz release-pr
: creates the release pr.release-plz release
: publishes the unpublished packages.
Follow the steps below to set up the GitHub Action.
1. Change GitHub Actions permissions
-
Go to the GitHub Actions settings:
-
Change "Workflow permissions" to allow GitHub Actions to create and approve pull requests (needed to create and update the PR).
2. Set the CARGO_REGISTRY_TOKEN
secret
Release-plz needs a token to publish your packages to the cargo registry.
- Retrieve your registry token following this guide.
- Add your cargo registry token as a secret in your repository following this guide.
As specified in the cargo publish
options:
- The token for crates.io shall be specified with the
CARGO_REGISTRY_TOKEN
environment variable. - Tokens for other registries shall be specified with environment variables of the form
CARGO_REGISTRIES_NAME_TOKEN
whereNAME
is the name of the registry in all capital letters.
If you are creating a new crates.io token, specify the following scope:
3. Setup the workflow
Add the release-plz workflow file under the .github/workflows
directory.
For example .github/workflows/release-plz.yml
.
Use one of the following examples as a starting point.
Example: release-pr and release
This is the suggested configuration if you are getting started with release-plz.
With this configuration, when you make changes to the main
branch:
- release-plz creates a pull request with the new versions, where it prepares the next release.
- release-plz releases the unpublished packages.
name: Release-plz
permissions:
pull-requests: write
contents: write
on:
push:
branches:
- main
jobs:
release-plz:
name: Release-plz
runs-on: ubuntu-latest
concurrency:
group: release-plz-${{ github.ref }}
cancel-in-progress: false
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@stable
- name: Run release-plz
uses: MarcoIeni/release-plz-action@v0.5
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
Notes:
fetch-depth: 0
is needed to clone all the git history, which is necessary to determine the next version and build the changelog.- The
concurrency
block guarantees that if a new commit is pushed while the job of the previous commit was still running, the new job will wait for the previous one to finish. In this way, only one instance of release-plz will run in the repository at the same time for the same branch, ensuring that there are no conflicts. See the GitHub docs to learn more.
Example: release-pr only
Use this configuration if you want release-plz to only update your packages,
and you want to handle cargo publish
and git tag push by yourself.
name: Release-plz
permissions:
pull-requests: write
contents: write
on:
push:
branches:
- main
jobs:
release-plz:
name: Release-plz
runs-on: ubuntu-latest
concurrency:
group: release-plz-${{ github.ref }}
cancel-in-progress: false
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@stable
- name: Run release-plz
uses: MarcoIeni/release-plz-action@v0.5
with:
command: release-pr
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Example: release only
Use this configuration if you want release-plz to only release your packages,
and you want to update Cargo.toml
versions and changelogs by yourself.
name: Release-plz
permissions:
pull-requests: write
contents: write
on:
push:
branches:
- main
jobs:
release-plz:
name: Release-plz
runs-on: ubuntu-latest
concurrency:
group: release-plz-${{ github.ref }}
cancel-in-progress: false
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@stable
- name: Run release-plz
uses: MarcoIeni/release-plz-action@v0.5
with:
command: release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
Example: release-pr and release on schedule
In the above examples, release-plz runs every time you merge a commit to the main
branch.
To run release-plz periodically, you can use the
schedule
event:
name: Release-plz
permissions:
pull-requests: write
contents: write
# Trigger the workflow every Monday.
on:
schedule:
# * is a special character in YAML so you have to quote this string
- cron: '0 0 * * MON'
jobs:
release-plz:
name: Release-plz
runs-on: ubuntu-latest
concurrency:
group: release-plz-${{ github.ref }}
cancel-in-progress: false
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@stable
- name: Run release-plz
uses: MarcoIeni/release-plz-action@v0.5
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
4. Set input variables (optional)
The GitHub action accepts the following input variables:
command
: The release-plz command to run. Accepted values:release-pr
,release
. (By default it runs both commands).registry
: Registry where the packages are stored. The registry name needs to be present in the Cargo config. If unspecified, thepublish
field of the package manifest is used. If thepublish
field is empty, crates.io is used.manifest_path
: Path to the Cargo.toml of the project you want to update. Both Cargo workspaces and single packages are supported. (Defaults to the root directory).version
: Release-plz version to use. E.g.0.3.70
. (Default: latest version).config
: Release-plz config file location. (Defaults torelease-plz.toml
or.release-plz.toml
).token
: Token used to publish to the cargo registry. Override theCARGO_REGISTRY_TOKEN
environment variable, or theCARGO_REGISTRIES_<NAME>_TOKEN
environment variable, used for registry specified in theregistry
input variable.backend
: Forge backend. Valid values:github
,gitea
. (Defaults togithub
).
You can specify the input variables by using the with
keyword.
For example:
jobs:
release-plz:
name: Release-plz
runs-on: ubuntu-latest
concurrency:
group: release-plz-${{ github.ref }}
cancel-in-progress: false
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@stable
- name: Run release-plz
uses: MarcoIeni/release-plz-action@v0.5
with: # <--- Input variables
command: release-pr
registry: my-registry
manifest_path: rust-crates/my-crate/Cargo.toml
version: 0.3.70
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}