repo-release-tools

repo-release-tools keeps release policy boring in the best possible way.

Use it from GitHub Marketplace when you want CI to validate branch names, commit subjects, and changelog policy. Install it from PyPI when you want a local CLI, hook integration, version bumps, and release-branch automation.

• GitHub Marketplace action: https://github.com/marketplace/actions/repo-release-tools-policy-checks
• PyPI package: https://pypi.org/project/repo-release-tools/

• Choose your entry point
  • Use the GitHub Action for CI policy checks
  • Use the Python package for local workflow automation
• Changelog workflows
• What the project includes
• Get your AI agent to actually use rrt
  • 1. Tell your agent, once, in its instruction file
  • 2. Connect the MCP server (optional, but better for anything that writes)
  • Prompt phrasings that work
  • Agent instruction snippet
• Start with the doc that matches your task
• License

Choose your entry point

Use the GitHub Action for CI policy checks

Choose the action if you want pull requests and pushes to fail fast when a repo drifts from your release policy.

• validates branch names such as feat/add-parser
• validates Conventional Commit subjects
• validates changelog policy in CI
• optionally checks that the working tree stays clean
• can run rrt doctor as a pre-release health gate

- uses: actions/checkout@v6
  with:
    fetch-depth: 0

- uses: Anselmoo/repo-release-tools@v1.17.1
  with:
    check-branch-name: "true"
    check-commit-subject: "true"
    check-changelog: "true"

See the full action guide: https://anselmoo.github.io/repo-release-tools/action/

See the full CLI and commands reference: https://github.com/Anselmoo/repo-release-tools/blob/main/docs/commands/rrt-cli.md

Use the Python package for local workflow automation

Choose the package if you want the developer-side tools: branch helpers, version bumps, config inspection, pre-commit hooks, and release automation. The Python package is published on PyPI and has a CI counterpart in the GitHub Action guide.

pip install repo-release-tools
rrt init
rrt branch new feat "add parser"
rrt git commit "add parser"
rrt git doctor
rrt bump patch

Or run the CLI without installing it permanently:

uvx repo-release-tools branch new feat "add parser"

If rrt is already installed and you want the bundled agent skill for Copilot, Claude, or Codex, install it with:

rrt skill install --target copilot-local
rrt skill install --target claude-local --target codex-local
rrt skill install --target codex-global --dry-run

For basic versioning, bump and ci-version can run without [tool.rrt] by auto-detecting repo-root pyproject.toml, package.json, Cargo.toml, .rrt.toml, or .config/rrt.toml. If multiple version files are found, they are updated together. Explicit config is for the nice extras: grouped releases, changelog paths, release branches, lock commands, generated files, and custom patterns.

Version targets also support common language/project files such as Python (pep621, python_version), Node/JS/TS (package_json), Go (go_version), Rust (cargo_toml), and .NET (csproj) so multi-language repositories can keep their release versions aligned. A mcp_server_json target keeps an MCP Registry server.json (top-level version, each package's version, and any oci package's image tag) in sync alongside a project's primary target.

Changelog workflows

Pick the style that matches how your repository lands changes.

incremental (default) — for teams that maintain changelog entries during development.

• rrt-update-unreleased and rrt-changelog hooks stay active.
• The GitHub Action resolves changelog-strategy: auto to per-commit.
• rrt bump defaults to auto.

squash — for repositories that squash many commits into one PR merge.

• Changelog write and check hooks skip enforcement.
• The GitHub Action resolves changelog-strategy: auto to release-only.
• rrt bump defaults to generate.

Minimal config:

[tool.rrt]
release_branch = "release/v{version}"
changelog_file = "CHANGELOG.md"
changelog_workflow = "incremental"  # or "squash"

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

Native config is also supported in package.json ("rrt": { ... }) and Cargo.toml ([package.metadata.rrt] / [workspace.metadata.rrt]). Go repos should use .rrt.toml or .config/rrt.toml.

What the project includes

• rrt CLI for branches, bumps, config inspection, and Git helpers
• rrt-hooks for pre-commit, lefthook, husky, and CI validation
• a reusable GitHub Action in action.yml
• bundled agent skills for uvx and installed-CLI workflows
• docs for branch policy, hook setup, and release workflows

Get your AI agent to actually use rrt

If you use Claude Code, Copilot, Cursor, or Codex on a repository that has rrt configured, the agent will happily reimplement what rrt already does — hand-editing a version string in three files, inventing a branch name the pre-commit hook then rejects, or writing a changelog entry in the wrong section. Not because it lacks the tools, but because nothing told it these are the tools for this job.

Two things fix that. Do both.

1. Tell your agent, once, in its instruction file

Paste the block from Agent instruction snippet below into your repository's CLAUDE.md, AGENTS.md, or .github/copilot-instructions.md. This is the highest-leverage step by a wide margin: it is read on every session, before the agent has formed a plan, and it costs nothing at runtime.

2. Connect the MCP server (optional, but better for anything that writes)

uv add "repo-release-tools[mcp]"

Then add .mcp.json at the repository root — Claude Code picks it up on next start:

{
  "mcpServers": {
    "rrt": { "type": "stdio", "command": "uv", "args": ["run", "rrt-mcp"] }
  }
}

With the server connected, most tools give the agent typed JSON instead of terminal output it has to parse (the four lock readers and rrt_config return raw dicts instead), commit subjects and branch names are passed as arguments instead of through shell quoting, and mutating operations default to a dry-run preview. See the MCP Server guide for Claude Desktop, global install, and HTTP transport with bearer auth.

The MCP server does not cover everything. rrt docs map, rrt docs generate, rrt docs publish, rrt docs inject, rrt tree --check, rrt toc, rrt changelog lint, rrt changelog compare, rrt drift generate/check, rrt artifacts --check, every other --snapshot write, and every rrt-hooks subcommand are CLI-only — a mixed session is expected, not a fallback.

Prompt phrasings that work

These reliably route to rrt rather than to hand-editing: