Repository navigation
docs(agents): document Release Manager automation that cuts and promotes release tags - #1956
Conversation
…tes release tags AGENTS.md told contributors that a merge stays inert until someone runs `cut-release.sh`, and called the health-gated promotion workflow "forthcoming". In practice the Release Manager (the `Canary Rollout` workflow in petry-projects/.github, acting as the petry-projects-release-manager[bot] App) already auto-cuts `<agent>/vX.Y.Z` and moves `<agent>/v<MAJOR>-next` every 4h sweep, and promotes through the rings when armed. That left sessions hand-cutting after merges and colliding with tags the bot had already created. - Reframe "Merging to main does not activate agent code": still inert on merge, but `next` catches up on the next autocut sweep and later rings move by gated promotion. The rule is now to state when a change reaches each channel. - New "Release automation — who cuts and moves tags" subsection: autocut / promote-all / sync-issues, their arm variables (CANARY_AUTO_CUT, CANARY_AUTO_PROMOTE), bump detection, watched paths, require_confirmation (today only dev-lead ring1->stable), when to hand-cut, rollback paths, and that a human go/no-go must be configured in canary-rings.json before the candidate reaches the ring. - Replace the stale "(forthcoming) promotion workflow" bullet and update the channel-skew sequencing step accordingly. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015fdDZDb4mhT65MU1izeA4R
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing |
|
Warning Review limit reachedNext included review available in 3 minutes. View limit detailsLimit details: You’ve used the included review currently available. You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Review configuration: ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Advanced Run ID: 📒 Files selected for processing (2)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Dev-Lead — waiting on PR blockers (intent: review-changes)PR: #1956 |
|
Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-09-27T00:20:11Z. |
|
Note @don-petry I reviewed this PR and no code changes were needed, but I can't mark it done yet: required check |
|
No description provided. |
There was a problem hiding this comment.
Code Review
This pull request updates the AGENTS.md documentation to detail the new Release Manager automation, which handles auto-cutting and moving release tags for agents. It explains the automated release steps (autocut, promote-all, sync-issues), details when manual intervention or manual runs of cut-release.sh are still appropriate, and updates the workflow sequencing instructions. The review feedback suggests standardizing the version placeholders (e.g., changing <ver> and <X.Y.Z> to <version>) throughout the document for consistency.
… promotion text Addresses CodeAnt review findings on #1956: - AGENTS.md: an existing release tag does not prove `next` moved, because autocut creates the release before moving the channel. Tell readers to compare `<agent>/v<M>-next` with the release's commit and to use `--promote` (not a new cut) if it lags. - AGENTS.md channel-skew step 2: show `cut-release.sh --promote --channel` for moving to an existing release. Without `--promote` it always cuts a new tag and fails when the version exists. - docs/release/runbook.md: add a "current state" note pointing at the Release Manager automation and at the AGENTS.md section. Replace the "Phase-1 human-driven" promotion rule, the stale "no channel-only-move mode / use git tag -f + push --force" gap (superseded by --promote #992; a force-push of a protected channel is rejected with GH013), the stale cross-repo "refuses a live cut" note (#872 wired), and the "#501 is future work" bullets. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015fdDZDb4mhT65MU1izeA4R
|
|
Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-09-27T00:23:10Z. |
donpetry-bot
left a comment
There was a problem hiding this comment.
Automated review — APPROVED ✓
Risk: LOW
Reviewed commit: 9a89c40c3eae6150c74b3cdb54ef68b389884837
Review mode: triage-approved (single reviewer)
Summary
Docs-only PR (2 files: AGENTS.md, docs/release/runbook.md; +111/-36) documenting the Release Manager automation that auto-cuts and promotes release tags. It corrects stale guidance that told maintainers to hand-cut releases (which now collides with autocut) and that called the promotion workflow forthcoming. No code, workflow, or config changes. Triage's low-risk assessment is confirmed.
Linked issue analysis
No closing issue reference — correct: the PR is a docs correction spun out of epic #1899 (open, on hold), which it references for context without closing. The PR body substantively documents the problem (maintainers hitting 'release tag already exists' after autocut) and the sources checked (canary-rollout.yml, canary-rings.json, tagger history).
Findings
- No blocking findings.
- Docs content is internally consistent: the runbook's stale 'human-driven / git tag -f' instructions are updated in the same PR that changes AGENTS.md, resolving the contradiction a bot reviewer flagged (thread resolved).
- All 5 review threads (codeant-ai x3, gemini-code-assist x2) are resolved; two were outdated by follow-up commits on this branch.
- Anchor slug #release-automation--who-cuts-and-moves-tags matches the new heading and both cross-links.
- Secret scan: run_secret_scanning MCP tool unavailable in this environment; gitleaks CI check passed (SUCCESS), and the diff is prose only.
CI status
All checks green on head SHA: Lint, ShellCheck, unit-tests, holdout-guard, SonarCloud (+ Code Analysis), CodeQL Analyze (actions/python), Secret scan (gitleaks), Agent Security Scan, agent-shield, guard, sync-scope-guard, duplicate-decl-gate, Compile agentic workflows — SUCCESS. cubic AI reviewer NEUTRAL (non-blocking); dependency-audit sub-jobs SKIPPED (no matching ecosystems); cancelled dev-lead dispatch/relay runs are superseded orchestration runs, not failures.
Reviewed automatically by the PR-review agent (single-reviewer mode: fable 5). Reply if you need a human review.
|
Acknowledged — CodeRabbit hit its OSS review rate limit and produced no findings on this PR (it lists only |
|
Acknowledged — this is a Codex usage-limit notice, not a review finding. No code change is warranted; the actionable review threads on this PR have been addressed separately. |
|
Acknowledged — this is a Qodo billing/trial-ended notice (reviews paused), not a review finding. No action needed on the PR content. |
|
Acknowledged — SonarCloud Quality Gate passed with 0 new issues, 0 security hotspots, and no duplication on new code. This is a passing-status notice, not a finding; no action needed. |
donpetry-bot
left a comment
There was a problem hiding this comment.
Automated review — APPROVED ✓
Risk: LOW
Reviewed commit: 9a89c40c3eae6150c74b3cdb54ef68b389884837
Review mode: triage-approved (single reviewer)
Summary
Docs-only PR updating AGENTS.md and docs/release/runbook.md to document the existing Release Manager automation (autocut -> promote-all -> sync-issues), replacing stale guidance that told maintainers to hand-cut releases and describing the runbook's manual path as the override. 2 files, +111/-36, no code, workflow, or config changes. Triage assessment (low-risk) confirmed.
Linked issue analysis
No closing issue reference (correct: this docs update does not complete an issue). The PR references epic #1895/#1899 (deep-tier canary with human go/no-go, still OPEN) as motivation, and the new docs directly support it by documenting that require_confirmation must be set in canary-rings.json before a candidate reaches the ring. Using a reference rather than a closing keyword avoids wrongly auto-closing the staged epic story.
Findings
- No blocking findings. Docs-only change; verified claims where checkable: the anchor #release-automation--who-cuts-and-moves-tags matches the new heading slug and its three cross-links; the section title "Release channel tags & the mutable-ref exception" referenced by test_reusable_pin_compliance.py is unchanged; markdownlint (Lint) and unit-tests are green.
- Runbook now correctly steers channel moves through cut-release.sh --promote instead of git tag -f + push --force (which the release-channel-tags ruleset rejects with GH013) — an improvement, not a risk.
- All 5 prior review threads (codeant-ai, gemini-code-assist) are resolved; prior bot review at this same SHA approved at LOW risk.
- Secret scan: run_secret_scanning MCP tool not available in this environment; gitleaks CI check passed (SUCCESS). No secret-like content in the diff (prose documentation only).
CI status
All completed checks green: Lint, ShellCheck, unit-tests, CodeQL (actions + python), SonarCloud, gitleaks secret scan, agent-shield, Agent Security Scan, holdout-guard, sync-scope-guard, duplicate-decl-gate all SUCCESS. Remaining CANCELLED entries are superseded dev-lead/review orchestration runs from earlier pushes; dependency-audit ecosystems SKIPPED (no dependency changes); cubic reviewer NEUTRAL. No failures.
Reviewed automatically by the PR-review agent (single-reviewer mode: fable 5). Reply if you need a human review.
donpetry-bot
left a comment
There was a problem hiding this comment.
Automated review — APPROVED ✓
Risk: LOW
Reviewed commit: 9a89c40c3eae6150c74b3cdb54ef68b389884837
Review mode: triage-approved (single reviewer)
Summary
Docs-only PR (AGENTS.md + docs/release/runbook.md, +111/−36) documenting the Release Manager automation (Canary Rollout workflow in petry-projects/.github) that auto-cuts release tags and promotes them through rings. Replaces stale guidance that promotion is fully human-driven, adds the autocut/promote-all/sync-issues table, and corrects the channel-move procedure to use cut-release.sh --promote instead of a force-pushed tag (rejected by the release-channel-tags ruleset). Triage's low-risk assessment is confirmed.
Linked issue analysis
No closing issue reference, which is correct: the branch (claude/issue-1899-epic-unblock) references epic #1899 (deep-tier canary rollout, open, on hold), and this PR unblocks it by documenting the release automation rather than completing it. The PR body is thorough and accurately describes the change.
Findings
- No blocking findings. Docs-only; no code, workflow, secret, or dependency changes.
- All 5 inline review threads (codeant-ai x3, gemini-code-assist x2) are resolved; the codeant-ai AGENTS.md/runbook consistency concern was addressed in the runbook update.
- All advisory-bot notices (Codex/Qodo/CodeRabbit rate or billing limits, SonarCloud pass) were explicitly dispositioned as informational by don-petry; no unanswered human questions.
- Prior approval from donpetry-bot already on the head SHA (reviewDecision: APPROVED).
- run_secret_scanning MCP tool not available in this environment; the gitleaks CI check (SUCCESS) covers secret scanning.
CI status
All substantive checks green on 9a89c40: Lint, ShellCheck, CodeQL (actions + python), SonarCloud quality gate, Secret scan (gitleaks), agent-shield, Agent Security Scan, unit-tests, holdout-guard, sync-scope-guard, duplicate-decl-gate, Compile agentic workflows. CANCELLED entries are superseded dev-lead dispatch/ci-relay/resume runs from the prior SHA (each has a later SUCCESS/SKIPPED run); the one QUEUED pr-auto-review/check-and-dispatch is this review's own dispatch. cubic reported NEUTRAL; dependency-audit ecosystems all SKIPPED (no manifests changed).
Reviewed automatically by the PR-review agent (single-reviewer mode: fable 5). Reply if you need a human review.
|
pr-review approved on PARTIAL advisory evidence: 4/7 required advisory bots reported before the gate's quiescence-timeout fallback proceeded. Recorded for the miss-rate metric (#1596). |



Summary
Updates
AGENTS.mdanddocs/release/runbook.mdto say what the Release Manager automation already does. It auto-cuts every release tag for thenextchannel and promotes releases through the rings, so contributors stop hand-cutting releases after routine merges.AGENTS.md:maindoes not activate agent code": a merge is still inert, butnextcatches up on the next autocut sweep and later rings move by gated promotion. The rule changes from "state whether a channel cut is required" to state when the change reaches each channel.Canary Rolloutworkflow inpetry-projects/.github, thepetry-projects-release-manager[bot]App, and thestandards/canary-rings.jsonregistry;autocut→promote-all→sync-issues, their arm variables (CANARY_AUTO_CUT,CANARY_AUTO_PROMOTE), watched paths, and bump detection;require_confirmation, which today is set only on dev-lead'sring1 → stable;cut-release.shis still appropriate, how to check whethernextactually moved (a release tag existing isn't enough), and the two rollback paths;canary-rings.jsonbefore its candidate reaches the ring. An issue label likedev-lead:hands-offdoes not stop the promotion gate.cut-release.sh --promoteto move to an existing release.docs/release/runbook.md(brought in line from review feedback):cut-release.sh --promote(feat(cut-release): add --promote for ring-to-ring channel moves (#501) #992) instead ofgit tag -f+push --force, which the ruleset now rejects with GH013.Problem
AGENTS.mdand the runbook told readers a merge stays inert until someone runscut-release.sh, and that the promotion workflow was still to come. In practice:pr-review/v1.17.0,dev-lead/v139.33.0andci-failure-analyst/v1.29.0after feat: implement issue #1898 — [Phase 2] Swap the deep tier to claude-opus-5-5 in engine.sh (model, chain, label, effort) #1935 merged, without anyone asking.v1.18.0,v139.34.0andv1.30.0about 46 minutes after feat(token-metrics): record per-call engine latency (duration_ms) (#1949) #1955 merged.release tag … already existson all three.The docs also didn't make clear that, once
CANARY_AUTO_PROMOTEis armed, most agents (pr-review included) reachstablewith no human step. That matters for canaries that expect a human go/no-go, such as epic #1895 / #1899.Sources checked:
petry-projects/.github.github/workflows/canary-rollout.yml, the header and cron33 */4 * * *;standards/canary-rings.json, including the_autocut_note,agent_ref_pathsand per-agentgate.transitions;e4ad94d);pr-review/*,dev-lead/*andci-failure-analyst/*releases.Risk
Low. The change is documentation only, in two files (
AGENTS.md,docs/release/runbook.md), with no code, workflow or config changes. The section title "Release channel tags & the mutable-ref exception" is unchanged, so the references to it intests/dev-lead/integration/test_reusable_pin_compliance.pystill resolve.Test plan
npx markdownlint-cli2@0.23.2 AGENTS.md docs/release/runbook.md(the versionlint.ymlpins, with the repo's.markdownlint-cli2.jsonc): 0 issues.#release-automation--who-cuts-and-moves-tagsmatches the heading slug and is used by all three cross-links (two in AGENTS.md, one in the runbook).git ls-remote --tags origin '<agent>/v<M>-next' '<agent>/vX.Y.Z^{}'check againstpr-review/v1.18.0; the two SHAs match as described.tests/,scripts/or.github/asserts the reworded sentences (checked with grep).Rollback
Revert this PR. No side effects.
Monitoring
n/a — no runtime effect. This is documentation only, so no channel cut is required (nothing under
scripts/,prompts/,personas/or a*-reusable.ymlchanged).Interaction contract
Checklist
shellcheck scripts/*.shpasses for any changed shell scripts. (No shell changes.)🤖 Generated with Claude Code
https://claude.ai/code/session_015fdDZDb4mhT65MU1izeA4R