Release Management

A Release groups multiple ChangeRequests into a single coordinated deployment with shared rollout/rollback plans, success criteria, and a chronological deployment log. ITIL Release & Deployment Management.

How end users experience a release

Most end users never directly interact with a Release — but they DO feel the effects. Here's what shows up on the user side:

• Linked-change visibility on tasks. If your submitted catalog request requires a system change (software upgrade, network config change, etc.), it may be bundled into a Change Request that's part of a larger Release. You'll see this on your task detail page as a "Linked Release: REL-2026-Q2-001" badge.
• Pre-deployment notifications. When a Release with scheduled-start < 7 days touches an affected CI you have a task on, the system sends a heads-up email: "Your request will be fulfilled as part of release REL-XXX scheduled for YYYY-MM-DD".
• Bundled resolution. When a Release transitions to deployed, every Change Request in that bundle auto-resolves, and every task linked to those changes gets a "Resolved as part of release" comment with the deployment timestamp.
• Rollback notification. If a Release is rolled back, all bundled tasks reopen with a "Rollback: [reason]" comment. Don't resubmit — wait for the team to communicate the next steps.
• Public status page (optional). If your org has enabled the public Trust Center, the upcoming + past Release windows show up there for transparency. Useful when customers need to know about scheduled maintenance.

For most users, the Release layer is invisible plumbing — you just see your task resolve when the deploy ships. The visibility is there for users who want to know when their request will be fulfilled.

Status lifecycle

planned → approved → scheduled → in-progress → deployed | rolled-back | cancelled

• planned — being designed; not committed
• approved — all linked ChangeRequests CAB-approved; ready to schedule
• scheduled — deployment window locked in
• in-progress — actively deploying; actualStart stamped automatically
• deployed — successful; actualEnd stamped automatically
• rolled-back — undone; rolledBackAt + rolledBackReason stamped
• cancelled — never deployed; reasoning in the deployment log

Designing a release

POST /api/releases (Admin) or MCP create_release. Fields:

• name, version (semver-ish), description, status
• scheduledStart, scheduledEnd (ISO date-time)
• releaseManager, releaseManagerEmail
• linkedChangeRequestIds[] — up to 100. Each linked CR should be CAB-approved before release status moves past planned.
• rolloutSteps[] — ordered steps with order, description, ownerEmail, estimatedMinutes, completed flag
• rollbackSteps[] — same shape, executed if rollback triggered
• successCriteria — free-form text describing what "deployed" means (smoke tests, monitoring thresholds, user acceptance)

Deployment log

Every release has a chronological deploymentLog[] for capturing notes during execution.

• POST /api/releases/:id/log (Auditor+) or MCP append_release_log — free-text entry
• Capped at 500 entries (last-N retention) to stay under Cosmos 2MB doc limit
• Status transitions auto-append a log entry capturing "from → to" + optional note
• Each entry has id, timestamp, author, authorEmail, text, optional status

Transitioning status

POST /api/releases/:id/status (Admin) or MCP transition_release_status. Body: status (required), note (optional), rollback_reason (required when status=rolled-back).

Auto-stamped timestamps:

• in-progress → actualStart set (if not already)
• deployed → actualEnd set
• rolled-back → rolledBackAt + rolledBackReason set

Every transition auto-appends a log entry. Don't manually post a "status changed" log entry — the transition handler does it.

Managing linked changes

POST /api/releases/:id/add-changes (Admin) — bulk add or remove ChangeRequest ids. Up to 100 per call. Idempotent. Use to compose the release from approved CRs, or to drop a CR that got rejected at CAB.

Note: the release's get_release response enriches with linked change summaries (controlId, controlTitle, changeType, cabDecision, approvalStatus, scheduledStart) so you can see at a glance which CRs are CAB-approved vs. pending.

REST endpoints

• GET /api/releases (Viewer+, filter by status)
• GET /api/releases/:id (Viewer+) — enriched with linked change summaries
• POST /api/releases (Admin)
• DELETE /api/releases/:id (Admin)
• POST /api/releases/:id/add-changes (Admin)
• POST /api/releases/:id/log (Auditor+)
• POST /api/releases/:id/status (Admin)

MCP tools (5, HTTP + stdio parity)

• list_releases — filter by status
• get_release — full detail including rollout/rollback steps + recent log
• create_release (Admin)
• transition_release_status (Admin)
• append_release_log (Auditor+)

Recommended patterns

• Rollout step ownership. Set ownerEmail on each step so during deployment you know exactly who owns each piece. Estimated minutes help build a realistic timeline.
• Always define rollback steps before approval. If you can't articulate how to roll back, you're not ready to deploy. The CAB should see rollback steps as part of the approval review.
• Success criteria should be measurable. "Users can log in" is bad; "Login success rate >99% in monitoring dashboard for 30 minutes post-deploy" is good.
• Append log entries during deployment. Real-time notes capture what actually happened — invaluable for post-deploy review or if rollback is triggered.
• On rollback, write a detailed rolledBackReason. This is the seed for the post-deployment review. Don't write "didn't work" — write "Auth service threw 500s on /api/login at 14:23 UTC, MTTR 8 min before rollback decision".

Pitfalls

• Releases don't auto-execute change requests. The release groups them and tracks the deployment plan; actual change execution still happens through the CR + remediation path. Use the release to coordinate, not to automate.
• Rollback steps aren't automatically run on rolled-back status. Status transition is just bookkeeping. Execute rollback steps manually (with log entries documenting each) before transitioning to rolled-back.
• Deployment log cap is last-500. For multi-day mega-releases that exceed this, summarize older log entries into a separate document and reference its link.

Related guides

• CAB workflow — changes should be CAB-approved before release status moves past planned
• CMDB — releases often involve multiple CIs; use affectedCiIds on each linked CR