repo-release-tools

repo-release-tools

repo-release-tools 让发布策略以尽可能省心的方式保持简单。

如果你想让 CI 验证分支名称、提交主题和变更日志策略，可通过 GitHub Marketplace 使用它。若需要本地 CLI、钩子集成、版本升级和发布分支自动化，则可从 PyPI 安装。

• GitHub Marketplace 操作：https://github.com/marketplace/actions/repo-release-tools-policy-checks

• PyPI 软件包：https://pypi.org/project/repo-release-tools/

• 选择你的使用入口

  • 使用 GitHub Action 检查 CI 策略
  • 使用 Python 软件包实现本地工作流自动化

• 变更日志工作流

• 项目包含的内容

• 让你的 AI Agent 真正使用 rrt

  • 1. 在指令文件中告诉你的 Agent 一次
  • 2. 连接 MCP 服务（可选，但对于任何写入操作都更好）
  • 有效的提示词措辞
  • Agent 指令片段

• 从与任务相匹配的文档开始

• 许可证

选择你的使用入口

使用 GitHub Action 检查 CI 策略

如果你希望在仓库偏离发布策略时，拉取请求和推送能够尽早失败，请选择此 Action。

• 验证分支名称，例如 feat/add-parser
• 验证 Conventional Commit 提交主题
• 在 CI 中验证变更日志策略
• 可选检查工作树是否保持干净
• 可运行 rrt doctor，作为发布前的健康检查关卡

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

- uses: Anselmoo/[email protected]
  with:
    check-branch-name: "true"
    check-commit-subject: "true"
    check-changelog: "true"

查看完整的 Action 指南： https://anselmoo.github.io/repo-release-tools/action/

查看完整的 CLI 和命令参考： https://github.com/Anselmoo/repo-release-tools/blob/main/docs/commands/rrt-cli.md

使用 Python 包实现本地工作流自动化

如果你需要开发者侧工具，例如分支辅助工具、版本号递增、配置检查、pre-commit 钩子和发布自动化，请选择此包。Python 包已发布到 PyPI，并提供对应的 CI 版本，详见 GitHub Action 指南。

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

或者运行 CLI，而无需永久安装：

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

如果已安装 rrt，并且想使用为 Copilot、Claude 或 Codex 打包的 Agent 技能，请通过以下命令安装：

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

对于基本的版本管理，bump 和 ci-version 无需 [tool.rrt]，即可自动检测仓库根目录中的 pyproject.toml、package.json、Cargo.toml、.rrt.toml 或 .config/rrt.toml。 如果找到多个版本文件，会一并更新。显式配置用于启用更多实用功能：分组发布、变更日志路径、发布分支、锁定命令、生成文件和自定义模式。

版本目标还支持常见的语言／项目文件，例如 Python（pep621、python_version）、Node/JS/TS（package_json）、Go（go_version）、Rust（cargo_toml）和 .NET（csproj），以便多语言仓库保持发布版本一致。mcp_server_json 目标可在更新项目主要目标的同时，保持 MCP 注册表的 server.json（顶层 version、每个 package 的 version，以及任何 oci package 的镜像标签）同步。

变更日志工作流

选择适合仓库合并变更方式的风格。

incremental（默认） — 适用于在开发期间维护变更日志条目的团队。

• rrt-update-unreleased 和 rrt-changelog 钩子保持启用。
• GitHub Action 会将 changelog-strategy: auto 解析为 per-commit。
• rrt bump 默认使用 auto。

squash — 适用于将多个提交压缩为一个 PR 合并的仓库。

• 变更日志写入和检查钩子会跳过强制要求。
• GitHub Action 会将 changelog-strategy: auto 解析为 release-only。
• rrt bump 默认使用 generate。

最简配置：

[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"

也支持原生配置：在 package.json 中使用（"rrt": { ... }），在 Cargo.toml 中使用（[package.metadata.rrt] / [workspace.metadata.rrt]）。Go 仓库应使用 .rrt.toml 或 .config/rrt.toml。

项目包含的内容

• 用于分支、版本号递增、配置检查和 Git 辅助操作的 rrt CLI
• 适用于 pre-commit、lefthook、husky 和 CI 验证的 rrt-hooks
• action.yml 中可复用的 GitHub Action
• 为 uvx 和已安装 CLI 工作流打包的 Agent 技能
• 关于分支策略、钩子设置和发布工作流的文档

让你的 AI Agent 真正使用 rrt

如果你在配置了 rrt 的仓库中使用 Claude Code、Copilot、Cursor 或 Codex，Agent 很可能会重新实现 rrt 已经实现的功能——手动编辑三个文件中的版本字符串、编造一个随后被 pre-commit 钩子拒绝的分支名，或将变更日志条目写入错误的章节。这并不是因为它缺少工具，而是因为没有人告诉它这些工具正是为此任务准备的。

有两种办法可以解决。两种都要做。

1. 在 Agent 的指令文件中一次性告知它

将下方 Agent 指令片段中的内容粘贴到仓库的 CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md 中。这是影响最大的一步：每次会话都会读取该内容，而且早于 Agent 制定计划，并且不会产生任何运行时开销。

2. 连接 MCP 服务（可选，但对于任何会写入内容的操作都更好）

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

然后在仓库根目录添加 .mcp.json——Claude Code 会在下次启动时读取它：

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

连接服务后，大多数工具会向 Agent 提供有类型的 JSON，而不是需要解析的终端输出（四个锁文件读取器和 rrt_config 返回的是原始字典）；提交说明和分支名称会作为参数传递，而不是通过 shell 引号传递；修改操作默认会先预览，不会实际执行。有关 Claude Desktop、全局安装以及带有 bearer 身份验证的 HTTP 传输，请参阅 MCP 服务指南。

MCP 服务无法涵盖所有内容。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、所有其他 --snapshot 写入操作，以及每个 rrt-hooks 子命令都只能通过 CLI 执行——混合使用是预期的工作方式，而不是备用方案。

有效的提示词表述

这些表述能可靠地将任务交给 rrt，而不是手动编辑：

• “在创建这个分支之前，用 rrt 检查分支名称能否通过钩子检查。”
• “用 rrt 预览一次次版本号升级——试运行——并列出它会修改的所有文件。”
• “添加条目之前，先用 rrt 读取 Unreleased 更新日志，避免重复。”
• “运行 rrt doctor，并告诉我缺少哪些钩子集成。”
• “编写提交消息之前，先用 rrt 验证主题。”
• “根据 rrt，这个仓库当前是什么版本？”——不要只问“是什么版本”，否则可能会触发读取某个随机文件。
• “打开 PR 之前，先运行 rrt release check。”

要点：明确提到 rrt，并指出具体的时机（“创建之前”“打开 PR 之前”）。Agent 会根据触发条件进行路由，而不是根据功能来路由。

Agent 指令片段

## Use `rrt` for release policy

This repo uses `repo-release-tools` (`rrt`) to enforce branch naming, Conventional
Commits, changelog format, and version consistency. Do not hand-roll any of it.

Before you act, use `rrt`:

| When you are about to… | Use |
|---|---|
| create a branch | `rrt branch new <type> "<desc>"` — or validate the name first with `rrt-hooks check-branch-name --branch <candidate>` |
| write a commit message | `rrt git commit --type <type> "<description>"`, which builds and validates the subject before committing |
| change a version number anywhere | `rrt bump <level> --dry-run` first — never edit version strings by hand; pins and the changelog move with it |
| add a changelog entry | read the existing `[Unreleased]` first; it is hook-managed |
| open a PR | `rrt release check` and `rrt doctor` |

Rules:
- Every mutating `rrt` command takes `--dry-run`. Use it first, show the user the
  preview, and only apply after they confirm.
- Never edit a version string by hand in more than one file — that is what `rrt bump` is for.
- Never hand-edit the `[Unreleased]` changelog section while the rrt hooks are active.
- If `rrt` is connected over MCP, prefer the `mcp__rrt__*` tools over shelling out:
  typed responses for most tools, no shell quoting of commit subjects, and dry-run is
  the default. Shell out for anything with no MCP tool (`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`, other `--snapshot` writes, `rrt-hooks *`).
- `rrt --help` lists every command. Check it before concluding rrt cannot do something.

从与任务相符的文档开始

• 文档索引：https://anselmoo.github.io/repo-release-tools/
• GitHub Action：https://anselmoo.github.io/repo-release-tools/action/
• CLI 参考：https://github.com/Anselmoo/repo-release-tools/blob/main/docs/commands/rrt-cli.md
• 钩子设置：https://github.com/Anselmoo/repo-release-tools/blob/main/docs/commands/hooks.md
• Conventional 分支：https://github.com/Anselmoo/repo-release-tools/blob/main/docs/commands/branch.md
• Git 工作流辅助工具：https://github.com/Anselmoo/repo-release-tools/blob/main/docs/commands/git_cmd.md
• Agent 技能：https://github.com/Anselmoo/repo-release-tools/blob/main/docs/commands/skill.md
• 项目树：https://github.com/Anselmoo/repo-release-tools/blob/main/docs/commands/tree.md
• Markdown 目录：https://github.com/Anselmoo/repo-release-tools/blob/main/docs/commands/toc.md
• 配置健康检查：https://github.com/Anselmoo/repo-release-tools/blob/main/docs/commands/doctor.md
• 运行时 EOL 跟踪：https://github.com/Anselmoo/repo-release-tools/blob/main/docs/commands/eol_check.md
• MCP 服务：https://anselmoo.github.io/repo-release-tools/mcp-server/
• Agent 指令：https://anselmoo.github.io/repo-release-tools/agent-instructions/

许可证

repo-release-tools 根据 MIT 许可证发布。

一些工作流构想最初受到 joseluisq/gitnow 的启发，但 rrt git 的功能范围有意设置得更窄，并围绕 Conventional 分支、安全提交和发布自动化进行了调整。