Skip to content
repo-release-tools
GitHub

rrt Version & Release

rrt Version & Release

Section titled “rrt Version & Release”

rrt bump

Section titled “rrt bump”

Bump a release version and prepare the associated release branch.

Overview

Section titled “Overview”

This command reads the active [tool.rrt] configuration, computes a new version, updates configured files, and creates the release branch named by the selected version group.

The bump value may be one of:

  • major, minor, or patch to increment the current version
  • alpha, beta, or rc to start or advance a pre-release channel
  • release to drop the pre-release suffix, or pre-release to advance it
  • calver to move to today’s calendar version
  • an explicit version string such as 2.1.0

Pre-release base

Section titled “Pre-release base”

Starting alpha, beta or rc from a final version targets the next patch by default. So rrt bump rc turns 1.0.0 into 1.0.1-rc.1.

--base LEVEL picks another core for one run. minor gives 1.1.0-rc.1 and major gives 2.0.0-rc.1. The flag overrides the prerelease_base key under [tool.rrt] or the version group. The MCP rrt_bump tool takes the same values as base, with the same default.

auto reads the Conventional Commits since the group’s last final tag. A breaking change means major, a feat means minor, anything else means patch. Later pre-release tags never move that range. changelog_paths and extra_commit_types apply as they do for changelog generation.

The base is ignored once the version is already a pre-release. So 1.0.1-rc.1 bumps to 1.0.1-rc.2, whatever --base says.

Version scheme

Section titled “Version scheme”

The version_scheme key names the grammar a group’s version follows. It takes semver, pep440 or calver, globally or per version group.

Left unset, the scheme is inferred from the primary target. A calendar-shaped version such as 2026.05.15 means calver. Otherwise a pep621 or python_version target means pep440, and any other target means semver.

--scheme SCHEME overrides the config for one run. The MCP rrt_bump tool takes the same values as scheme, with the same default. An unknown value in config is a config error, so rrt bump exits 1.

A calver scheme only accepts the calver bump kind or an explicit calendar version; major, rc, dev and the other keyword kinds are refused with a clear error, since they have no meaning for a calendar version.

What the command updates

Section titled “What the command updates”

Depending on the selected version group, the command can update:

  • version targets defined in [[tool.rrt.version_targets]]
  • dependency or documentation pins configured for the group
  • the changelog file
  • lockfiles, when the group defines a lock command

Release workflow

Section titled “Release workflow”
  1. Load the repository config from [tool.rrt].
  2. Resolve the selected version group.
  3. Compute the new version from the current group version or the explicit <bump> value.
  4. Update version targets and optional pin targets.
  5. Update the changelog unless --no-changelog is set.
  6. Run the configured lock and generated-asset commands unless --no-update is set.
  7. Create the release branch and stage or commit the resulting changes.

Changelog behavior

Section titled “Changelog behavior”

The changelog update logic supports three modes:

  • auto - promote [Unreleased] when it has entries, otherwise generate a new section from git history
  • promote - require a non-empty [Unreleased] section and rename it to the new version heading
  • generate - always generate a fresh section from the commit log

When an empty [Unreleased] placeholder exists, generated content is kept below it so the placeholder stays at the top of the file.

Safety notes

Section titled “Safety notes”
  • The working tree must be clean unless --dry-run is used.
  • Existing release branches are refused unless --force is set.
  • An explicit <bump> version that is not strictly newer than the current one (RRT-VER-1 I5) is refused unless --force is set – --force also allows this downgrade or no-op bump, alongside its existing release-branch-reset meaning. A keyword kind (major, rc, dev, …) always computes a strictly newer version on its own, so this check never applies to one.
  • --no-commit leaves the branch created with staged changes only.
  • --dry-run previews the planned file edits and git actions without writing to disk.

Examples

Section titled “Examples”
  • rrt bump patch
  • rrt bump minor --dry-run
  • rrt bump 2.1.0 --no-changelog --no-commit
  • rrt bump major --base-branch develop
  • rrt bump rc --dry-run
  • rrt bump rc --base minor --dry-run
  • rrt bump beta --base auto
  • rrt bump calver --scheme calver --dry-run

Version target configuration reference

Section titled “Version target configuration reference”

kind='pattern' targets

Section titled “kind='pattern' targets”

When a version string lives outside a well-known format (pep621, cargo_toml, package_json, etc.), use kind='pattern' with a single-capture-group regex. The captured group is exactly the version string — no prefix or suffix groups needed.

[[tool.rrt.version_targets]]
path = "src/myapp/__init__.py"
kind = "pattern"
pattern = '^VERSION = "([^"]+)"$'

Rules:

  • pattern must compile as a valid Python regex.
  • The regex must contain exactly 1 capture group whose match is the version string itself.
  • kind='pattern' is mutually exclusive with section, field, and all other kind values.
  • The pattern is applied with re.MULTILINE; use ^ / $ anchors for line-level matching.

kind='pattern' differs from the legacy bare-pattern approach (no kind), which requires 3 groups — (prefix)(version)(suffix). The kind='pattern' form is preferred for new targets because the regex is shorter and group intent is unambiguous:

# Legacy 3-group pattern — still supported
[[tool.rrt.version_targets]]
path = "docs/conf.py"
pattern = '^(release = ")([^"]+)(")$'


# Preferred: kind='pattern' with 1 capture group
[[tool.rrt.version_targets]]
path = "docs/conf.py"
kind = "pattern"
pattern = '^release = "([^"]+)"$'

pin_target_missing

Section titled “pin_target_missing”

Controls what happens when a [[tool.rrt.pin_targets]] entry pattern finds no matches in the target file:

Value Behavior
"error" (default) rrt bump fails if any pin target has zero matches
"warn" rrt bump prints a warning and continues

Set in [tool.rrt]:

[tool.rrt]
pin_target_missing = "warn"

Use "warn" during a migration where some pin files may not yet contain the expected pattern, or when a pin target is intentionally optional.

pin_target_missing applies to rrt bump only; rrt release check always reports missing pin target matches as warnings regardless of this setting.

prerelease_base

Section titled “prerelease_base”

Picks the core an alpha, beta or rc bump targets when the current version is final:

Value 1.0.0 + rc Behavior
"patch" (default) 1.0.1-rc.1 Next patch, like npm and Poetry
"minor" 1.1.0-rc.1 Next minor
"major" 2.0.0-rc.1 Next major
"auto" any of the above Level from Conventional Commits since the last final tag

auto scans the commits after the group’s last final tag. A breaking change means major, a feat means minor, and anything else means patch. Pre-release tags such as v1.0.1-rc.1 never move that range.

[tool.rrt]
prerelease_base = "minor"


[[tool.rrt.version_groups]]
name = "sdk"
prerelease_base = "auto"   # this group's own value wins over the global one

Override it for one run on either surface. Both take the same values and share the same default:

Terminal window
rrt bump rc --base major           # CLI: 1.0.0 -> 2.0.0-rc.1
rrt_bump(level="rc", base="major")  # MCP: same result as the CLI

The base only applies when a channel starts from a final version. Inside a channel the core stays put: 1.0.1-rc.1 bumps to 1.0.1-rc.2. Switching channel keeps it too, so 1.0.1-beta.2 bumps to 1.0.1-rc.1.

version_scheme

Section titled “version_scheme”

Names the grammar a group’s version is read, bumped and written in:

Value Example Grammar
"semver" 1.2.3-rc.1 Semantic Versioning 2.0
"pep440" 1.2.3rc1 Python PEP 440 spellings
"calver" 2026.05.15 Calendar versions (YYYY.MM, YYYY.MM.DD, YYYY.M.D)

There is no default. When the key is unset, the scheme is inferred from the group’s primary target:

  1. A calendar-shaped version, such as 2026.05.15, means calver.
  2. Otherwise a pep621 or python_version target means pep440.
  3. Any other target means semver.
[tool.rrt]
version_scheme = "pep440"


[[tool.rrt.version_groups]]
name = "web"
version_scheme = "semver"   # this group's own value wins over the global one

Any other value, including a different case such as "SemVer", is a config error. Override it for one run on either surface, with the same values:

Terminal window
rrt bump patch --scheme pep440     # CLI
rrt_bump(level="patch", scheme="pep440")  # MCP: same values as the CLI

version_groups — per-component versioning

Section titled “version_groups — per-component versioning”

version_groups lets a single repository maintain multiple independently released components, each with its own version, changelog, and release branch.

[[tool.rrt.version_groups]]
name = "backend"
release_branch = "release/backend/v{version}"
changelog_file = "backend/CHANGELOG.md"


  [[tool.rrt.version_groups.version_targets]]
  path = "backend/pyproject.toml"
  kind = "pep621"


[[tool.rrt.version_groups]]
name = "sdk"
release_branch = "release/sdk/v{version}"
changelog_file = "sdk/CHANGELOG.md"
tag_prefix = "sdk-v"
changelog_paths = ["sdk/"]


  [[tool.rrt.version_groups.version_targets]]
  path = "sdk/package.json"
  kind = "package_json"

Each group supports: release_branch, changelog_file, changelog_workflow, tag_prefix, prerelease_base, version_scheme, changelog_paths, lock_command, generated_files, version_targets, and pin_targets.

prerelease_base (default "patch") picks the core an alpha, beta or rc bump targets from a final version; see prerelease_base above. A group’s own value wins over the [tool.rrt] one.

version_scheme (no default) names the group’s version grammar: semver, pep440 or calver. Unset, it is inferred from the group’s primary target; see version_scheme above. A group’s own value wins over the [tool.rrt] one.

tag_prefix (default "v") names the group’s release tags. It is the default for rrt tag create --prefix / rrt tag check --prefix, and it is what anchors a generated changelog section to the group’s own latest tag — without it, a repository holding both v* and sdk-v* tags would start every group’s range at whichever tag sorts first overall. A {group} token in the prefix renders to the group name, so "{group}-v" means sdk-v here. The latest tag is chosen by version precedence: v1.0.0 outranks v1.0.0-rc.2, and non-version tags such as vnext are ignored.

changelog_paths optionally restricts generated entries to commits touching the group’s own files, so one group’s section cannot pick up another’s work.

Bump a specific group:

Terminal window
rrt bump minor --group backend
rrt bump patch --group sdk

Bump several groups in one invocation with a comma-separated list – each group gets its own release branch and commit, identical to running the command once per group:

Terminal window
rrt bump patch --group backend,sdk

When a single group is configured, --group is optional. With multiple groups, set default_group_name to select the default:

[tool.rrt]
default_group_name = "backend"

Caveats

Section titled “Caveats”

A kind='pattern' regex must have exactly one capture group. The legacy bare-pattern form still works but needs three groups instead, and the two styles cannot be mixed on the same target.

pin_target_missing only changes rrt bump behavior. rrt release check always reports a missing pin match as a warning, regardless of this setting.

--base is now a flag of its own that sets the pre-release base. It no longer abbreviates --base-branch, so spell out --base-branch to pick the branch. An auto base reads git history, so it needs the group’s release tags locally.

With more than one version_group configured, --group becomes required unless default_group_name names a default. Bumping several groups in one invocation still creates one release branch and one commit per group.

Section titled “Related docs”
Usage:  rrt bump [OPTIONS] <bump>


Bump project version using [tool.rrt] config.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  <bump>                  major | minor | patch | release | alpha | beta | rc | pre-release | calver | <version>  — bump kind or explicit version


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help              Show this message and exit.
  --calver-scheme SCHEME  CalVer scheme to use when bump=calver (YYYY.MM | YYYY.MM.DD | YYYY.M.D).


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Pre-release
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  --base LEVEL            Core level for starting alpha|beta|rc from a final version (patch | minor | major | auto). Overrides [tool.rrt] prerelease_base.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Version scheme
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  --scheme SCHEME         Version grammar to read, bump and write in (semver | pep440 | calver). Overrides [tool.rrt] version_scheme.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Release control
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  --dry-run               Preview without writing to disk.
  --force                 Reset the release branch if it already exists, and allow an explicit <bump> version that is not strictly newer than the current one.
  --no-commit             Skip the git commit step.
  --no-verify             Pass --no-verify to git commit (bypass pre-commit hooks).


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Content
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  --no-changelog          Do not update the changelog file.
  --no-pin-sync           Skip dependency pin synchronisation.
  --no-update             Skip lockfile and generated-asset refresh steps.
  --include-maintenance   Include maintenance commits in changelog.
  --changelog-mode MODE   How to write changelog entries (auto | promote | generate).


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Git
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  --base-branch BRANCH    Branch to base the release on.
  --group GROUP           Version group to bump when multiple groups are configured. Pass a comma-separated list (e.g. 'a,b,c') to bump several groups in one invocation, each with its own release branch and commit.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt bump patch
  $ rrt bump minor --dry-run
  $ rrt bump 2.1.0 --no-changelog --no-commit
  $ rrt bump major --base-branch develop
  $ rrt bump release --dry-run
  $ rrt bump rc --base minor --dry-run
  $ rrt bump patch --group self-assess,cupertino,confab

rrt changelog

Section titled “rrt changelog”

Changelog management command group (compare, lint).

Overview

Section titled “Overview”

rrt changelog provides a unified entrypoint for auditing and validating the project’s changelog file. It centralizes utilities for diffing release sections and enforcing stylistic consistency across entries, ensuring that the human-readable history remains accurate and professional.

This module acts as a dispatcher for specialized subcommands that handle the parsing, comparison, and linting of changelog data.

Responsibilities

Section titled “Responsibilities”
  • coordinate changelog-related subcommands
  • provide a consistent interface for changelog auditing and quality control
  • dispatch execution to specialized compare and lint handlers

Subcommands

Section titled “Subcommands”
  • compare: Performs a structured diff between two named release sections. It classifies entries as unique to the starting version, common to both, or unique to the target version. Useful for PR reviews and release auditing.
  • lint: Validates the style and structure of changelog entries. It checks for sentence casing, trailing punctuation, line length limits, and duplicate entries.

Behavior

Section titled “Behavior”
  • Automatically detects the changelog format (Markdown or RST) based on the file extension.
  • Discovers the changelog file location from the active [tool.rrt] configuration.
  • Supports both machine-readable (JSON) and human-friendly (colored terminal) outputs for auditing subcommands.

Examples

Section titled “Examples”
  • rrt changelog compare v1.2.0 v1.3.0
  • rrt changelog lint
  • rrt changelog lint --release v1.5.0 --no-fail
  • rrt changelog compare v1.0.0 v2.0.0 --format json

Caveats

Section titled “Caveats”

Both subcommands require a changelog file discoverable from the active [tool.rrt] configuration. Format detection depends on the file extension, so a misnamed file is parsed with the wrong rules. This group only dispatches; compare and lint carry their own additional caveats.

Section titled “Related docs”
Usage:  rrt changelog [OPTIONS] <changelog_command>


Commands for working with the project changelog.


Subcommands:
  compare  Diff two named release sections.
  lint     Lint entries for style consistency.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  compare     Compare two release sections in the changelog.
  lint        Lint changelog entries for style consistency.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help  Show this message and exit.

rrt changelog compare

Section titled “rrt changelog compare”
Usage:  rrt changelog compare [OPTIONS] <from> <to>


Parse and diff two named release sections from the configured changelog file.


Each entry is classified as only-in-FROM, common, or only-in-TO.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  <from>        Release label to compare from.
  <to>          Release label to compare to.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help    Show this message and exit.
  --format      Output format (default: text).
  --group NAME  Version group name.

rrt changelog lint

Section titled “rrt changelog lint”
Usage:  rrt changelog lint [OPTIONS]


Validate entries in [Unreleased] (or a named release) for style rules:
sentence case, no trailing period, max length, and no duplicates.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help         Show this message and exit.
  --release VERSION  Lint a specific named release section instead of [Unreleased].
  --no-fail          Report violations without exiting non-zero.
  --group NAME       Version group name.

rrt ci-version

Section titled “rrt ci-version”

Compute and apply CI release versions from [tool.rrt] config.

file: ci_version.py

Section titled “file: ci_version.py”

Overview

Section titled “Overview”

The rrt ci-version command family computes deterministic CI versions and applies them safely. It reads the repository’s [tool.rrt] configuration to discover version targets and group defaults. It combines the current CI environment, or explicit CLI overrides, with configured rules to produce machine-friendly version identifiers. Use it in CI pipelines and release workflows that need a computed pre-release version.

Subcommands:

  • compute — print a single version line for scripting and capture.
  • apply — write an explicit version string to every target that declares a ci_format, converting the value when the target format requires it.
  • sync — compute then apply the version in one step. Both apply and sync support --dry-run for safe previews.

Examples

Section titled “Examples”
Terminal window
rrt ci-version compute
rrt ci-version compute --base 1.2.3 --ref refs/heads/main --run-id 42 --run-attempt 3
rrt ci-version apply 1.2.3.dev42 --group backend --dry-run
rrt ci-version sync --dry-run

Caveats

Section titled “Caveats”

Version rules are fixed and not user-configurable. Tag builds (refs/tags/v*) yield the tag name with the leading v removed. Builds on refs/heads/main produce a PEP 440 dev release using {base}.dev{GITHUB_RUN_ID}{GITHUB_RUN_ATTEMPT:02d}. Any other ref returns the configured base version unchanged.

Only pep440 and semver_pre target formats are supported. Converting to semver_pre only works for versions ending in .dev<digits>; other suffixes fail fast instead of writing an invalid Cargo SemVer string. apply needs at least one version target with ci_format configured in the selected group, or it exits with an error and writes nothing.

Section titled “Related docs”
  • /repo-release-tools/commands/version-release/
  • /repo-release-tools/commands/ci-automation/
  • /repo-release-tools/action/
Usage:  rrt ci-version [OPTIONS] <ci_version_cmd>


Compute and apply CI pre-release versions (PEP 440 / SemVer).


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  compute     Print the published version for the current GitHub Actions run.
  apply       Apply a concrete version string to all ci_format-configured targets.
  sync        Compute the published version from GitHub Actions env and apply it.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help  Show this message and exit.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt ci-version compute
  $ rrt ci-version apply 1.2.3.dev4
  $ rrt ci-version sync

rrt ci-version compute

Section titled “rrt ci-version compute”
Usage:  rrt ci-version compute [OPTIONS]


Print the CI/published version for the current GitHub Actions context, using --base and --group overrides when provided.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help       Show this message and exit.
  --group GROUP    Version group to read/apply when multiple release groups are configured.
  --base VERSION   Base version to compute from (default: read from first configured version target).
  --ref REF        Git ref override (default: $GITHUB_REF).
  --ref-name NAME  Git ref-name override (default: $GITHUB_REF_NAME).
  --run-id ID      GitHub Actions run ID override (default: $GITHUB_RUN_ID).
  --run-attempt N  GitHub Actions run-attempt override (default: $GITHUB_RUN_ATTEMPT).


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt ci-version compute
  $ rrt ci-version compute --base 1.2.3 --ref refs/heads/main --run-id 42 --run-attempt 3

rrt ci-version apply

Section titled “rrt ci-version apply”
Usage:  rrt ci-version apply [OPTIONS] <version>


Apply one explicit CI version string to every configured ci_format target in the selected version group.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  <version>      Version string to apply (e.g. 0.2.0.dev12345601).


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help     Show this message and exit.
  --dry-run      Preview without writing changes.
  --group GROUP  Version group to update when multiple release groups are configured.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt ci-version apply 1.2.3.dev4201
  $ rrt ci-version apply 1.2.3.dev4201 --group backend --dry-run

rrt ci-version sync

Section titled “rrt ci-version sync”
Usage:  rrt ci-version sync [OPTIONS]


Compute the current GitHub Actions CI version and apply it to every configured ci_format target.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help       Show this message and exit.
  --group GROUP    Version group to read/apply when multiple release groups are configured.
  --base VERSION   Base version to compute from (default: read from first configured version target).
  --ref REF        Git ref override (default: $GITHUB_REF).
  --ref-name NAME  Git ref-name override (default: $GITHUB_REF_NAME).
  --run-id ID      GitHub Actions run ID override (default: $GITHUB_RUN_ID).
  --run-attempt N  GitHub Actions run-attempt override (default: $GITHUB_RUN_ATTEMPT).
  --dry-run        Preview without writing changes.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt ci-version sync --dry-run
  $ rrt ci-version sync --group backend --ref refs/heads/main --run-id 42 --run-attempt 1

rrt release

Section titled “rrt release”

Validate release-oriented rrt configuration targets for the current repository.

Overview

Section titled “Overview”

rrt release check is the feature-specific health gate for release automation. It focuses on the config targets that drive version bumps and changelog updates, without mixing in broader repository automation checks.

What it checks

Section titled “What it checks”

For each resolved version group, the command checks:

  • version target files exist
  • version target values can be read
  • pin target patterns compile as regular expressions
  • pin target files contain at least one match
  • pin target captured versions match the group’s canonical version
  • the group changelog file exists

It also checks any global pin targets, deduplicating repeated path/pattern pairs so the same target is not reported twice.

Output and severity

Section titled “Output and severity”

The command prints one grouped report per version group and an overall status at the end.

  • missing targets and missing changelog files are errors
  • unreadable version content is reported as a warning
  • pin patterns that compile but do not match are reported as a warning
  • pin patterns that match but capture a stale version (drift from the group’s canonical version) are reported as a warning
  • valid matches and readable targets are reported as OK

Config discovery behavior

Section titled “Config discovery behavior”

If no config file can be found in the current directory or any ancestor, the command prints repository guidance and exits with an error. The supported config roots are pyproject.toml, package.json, Cargo.toml, .rrt.toml, and .config/rrt.toml.

If a config is auto-detected, the command emits a notice on stderr before the main report so you can tell that rrt did not use an explicitly selected file.

Examples

Section titled “Examples”
Terminal window
rrt release check

The command can be run from a nested subdirectory inside the repository; rrt walks upward until it finds the repo root and then checks the resolved config from there.

Version targets may also point at Go, Rust, or .NET-style version files when you need to keep multiple language surfaces aligned.

rrt doctor vs rrt release check

Section titled “rrt doctor vs rrt release check”
Check rrt doctor rrt release check
Hook manager integration Yes No
CI workflow surfaces Yes No
Version target reachability No Yes
Pin target regex matches No Yes
Changelog file existence No Yes

Rule of thumb: run rrt doctor to confirm automation wiring is in place; run rrt release check before cutting a release to confirm that the files rrt bump will touch are reachable.

Common failures

Section titled “Common failures”
Error: version target 'src/myapp/__init__.py' not found

→ The file was moved or renamed. Update path in pyproject.toml.

Error: pin target pattern has no matches in 'docs/conf.py'

→ The pattern compiles but matches nothing. Check the regex, or set pin_target_missing = "warn" to downgrade to a warning during migration.

Warning: docs/README.md drift: pin has '0.15.17', expected '0.15.18'

→ The pin pattern matched, but the captured version is stale — the file was not updated on the last release. Run rrt bump to refresh pin targets, or check for a release step that skipped this file.

Error: changelog file 'CHANGELOG.md' not found

→ First-release setup: the changelog file doesn’t exist yet. Create it with [Unreleased] as a placeholder section.

Hook usage

Section titled “Hook usage”
Terminal window
rrt release check


# Or via pre-commit (manual stage):
pre-commit run rrt-release-check --hook-stage manual

Caveats

Section titled “Caveats”

The check only covers targets reachable from [tool.rrt]. A version string maintained outside any configured target or pin is invisible to it.

Pin target drift and missing matches are always reported as warnings, not errors, regardless of the pin_target_missing setting that governs rrt bump. A clean rrt release check run can still hide a stale or missing pin.

Section titled “Related docs”
Usage:  rrt release [OPTIONS] <release_command>


Release-specific workflows and checks.


Use `rrt release check` to validate version targets, pin targets, and changelog files without mixing in broader repository automation checks.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  check       Validate version targets, pin targets, and changelog files.
  notes       Emit a changelog release section as a formatted release body.
  repair      Fix drift or recreate a release branch cleanly.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help  Show this message and exit.

rrt release check

Section titled “rrt release check”
Usage:  rrt release check [OPTIONS]


Validate the release-oriented parts of the resolved rrt configuration for the current repository, starting from the nearest repo root above the current working directory.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help  Show this message and exit.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt release check

rrt release notes

Section titled “rrt release notes”
Usage:  rrt release notes [OPTIONS]


Extract a section from the configured changelog and emit it as a formatted release body ready for GitHub, GitLab, or any markdown editor. Defaults to [Unreleased]; use --version or --latest-released to target a published section.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help         Show this message and exit.
  --format FORMAT    Output format: md (default) or gh-release.
  --group GROUP      Version group to read from when multiple groups are configured.
  --version VERSION  Extract notes for a specific released section (e.g. 1.2.3 or v1.2.3). Matching is case- and v-prefix-insensitive.
  --latest-released  Extract notes for the topmost released section (the one just below [Unreleased]). Useful in tag-triggered CI release jobs.
  --output PATH      Write the release body to PATH instead of stdout.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt release notes
  $ rrt release notes --format gh-release
  $ rrt release notes --format md > RELEASE_BODY.md
  $ rrt release notes --latest-released --output RELEASE_CHANGELOG.md
  $ rrt release notes --version 1.2.3

rrt release repair

Section titled “rrt release repair”
Usage:  rrt release repair [OPTIONS]


Verify (and optionally fix) version target / pin target / changelog drift on the current branch, or recreate the branch cleanly from a base ref while preserving the declared version and its [VERSION] changelog body.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help             Show this message and exit.
  --from BASE            Recreate mode: rewind the current branch to BASE (commit, branch, or tag) and replay the version bump. Without this flag the command runs in verify-and-fix mode.
  --yes, -y              Required to apply changes; otherwise the command only previews.
  --hotfix               Implies --yes and tags the commit as `chore(release): repair v{ver}` so hotfix recoveries are distinguishable from regular bumps.
  --changelog-from PATH  Read the [VERSION] body from PATH instead of the current branch's CHANGELOG.md. Useful when the polluted HEAD has lost the section.
  --force-allow-pushed   Allow recreate when the branch is ahead of origin/<branch>. The new history must then be force-pushed with `git push --force-with-lease`.
  --no-backup            Skip the `repair/backup/<branch>-<ts>` ref that is otherwise written before any destructive operation.
  --group GROUP          Pick the version group when multiple are configured.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt release repair
  $ rrt release repair --yes
  $ rrt release repair --from main --yes
  $ rrt release repair --from main --hotfix

rrt sync

Section titled “rrt sync”

rrt sync — discover newer upstream releases for the tracked package.

Overview

Section titled “Overview”

Reads the current project version from the configured version group. Fetches all released versions from the configured upstream registry (PyPI, npm, NuGet, crates.io, or Packagist). It prints versions that are strictly newer than the current one. Output is one version per line by default, or a JSON array with --json.

With --bump, the command shifts to mirror-orchestration mode. For each newer version, in ascending order, it applies version targets and optionally commits and tags the result.

Configuration

Section titled “Configuration”

rrt sync reads upstream version information using the [tool.rrt.upstream] block in your project config:

[tool.rrt.upstream]
package = "my-package"
provider = "pypi"
commit_message = "Mirror: {version}"

package is the registry name of the upstream package. provider selects the registry to query. commit_message is a Python format string; {version} is replaced with the new version string and used as the git commit message when --commit is given.

Supported providers

Section titled “Supported providers”
Provider provider value Notes
PyPI pypi Python package index; queries /pypi/<package>/json
npm npm Node package registry; queries /package/<package>
NuGet nuget .NET package registry; queries the NuGet API
crates.io crates Rust crate registry; requires a User-Agent header — handled internally
Packagist packagist PHP package registry; package must be in vendor/name form

Examples

Section titled “Examples”
Terminal window
# List newer versions one per line (default)
rrt sync


# Emit a JSON array of newer version strings
rrt sync --json


# Target a specific version group
rrt sync --group backend

Mirror-orchestration mode

Section titled “Mirror-orchestration mode”
Terminal window
# Apply every newer version to version targets (no git side-effects)
rrt sync --bump


# Apply + commit each version with the default message "Mirror: <version>"
rrt sync --bump --commit


# Apply + commit + annotated tag per version
rrt sync --bump --commit --tag


# Preview the plan without touching anything
rrt sync --bump --commit --tag --dry-run


# Custom commit message template
rrt sync --bump --commit --commit-message "chore: mirror {version}"

CI mirror loop

Section titled “CI mirror loop”

Use rrt sync output to drive a CI bump loop that tracks upstream releases:

Terminal window
for v in $(rrt sync); do
    rrt bump "$v" --no-changelog --force
done

Or let rrt sync --bump --commit --tag handle the full loop in a single call.

Hook

Section titled “Hook”

rrt-sync is published as a manual-stage pre-commit hook. Add it to your .pre-commit-config.yaml to run it on demand before a release:

repos:
  - repo: https://github.com/Anselmoo/repo-release-tools
    rev: v1.10.0
    hooks:
      - id: rrt-sync
Terminal window
pre-commit run rrt-sync --hook-stage manual

Caveats

Section titled “Caveats”

rrt sync skips upstream versions it cannot parse as semver or PEP 440. These are silently ignored rather than reported. “Newer” and “ascending” follow SemVer 2.0 precedence, so 1.0.0-rc.10 comes after 1.0.0-rc.2. A PEP 440 spelling orders like its SemVer twin, so 1.0.0rc1 equals 1.0.0-rc.1. A post release such as 1.0.0.post1 sorts after 1.0.0. --bump applies newer versions strictly in ascending order. It stops at the first failed tag creation. The command requires [tool.rrt.upstream].package to be configured. Without it, rrt sync exits with an error.

Section titled “Related docs”
Usage:  rrt sync [OPTIONS]


Fetch all released versions of the configured upstream package and print those that are strictly newer than the current project version.  With --bump, apply each newer version in ascending order, optionally committing and tagging each one.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help             Show this message and exit.
  --group GROUP          Version group name (default: first/default group).
  --json                 Emit a JSON array of newer version strings instead of one-per-line output.
  --dry-run              Preview without side effects.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Mirror orchestration
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  --bump                 Apply each newer version to version_targets + pin_targets in ascending order.  Without this flag the command lists newer versions only.
  --commit               After each version's apply, stage changed files and create a git commit.
  --tag                  After each version's apply (and optional commit), create an annotated git tag.
  --commit-message TMPL  Override the commit message template.  Use {version} as a placeholder (e.g. 'chore: mirror {version}').  Defaults to group.upstream_commit_message ('Mirror: {version}').


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt sync
  $ rrt sync --json
  $ rrt sync --group backend
  $ rrt sync --bump
  $ rrt sync --bump --commit --tag
  $ rrt sync --bump --commit --commit-message 'chore: mirror {version}' --dry-run

rrt tag

Section titled “rrt tag”

Create and validate release tags for the current repository.

Overview

Section titled “Overview”

rrt tag centralizes the management of Git release tags, ensuring that the repository’s version history remains consistent with its configuration. It automates the creation of annotated tags and provides validation tools to verify that existing tags align with the project’s versioning policy.

The command supports both manual release tagging and automated verification in CI pipelines, helping to maintain a clean and reliable release record.

Responsibilities

Section titled “Responsibilities”
  • create annotated Git tags matching the current configured version
  • support custom tag prefixes and annotation messages
  • validate that existing tags follow the expected naming convention
  • verify that the expected tag for the current version is present
  • optionally push newly created tags to the remote repository

Tag Format

Section titled “Tag Format”

By default, tags are created with a v prefix (e.g., v1.2.3) as is standard for many version control and release automation tools.

  • The prefix comes from the resolved group’s tag_prefix setting, which is itself v unless configured. Setting it per group (e.g. sdk-v) is what lets rrt bump anchor that group’s changelog range to its own tags.
  • The prefix can be overridden for one invocation using --prefix <string>.
  • The prefix can be removed entirely using --prefix "".
  • Tag names are derived directly from the current version read from the active [tool.rrt] configuration group.

Behavior

Section titled “Behavior”
  • create: Reads the current version from config, builds the tag name and message, and executes git tag -a. Refuses to overwrite existing tags unless --force is used.
  • check: Scans all repository tags, identifies those that don’t match the requested prefix, and verifies the presence of the tag corresponding to the current version.
  • push: When --push is used with create, the command executes git push origin <tag> after a successful local tag creation.
  • dry-run: Previews the git commands that would be executed without modifying the repository.

Examples

Section titled “Examples”
  • rrt tag create
  • rrt tag create --push --message "Production release v1.5.0"
  • rrt tag create --prefix "" --force
  • rrt tag check
  • rrt tag check --strict --prefix "rel-"

Caveats

Section titled “Caveats”
  • Requires a valid Git repository and repo-release-tools configuration.
  • Annotated tags are used to ensure that metadata (author, date, message) is correctly captured in the Git history.
  • The check --strict mode is recommended for CI pipelines to ensure that a tag was correctly created before a release proceeds.
Section titled “Related docs”
Usage:  rrt tag [OPTIONS] <tag_command>


Create annotated git tags from the current configured version, or check that existing tags follow the naming convention.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  create      Create an annotated git tag for the current version.
  check       Validate existing tags against the configured version.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help  Show this message and exit.

rrt tag create

Section titled “rrt tag create”
Usage:  rrt tag create [OPTIONS]


Create an annotated git tag matching the current configured version.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help       Show this message and exit.
  --prefix PREFIX  Tag prefix. Defaults to the group's configured 'tag_prefix' (itself 'v' unless set). Pass empty string for no prefix. Include the '{group}' token to render each group's name when --group lists multiple groups (e.g. '{group}-v').
  --message MSG    Annotation message. Defaults to 'Release <tag>'.
  --push           Push the tag to origin after creating it.
  --force          Delete and recreate the tag if it already exists.
  --dry-run        Preview what would happen without making changes.
  --group GROUP    Version group to read when multiple groups are configured. Pass a comma-separated list (e.g. 'a,b,c') to tag several groups in one invocation; --prefix must then include the '{group}' token.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt tag create
  $ rrt tag create --push
  $ rrt tag create --prefix '' --message 'Release 1.2.3'
  $ rrt tag create --group backend,sdk --prefix '{group}-v'
  $ rrt tag check
  $ rrt tag check --strict
  $ rrt tag check --group backend,sdk --prefix '{group}-v'

rrt tag check

Section titled “rrt tag check”
Usage:  rrt tag check [OPTIONS]


Check that existing git tags follow the naming convention.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help       Show this message and exit.
  --prefix PREFIX  Expected tag prefix. Defaults to the group's configured 'tag_prefix' (itself 'v' unless set). Include the '{group}' token to render each group's name when --group lists multiple groups (e.g. '{group}-v').
  --strict         Fail if the expected tag for the current version is missing.
  --group GROUP    Version group to read when multiple groups are configured. Pass a comma-separated list (e.g. 'a,b,c') to check several groups in one invocation; --prefix must then include the '{group}' token.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt tag create
  $ rrt tag create --push
  $ rrt tag create --prefix '' --message 'Release 1.2.3'
  $ rrt tag create --group backend,sdk --prefix '{group}-v'
  $ rrt tag check
  $ rrt tag check --strict
  $ rrt tag check --group backend,sdk --prefix '{group}-v'

rrt workspace

Section titled “rrt workspace”

Coordinate version bumps across multiple packages in a monorepo.

Overview

Section titled “Overview”

rrt workspace bump applies the same version bump to every listed package in one pass. It reads each package’s own [tool.rrt] configuration, verifies that all packages are loadable, then updates version targets and changelogs in a single coordinated sweep.

When to use this

Section titled “When to use this”

Use rrt workspace bump when your repository contains multiple independently-versioned packages (e.g. a Python backend, a TypeScript SDK, and a Go CLI tool) that are always released together at the same version.

What it does

Section titled “What it does”
  1. Resolve each package path from --packages.
  2. Load each package’s rrt config and read its current version.
  3. Compute the new version using the same bump logic as rrt bump. Keyword kinds are major, minor, patch, release, pre-release, alpha, beta, rc and calver. Starting alpha, beta or rc from a final version targets the next patch unless the package sets prerelease_base. --base LEVEL overrides that for every package. auto reads each package’s own Conventional Commits since its last final tag.
  4. For each package: update version targets and, unless --no-changelog, the changelog.
  5. Report every file write to stdout (or preview them with --dry-run).

Safety notes

Section titled “Safety notes”
  • All package configs must exist and be valid before any file is written.
  • Every package’s new version is computed before any file is written. An impossible bump for any package aborts the run with exit code 1.
  • --dry-run previews all planned writes without touching any file.

Examples

Section titled “Examples”
Terminal window
rrt workspace bump minor --packages api,sdk,docs
rrt workspace bump 2.0.0 --packages ./packages/api,./packages/sdk
rrt workspace bump patch --dry-run --packages api,sdk
rrt workspace bump release --packages api,sdk
rrt workspace bump rc --base minor --packages api,sdk

Caveats

Section titled “Caveats”

Every package needs its own loadable [tool.rrt] configuration. A missing or invalid config in any package aborts the whole run before any file is written.

An impossible bump for any package also aborts before any write. Examples are pre-release on a stable version or release on a final version. The error line names the package and the reason.

release drops the pre-release suffix, so 1.2.0-rc.1 becomes 1.2.0.

--base only matters when a channel starts from a final version. A package already on a pre-release keeps its core, so 1.0.1-rc.1 becomes 1.0.1-rc.2. --base is its own flag and is not an abbreviation of any other option.

Config loading is validated up front, but the actual writes still happen package by package. Each package’s own version-target write is atomic, yet if a later package fails mid-run, earlier packages keep their already applied changes. There is no cross-package rollback.

Changelog promotion is skipped per package when that package has no [Unreleased] section or the section has no entries. Use --no-changelog to skip it everywhere.

Section titled “Related docs”
Usage:  rrt workspace [OPTIONS] <workspace_command>


Apply a unified version bump to every listed package.


Each package must have its own [tool.rrt] configuration. All configs are validated before any file is written.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  bump        Bump versions across all listed packages.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help  Show this message and exit.

rrt workspace bump

Section titled “rrt workspace bump”
Usage:  rrt workspace bump [OPTIONS] <bump>


Apply the same version bump to every package listed in --packages.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  <bump>            major | minor | patch | release | pre-release | alpha | beta | rc | calver | <version>


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help        Show this message and exit.
  --packages PATHS  Comma-separated list of package directories to bump.
  --base LEVEL      Core level for starting alpha|beta|rc from a final version (patch | minor | major | auto). Overrides [tool.rrt] prerelease_base.
  --dry-run         Preview without writing to disk.
  --no-changelog    Skip changelog updates.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt workspace bump minor --packages api,sdk,docs
  $ rrt workspace bump 2.0.0 --packages ./packages/api,./packages/sdk
  $ rrt workspace bump patch --dry-run --packages api,sdk
  $ rrt workspace bump release --packages api,sdk
  $ rrt workspace bump rc --base minor --packages api,sdk

Badge families are intentionally complete for the current icon registry across platform, registry, and language labels; see src/repo_release_tools/tools/platform.py if you think one is missing.

Chat is powered by Context7, a third-party service with its own terms and privacy policy.