FlowOS Docs
ITSM

Release Management

Plan, approve, deploy, and roll back releases; group change requests into a release; track ITIL release phases and a release calendar.

Overview

A releasegroups one or more change requests into a single deployable unit — e.g. "v2.4.0 to production" — with its own approval, deployment, and rollback lifecycle, optional ITIL release phases with checklists, and a calendar view. Releases are stored in their own releases collection and referenced back from ChangeRequest.releaseId.

Model Fields

FieldTypeRequiredDefaultDescription
numberstringrequiredauto (REL-NNNN)Human-readable identifier, generated on create.
namestringrequired—Display name of the release.
versionstringrequired—Version identifier, e.g. "2.4.0".
typeenumrequired—major · minor · patch · hotfix
environmentstringrequired—Target environment, e.g. "production".
statusenumoptionalplannedplanned · in_progress · deployed · rolled_back · cancelled
plannedDatedateoptional—Planned release date, used by the release calendar.
actualDatedateoptional—Set automatically to now() when deployed.
linkedChangeIdsObjectId[]optional[]Change requests included in this release (ref ChangeRequest).
releaseManagerIdObjectIdoptionalcreating userOwner of the release (ref User). Set to the creator automatically if their id is a valid ObjectId.
deployedBy / deployedAtObjectId / dateoptional—Set by the /deploy action.
approvedBy / approvedAtObjectId / dateoptional—Set by the /approve action.
releaseNotesstringoptional—Notes describing what’s in the release.
successCriteriastringoptional—How success will be measured post-deploy.
rollbackPlanstringoptional—Plan to revert if the release fails.
phasesIReleasePhase[]optional[]ITIL release phases — see below.
createdAt / updatedAttimestampoptionalautoManaged by the record.

Release phase fields (phases[])

FieldTypeRequiredDefaultDescription
namestringrequired—Phase name, e.g. "Build", "Staging validation", "Go-live".
descriptionstringoptional—What happens in this phase.
statusenumoptionalpendingpending · in_progress · completed · skipped
plannedStart / plannedEnddateoptional—Planned window for the phase.
actualStart / actualEnddateoptional—Actual window, set via the phase update endpoint.
assignedTostringoptional—Owner of the phase.
checklist{ item, completed }[]optional[]Checklist items for the phase.

Lifecycle

  • •planned — Default status on create.
  • •in_progress — Not set automatically by any action; available as a manual status via PATCH, and accepted by /deploy as a starting state.
  • •deployed — Set by /deploy, only from planned or in_progress. Sets deployedBy, deployedAt, and actualDate.
  • •rolled_back — Set by /rollback, only from deployed.
  • •cancelled — Manual status via PATCH; no dedicated action endpoint.

/approve only transitions a release currently in planned status; it sets approvedAt/approvedBy but does not itself change status.

bash
POST /api/releases
{
  "name": "Checkout service v2.4.0",
  "version": "2.4.0",
  "type": "minor",
  "environment": "production",
  "plannedDate": "2026-10-01T02:00:00.000Z",
  "releaseNotes": "Adds saved payment methods, fixes cart total rounding.",
  "rollbackPlan": "Redeploy previous image tag 2.3.6 via the deploy pipeline."
}

# Approve
POST /api/releases/:id/approve

# Deploy
POST /api/releases/:id/deploy

# Roll back after a deployed release
POST /api/releases/:id/rollback

Linking Change Requests to a Release

A ChangeRequest carries its own releaseId field pointing back at the release it belongs to. Adding a change to a release sets that change’s releaseId and adds the change to the release’s linkedChangeIds array; removing it clears both sides. Listing a release’s changes matches on either direction of the link (a change with releaseId equal to the release, or an id present in linkedChangeIds), so the two are kept in sync by the add/remove endpoints but read defensively.

See Change Management for the full change request field reference.

bash
# List changes in a release
GET /api/releases/:id/changes

# Add a change to a release
POST /api/releases/:id/changes
{ "changeId": "665f1a2b3c4d5e6f7a8b9c0d" }

# Remove a change from a release
DELETE /api/releases/:id/changes/:changeId

Phases & Calendar

Phases can be appended to a release and updated individually (status, actual start/end, assignee, checklist). GET /api/releases/calendar returns every release whose plannedDate or actualDate falls in the given month, grouped by date, for calendar-style rendering.

Release create, update, approve, deploy, and rollback all emit platform events (release.created, release.updated, release.approved, release.deployed, release.rolled_back) that can trigger workflows.

API Quick Reference

GET
/api/releases

List releases. Query: status, environment, type

POST
/api/releases

Create a release (requires name, version, type, environment)

GET
/api/releases/:id

Get a release with populated manager, deployer, approver, and linked changes

PATCH
/api/releases/:id

Update release fields

POST
/api/releases/:id/approve

Approve (from planned)

POST
/api/releases/:id/deploy

Deploy (from planned or in_progress)

POST
/api/releases/:id/rollback

Roll back (from deployed)

DELETE
/api/releases/:id

Delete a release

GET
/api/releases/:id/changes

List change requests linked to the release

POST
/api/releases/:id/changes

Link a change request to the release (body: { changeId })

DELETE
/api/releases/:id/changes/:changeId

Unlink a change request from the release

POST
/api/releases/:id/phases

Add a phase (body: { name, description?, plannedStart?, plannedEnd?, assignedTo?, checklist? })

PATCH
/api/releases/:id/phases/:phaseIndex

Update a phase’s status, actual dates, assignee, or checklist

GET
/api/releases/calendar

Releases for a given month, grouped by date. Query: year, month