releez

releez is a CLI tool for managing semantic versioned releases. It automates version bumping, changelog generation, release PRs, and git tags — powered by git-cliff under the hood.

Full documentation at hotdog-werx.github.io/releez

uv tool install releez

Commands

releez release start           # bump version, update changelog, open PR
releez release preview         # print what would be released
releez release notes           # print unreleased changelog section
releez release tag             # create git tags after merging the release PR
releez version artifact        # compute semver/docker/pep440 versions for CI
releez changelog regenerate    # rebuild the full CHANGELOG from git history

Common flags: --bump auto|patch|minor|major, --base <branch>, --dry-run, --alias-versions none|major|minor.

For monorepo projects, add --project <name> (repeatable) or --all.

Monorepo support

Configure multiple independently-versioned projects in your root pyproject.toml:

[tool.releez]
base-branch = "main"

[[tool.releez.projects]]
name = "core"
path = "packages/core"
tag-prefix = "core-"
changelog-path = "CHANGELOG.md"

[[tool.releez.projects]]
name = "ui"
path = "packages/ui"
tag-prefix = "ui-"
changelog-path = "CHANGELOG.md"

Each project gets its own changelog, release branch, PR, and tags (e.g. core-1.2.3, core-v1). releez auto-detects which projects have unreleased changes.

See the Monorepo Setup Guide for full configuration, change detection, uv workspace integration, and CI patterns.

Support branches

Support branches are long-lived maintenance lines for shipping hotfixes or backported features on older majors (e.g. support/1.x while 2.x development continues on the default branch).

Create a support branch with:

releez release support-branch 1            # single-repo → support/1.x
releez release support-branch 1 --project ui  # monorepo  → support/ui-1.x

Release from a support branch with the normal releez release start command — Releez detects the branch automatically and scopes versioning to the correct major line.

See the Support Branches guide for full details including --commit overrides, custom naming, and monorepo configuration.

Configuration

Precedence (highest first): CLI flags → RELEEZ_* env vars → releez.toml → pyproject.toml ([tool.releez]).

[tool.releez]
base-branch = "master"
git-remote = "origin"
alias-versions = "minor"

[tool.releez.hooks]
post-changelog = [
  ["uv", "version", "{version}"], # {version} = bare semver
  ["prettier", "--write", "{changelog}"],
]

Hooks run automatically after the changelog is updated. Template variables: {version} (bare semver), {project_version} (full tagged version, e.g. core-1.2.3), {changelog} (absolute path).

See the Settings reference and Hooks documentation for details.

GitHub Action

releez ships a composite GitHub Action. Pin it by tag — the matching CLI version is installed automatically.

Modes

Validate a release PR

- uses: hotdog-werx/releez@v0
  with:
    mode: validate
    post-comment: 'true'

Finalize and create a GitHub Release

- id: releez
  uses: hotdog-werx/releez@v0
  with:
    mode: finalize
    alias-versions: major

- uses: softprops/action-gh-release@v2
  with:
    tag_name: ${{ steps.releez.outputs.release-version }}
    body: ${{ steps.releez.outputs.release-notes }}

Artifact versions for a Docker build

- id: version
  uses: hotdog-werx/releez@v0
  with:
    mode: version-artifact
    is-full-release: ${{ github.event_name != 'pull_request' }}
    prerelease-number: ${{ github.event.pull_request.number }}

Key outputs: release-version, semver-versions, docker-versions, pep440-versions, semver-version, docker-version, pep440-version (singular = exact version only, no aliases), release-notes, project (monorepo).

For the full input/output reference and workflow recipes see the Action Reference and Workflow Recipes.

GitHub recommendations

Prefer squash merging with "Pull request title" as the default commit message. This keeps your history aligned with semantic PR titles and works well with amannn/action-semantic-pull-request and git-cliff changelog generation.