### 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
```

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

### 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  


```

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

### 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
```

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

### 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  

```

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

### 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  

```

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

### 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 }}  


```

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

### 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  

```

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

### Configure commit_preprocessors with regex replacements

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

Defines commit preprocessors that manipulate commit messages before parsing/grouping. Each entry uses a regex `pattern` and a `replace` string; examples cover replacing text, removing prefixes, stripping gitmoji, and hyperlinking PRs/commits.

```toml
commit_preprocessors = [  

  # Replace `foo` with `bar`  

  { pattern = "foo", replace = "bar" },  

  

  # Replace `<REPO>` in the template body with the repository URL  

  { pattern = '<REPO>', replace = "https://github.com/me/my-proj" },  

  

  # Replace multiple spaces with a single space.  

  { pattern = "  +", replace = " "}  

  

  # Replace the issue number with the link. `\(` is used to escape the `(` character.  

  # ${1} contains the issue number.  

  { pattern = "\(#([0-9]+)\)", replace = "([#${1}](https://github.com/me/my-proj/issues/${1}))"}  

  

  # Replace the issue link with the number.  

  { pattern = "https://github.com/[^ ]/issues/([0-9]+)", replace = "[Issue #${1}]"}  

  

  # Remove prefix  

  { pattern = 'Merged PR #[0-9]: (.*)', replace = "$1"}  

  

  # Remove gitmoji from commit messages, both actual UTF emoji and :emoji:  

  { pattern = ' *(:\w+:|[\p{Emoji_Presentation}\p{Extended_Pictographic}\u{200D}]) *', replace = "" },  

  

  # Hyperlink PR references from merge commits.  

  { pattern = "Merge pull request #([0-9]+) from [^ ]+", replace = "PR # [${1}](https://github.com/me/my-proj/pull/${1}):"}  

  

  # Hyperlink commit links, with short commit hash as description.  

  { pattern = "https://github.com/orhun/git-cliff/commit/([a-f0-9]{7})[a-f0-9]*", replace = "commit # [${1}](${0})"}  

  

  # Hyperlink bare commit hashes like "abcd1234" in commit logs, with short commit hash as description.  

  { pattern = "([ \n])(([a-f0-9]{7})[a-f0-9]*)", replace = "${1}commit # [${3}](https://github.com/me/my-proj/commit/${2})"}  

]  

```

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

### JSON output of release-plz release -o json

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

Output of `release-plz release -o json` showing the schema and an example. The `releases` array is empty if no packages were released. The `tag` field is always present, even when tag creation is disabled via `git_tag_enable`. `prs` lists PRs from the changelog body, each with `html_url` and `number`.

```json
{
  "releases": [
    {
      "package_name": "<package_name>",
      "prs": "<prs>",
      "tag": "<tag_name>",
      "version": "<version>"
    }
  ]
}
```

```json
{
  "releases": [
    {
      "package_name": "my_crate",
      "prs": [
        {
          "html_url": "https://github.com/user/proj/pull/1439",
          "number": 1439
        }
      ],
      "tag": "v0.1.0",
      "version": "0.1.0"
    }
  ]
}
```

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

### Close old release PRs before running release-plz

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

Closes any open release PRs whose head branch starts with 'release-plz-' before running release-plz with the `release-pr` command. This forces release-plz to open new PRs instead of updating existing ones.

```yaml
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@v6  

        with:  

          fetch-depth: 0  

          persist-credentials: false  

      - name: Install Rust toolchain  

        uses: dtolnay/rust-toolchain@stable  

      - name: Close old release PR  

        env:  

          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  

        run: |  

          # List all opened PRs which head branch starts with "release-plz-"  

          release_pr=$(gh pr list --state='open' --json number,headRefName --jq '.[] | select(.headRefName | startswith("release-plz-")) | .number')  

          # Close the release PR if there is one  

          if [[ -n "$release_pr" ]]; then  

            echo "Closing old release PR $release_pr"  

            gh pr close $release_pr  

          else  

            echo "No open release PR"  

          fi  

      - name: Run release-plz PR  

        uses: release-plz/action@v0.5  

        with:  

          command: release-pr  

        env:  

          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  

          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}  


```

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

### Set custom_minor_increment_regex in [workspace]

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

Example of setting custom_minor_increment_regex in the [workspace] section. With this pattern, commits like 'minor: add feature', 'enhancement: new capability', or '🎉: exciting change' trigger a minor version bump instead of a patch bump.

```toml
[workspace]  

custom_minor_increment_regex = "^minor|^enhancement|^🎉"  


```

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

### 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" }
```

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

### 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 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 %}"  

```

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

### Custom pr_body Tera template

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

Example of customizing the PR body template using Tera. It iterates over releases and conditionally includes title and changelog. Note that 'release.title' and 'release.changelog' may be unset, so use '{% if %}' checks.

```toml
[workspace]  

pr_body = """  

{% for release in releases %}  

{% if release.title %}  

### {{release.title}}  

{% endif %}  

Package: {{release.package}} {{release.previous_version}} -> {{release.next_version}}  

{% if release.changelog %}  

Changes:  

{{release.changelog}}  

{% endif %}  

{% endfor -%}  

"""  

```

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

### Configure log level with RELEASE_PLZ_LOG

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

Set the RELEASE_PLZ_LOG environment variable to configure the log level. Use DEBUG or TRACE for more detailed logs.

```bash
RELEASE_PLZ_LOG=DEBUG release-plz  

RELEASE_PLZ_LOG=TRACE release-plz  
```

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

### Configure postprocessors to format changelog

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

Defines a postprocessor that runs `dprint fmt --stdin md` on the rendered changelog to enforce formatting. Postprocessors use the same syntax as commit preprocessors.

```toml
postprocessors = [  

    # Format the rendered changelog using `dprint`  

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

]  

```

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

### Complete release-plz workflow (release-plz.yml)

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

The main workflow file to copy into .github/workflows/release-plz.yml. It defines two jobs: release-plz-release (runs 'release-plz release') and release-plz-pr (runs 'release-plz release-pr'). Requires GITHUB_TOKEN and CARGO_REGISTRY_TOKEN secrets.

```yaml
name: Release-plz  

  
on:  
  push:  
    branches:  
      - main  
  
jobs:  
  
  # Release unpublished packages.  
  release-plz-release:  
    name: Release-plz release  
    runs-on: ubuntu-latest  
    permissions:  
      contents: write  
      pull-requests: read  
    steps:  
      - &checkout  
        name: Checkout repository  
        uses: actions/checkout@v6  
        with:  
          fetch-depth: 0  
          persist-credentials: false  
      - &install-rust  
        name: Install Rust toolchain  
        uses: dtolnay/rust-toolchain@stable  
      - name: Run release-plz  
        uses: release-plz/action@v0.5  
        with:  
          command: release  
        env:  
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}  
  
  # Create a PR with the new versions and changelog, preparing the next release.  
  release-plz-pr:  
    name: Release-plz PR  
    runs-on: ubuntu-latest  
    permissions:  
      contents: write  
      pull-requests: write  
    concurrency:  
      group: release-plz-${{ github.ref }}  
      cancel-in-progress: false  
    steps:  
      - *checkout  
      - *install-rust  
      - name: Run release-plz  
        uses: release-plz/action@v0.5  
        with:  
          command: release-pr  
        env:  
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}  

```

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

### Configure release-plz for external Git submodules

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

Enable recursive cloning of submodules hosted on a different forge (e.g., GitHub) and provide credentials in the .git-credentials format. Required only when submodules are hosted outside GitLab.

```yaml
include:  

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

    inputs:  

      git_submodule_recursive: true  

      git_credentials: ["https://${GH_USERNAME}:${GH_TOKEN}@github.com"]  


```

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

### GitHub Actions workflow for release-plz with output reading

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

This YAML workflow defines two jobs: 'release-plz-release' and 'release-plz-pr'. The first job runs the release command and reads the 'releases' and 'releases_created' outputs. The second job runs the release-pr command and reads the 'prs', 'pr', and 'prs_created' outputs. The workflow uses jq to parse the JSON outputs and demonstrates how to access specific fields. It requires the GITHUB_TOKEN and CARGO_REGISTRY_TOKEN secrets.

```yaml
jobs:  

  release-plz-release:  
    name: Release-plz release  
    runs-on: ubuntu-latest  
    permissions:  
      contents: write  
    steps:  
      - &checkout  
        name: Checkout repository  
        uses: actions/checkout@v6  
        with:  
          fetch-depth: 0  
          persist-credentials: false  
      - &install-rust  
        name: Install Rust toolchain  
        uses: dtolnay/rust-toolchain@stable  
      - name: Run release-plz  
        id: release-plz # <--- ID used to refer to the outputs. Don't forget it.  
        uses: release-plz/action@v0.5  
        with:  
          command: release  
        env:  
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}  
      - name: Read release output  
        env:  
          RELEASES: ${{ steps.release-plz.outputs.releases }}  
          RELEASES_CREATED: ${{ steps.release-plz.outputs.releases_created }}  
        run: |  
          set -e  
          echo "releases: $RELEASES" # example: [{"package_name":"my-package","prs":[{"html_url":"https://github.com/user/proj/pull/1439","number":1439}],"tag":"v0.1.0","version":"0.1.0"}]  
          echo "releases_created: $RELEASES_CREATED" # example: true  

          # get the number of releases with jq  
          releases_length=$(echo "$RELEASES" | jq 'length')  
          echo "releases_length: $releases_length"  

          # access the first release with jq  
          release_version=$(echo "$RELEASES" | jq -r '.[0].version')  
          echo "release_version: $release_version"  

          # access the first release with fromJSON. Docs: https://docs.github.com/en/actions/learn-github-actions/expressions  
          echo "release_version: ${{ fromJSON(steps.release-plz.outputs.releases)[0].version }}"  

          release_tag=$(echo "$RELEASES" | jq -r '.[0].tag')  
          echo "release_tag: $release_tag"  

          release_package_name=$(echo "$RELEASES" | jq -r '.[0].package_name')  
          echo "release_package_name: $release_package_name"  

          # print all names of released packages, one per line  
          echo "package_names: $(echo "$RELEASES" | jq -r '.[].package_name')"  
          # TODO: show how to store this in a variable and iterate over it (maybe an array?). PR welcome!  

          # iterate over released packages  
          for package_name in $(echo "$RELEASES" | jq -r '.[].package_name'); do  
              echo "released $package_name"  
          done  

  release-plz-pr:  
    name: Release-plz PR  
    runs-on: ubuntu-latest  
    permissions:  
      contents: write  
      pull-requests: write  
    concurrency:  
      group: release-plz-${{ github.ref }}  
      cancel-in-progress: false  
    steps:  
      - *checkout  
      - *install-rust  
      - name: Run release-plz  
        id: release-plz # <--- ID used to refer to the outputs. Don't forget it.  
        uses: release-plz/action@v0.5  
        with:  
          command: release-pr  
        env:  
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}  
      - name: Read release-pr output  
        env:  
          PRS: ${{ steps.release-plz.outputs.prs }}  
          PR: ${{ steps.release-plz.outputs.pr }}  
          PRS_CREATED: ${{ steps.release-plz.outputs.prs_created }}  
        run: |  
          set -e  
          echo "prs: $PRS" # example: [{"base_branch":"main","head_branch":"release-plz-2024-05-01T20-38-05Z","html_url":"https://github.com/MarcoIeni/rust-workspace-example/pull/198","number":198, "releases":[{"package_name":"my-package","version":"0.1.0"}]}]  
          echo "pr: $PR" # example: {"base_branch":"main","head_branch":"release-plz-2024-05-01T20-38-05Z","html_url":"https://github.com/MarcoIeni/rust-workspace-example/pull/198","number":198}  
          echo "prs_created: $PRS_CREATED" # example: true  

          echo "pr_number: ${{ fromJSON(steps.release-plz.outputs.pr).number }}"  
          echo "pr_html_url: ${{ fromJSON(steps.release-plz.outputs.pr).html_url }}"  
          echo "pr_head_branch: ${{ fromJSON(steps.release-plz.outputs.pr).head_branch }}"  
          echo "pr_base_branch: ${{ fromJSON(steps.release-plz.outputs.pr).base_branch }}"  

```

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

### Run release-pr with GitLab forge

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

Run release-pr for a GitLab repository. Requires a token with Maintainer role and api and write_repository scopes.

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

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

### Configure single git tag in release-plz.toml

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

Use this `release-plz.toml` configuration to create a single git tag for all crates in a workspace. It disables git releases and tags for all packages by default, then enables them for `my_main_package`, optionally customizing the tag name to remove the package prefix. With this configuration, release-plz only creates the git tag when releasing `my_main_package`.

```toml
[workspace]  

# Disable git releases for all packages by default  

git_release_enable = false  

  

# Disable git tags for all packages by default  

git_tag_enable = false  

  

# Options for the package I care the most, e.g. `my_main_package`.  

[[package]]  

name = "my_main_package"  

# (Optional) Customize the git tag name to remove the `my_main_package` prefix.  

git_tag_name = "v{{ version }}"  

  

# Enable git tags for this package  

git_tag_enable = true  

  

# Enable git releases for this package  

git_release_enable = true  



```

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

### Add release labels to PRs with release-plz GitHub Action

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

GitHub Actions workflow that runs release-plz and then adds a label to the PRs that were included in each release. The workflow uses the `release-plz` action with `command: release` and reads the `releases` output to iterate over released packages and their PRs. It creates a label named `released:<package_name>-<version>` and adds it to each PR using `gh pr edit`. Ensure the GitHub token has permission for the operations.

```yaml
jobs:  

  release-plz-pr:  

    runs-on: ubuntu-latest  

    permissions:  

      pull-requests: write  

      contents: write  

    concurrency:  

      group: release-plz-${{ github.ref }}  

      cancel-in-progress: false  

    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  

        id: release-plz # <--- ID used to refer to the outputs. Don't forget it.  

        uses: release-plz/action@v0.5  

        with:  

          command: release  

        env:  

          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  

          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}  

      - name: Tag released PRs  

        env:  

          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  

          RELEASES: ${{ steps.release-plz.outputs.releases }}  

        run: |  

          set -e  

  

          # Iterate over released packages and add a label to the PRs  

          # shipped with the release.  

          for release in $(echo "$RELEASES" | jq -r -c '.[]'); do  

              package_name=$(echo "$release" | jq -r '.package_name')  

              version=$(echo "$release" | jq -r '.version')  

              prs_length=$(echo "$release" | jq '.prs | length')  

              if [ "$prs_length" -gt 0 ]; then  

                  # Create label.  

                  # Use `--force` to overwrite the label,  

                  # so that the command does not fail if the label already exists.  

                  label="released:$package_name-$version"  

                  echo "Creating label $label"  

                  gh label create $label --color BFD4F2 --force  

                  for pr in $(echo "$release" | jq -r -c '.prs[]'); do  

                      pr_number=$(echo "$pr" | jq -r '.number')  

                      echo "Adding label $label to PR #$pr_number"  

                      gh pr edit $pr_number --add-label $label  

                  done  

              else  

                  echo "No PRs found for package $package_name"  

              fi  

          done  
```

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

### Set version for a specific package in a workspace

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

In a workspace, specify a version with the syntax `<package_name>@<version>`. You can also set multiple versions, separated by space.

```bash
release-plz set-version my_crate@1.2.3
```

```bash
release-plz set-version crate1@1.2.3 crate2@2.0.0
```

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

### Customize changelog path per package

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

Sets a default changelog path for all packages and overrides it for 'package_b' to use its own changelog file.

```toml
[workspace]  

changelog_path = "./CHANGELOG.md"  

  

[[package]]  

name = "package_b"  

changelog_path = "package_b/CHANGELOG.md"  

```

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

### Include release-plz component in .gitlab-ci.yml

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

Add the release-plz component to your GitLab CI/CD pipeline. The component is referenced by its fully qualified name and version, and must be included in your .gitlab-ci.yml file.

```yaml
include:  

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


```