Skip to content

docs(agents): document Release Manager automation that cuts and promotes release tags - #1956

Merged
don-petry merged 2 commits into
mainfrom
claude/issue-1899-epic-unblock-26fy14
Sep 26, 2026
Merged

don-petry merged 2 commits into
mainfrom
claude/issue-1899-epic-unblock-26fy14

Conversation

@don-petry

@don-petry don-petry commented Sep 26, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Updates AGENTS.md and docs/release/runbook.md to say what the Release Manager automation already does. It auto-cuts every release tag for the next channel and promotes releases through the rings, so contributors stop hand-cutting releases after routine merges.

AGENTS.md:

  • Reframed "Merging to main does not activate agent code": a merge is still inert, but next catches 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.
  • New subsection "Release automation — who cuts and moves tags" (under "Release channel tags & the mutable-ref exception"). It covers:
    • the Canary Rollout workflow in petry-projects/.github, the petry-projects-release-manager[bot] App, and the standards/canary-rings.json registry;
    • 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's ring1 → stable;
    • when a manual cut-release.sh is still appropriate, how to check whether next actually moved (a release tag existing isn't enough), and the two rollback paths;
    • that a release needing a human go/no-go must be configured in canary-rings.json before its candidate reaches the ring. An issue label like dev-lead:hands-off does not stop the promotion gate.
  • Replaced the stale bullet that called the health-gated promotion workflow "(forthcoming)".
  • Channel-skew sequencing step 2 now uses cut-release.sh --promote to move to an existing release.

docs/release/runbook.md (brought in line from review feedback):

Problem

AGENTS.md and the runbook told readers a merge stays inert until someone runs cut-release.sh, and that the promotion workflow was still to come. In practice:

The docs also didn't make clear that, once CANARY_AUTO_PROMOTE is armed, most agents (pr-review included) reach stable with no human step. That matters for canaries that expect a human go/no-go, such as epic #1895 / #1899.

Sources checked:

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 in tests/dev-lead/integration/test_reusable_pin_compliance.py still resolve.

Test plan

  • npx markdownlint-cli2@0.23.2 AGENTS.md docs/release/runbook.md (the version lint.yml pins, with the repo's .markdownlint-cli2.jsonc): 0 issues.
  • Checked that the anchor #release-automation--who-cuts-and-moves-tags matches the heading slug and is used by all three cross-links (two in AGENTS.md, one in the runbook).
  • Ran the documented git ls-remote --tags origin '<agent>/v<M>-next' '<agent>/vX.Y.Z^{}' check against pr-review/v1.18.0; the two SHAs match as described.
  • Nothing under 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.yml changed).

Interaction contract

  • N/A — this PR does not add or change an agentic role.

Checklist

  • shellcheck scripts/*.sh passes for any changed shell scripts. (No shell changes.)
  • Docs updated where behavior or standards changed.

🤖 Generated with Claude Code

https://claude.ai/code/session_015fdDZDb4mhT65MU1izeA4R

…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
@don-petry
don-petry requested a review from a team as a code owner September 26, 2026 23:18
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

@qodo-code-review

Copy link
Copy Markdown

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

@coderabbitai

coderabbitai Bot commented Sep 26, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

Next included review available in 3 minutes.

Check out review usage here.

View limit details

Limit 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.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 80abce67-04e3-44b4-aabf-59ecd2c8da97

📥 Commits

Reviewing files that changed from the base of the PR and between e6cdf20 and 9a89c40.

📒 Files selected for processing (2)
  • AGENTS.md
  • docs/release/runbook.md

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@don-petry

Copy link
Copy Markdown
Collaborator Author

Dev-Lead — waiting on PR blockers (intent: review-changes)

PR: #1956
No changes were committed, but the PR still can't be marked done: required check SonarCloud is still pending. The retry cron will re-attempt automatically. Next attempt after: 2026-09-26T23:50:09Z

@donpetry-bot

Copy link
Copy Markdown
Contributor

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.

@don-petry

Copy link
Copy Markdown
Collaborator Author

Note

@don-petry I reviewed this PR and no code changes were needed, but I can't mark it done yet: required check SonarCloud is still pending. I'll re-check automatically.
Next attempt after: 2026-09-26T23:50:09Z

@don-petry
don-petry enabled auto-merge (squash) September 26, 2026 23:20
Comment thread AGENTS.md Resolved
Comment thread AGENTS.md Resolved
Comment thread AGENTS.md Resolved
@don-petry

Copy link
Copy Markdown
Collaborator Author

No description provided.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread AGENTS.md Resolved
Comment thread AGENTS.md Resolved
@don-petry
don-petry disabled auto-merge September 26, 2026 23:21
… 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
@sonarqubecloud

Copy link
Copy Markdown

@donpetry-bot

Copy link
Copy Markdown
Contributor

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 donpetry-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@don-petry

Copy link
Copy Markdown
Collaborator Author

Acknowledged — CodeRabbit hit its OSS review rate limit and produced no findings on this PR (it lists only AGENTS.md and docs/release/runbook.md as selected for processing, with no review comments). No action needed; the substantive review threads from codeant-ai and gemini-code-assist have been addressed separately.

@don-petry

Copy link
Copy Markdown
Collaborator Author

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.

@don-petry

Copy link
Copy Markdown
Collaborator Author

Acknowledged — this is a Qodo billing/trial-ended notice (reviews paused), not a review finding. No action needed on the PR content.

@don-petry

Copy link
Copy Markdown
Collaborator Author

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.

@don-petry
don-petry merged commit d8c2361 into main Sep 26, 2026
75 of 158 checks passed
@don-petry
don-petry deleted the claude/issue-1899-epic-unblock-26fy14 branch September 26, 2026 23:27

@donpetry-bot donpetry-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 donpetry-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@donpetry-bot

Copy link
Copy Markdown
Contributor

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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants