{ "markdown": "# repo-release-tools\n\n\n\n\n

\n \n \n \"GitHub\"\n \n \n \n \"PyPI\"\n

\n\n\n\n

\n \n \n \"REPO-RELEASE-TOOLS\n

\n\n\n`repo-release-tools` keeps release policy boring in the best possible way.\n\nUse it from **GitHub Marketplace** when you want CI to validate branch names,\ncommit subjects, and changelog policy. Install it from **PyPI** when you want a\nlocal CLI, hook integration, version bumps, and release-branch automation.\n\n- GitHub Marketplace action: \n- PyPI package: \n\n\n- [Choose your entry point](#choose-your-entry-point)\n - [Use the GitHub Action for CI policy checks](#use-the-github-action-for-ci-policy-checks)\n - [Use the Python package for local workflow automation](#use-the-python-package-for-local-workflow-automation)\n- [Changelog workflows](#changelog-workflows)\n- [What the project includes](#what-the-project-includes)\n- [Get your AI agent to actually use rrt](#get-your-ai-agent-to-actually-use-rrt)\n - [1. Tell your agent, once, in its instruction file](#1-tell-your-agent-once-in-its-instruction-file)\n - [2. Connect the MCP server (optional, but better for anything that writes)](#2-connect-the-mcp-server-optional-but-better-for-anything-that-writes)\n - [Prompt phrasings that work](#prompt-phrasings-that-work)\n - [Agent instruction snippet](#agent-instruction-snippet)\n- [Start with the doc that matches your task](#start-with-the-doc-that-matches-your-task)\n- [License](#license)\n\n\n## Choose your entry point\n\n### Use the GitHub Action for CI policy checks\n\nChoose the action if you want pull requests and pushes to fail fast when a repo\ndrifts from your release policy.\n\n- validates branch names such as `feat/add-parser`\n- validates Conventional Commit subjects\n- validates changelog policy in CI\n- optionally checks that the working tree stays clean\n- can run `rrt doctor` as a pre-release health gate\n\n```yaml\n- uses: actions/checkout@v6\n with:\n fetch-depth: 0\n\n- uses: Anselmoo/repo-release-tools@v1.17.1\n with:\n check-branch-name: \"true\"\n check-commit-subject: \"true\"\n check-changelog: \"true\"\n```\n\nSee the full action guide:\n\n\nSee the full CLI and commands reference:\n\n\n### Use the Python package for local workflow automation\n\nChoose the package if you want the developer-side tools: branch helpers,\nversion bumps, config inspection, pre-commit hooks, and release automation.\nThe Python package is published on [PyPI](https://pypi.org/project/repo-release-tools/)\nand has a CI counterpart in the [GitHub Action guide](https://anselmoo.github.io/repo-release-tools/action/).\n\n```bash\npip install repo-release-tools\nrrt init\nrrt branch new feat \"add parser\"\nrrt git commit \"add parser\"\nrrt git doctor\nrrt bump patch\n```\n\nOr run the CLI without installing it permanently:\n\n```bash\nuvx repo-release-tools branch new feat \"add parser\"\n```\n\nIf `rrt` is already installed and you want the bundled agent skill for Copilot,\nClaude, or Codex, install it with:\n\n```bash\nrrt skill install --target copilot-local\nrrt skill install --target claude-local --target codex-local\nrrt skill install --target codex-global --dry-run\n```\n\nFor basic versioning, `bump` and `ci-version` can run without `[tool.rrt]` by\nauto-detecting repo-root `pyproject.toml`, `package.json`, `Cargo.toml`,\n`.rrt.toml`, or `.config/rrt.toml`.\nIf multiple version files are found, they are updated together. Explicit config\nis for the nice extras: grouped releases, changelog paths, release branches,\nlock commands, generated files, and custom patterns.\n\nVersion targets also support common language/project files such as Python\n(`pep621`, `python_version`), Node/JS/TS (`package_json`), Go (`go_version`),\nRust (`cargo_toml`), and .NET (`csproj`) so multi-language repositories can\nkeep their release versions aligned. A `mcp_server_json` target keeps an MCP\nRegistry `server.json` (top-level `version`, each package's `version`, and\nany `oci` package's image tag) in sync alongside a project's primary target.\n\n## Changelog workflows\n\nPick the style that matches how your repository lands changes.\n\n**`incremental` (default)** — for teams that maintain changelog entries during development.\n- `rrt-update-unreleased` and `rrt-changelog` hooks stay active.\n- The GitHub Action resolves `changelog-strategy: auto` to `per-commit`.\n- `rrt bump` defaults to `auto`.\n\n**`squash`** — for repositories that squash many commits into one PR merge.\n- Changelog write and check hooks skip enforcement.\n- The GitHub Action resolves `changelog-strategy: auto` to `release-only`.\n- `rrt bump` defaults to `generate`.\n\nMinimal config:\n\n```toml\n[tool.rrt]\nrelease_branch = \"release/v{version}\"\nchangelog_file = \"CHANGELOG.md\"\nchangelog_workflow = \"incremental\" # or \"squash\"\n\n[[tool.rrt.version_targets]]\npath = \"pyproject.toml\"\nkind = \"pep621\"\n```\n\nNative config is also supported in `package.json` (`\"rrt\": { ... }`) and\n`Cargo.toml` (`[package.metadata.rrt]` / `[workspace.metadata.rrt]`). Go repos\nshould use `.rrt.toml` or `.config/rrt.toml`.\n\n## What the project includes\n\n- `rrt` CLI for branches, bumps, config inspection, and Git helpers\n- `rrt-hooks` for `pre-commit`, `lefthook`, `husky`, and CI validation\n- a reusable GitHub Action in `action.yml`\n- bundled agent skills for `uvx` and installed-CLI workflows\n- docs for branch policy, hook setup, and release workflows\n\n## Get your AI agent to actually use rrt\n\nIf you use Claude Code, Copilot, Cursor, or Codex on a repository that has `rrt`\nconfigured, the agent will happily reimplement what `rrt` already does — hand-editing a\nversion string in three files, inventing a branch name the pre-commit hook then rejects,\nor writing a changelog entry in the wrong section. Not because it lacks the tools, but\nbecause nothing told it these are the tools for this job.\n\nTwo things fix that. Do both.\n\n### 1. Tell your agent, once, in its instruction file\n\nPaste the block from [Agent instruction snippet](#agent-instruction-snippet) below into\nyour repository's `CLAUDE.md`, `AGENTS.md`, or `.github/copilot-instructions.md`. This is\nthe highest-leverage step by a wide margin: it is read on every session, before the agent\nhas formed a plan, and it costs nothing at runtime.\n\n### 2. Connect the MCP server (optional, but better for anything that writes)\n\n```bash\nuv add \"repo-release-tools[mcp]\"\n```\n\nThen add `.mcp.json` at the repository root — Claude Code picks it up on next start:\n\n```json\n{\n \"mcpServers\": {\n \"rrt\": { \"type\": \"stdio\", \"command\": \"uv\", \"args\": [\"run\", \"rrt-mcp\"] }\n }\n}\n```\n\nWith the server connected, most tools give the agent typed JSON instead of terminal\noutput it has to parse (the four lock readers and `rrt_config` return raw dicts instead),\ncommit subjects and branch names are passed as arguments instead of through shell\nquoting, and mutating operations default to a dry-run preview. See the\n[MCP Server guide](https://anselmoo.github.io/repo-release-tools/mcp-server/) for\nClaude Desktop, global install, and HTTP transport with bearer auth.\n\nThe MCP server does not cover everything. `rrt docs map`, `rrt docs generate`,\n`rrt docs publish`, `rrt docs inject`, `rrt tree --check`, `rrt toc`, `rrt changelog lint`,\n`rrt changelog compare`, `rrt drift generate`/`check`, `rrt artifacts --check`, every other\n`--snapshot` write, and every `rrt-hooks` subcommand are CLI-only — a mixed session is\nexpected, not a fallback.\n\n### Prompt phrasings that work\n\nThese reliably route to `rrt` rather than to hand-editing:\n\n- \"Check with rrt whether this branch name will pass the hooks before you create it.\"\n- \"Use rrt to preview a minor bump — dry run — and show me every file it would touch.\"\n- \"Read the Unreleased changelog with rrt before adding an entry, so you don't duplicate one.\"\n- \"Run rrt doctor and tell me which hook integrations are missing.\"\n- \"Before you write that commit message, validate the subject with rrt.\"\n- \"What version is this repo at according to rrt?\" — not \"what's the version\", which\n invites reading a random file.\n- \"Run rrt release check before you open the PR.\"\n\nThe pattern: name `rrt` explicitly, and name the *moment* (\"before you create it\",\n\"before you open the PR\"). Agents route on triggers, not on capabilities.\n\n### Agent instruction snippet\n\n```markdown\n## Use `rrt` for release policy\n\nThis repo uses `repo-release-tools` (`rrt`) to enforce branch naming, Conventional\nCommits, changelog format, and version consistency. Do not hand-roll any of it.\n\nBefore you act, use `rrt`:\n\n| When you are about to… | Use |\n|---|---|\n| create a branch | `rrt branch new \"\"` — or validate the name first with `rrt-hooks check-branch-name --branch ` |\n| write a commit message | `rrt git commit --type \"\"`, which builds and validates the subject before committing |\n| change a version number anywhere | `rrt bump --dry-run` first — never edit version strings by hand; pins and the changelog move with it |\n| add a changelog entry | read the existing `[Unreleased]` first; it is hook-managed |\n| open a PR | `rrt release check` and `rrt doctor` |\n\nRules:\n- Every mutating `rrt` command takes `--dry-run`. Use it first, show the user the\n preview, and only apply after they confirm.\n- Never edit a version string by hand in more than one file — that is what `rrt bump` is for.\n- Never hand-edit the `[Unreleased]` changelog section while the rrt hooks are active.\n- If `rrt` is connected over MCP, prefer the `mcp__rrt__*` tools over shelling out:\n typed responses for most tools, no shell quoting of commit subjects, and dry-run is\n the default. Shell out for anything with no MCP tool (`rrt docs map`, `rrt docs\n generate`, `rrt docs publish`, `rrt docs inject`, `rrt tree --check`, `rrt toc`,\n `rrt changelog lint`, `rrt changelog compare`, `rrt drift generate`/`check`,\n `rrt artifacts --check`, other `--snapshot` writes, `rrt-hooks *`).\n- `rrt --help` lists every command. Check it before concluding rrt cannot do something.\n```\n\n## Start with the doc that matches your task\n\n\n- Docs index: \n- GitHub Action: \n- CLI reference: \n- Hook setup: \n- Conventional branches: \n- Git workflow helpers: \n- Agent skills: \n- Project tree: \n- Markdown TOC: \n- Config health checks: \n- Runtime EOL tracking: \n- MCP Server: \n- Agent instructions: \n\n\n## License\n\n`repo-release-tools` is released under the MIT License.\n\nSome workflow ideas were initially inspired by\n[`joseluisq/gitnow`](https://github.com/joseluisq/gitnow), but the `rrt git`\nsurface is intentionally narrower and reshaped around conventional branching,\nsafe commits, and release automation.\n", "bytes": 13667, "sha": "a0dcc47e5bf06ee5f4fe8976f1b29303bacc53716cc6db9053b5665c0900c686", "repo_slug": "anselmoo/repo-release-tools", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_anselmoo_repo_release_tools_8e4deacf/readme" }