docs(release): cut/promote/rollback runbook (#498)

[don-petry]

What

Add docs/release/runbook.md — the operational runbook for the per-agent channel-tag release model. Cross-linked from versioning.md.

Covers

• Roles & gating — cutting vX.Y.Z is harmless; promotion (moving stable) is human-driven and restricted by the release-channel-tags ruleset (OrgAdmin + Integration only).
• Cut — cut-release.sh <agent> <ver> --ref origin/main --push; refuses to overwrite immutable tags.
• Promote — cut+promote in one step for a new release; for an already-cut release, the direct git tag -f move (documents the cut-release.sh channel-only-move gap).
• Roll back — move stable back to the prior vX.Y.Z in < 5 min, no caller edits (promotion in reverse).
• Verify — confirm a caller run resolves @refs/tags/<agent>/stable (<sha>).
• Gotchas — stale-channel regression, CodeQL-on-PR synchronize trick, the SHA-pin exception.

Validation (#498 done-when)

The cut → promote → verify path was exercised live this cycle: pr-review/v1.5.3 (the #534 fix) and dev-lead/v1.2.0 cut + promoted, each verified by a caller run resolving the channel tag. Rollback is the same single tag-move in reverse against the immutable targets.

Closes #498. Pairs with the standards ratification PR petry-projects/.github#440.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive runbook documenting the release model and operational procedures for channel tag management
  • Updated versioning documentation with references to release and rollback procedures

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Warning

Review limit reached

@don-petry, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 40 minutes and 20 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: c6579044-899e-4f70-b7ed-b084765ca3e7

📥 Commits

Reviewing files that changed from the base of the PR and between 43c8965 and fa48022.

📒 Files selected for processing (1)

• docs/release/runbook.md

📝 Walkthrough

Walkthrough

This PR adds a comprehensive release runbook for agent versioning, documenting the per-agent channel-tag release model with immutable version tags and mutable stable channel tags. The new runbook covers cutting releases, promoting stable, rolling back, and verifying resolution, with operational gotchas and gating rules. Related versioning docs are updated to link to the new runbook.

Changes

Agent Release Runbook

Layer / File(s)	Summary
Release scheme and gating rules docs/release/runbook.md	Introduces the per-agent channel-tag model, distinguishing immutable version tags (<agent>/vX.Y.Z) from mutable channel tags (<agent>/stable), and defining roles and gating for cutting versus promoting releases.
Release operations procedures docs/release/runbook.md	Documents workflows for cutting immutable tags, promoting stable (both new and already-cut releases), rolling back by moving stable to prior tags, verifying caller resolution, and lists operational gotchas including promotion gating, channel behavior, stale pinning, and CodeQL defaults.
Runbook reference in versioning docs docs/release/versioning.md	Links the new runbook from the agent versioning & release channels section, replacing the inline runbook description with a reference to the dedicated documentation.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related issues

• [Phase 1] Release-cut + rollback runbook #498: This PR implements the exact release-cut/promotion/rollback runbook requested by issue #498, documenting the channel-tag model and operational procedures for safe per-agent releases.

Possibly related PRs

• petry-projects/.github-private#504: Both PRs are documentation-only and describe the "agent channel tags vs immutable version tags" safe-release strategy with mutable stable promote/rollback operations.
• petry-projects/.github-private#509: Complements this runbook by adding ruleset-based protection for the same pr-review/dev-lead mutable channel tags described in the operations procedures.

Suggested labels

documentation, initiative

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a release runbook for cutting, promoting, and rolling back releases, which is reflected in both the raw summary and PR objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/release-runbook

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive release runbook (runbook.md) detailing the operational procedures for cutting, promoting, and rolling back releases using the per-agent channel-tag release model, and updates versioning.md to reference this new document. The review feedback provides valuable improvements to the runbook, including refining the git tag listing command to filter out mutable channel tags during rollback, correcting the grep pattern for verifying workflow runs to ensure it matches the pr-review agent's workflow name, and improving readability/formatting in the "Gotchas" section.

[don-petry]

Dev-Lead — review-changes (applied)

Changes committed and pushed.

[Copilot]

Pull request overview

Adds an operational release runbook for the per-agent channel-tag model and links it from the existing versioning documentation, so operators have a single, cross-referenced procedure for cut/promote/rollback/verify.

Changes:

• Add docs/release/runbook.md documenting cut, promote, rollback, verification, and rollout “gotchas” for pr-review and dev-lead.
• Update docs/release/versioning.md to link to the new runbook.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
docs/release/versioning.md	Adds a cross-link to the new promote/rollback runbook.
docs/release/runbook.md	Introduces the operational runbook for cutting releases and moving per-agent channel tags.

[don-petry]

Dev-Lead — review-changes (applied)

Changes committed and pushed.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/release/runbook.md`:
- Around line 78-79: Update the wording in the runbook sentence that currently
says "re-creates the immutable tag first" to accurately say that `cut-release.sh
--channel` "creates the immutable tag" (not "re-creates") and clarify that it
will error if the `vX.Y.Z` tag already exists because immutable tags are never
overwritten; ensure the sentence references the `cut-release.sh --channel`
behavior and the `vX.Y.Z` tag existence check so it no longer implies modifying
an existing tag.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: cbcee46a-6368-44bd-8eb2-442b92ebf28d

📥 Commits

Reviewing files that changed from the base of the PR and between 58389d5 and 43c8965.

📒 Files selected for processing (2)

• docs/release/runbook.md
• docs/release/versioning.md

[don-petry]

@coderabbitai resolve

[don-petry]

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

PR: #558
No changes were committed, but the PR still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews). The retry cron will re-attempt automatically. Next attempt after: 2026-06-10T22:47:43Z

[don-petry]

Note

@don-petry I reviewed this PR and no code changes were needed, but it still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews), so I cannot mark it done yet. I'll re-check automatically.
Next attempt after: 2026-06-10T22:47:43Z

[coderabbitai]

✅ Action performed

Comments resolved and changes approved.

[don-petry]

Dev-Lead — review-changes (applied)

Changes committed and pushed.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[don-petry]

Dev-Lead — review-changes (no-changes)

No changes were needed for this PR.

[donpetry-bot]

Automated review — APPROVED ✓

Risk: LOW
Reviewed commit: fa480225b34cdfb3c48e113ce09f1a4d4a11dca6
Review mode: triage-approved (single reviewer)

Summary

Docs-only PR: adds docs/release/runbook.md (new, 172 lines) covering cut / promote / rollback / verify procedures for the per-agent channel-tag release model, plus a 3-line cross-link update in docs/release/versioning.md. No code, scripts, workflows, or config touched.

Linked issue analysis

Closes #498 (the runbook deliverable for the per-agent release model). The runbook covers all the body's stated scope — roles & gating (promotion human-driven, restricted by release-channel-tags ruleset), cut-release.sh usage and the immutable-tag refusal, the channel-only-move gap workaround via direct git tag -f, < 5-minute rollback, caller verification via the reusable-resolution log line, and the gotchas (stale-channel regression, CodeQL synchronize trick, SHA-pin exception). PR body documents that the cut → promote → verify path was exercised live this cycle against pr-review/v1.5.3 and dev-lead/v1.2.0.

Findings

No blocking issues. Internal cross-links in runbook.md (versioning.md, AGENTS.md, initiatives/agentic-release-strategy.md) point to real paths; the back-link from versioning.md correctly replaces the issue-tracker stub. Prior CodeRabbit review comments were addressed (CHANGES_REQUESTED dismissed, final review approved). Docs-only diff so no security, dependency, or runtime surface area.

CI status

All required checks green: Lint, ShellCheck, CodeQL (actions + python), Agent Security Scan, Secret scan (gitleaks), SonarCloud, unit-tests, Compile agentic workflows, AgentShield. Dependency-audit ecosystems correctly skipped (none applicable). review / review is queued for the new run but a prior review / review already completed SUCCESS.

---

Reviewed automatically by the PR-review agent (single-reviewer mode: opus 4.7). Reply if you need a human review.

[donpetry-bot]

Automated review — APPROVED ✓

Risk: LOW
Reviewed commit: fa480225b34cdfb3c48e113ce09f1a4d4a11dca6
Review mode: triage-approved (single reviewer)

Summary

Docs-only PR adding docs/release/runbook.md (172 lines) and updating a cross-link in docs/release/versioning.md (3-line edit). Closes #498. No code, scripts, workflows, or configuration touched. Triage assessment is confirmed: LOW risk.

Linked issue analysis

Issue #498 calls for the cut/promote/rollback runbook for the per-agent channel-tag release model. The new runbook covers each required area: roles & gating (who can move <agent>/stable), cut procedure (cut-release.sh ... --push), promote (new-release one-step path and the already-cut direct git tag -f path, with the known cut-release.sh channel-only-move gap clearly called out), rollback (single tag-move in reverse to the immutable vX.Y.Z target), verification (resolved @refs/tags/<agent>/stable (<sha>) line from a fresh caller run), and gotchas learned in the #495 rollout. PR body's claim that the cut→promote→verify path was exercised live this cycle (pr-review/v1.5.3 and dev-lead/v1.2.0) matches the documented validation section.

Findings

No blocking issues.

• Risk class: LOW — documentation only, no executable code, no workflow changes, no secrets/auth/migrations.
• Content accuracy: commands shown (scripts/cut-release.sh, git tag -f ... && git push --force, gh run view ... | grep '@refs/tags/') are consistent with the cut-release script's existing behavior, and the release-channel-tags ruleset + AGENTS.md "mutable-ref exception" references match the standards already in this repo.
• Documented gap (cut-release.sh has no --channel-only mode for already-cut releases) is explicitly flagged rather than hidden — appropriate for a runbook.
• Cross-link in versioning.md correctly redirects #498/#501/#505 references and now points at the new runbook.
• Markdown formatting and structure are clean (headings, code fences, table).

CI status

All required checks green: Lint, ShellCheck, unit-tests, CodeQL (actions + python), SonarCloud, Secret scan (gitleaks), Agent Security Scan, Compile agentic workflows, AgentShield, CodeRabbit, prior PR-review-agent run. Dependency-audit ecosystem jobs and dependabot-automerge correctly skipped (no dependency or dependabot changes). reviewDecision is APPROVED.

---

Reviewed automatically by the PR-review agent (single-reviewer mode: opus 4.7). Reply if you need a human review.