{"id":51165586,"url":"https://github.com/Forward-Future/DeployBot","last_synced_at":"2026-07-15T03:00:33.936Z","repository":{"id":366231234,"uuid":"1275534185","full_name":"Forward-Future/DeployBot","owner":"Forward-Future","description":"Agent-managed GitHub merge queue for Codex, Claude Code, Cursor, and MCP clients","archived":false,"fork":false,"pushed_at":"2026-06-20T21:51:48.000Z","size":69,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T22:13:52.535Z","etag":null,"topics":["claude-code","codex","coding-agents","github-actions","mcp","merge-queue"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Forward-Future.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-20T20:22:48.000Z","updated_at":"2026-06-20T22:13:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Forward-Future/DeployBot","commit_stats":null,"previous_names":["forward-future/deploybot"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Forward-Future/DeployBot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forward-Future%2FDeployBot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forward-Future%2FDeployBot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forward-Future%2FDeployBot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forward-Future%2FDeployBot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Forward-Future","download_url":"https://codeload.github.com/Forward-Future/DeployBot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forward-Future%2FDeployBot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35488230,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-15T02:00:06.706Z","response_time":131,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","codex","coding-agents","github-actions","mcp","merge-queue"],"created_at":"2026-06-26T19:00:22.701Z","updated_at":"2026-07-15T03:00:33.925Z","avatar_url":"https://github.com/Forward-Future.png","language":"Python","funding_links":[],"categories":["MCP 服务器精选列表"],"sub_categories":["🔄 版本控制 (Git / GitHub / GitLab)"],"readme":"# DeployBot\n\nDeployBot is a provider-neutral GitHub merge queue for coding agents.\nCodex, Claude Code, Cursor, or any MCP client can prepare and review a pull\nrequest; the user keeps the final merge decision by saying `deploy`.\n\nDeployBot stores authority in GitHub labels and authenticated comments. It\nrecords deploy intent immediately, promotes the final exact reviewed head,\nfreezes bursts, merges independent work back-to-back, scaffolds cumulative\nintegration PRs, follows `main` through production, and pauses after failures.\n\n## Install\n\nInstall the reviewed `v0.2.25` source commit directly from GitHub:\n\n```bash\npython3 -m pip install \\\n  'deploybot-merge-queue[mcp] @ git+https://github.com/Forward-Future/DeployBot.git@3fb42e2e3cf3a6f21cddf43e3d06deaa24a3ac80'\ndeploybot init\n```\n\n`deploybot init` writes the safe starter policy. The annotated\n[example policy](.mergequeue.example.toml) shows every supported section, and\nthe [CLI, MCP, policy, and Action reference](docs/reference.md) lists every\ncurrent command, tool, option, and configuration field.\n\nInvoke the bundled `$deploybot` skill to inspect or operate the queue. Typical\nrequests include “show the delivery pipeline,” “why is PR 42 blocked?”, and\n“deploy this PR.” Status and diagnostics are read-only:\n\n```bash\ndeploybot status\ndeploybot status --json\ndeploybot doctor\ndeploybot metrics --json\ndeploybot inspect 42 --json\n```\n\nFor development from the Astro source tree, install\n`./packages/agent-merge-queue[mcp]` instead.\n\nEdit `.mergequeue.toml` to name the required checks, optional review providers,\nand every exact GitHub login whose queue markers are trusted. Do not grant\nauthority by broad repository role. GitHub verifies comment authors; its normal\ntoken permissions control label, comment, and merge writes. Authentication\ncomes from the GitHub CLI:\n\n```bash\ngh auth login\ndeploybot ensure-labels\ndeploybot doctor\n```\n\nThe base installation has no review-service dependency. Repositories can use\nrequired checks alone or add GitHub approvals, a generic bot, an agent-review\ncheck, or any combination.\n\n## Security model\n\nProtect the base branch with a GitHub ruleset that independently requires the\nsame checks named in `.mergequeue.toml`, and do not give DeployBot's merge\ncredential permission to bypass that ruleset. DeployBot reads check display\nnames to coordinate the queue; GitHub's ruleset is the authoritative check\nidentity and the final atomic merge guard.\n\nKeep workflow changes reviewed, pin third-party Actions to full commit hashes,\nand never execute pull-request-head code in the privileged coordinator. The MCP\nserver uses the local process's existing GitHub credentials and accepts explicit\nrepository selectors, so run it only from a trusted coding client and workspace.\n\n## Durable manual deploy gate\n\nThe installed agent adapter treats the user's exact `deploy` instruction as\nauthority for that thread's PR only. It records the intent immediately—even if\nCI or review is still running:\n\n```bash\ndeploybot request \u003cpr-number\u003e \\\n  --provider codex --thread-id \"$CODEX_THREAD_ID\"\n```\n\nThe event worker promotes only the intent-bound exact head after all checks and\nreview providers pass. If review fixes create a replacement head, the trusted\nsource agent runs `deploybot refresh-request \u003cpr\u003e` after its fresh evidence;\nthe user does not repeat `deploy`. No polling timer is involved.\n\nInstall `examples/github-workflow.yml` on the default branch. It reacts to\ndeploy labels, ready/synchronize events, reviews, named CI `workflow_run`\ncompletions, and completed external check suites. Keep its `workflows` list\naligned with `pipeline.ci_workflows`. Each wake runs two independently\nserialized jobs: the queue reactor can admit more ready work immediately, while\nthe release-only follower owns cumulative exact `main` through CI, deployment,\nand verification. The follower exits immediately when no release needs work and\ndispatches deployment when GitHub suppresses the `workflow_run` handoff for\ntoken-dispatched CI, avoiding a wait for the five-minute scheduled\nreconciliation. The schedule still rereads all durable state if GitHub\nconcurrency coalesces the last event in a burst. Neither privileged job checks\nout or executes pull-request code. Pin the Action to the full reviewed release\ncommit:\n\n```yaml\n- uses: Forward-Future/DeployBot@3fb42e2e3cf3a6f21cddf43e3d06deaa24a3ac80\n```\n\nThe Action uses GitHub's built-in workflow token. GitHub intentionally does not\nturn merges made by that token into ordinary `push` workflow runs, so DeployBot\ndispatches each configured CI workflow once after it merges a batch. GitHub can\nalso suppress the usual `workflow_run` handoff after that token-driven CI run,\nso DeployBot explicitly dispatches each configured deployment workflow after\nexact-main CI succeeds. CI workflows must accept `workflow_dispatch`.\nDeployment workflows must accept `workflow_dispatch` inputs named `ci_sha` and\n`ci_run_id`, verify that run through the GitHub API, and deploy only when it is\nsuccessful CI for the current base-branch head. Skipped deployment wake-ups\nfrom pull-request CI are ignored. Set Action input `dispatch_ci: \"false\"` only\nwhen a caller supplies a different merge identity that already triggers push\nCI.\n\nWhen integration PR checks depend on normal PR-authored events, mint a GitHub\nApp installation token in an earlier workflow step and pass it as the Action's\n`token` input. Set `integration.require_non_actions_author = true` so a missing\nApp token fails before it freezes or creates an unusable integration PR. Add\nthe App's exact bot login (for example, `deploybot-app[bot]`) to\n`queue.coordinator_actors` so its integration records are trusted.\n\nThe deployment workflow keeps its normal `workflow_run` trigger for push CI\nand adds this exact-input recovery path for DeployBot-dispatched CI:\n\n```yaml\non:\n  workflow_run:\n    workflows: [CI]\n    types: [completed]\n  workflow_dispatch:\n    inputs:\n      ci_sha:\n        required: true\n        type: string\n      ci_run_id:\n        required: true\n        type: string\n```\n\nBefore releasing, use `ci_run_id` to read the run from GitHub and require its\nworkflow name, base branch, head SHA, event, status, and conclusion to match the\nexpected successful exact-main CI run. The deployment must still pull the\ncurrent base branch and stop if it no longer equals `ci_sha`.\n\nThe deployment workflow must also acquire the repository's shared deployment\nlock, fetch the base branch again after acquiring it, and coalesce superseded\nrequests onto that newest integrated SHA. It must never deploy an older SHA after\na newer one, and it keeps the lock through production health verification. These\nrelease rules are unchanged by `release_admission = \"merged\"`; only merge\nadmission becomes asynchronous.\n\nThe workflow bot and each person allowed to request deployment must be\nexplicitly listed:\n\n```toml\n[queue]\ntrusted_actors = [\"@repository-owner\"]\ncoordinator_actors = [\"@repository-owner\", \"github-actions[bot]\"]\n```\n\n`@repository-owner` resolves to the owner in `owner/repository`. Organization\nrepositories should replace it with the exact human or bot logins they trust.\nCoordinator accounts may promote, freeze, integrate, and complete batches, but\nthey cannot create the original per-pull-request deploy intent.\n\n## Delivery controller\n\n`deploybot status` reports active metadata-only agent threads, pending native\nnotifications, every PR stage, deploy requests and their exact authorized heads,\nqueue order, queued and pre-queue intent overlaps, exact-`main` CI, deployment,\npipeline pause state, and every open PR that has not been bound to its native\nopening thread. It alerts when a deploy request exceeds the configured\nready-to-merge target and names the current gate. It never stores prompts,\ntranscripts, source, or credentials. A failed PR rollup is reconciled against\nthe exact commit's check runs before DeployBot creates a repair block, so a\ncancelled superseded run cannot hide its replacement.\n\n`deploybot react` promotes ready intent, skips blockers, drains independent\nwork, and creates integration PRs when configured. New batches contain at most\n`integration.max_batch_size` entries; later FIFO work remains in the next batch.\nA larger indivisible source-overlap or dependency closure is the sole exception:\nit ships alone, never mixed with unrelated work.\nBy default, `pipeline.release_admission = \"merged\"`: after one healthy merge,\nDeployBot immediately admits the next independent ready PR or batch. Exact-main\nCI, deployment, and health checks keep tracking asynchronously, and a later real\nfailure pauses future merges. Use `ci-passed` to wait for exact-main CI before\nadmitting more work, or `verified` to wait until the cumulative revision is live.\nDraft status and incomplete\nchecks or reviews remain waiting states; they do not create a repair latch. A\nconflict, failed gate, unresolved review, manual block, or stale authorized head\nproduces a repair handoff containing the source thread, base/head SHAs, source\npaths, and one return command. Old draft-only repair latches self-clear once the\ncontroller recognizes them:\n\nIn `overlap` mode, a ready source waits when another active, near-ready intent\nbelongs to the same source-overlap component. Unrelated ready work still drains,\nand the held component freezes together once its remaining gates pass.\nWhen more than one cumulative integration pull request needs controller-owned\nexact-head CI, DeployBot dispatches every missing workflow before it waits. The\nworkflows then run in parallel instead of making later batches wait for an\nearlier runner delay. Slow-queue status names the missing, queued, or failed\nexact integration workflow instead of reporting only a generic merge worker.\n\n```bash\ndeploybot resume \u003cpr-number\u003e\n```\n\n`resume` atomically verifies the replacement head, clears the block, requeues,\nand emits a new wake-up event. `follow` tracks newer cumulative `main` revisions\nuntil exact CI, deployment, and optional HTTP checks pass. A CI or deploy failure\ncan pause further merges until `deploybot unpause`.\nBefore presenting an unpause request, adapters must refresh `deploybot status\n--json` and suppress stale prompts when the durable controller is already\nrunning or the release advanced. The original deploy instruction authorizes the\ncoordinator to unpause the matching failed release after its elected repair\nhead passes fresh checks and review. Pass that status result's failed main SHA\nand unique `control_id` to `deploybot unpause --sha SHA --control-id ID` so a\nconcurrent newer pause remains authoritative. Rollback,\nbypass, and mismatched recovery still require explicit user direction.\n\nBefore starting an exact-main recovery, an agent runs\n`deploybot claim-release-repair --provider CLIENT --thread-id ID`. A\ndeterministic branch ref elects exactly one repair owner for that failed SHA;\nother threads receive the recorded owner instead of creating duplicate PRs.\n\nAt merge time, DeployBot records a non-expiring notification obligation. At\nexact-main verification, it promotes every contained obligation to `pending`,\nmoves the matching PR-opening thread to `deployed` when that thread has not\nmoved on, and returns a stable `thread_notifications` payload for each one.\nThe provider adapter posts the supplied message into that native thread; for\nCodex it wakes the thread with `send_message_to_thread`. The PR-opening thread\nthen acknowledges delivery and becomes `completed`. The message is a human-readable\nrelease receipt with the pull-request title and link, up to three feature\nhighlights from its release notes, the exact deployed `main`, and CI/deployment\nevidence. Adapters present that receipt verbatim and keep successful\nacknowledgement IDs internal. PR-authored text is rendered inert; only\nDeployBot-generated PR and release-evidence links remain clickable:\n\n```bash\ndeploybot thread acknowledge --provider codex --thread-id \"$CODEX_THREAD_ID\" \\\n  --notification-id \"$DEPLOYBOT_NOTIFICATION_ID\"\n```\n\nWhen `main` advances during a genuine repair, the next promotion pass records a\nnew `repair-required` event for the new base SHA even when the PR head and failure\ntext are unchanged. Every affected source owner can refresh in parallel; FIFO is\nstill enforced when repaired heads re-enter the merge queue.\n\nIntegration-conflict repair packets include the complete frozen pull-request and\nhead map. The elected owner must prove every frozen head is present before\nresuming the cumulative integration pull request.\n\nToken-authored integration PR `pull_request` runs are never accepted as exact CI\nevidence. This includes GitHub's `action_required` zero-job placeholder:\nDeployBot ignores it and dispatches the configured exact-branch\n`workflow_dispatch` run itself. Failures in that owned run still fail closed.\n\nDeployBot does not treat a registry comment as user notification. If native\ndelivery fails, an independent outbox entry stays visible under pending\n`notifications`, even if the PR-opening thread starts new work, and the same\n`notification_id` can be retried. When `pipeline.webhook_url_env` is configured,\nthe provider-neutral webhook also receives the `thread-deployed` payload and\nscheduled followers retry it. Without a configured webhook, pending receipts do\nnot keep the release worker running; the source adapter's native thread heartbeat\nretrieves, acknowledges, and displays the final notification instead.\nThe first trusted `thread update` in `pr-draft`, `pr-review`, or `ready` phase\nthat includes a PR number immutably binds that PR to its opening native thread.\nLater deploy, repair, integration, and coordinator threads cannot replace it.\n`deploybot request` uses that recorded owner even when another thread authorizes\nthe release. An unowned PR cannot enter the delivery pipeline, so DeployBot\nnever silently routes its receipt to the authorizing caller. The\nrequest result makes this ownership explicit in\n`notification_handoff.required_action`; clients must complete that action before\nending the PR-opening-thread response.\n\n```toml\n[pipeline]\nci_workflows = [\"CI\"]\ndeploy_workflows = [\"Deploy\"]\nbatch_settle_seconds = 0\nci_failure_grace_seconds = 90\npromotion_workers = 4\nhold_merges_while_releasing = true\nrepair_branch_prefix = \"deploybot/repair\"\nready_to_merge_target_minutes = 15\nmerge_to_live_target_minutes = 10\nauto_promote = true\nintent_scope = \"head\"\npause_on_failure = true\nrelease_admission = \"merged\" # or \"ci-passed\" / \"verified\" for stricter admission\n\n[[pipeline.verifications]]\nname = \"Login\"\nurl = \"https://example.com/login\"\nexpected_status = 200\n\n[integration]\n# manual, overlap, or all (one cumulative pre-merge validation PR)\nmode = \"overlap\"\nmax_batch_size = 3\n# require_non_actions_author = true\n# ci_satisfies_checks = [\"Stable PR head\", \"Full test suite\"]\n```\n\nFor `overlap` or `all` mode with the hosted coordinator, enable **Allow GitHub\nActions to create and approve pull requests** under the repository's Actions\nworkflow-permission settings. `deploybot doctor` reports this prerequisite.\n\n## Review providers\n\nRequired checks are always exact-head gates. Optional providers use normalized\npass, waiting, or blocked verdicts.\n\n```toml\n[queue]\nrequired_checks = [\"CI\"]\n\n[review]\n\n[[review.providers]]\nkind = \"github-approvals\"\nname = \"Human approval\"\nallowed_reviewers = [\"reviewer-login\"]\nminimum_approvals = 1\n\n[[review.providers]]\nkind = \"bot\"\nname = \"Review bot\"\nlogin = \"review-bot\"\ncheck_name = \"Review Bot\"\nrequire_formal_review = true\nrequire_resolved_threads = true\n```\n\nA bot score is optional. When used, its comment must contain the exact reviewed\ncommit SHA so an older score can never authorize a replacement head.\n\n## Clients\n\n- Codex: install the CLI and the CLI-only plugin under\n  `adapters/codex/agent-merge-queue`. The Codex adapter intentionally does not\n  start an MCP subprocess.\n- Claude Code: install the plugin under `adapters/claude-code`.\n- Cursor: copy the files under `adapters/cursor` or use its MCP configuration.\n- Other clients: connect `deploybot-mcp` over stdio or call the CLI directly.\n\nThe Claude Code and Cursor MCP configurations launch the pinned public release\nwith `uvx`.\nThe `mergeq` and `mergeq-mcp` command aliases remain for compatibility.\n\n## Command overview\n\nAll commands accept the global `--config PATH` and `--repository OWNER/REPO`\noptions before the subcommand. A missing pull-request selector resolves the PR\nfor the current branch.\n\n```text\ndeploybot init [--force]\ndeploybot ensure-labels\ndeploybot status --json\ndeploybot plan --json\ndeploybot doctor --json\ndeploybot inspect [PR] --json\ndeploybot thread update --provider CLIENT --thread-id ID --phase PHASE [metadata]\ndeploybot thread acknowledge --provider CLIENT --thread-id ID --notification-id ID\ndeploybot request [PR] [--provider CLIENT] [--thread-id ID] [--thread-url URL]\ndeploybot cancel-request [PR]\ndeploybot refresh-request [PR]\ndeploybot enqueue [PR]\ndeploybot promote\ndeploybot freeze --json\ndeploybot drain --json\ndeploybot react [--follow] [--dispatch-ci] [--timeout SECONDS]\ndeploybot integrate [--all]\ndeploybot follow [--timeout SECONDS] [--poll SECONDS] [--json]\ndeploybot metrics --json\ndeploybot pause --reason \"main CI failed\"\ndeploybot unpause --sha FAILED_MAIN_SHA --control-id PAUSE_CONTROL_ID\ndeploybot block [PR] --reason \"...\"\ndeploybot unblock [PR]\ndeploybot resume [PR]\ndeploybot dequeue [PR] --reason \"...\"\ndeploybot merge [PR] --batch BATCH_ID\n```\n\n`status` is the read-only full delivery view. `plan` is the narrower queue-only\nview. `doctor` verifies CLI auth, policy, labels, actors, check names, and branch\nprotection without changing the repository.\n\nThe MCP server exposes named equivalents for the operational commands, plus\nexplicit `repository` and `config` arguments on every tool. See the\n[complete reference](docs/reference.md#mcp-tools) for the exact mapping and\narguments.\n\n`drain` merges only independent, green, exact-head-reviewed PRs. Integration\nmode `overlap` creates one cumulative PR for shared source; mode `all` routes the\nwhole frozen batch through one cumulative PR before `main`. DeployBot never\ninvents a conflict resolution: it prepares the branch and hands the exact repair\nback to an agent.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FForward-Future%2FDeployBot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FForward-Future%2FDeployBot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FForward-Future%2FDeployBot/lists"}