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. For automation needing structured start outputs, pass --result-file <path> to releez release start to write one release result as JSON; use a single project when doing so.

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'

Start a release from a workflow

- uses: actions/checkout@v6
  with:
    fetch-depth: 0
    fetch-tags: true
- run: |
    git config user.name 'github-actions[bot]'
    git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
- id: releez
  uses: hotdog-werx/releez@v0
  with:
    mode: start
    project: core # omit for single-package repos

The job needs contents: write and pull-requests: write. The action uses github-token for git-cliff and PR creation; the checkout credential is used to push. For a custom token, pass it to both the checkout and the action. Install any tools required by configured post-changelog hooks before this step. release-branch and pull-request-url outputs are available when created. With dry-run: 'true', the release preview appears in the job summary.

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), and start-mode release-branch / pull-request-url.

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.