Release-plz

https://release-plz.ieni.dev/docs
Admin
Release-plz is a Rust open-source project that automates the tedious and error-prone tasks of...
Tokens:45,016
Snippets:324
Trust Score:7.1
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install release-plz with pacman

Source: https://release-plz.ieni.dev/docs/usage/installation

Installs release-plz from the Arch Linux community repository using pacman.

```bash
pacman -S release-plz
```

--------------------------------

### Install release-plz with Cargo

Source: https://release-plz.ieni.dev/docs/usage/installation

Installs release-plz from crates.io using Cargo. Requires the Rust toolchain to be installed first.

```bash
cargo install --locked release-plz
```

--------------------------------

### Install and use release-plz locally

Source: https://release-plz.ieni.dev/docs

Local workflow for using release-plz: install the CLI, navigate to the project, update Cargo.toml, Cargo.lock, and CHANGELOG.md, commit the changes, then create the git tag and publish to crates.io.

```bash
cargo install --locked release-plz
```

```bash
cd path/to/your/project
```

```bash
release-plz update
```

```bash
git add . && git commit -m "chore: release"
```

```bash
release-plz release
```

--------------------------------

### Install release-plz with apk

Source: https://release-plz.ieni.dev/docs/usage/installation

Installs release-plz from Alpine Linux's testing repository using apk. Requires enabling the testing repository first.

```bash
apk add release-plz
```

--------------------------------

### Install release-plz-git with paru

Source: https://release-plz.ieni.dev/docs/usage/installation

Installs the VCS package release-plz-git from the AUR using the paru helper.

```bash
paru -S release-plz-git
```

--------------------------------

### Example release-plz.toml configuration for a Cargo workspace

Source: https://release-plz.ieni.dev/docs/config

Use this example to configure release-plz for a Cargo workspace. It shows workspace-level defaults and per-package overrides for packages a, b, and c. The file should be named release-plz.toml or .release-plz.toml and placed in the same directory as the root Cargo.toml.

```toml
[workspace]  

allow_dirty = true # allow updating repositories with uncommitted changes  

changelog_update = false # disable changelog updates  

dependencies_update = true # update dependencies with `cargo update`  

git_release_enable = false # disable GitHub/Gitea releases  

pr_branch_prefix = "release-plz-" # PR branch prefix  

pr_labels = ["release"] # add the `release` label to the release Pull Request  

publish_allow_dirty = true # add `--allow-dirty` to `cargo publish`  

semver_check = false # disable API breaking changes checks  

publish_timeout = "10m" # set a timeout for `cargo publish`  

release_commits = "^feat:" # prepare release only if at least one commit matches a regex  

  

[[package]] # the double square brackets define a TOML table array  

name = "package_a"  

changelog_include = ["package_b"] # include commits from `package_b` in the changelog  

changelog_path = "docs/CHANGELOG.md" # use a custom changelog path for `package_a`  

changelog_update = true # enable changelog update for `package_a`  

git_release_enable = true # enable GitHub/Gitea releases for `package_a`  

publish = false # disable `cargo publish` for `package_a`  

  

[[package]]  

name = "package_b"  

semver_check = true # enable semver_check for `package_b`  

publish_no_verify = true # add `--no-verify` to `cargo publish` for `package_b`  

publish_features = ["a", "b"] # add `--features=a,b` to `cargo publish` for `package_b`  

publish_all_features = true # add `--all-features` to `cargo publish` for `package_b`  

  

[[package]]  

name = "package_c"  

release = false # don't process this package  

  

[changelog]  

protect_breaking_commits = true # always include commits with breaking changes in the changelog  


```

--------------------------------

### Configure [workspace] section in release-plz.toml

Source: https://release-plz.ieni.dev/docs/config

Example of a full [workspace] section in release-plz.toml showing all available fields with comments. Use as a reference for configuring global defaults applied to all packages.

```toml
[workspace]  

allow_dirty = true # allow updating repositories with uncommitted changes  

changelog_config = "config/git-cliff.toml"  

changelog_update = false  

dependencies_update = true # update dependencies with `cargo update`  

git_release_enable = true  

pr_branch_prefix = "feat-pr-" # Release PR branch prefix  

publish_allow_dirty = true  

publish_no_verify = false  

repo_url = "https://github.com/<owner>/<repo>"  

semver_check = false  


```

--------------------------------

### Example JSON output for release-pr

Source: https://release-plz.ieni.dev/docs/usage/release-pr

Example JSON output from release-pr with -o json, showing a single PR with head_branch release-plz-2024-04-03T21-57-37Z, base_branch main, and one release for my_package version 1.0.3.

```json
{  

  "prs": [  

    {  

      "head_branch": "release-plz-2024-04-03T21-57-37Z",  

      "base_branch": "main",  

      "html_url": "http://localhost:3000/zodpwlgr/xcpayeoa/pulls/1",  

      "number": 1,  

      "releases": [  

        {  

          "package_name": "my_package",  

          "version": "1.0.3"  

        }  

      ]  

    }  

  ]  

}  


```

--------------------------------

### Example job with if condition

Source: https://release-plz.ieni.dev/docs/github/quickstart

Shows how to apply the if condition to the release-plz-release job, using 'marco' as the repository owner.

```yaml
jobs:  
  release-plz-release:  
    name: Release-plz release  
    runs-on: ubuntu-latest  
    if: ${{ github.repository_owner == 'marco' }}  

```

--------------------------------

### Configure [changelog] section

Source: https://release-plz.ieni.dev/docs/config

Example configuration for the `[changelog]` section. Shows how to set header, body, trim, protect_breaking_commits, sort_commits, commit_preprocessors, commit_parsers, postprocessors, and link_parsers.

```toml
[changelog]  

header = "# Changelog"  

body = "Body"  

trim = true  

protect_breaking_commits = true  

sort_commits = "newest"  

  

commit_preprocessors = [  

  # remove issue numbers from commits  

  { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "" },  

]  

  

commit_parsers = [  

    { message = "^.*: add", group = "Added" },  

    { message = "^.*: support", group = "Added" },  

    { message = "^.*: remove", group = "Removed" },  

    { message = "^.*: delete", group = "Removed" },  

    { message = "^test", group = "Fixed" },  

    { message = "^fix", group = "Fixed" },  

    { message = "^.*: fix", group = "Fixed" },  

    { message = "^.*", group = "Changed" },  

]  

  

postprocessors = [  

    # Format the rendered changelog using `dprint`  

    { pattern = ".*", replace = "dprint fmt --stdin md" }  

]  

  

link_parsers = [  

    { pattern = "RFC(\\d+)", text = "ietf-rfc$1", href = "https://datatracker.ietf.org/doc/html/rfc$1"}  

]  

```

--------------------------------

### fish completions: current session and persistent setup

Source: https://release-plz.ieni.dev/docs/usage/shell-completion

For fish, load completions in the current session by piping the generated output to source. To persist, write the completion file to the fish completions directory.

```shell
release-plz generate-completions fish | source  

```

```shell
release-plz generate-completions fish > $HOME/.config/fish/completions/release-plz.fish  

```

--------------------------------

### Generated changelog output example

Source: https://release-plz.ieni.dev/docs/changelog/examples

Example output of git-cliff showing a generated changelog with sections for Unreleased, versions 1.0.1 and 1.0.0, and grouped commits by type (Refactor, Miscellaneous Tasks, Features, Bug Fixes, Documentation).

```markdown
# Changelog  

## [Unreleased]  

## [1.0.1](https://github.com/orhun/git-cliff-readme-example/compare/v1.0.0...v1.0.1)  

### 🚜 Refactor  

- refactor(parser): expose string functions ([e4fd3cf](e4fd3cf8e2e6f49c0b57f66416e886c37cbb3715))  

### ⚙️ Miscellaneous Tasks  

- chore(release): add release script ([06412ac](06412ac1dd4071006c465dde6597a21d4367a158))  

## [1.0.0](https://github.com/orhun/git-cliff-readme-example/releases/tag/v1.0.0) - 2021-07-18  

### ⛰️  Features  

- feat(parser): add ability to parse arrays ([a140cef](a140cef0405e0bcbfb5de44ff59e091527d91b38))  

### 🐛 Bug Fixes  

- fix(args): rename help argument due to conflict ([9add0d4](9add0d4616dc95a6ea8b01d5e4d233876b6e5e00))  

### 📚 Documentation  

- docs(project): add README.md ([81fbc63](81fbc6365484abf0b4f4b05d384175763ad8db44))  

- docs(example)!: add tested usage example ([ad27b43](ad27b43e8032671afb4809a1a3ecf12f45c60e0e))  


```

--------------------------------

### Example changelog output with package sections

Source: https://release-plz.ieni.dev/docs/extra/single-changelog

Shows the resulting changelog file when using the custom body template. It includes sections for 'marco-test-two' and 'marco-test-three' with their versions and commit groups.

```markdown
# Changelog  

  

All notable changes to this project will be documented in this file.  

  

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),  

and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).  

  

## [Unreleased]  

  

## `marco-test-two` - [0.4.20](https://github.com/marcoieni/rust-workspace-example/compare/marco-test-two-v0.4.19...marco-test-two-v0.4.20) - 2024-05-17  

  

### Added  

- new feature  

  

## `marco-test-three` - [0.1.16](https://github.com/marcoieni/rust-workspace-example/compare/marco-test-three-v0.1.15...marco-test-three-v0.1.16) - 2024-05-17  

  

### Other  

- Small change  

```

--------------------------------

### zsh completions: current session and persistent setup

Source: https://release-plz.ieni.dev/docs/usage/shell-completion

For zsh, load completions in the current session with bashcompinit and source the generated completions. To persist, generate the completion file and move it to the zsh site-functions directory.

```shell
autoload bashcompinit; bashcompinit  

source <(release-plz generate-completions)  

```

```shell
release-plz generate-completions zsh > _release-plz  

sudo mv _release-plz /usr/local/share/zsh/site-functions/  

```

--------------------------------

### Configure release-plz component stage input

Source: https://release-plz.ieni.dev/docs/gitlab

Configure the release-plz component to run at a custom stage by setting the 'stage' input. This example changes the stage to 'special_deploy_stage'.

```yaml
include:  

  - component: $CI_SERVER_FQDN/release-plz/components/release-plz@0.1.0  

    inputs:  

      stage: "special_deploy_stage"  


```

--------------------------------

### bash completions: current session and persistent setup

Source: https://release-plz.ieni.dev/docs/usage/shell-completion

For bash, load completions in the current session by sourcing the generated output. To persist, write the completion file to the bash-completion directory; the bash-completion package is required.

```shell
source <(release-plz generate-completions)  

```

```shell
release-plz generate-completions bash > ~/.local/share/bash-completion/completions/release-plz  

```

--------------------------------

### Schedule release-plz workflow with cron

Source: https://release-plz.ieni.dev/docs/github/advanced

Use the `schedule` event with a cron expression to trigger the workflow periodically. The example triggers every Monday at midnight UTC.

```yaml
# Trigger the workflow every Monday.  

on:  

  schedule:  

    # * is a special character in YAML so you have to quote this string  

    - cron:  '0 0 * * MON'  


```

--------------------------------

### Override package configuration with [[package]]

Source: https://release-plz.ieni.dev/docs/config

Example configuration for the `[[package]]` section, overriding workspace fields for the `my_package` package. Shows setting changelog path, disabling semver check and changelog update, enabling git release, and setting publish options.

```toml
[[package]]  

name = "my_package"  

changelog_path = "docs/CHANGELOG.md"  

semver_check = false  

changelog_update = false  

git_release_enable = true  

publish = true  

publish_allow_dirty = true  

publish_no_verify = true  

```

--------------------------------

### Include commits from other packages with changelog_include

Source: https://release-plz.ieni.dev/docs/config

Example of the `changelog_include` field in the `[[package]]` section, including commits from another package (`release_plz_core`) in the changelog of the current package.

```toml
changelog_include = ["release_plz_core"]  

```

--------------------------------

### Configure version_group for packages

Source: https://release-plz.ieni.dev/docs/config

Configuration example for the `version_group` field. Two packages `aaa` and `bbb` share the same `version_group` value, so release-plz will assign them the same version (the highest among their next versions).

```toml
[[package]]  

name = "aaa"  

version_group = "group1"  

  

[[package]]  

name = "bbb"  

version_group = "group1"  

```

--------------------------------

### GitHub Actions step with release-plz input variables

Source: https://release-plz.ieni.dev/docs/github/input

Example GitHub Actions workflow step that runs release-plz with the `release-pr` command, a custom registry, a manifest path, a specific version, and `dry_run: true`. It sets `GITHUB_TOKEN` and `CARGO_REGISTRY_TOKEN` environment variables for authentication.

```yaml
steps:  

  - ...  

  - name: Run release-plz  

    uses: release-plz/action@v0.5  

    # Input variables  

    with:  

      command: release-pr  

      registry: my-registry  

      manifest_path: rust-crates/my-crate/Cargo.toml  

      version: 0.3.70  

      dry_run: true  

    env:  

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  

      CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}  
```

--------------------------------

### Rendered changelog output with contributors

Source: https://release-plz.ieni.dev/docs/changelog/examples

Example changelog output generated by the custom template, showing the rendered Markdown with version sections, commit messages, contributor usernames, and links. It demonstrates the expected format for the release-plz changelog with contributor attribution.

```markdown
# Changelog  

  

All notable changes to this project will be documented in this file.  

  

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),  

and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).  

  

## [Unreleased]  

  

## [1.0.1](https://github.com/orhun/git-cliff-readme-example/compare/v1.0.0...v1.0.1) - 2021-07-18  

  

### Added  

  

- Add release script (by @orhun)  

  

### Changed  

  

- Expose string functions (by @orhun)  

  

### Contributors  

  

* @orhun  

  

## [1.0.0](https://github.com/orhun/git-cliff-readme-example/releases/tag/v1.0.0) - 2021-07-18  

  

### Added  

  

- Add README.md (by @orhun)  

- Add ability to parse arrays (by @orhun)  

- Add tested usage example (by @orhun)  

  

### Fixed  

  

- Rename help argument due to conflict (by @orhun)  

  

### Contributors  

  

* @orhun  


```

--------------------------------

### Single-job GitHub Actions workflow for release-plz

Source: https://release-plz.ieni.dev/docs/extra/single-job-workflow

A complete GitHub Actions workflow that runs both `release` and `release-pr` in sequence by omitting the `with: command:` field. Requires `pull-requests: write` and `contents: write` permissions, and sets `GITHUB_TOKEN` and `CARGO_REGISTRY_TOKEN` environment variables. This setup is not recommended; bug reports caused by it won't be investigated.

```yaml
name: Release-plz  

  

permissions:  

  pull-requests: write  

  contents: write  

  

on:  

  push:  

    branches:  

      - main  

  

jobs:  

  

  release-plz:  

    name: Release-plz  

    runs-on: ubuntu-latest  

    steps:  

      - name: Checkout repository  

        uses: actions/checkout@v6  

        with:  

          fetch-depth: 0  

          persist-credentials: false  

      - name: Install Rust toolchain  

        uses: dtolnay/rust-toolchain@stable  

      - name: Run release-plz  

        uses: release-plz/action@v0.5  

        # No `command:` line — both `release` and `release-pr` run in order.  

        env:  

          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  

          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}  


```

--------------------------------

### Parser: group doc commits with default_scope

Source: https://release-plz.ieni.dev/docs/config

Parser that groups commits starting with "doc" as "Documentation" and sets the default scope to "other". For example, "docs: xyz" is processed as "docs(other): xyz".

```toml
{ message = "^doc", group = "Documentation", default_scope = "other" }
```

--------------------------------

### pr_labels example

Source: https://release-plz.ieni.dev/docs/config

Example of adding a label to the release pull request using the pr_labels array. By default, no labels are added.

```toml
[workspace]  

pr_labels = ["release"] # add the `release` label to the release Pull Request  

```

--------------------------------

### Release to Gitea with --forge gitea

Source: https://release-plz.ieni.dev/docs/usage/release

Run release-plz release for a Gitea repository. Requires a Gitea token with 'read:repository' and 'write:repository' permissions.

```bash
release-plz release --forge gitea --git-token <gitea_token>
```

--------------------------------

### Breaking change with BREAKING CHANGE footer

Source: https://release-plz.ieni.dev/docs/changelog/format

Example of a commit that sets the breaking flag to true via a BREAKING CHANGE footer.

```text
feat: add xyz  

BREAKING CHANGE: this is a breaking change  

```

--------------------------------

### Breaking change with exclamation mark

Source: https://release-plz.ieni.dev/docs/changelog/format

Example of a commit that sets the breaking flag to true via an exclamation mark after the type and scope.

```text
feat(scope)!: this is a breaking change  

```

--------------------------------

### Parser: skip refactor(clippy) commits

Source: https://release-plz.ieni.dev/docs/config

Parser that skips commits whose message starts with "refactor(clippy)".

```toml
{ message = "^refactor\\(clippy\\)", skip = true }
```

--------------------------------

### CD workflow to upload Rust binaries on release

Source: https://release-plz.ieni.dev/docs/extra/releasing-binaries

GitHub Actions workflow that runs on the 'release' event (published) and builds/upload Rust binaries for multiple targets using taiki-e/upload-rust-binary-action. Replace 'MyOwner' with your username and 'my-bin-v' with your release name per git_release_name. Requires the release-plz GitHub Action to trigger further workflow runs.

```yaml
name: CD # Continuous Deployment  

on:  
  release:  
    types: [published]  

env:  
  CARGO_INCREMENTAL: 0  
  CARGO_NET_GIT_FETCH_WITH_CLI: true  
  CARGO_NET_RETRY: 10  
  CARGO_TERM_COLOR: always  
  RUST_BACKTRACE: 1  
  RUSTFLAGS: -D warnings  
  RUSTUP_MAX_RETRIES: 10  

defaults:  
  run:  
    shell: bash  

jobs:  
  upload-assets:  
    name: ${{ matrix.target }}  
    if: github.repository_owner == 'MyOwner' && startsWith(github.event.release.name, 'my-bin-v')  
    runs-on: ${{ matrix.os }}  
    permissions:  
      contents: write  
    strategy:  
      matrix:  
        include:  
          - target: aarch64-unknown-linux-gnu  
            os: ubuntu-22.04  
          - target: aarch64-unknown-linux-musl  
            os: ubuntu-22.04  
          - target: aarch64-apple-darwin  
            os: macos-14  
          - target: aarch64-pc-windows-msvc  
            os: windows-2022  
          - target: x86_64-unknown-linux-gnu  
            os: ubuntu-22.04  
          - target: x86_64-unknown-linux-musl  
            os: ubuntu-22.04  
          - target: x86_64-pc-windows-msvc  
            os: windows-2022  
          - target: x86_64-unknown-freebsd  
            os: ubuntu-22.04  
    timeout-minutes: 60  
    steps:  
      - name: Checkout repository  
        uses: actions/checkout@v6  
        with:  
          persist-credentials: false  
      - name: Install Rust toolchain  
        uses: dtolnay/rust-toolchain@stable  
      - uses: taiki-e/setup-cross-toolchain-action@v1  
        with:  
          target: ${{ matrix.target }}  
        if: startsWith(matrix.os, 'ubuntu') && !contains(matrix.target, '-musl')  
      - uses: taiki-e/install-action@v2  
        with:  
          tool: cross  
        if: contains(matrix.target, '-musl')  
      - run: echo "RUSTFLAGS=${RUSTFLAGS} -C target-feature=+crt-static" >> "${GITHUB_ENV}"  
        if: endsWith(matrix.target, 'windows-msvc')  
      - uses: taiki-e/upload-rust-binary-action@v1  
        with:  
          bin: my-bin  
          target: ${{ matrix.target }}  
          tar: all  
          zip: windows  
          token: ${{ secrets.GITHUB_TOKEN }}  
```

--------------------------------

### Release to GitLab with --forge gitlab

Source: https://release-plz.ieni.dev/docs/usage/release

Run release-plz release for a GitLab repository. Requires a GitLab token with Maintainer role or higher and scopes 'api' and 'write_repository'.

```bash
release-plz release --forge gitlab --git-token <gitlab_token>
```

--------------------------------

### Read commit with $COMMIT_SHA in replace_command

Source: https://release-plz.ieni.dev/docs/config

Reads the commit message itself using the `$COMMIT_SHA` environment variable, which is set when executing the command. This example runs `git show` to retrieve the full commit body.

```toml
{ pattern = '.*', replace_command = 'git show -s --format=%B $COMMIT_SHA' }
```

--------------------------------

### List packaged files with cargo package --list

Source: https://release-plz.ieni.dev/docs/faq

Lists the files that cargo would include in the package. Use this to see which files are packaged and thus trigger release PRs and release-plz update changes.

```bash
cargo package --list
```

--------------------------------

### Run release-pr with Gitea forge

Source: https://release-plz.ieni.dev/docs/usage/release-pr

Run release-pr for a Gitea repository. The token needs read:repository, write:repository, read:issue, and write:issue permissions.

```bash
release-plz release-pr --git-token <gitea application token> --forge gitea
```

--------------------------------

### Custom pr_name Tera template

Source: https://release-plz.ieni.dev/docs/config

Example of customizing the PR name template using Tera. The template checks if 'package' and 'version' variables are set to avoid failures in workspaces with multiple public packages.

```toml
[workspace]  

pr_name = "release{% if package and version %} {{ package }} v{{ version }}{% endif %}"  

```
Tokens:
Raw