DeployBot

# 部署机器人 部署机器人（DeployBot）是一个与提供商无关的 GitHub 合并队列，适用于编码代理。Codex、Claude Code、Cursor 或任何 MCP 客户端都可以准备和审查拉取请求；用户通过说“部署”来做出最终的合并决定。 DeployBot 将权限存储在 GitHub 标签和身份验证评论中。它立即记录部署意图，促进最终的精确审查头部，冻结突发，合并独立工作，搭建累积集成拉取请求，跟随主分支到生产，并在失败后暂停。 ## 安装 直接从 GitHub 安装已审查的 `v0.2.20` 源提交： ```bash python3 -m pip install \ 'deploybot-merge-queue[mcp] @ git+https://github.com/Forward-Future/DeployBot.git@3bf238140fba3d4d5fbd2d739b9f5422e99567dd' deploybot init ``` `deploybot init` 编写安全启动策略。注解 [示例策略](.mergequeue.example.toml) 显示了每个支持的章节，[CLI、MCP、策略和操作参考](docs/reference.md) 列出了每个当前命令、工具、选项和配置字段。 调用捆绑的 `$deploybot` 技能来检查或操作队列。典型的请求包括“显示交付管道”、“为什么 PR 42 被阻止？”和“部署此 PR”。状态和诊断是只读的： ```bash deploybot status deploybot status --json deploybot doctor deploybot metrics --json deploybot inspect 42 --json ``` 对于从 Astro 源树进行开发，请安装 `./packages/agent-merge-queue[mcp]` 代替。 编辑 `.mergequeue.toml` 以命名所需的检查、可选的审查提供者和每个确切的 GitHub 登录，其队列标记是受信任的。不要通过广泛的存储库角色授予权限。GitHub 验证评论作者；其正常的令牌权限控制标签、评论和合并写入。身份验证来自 GitHub CLI： ```bash gh auth login deploybot ensure-labels deploybot doctor ``` 基本安装没有审查服务依赖。存储库可以使用所需的检查 alone 或添加 GitHub 批准、通用机器人、代理审查检查或任何组合。 ## 安全模型 使用 GitHub 规则集保护基本分支，该规则集独立要求与 `.mergequeue.toml` 中命名的相同的检查，并且不允许 DeployBot 的合并凭证绕过该规则集。DeployBot 读取检查显示名称以协调队列；GitHub 的规则集是权威的检查身份和最终的原子合并保护。 保持工作流更改审查，固定第三方操作到完整的提交哈希，并永远不要在特权协调器中执行拉取请求头代码。MCP 服务器使用本地进程的现有 GitHub 凭证，并接受明确的存储库选择器，因此请仅从受信任的编码客户端和工作空间运行它。 ## 持久的手动部署门 安装的代理适配器将用户的确切 `deploy` 指令视为该线程的 PR 的权限。它立即记录意图 - 即使 CI 或审查仍在进行中： ```bash deploybot request <pr-number> \ --provider codex --thread-id "$CODEX_THREAD_ID" ``` 事件工作者仅在所有检查和审查提供者通过后促进意图绑定的确切头部。如果审查修复创建了替换头部，则受信任的源代理运行 `deploybot refresh-request <pr>` 以获取其新证据；用户无需重复 `deploy`。不涉及任何轮询计时器。 在默认分支上安装 `examples/github-workflow.yml`。它对部署标签、就绪/同步事件、审查、命名的 CI `workflow_run` 完成和已完成的外部检查套件做出反应。保持其 `workflows` 列表与 `pipeline.ci_workflows` 保持一致。五分钟的计划协调会重新读取所有持久状态，以防 GitHub 并发性将最后一个待处理事件合并到突发中。特权工作者永远不会签出或执行拉取请求代码。操作默认跟随发布，因此相同的序列化工作者可以在 GitHub 抑制 `workflow_run` 事件时调度部署。固定操作到完整的已审查发布提交： ```yaml - uses: Forward-Future/DeployBot@3bf238140fba3d4d5fbd2d739b9f5422e99567dd ``` 操作使用 GitHub 内置的工作流令牌。GitHub 故意不将该令牌制作的合并转换为普通的 `push` 工作流运行，因此 DeployBot 在合并一批后调度每个配置的 CI 工作流。GitHub 还可以抑制该令牌驱动的 CI 运行后的通常 `workflow_run` 移交，因此 DeployBot 在确切的主要 CI 成功后明确调度每个配置的部署工作流。CI 工作流必须接受 `workflow_dispatch`。部署工作流必须接受名为 `ci_sha` 和 `ci_run_id` 的 `workflow_dispatch` 输入，验证 GitHub API 的运行，并仅在当前基本分支头部的成功 CI 时部署。跳过部署唤醒的拉取请求 CI 被忽略。设置操作输入 `dispatch_ci: "false"` 仅当调用者提供一个已经触发推送 CI 的不同合并身份时。 当集成 PR 检查依赖于普通的 PR 作者事件时，在较早的工作流步骤中创建一个 GitHub 应用程序安装令牌，并将其作为操作的 `token` 输入传递。设置 `integration.require_non_actions_author = true`，以便在缺少应用程序令牌时在冻结或创建不可用的集成 PR 之前失败。 将应用程序的确切机器人登录名（例如 `deploybot-app[bot]`）添加到 `queue.coordinator_actors`，以便其集成记录是受信任的。 部署工作流保留其正常的 `workflow_run` 触发器用于推送 CI，并为 DeployBot 调度的 CI 添加此确切输入恢复路径： ```yaml on: workflow_run: workflows: [CI] types: [completed] workflow_dispatch: inputs: ci_sha: required: true type: string ci_run_id: required: true type: string ``` 在发布之前，使用 `ci_run_id` 从 GitHub 读取运行，并要求其工作流名称、基本分支、头部 SHA、事件、状态和结论与预期的成功确切主要 CI 运行相匹配。部署仍必须提取当前基本分支，并在其不再等于 `ci_sha` 时停止。 工作流机器人和允许请求部署的每个人必须被明确列出： ```toml [queue] trusted_actors = ["@repository-owner"] coordinator_actors = ["@repository-owner", "github-actions[bot]"] ``` `@repository-owner` 解析为 `owner/repository` 中的所有者。组织存储库应将其替换为他们信任的确切人类或机器人登录名。协调员帐户可以促进、冻结、集成和完成批次，但不能创建原始的每个拉取请求部署意图。 ## 交付控制器 `deploybot status` 报告活动元数据代理线程、待处理本机通知、每个 PR 阶段、部署请求及其确切授权头部、队列顺序、队列和预队列意图重叠、确切 `main` CI、部署、管道暂停状态和每个未绑定到其本机打开线程的打开 PR。当部署请求超过配置的就绪合并目标时，它会发出警报，并命名当前的门。 它永远不会存储提示、转录、源或凭证。失败的 PR 汇总在 DeployBot 创建修复块之前，会与确切提交的检查运行进行协调，因此取消的被取代运行不会隐藏其替换。 `deploybot react` 促进就绪意图、跳过阻止器、排出独立工作，并在配置时创建集成 PR。新批次最多包含 `integration.max_batch_size` 条目；后来的 FIFO 工作保留在下一个批次中。较大的不可分割的源重叠或依赖关系闭包是唯一的例外：它单独发货，永远不会与无关工作混合。 在合并后，入口在累积的主要版本验证为实时之前保持关闭，防止较新的合并饿死较旧的部署。草稿状态和不完整的检查或审查保持等待状态；它们不会创建修复锁定。冲突、失败的门、未解决的审查、手动阻止或过时的授权头部会产生包含源线程、基本/头部 SHA、源路径和一个返回命令的修复移交。旧的仅草稿修复锁定会在控制器识别它们时自动清除： 在 `overlap` 模式下，当另一个活动、近似就绪意图属于同一个源重叠组件时，就绪源会等待。无关的就绪工作仍会排出，而被阻止的组件会一起冻结，一旦其剩余的门通过。 当多个累积集成拉取请求需要控制器拥有的确切头部 CI 时，DeployBot 会调度所有缺失的工作流，然后再等待。然后，这些工作流并行运行，而不是让后续批次等待较早的运行器延迟。慢队列状态会命名缺失、排队或失败的确切集成工作流，而不是仅报告通用合并工作器。 ```bash deploybot resume <pr-number> ``` `resume` 原子地验证替换头部，清除阻止，重新排队，并发出新的唤醒事件。`follow` 跟踪较新的累积 `main` 修订版，直到确切的 CI、部署和可选的 HTTP 检查通过。CI 或部署失败可以暂停进一步合并，直到 `deploybot unpause`。 在呈现取消暂停请求之前，适配器必须刷新 `deploybot status --json` 并抑制过时的提示，当持久控制器已经运行或版本提前时。原始部署指令授权协调器在匹配的失败版本通过其选定的修复头部后取消暂停。传递该状态结果的失败主 SHA 和唯一 `control_id` 到 `deploybot unpause --sha SHA --control-id ID`，以便并发的新暂停保持权威。回滚、绕过和不匹配的恢复仍然需要明确的用户方向。 在开始确切的主要恢复之前，代理运行 `deploybot claim-release-repair --provider CLIENT --thread-id ID`。确定性分支引用为该失败的 SHA 选择一个确切的修复所有者；其他线程接收记录的所有者而不是创建重复的 PR。 在合并时，DeployBot 记录一个非过期的通知义务。在确切的主要验证中，它将每个包含的义务提升为 `pending`，当该线程未移动时，将匹配的 PR-打开线程移动到 `deployed`，并为每个线程返回一个稳定的 `thread_notifications` 载荷。提供者适配器将提供的消息发布到本机线程；对于 Codex，它使用 `send_message_to_thread` 唤醒线程。然后，PR-打开线程确认传递并变为 `completed`。消息是带有拉取请求标题和链接、可读的版本收据，包含其版本说明的前三个功能亮点、确切的部署 `main` 和 CI/部署证据。适配器原样呈现收据并保持成功的确认 ID 内部。PR 作者的文本被渲染为惰性；只有 DeployBot 生成的 PR 和版本证据链接保持可点击： ```bash deploybot thread acknowledge --provider codex --thread-id "$CODEX_THREAD_ID" \ --notification-id "$DEPLOYBOT_NOTIFICATION_ID" ``` DeployBot 不将注册表评论视为用户通知。如果本机交付失败，则在待处理 `notifications` 下，独立的邮箱条目仍然可见，即使 PR-打开线程启动了新的工作，并且相同的 `notification_id` 可以重试。当配置了 `pipeline.webhook_url_env` 时，提供者中立的 webhook 还会收到 `thread-deployed` 载荷，调度跟随者会重试它。没有配置 webhook 时，待处理收据不会使版本工作者运行；源适配器的本机线程心跳检索、确认并显示最终通知。 在 `pr-draft`、`pr-review` 或 `ready` 阶段的第一个受信任的 `thread update` 包含 PR 编号，该编号不可更改地将该 PR 绑定到其打开的本机线程。后续部署、修复、集成和协调器线程无法替换它。`deploybot request` 使用记录的所有者，即使另一个线程授权版本。未拥有的 PR 无法进入交付管道，因此 DeployBot 永远不会将其收据静默路由到授权调用者。请求结果在 `notification_handoff.required_action` 中明确此所有权；客户端必须在结束 PR-打开线程响应之前完成此操作。 ```toml [pipeline] ci_workflows = ["CI"] deploy_workflows = ["Deploy"] batch_settle_seconds = 15 ci_failure_grace_seconds = 90 promotion_workers = 4 hold_merges_while_releasing = true repair_branch_prefix = "deploybot/repair" ready_to_merge_target_minutes = 15 merge_to_live_target_minutes = 10 auto_promote = true intent_scope = "head" pause_on_failure = true [[pipeline.verifications]] name = "Login" url = "https://example.com/login" expected_status = 200 [integration] # manual, overlap, or all (一个累积的预合并验证 PR) mode = "overlap" max_batch_size = 3 # require_non_actions_author = true # ci_satisfies_checks = ["Stable PR head", "Full test suite"] ``` 对于 `overlap` 或 `all` 模式与托管协调器，请在存储库的操作工作流权限设置下启用 **允许 GitHub 操作创建和批准拉取请求**。`deploybot doctor` 报告此先决条件。 ## 审查提供者 所需的检查始终是确切的头部门。可选提供者使用标准化的通过、等待或阻止的裁决。 ```toml [queue] required_checks = ["CI"] [review] [[review.providers]] kind = "github-approvals" name = "人类审批" allowed_reviewers = ["reviewer-login"] minimum_approvals = 1 [[review.providers]] kind = "bot" name = "审查机器人" login = "review-bot" check_name = "审查机器人" require_formal_review = true require_resolved_threads = true ``` 机器人分数是可选的。当使用时，其评论必须包含确切的审查提交 SHA，以便较旧的分数永远不会授权替换头部。 ## 客户端 - Codex：安装 CLI 和 CLI 插件，在 `adapters/codex/agent-merge-queue` 下。Codex 适配器故意不启动 MCP 子进程。 - Claude Code：在 `adapters/claude-code` 下安装插件。 - Cursor：复制 `adapters/cursor` 下的文件或使用其 MCP 配置。 - 其他客户端：通过 stdio 连接 `deploybot-mcp` 或直接调用 CLI。 Claude Code 和 Cursor MCP 配置使用 `uvx` 启动固定的公共版本。 `mergeq` 和 `mergeq-mcp` 命令别名保留用于兼容性。 ## 命令概述 所有命令都接受全局 `--config PATH` 和 `--repository OWNER/REPO` 选项，然后是子命令。缺少拉取请求选择器会解析为当前分支的 PR。 ```text deploybot init [--force] deploybot ensure-labels deploybot status --json deploybot plan --json deploybot doctor --json deploybot inspect [PR] --json deploybot thread update --provider CLIENT --thread-id ID --phase PHASE [metadata] deploybot thread acknowledge --provider CLIENT --thread-id ID --notification-id ID deploybot request [PR] [--provider CLIENT] [--thread-id ID] [--thread-url URL] deploybot cancel-request [PR] deploybot refresh-request [PR] deploybot enqueue [PR] deploybot promote deploybot freeze --json deploybot drain --json deploybot react [--follow] [--dispatch-ci] [--timeout SECONDS] deploybot integrate [--all] deploybot follow [--timeout SECONDS] [--poll SECONDS] [--json] deploybot metrics --json deploybot pause --reason "main CI failed" deploybot unpause --sha FAILED_MAIN_SHA --control-id PAUSE_CONTROL_ID deploybot block [PR] --reason "..." deploybot unblock [PR] deploybot resume [PR] deploybot dequeue [PR] --reason "..." deploybot merge [PR] --batch BATCH_ID ``` `status` 是只读的完整交付视图。`plan` 是仅限队列的较窄视图。`doctor` 在不更改存储库的情况下验证 CLI 身份验证、策略、标签、操作员、检查名称和分支保护。 MCP 服务器为操作命令提供了命名等价物，以及每个工具的显式 `repository` 和 `config` 参数。有关确切的映射和参数，请参见 [完整参考](docs/reference.md#mcp-tools)。 `drain` 仅合并独立、绿色、确切头部审查的 PR。集成模式 `overlap` 为共享源创建一个累积的 PR；模式 `all` 将整个冻结批次路由到一个累积的 PR，然后再到 `main`。DeployBot 永远不会发明冲突解决：它准备分支并将确切的修复交回代理。