Promotion¶

Promotion is the process of moving a deployment artifact from one ring to the next. Manifest Platform enforces a structured promotion workflow with configurable approval gates, automated validation, and full audit trails so that every production change is intentional and traceable.

Promotion Workflow¶

When you promote a deployment, the platform does not rebuild the artifact. The same immutable bundle that passed validation in the source ring is deployed to the target ring, ensuring what you tested is exactly what reaches production.

sequenceDiagram
    participant U as User / CI
    participant P as Platform
    participant SRC as Source Ring
    participant TGT as Target Ring

    U->>P: Request promotion (source → target)
    P->>SRC: Verify deployment is Active & healthy
    P->>P: Check approval gate policy

    alt Approval required
        P->>U: Request approval from designated reviewers
        U->>P: Approval granted
    end

    P->>TGT: Deploy artifact to target ring
    P->>TGT: Run validation checks
    TGT-->>P: Health checks pass
    P->>U: Promotion complete
    P->>P: Record audit event

Promotion Rules¶

The platform enforces these rules by default:

Sequential promotion -- Artifacts must move through rings in order. You cannot skip staging and promote directly from dev to production.
Healthy source -- The deployment in the source ring must be in the Active state with all health checks passing.
No concurrent promotions -- Only one promotion can be in progress per solution per target ring.
Artifact immutability -- The deployed artifact is identical across rings. Configuration varies by ring, but code does not.

Skipping rings

Enterprise organizations can configure exceptions to sequential promotion for hotfix scenarios. This requires explicit admin approval and is logged as a policy override in the audit trail.

Triggering a Promotion¶

Platform UICLI

Navigate to Solution > Deployments
Find the active deployment in the source ring
Click Promote and select the target ring
Review the diff of configuration changes between rings
Add an optional promotion note
Click Confirm Promotion (or submit for approval if a gate is configured)

# Promote a deployment to the next ring
flow-sdk promote <deployment-id> --target-ring staging

# Promote with a note
flow-sdk promote <deployment-id> --target-ring production \
  --notes "Approved in weekly release review"

Approval Gates¶

Approval gates prevent deployments from reaching sensitive rings without explicit human review. Gates are configurable per ring and can require one or more approvers.

Gate Configuration¶

# flow-solution.yaml
promotion:
  gates:
    staging:
      required_approvals: 1
      allowed_approvers:
        - role: solution-builder
        - role: admin
      auto_approve_from_ci: false
      timeout: 24h
    production:
      required_approvals: 2
      allowed_approvers:
        - role: admin
      require_ticket_reference: true
      timeout: 48h

Setting	Description
`required_approvals`	Number of distinct approvals needed before promotion proceeds
`allowed_approvers`	Roles or specific users who can approve
`auto_approve_from_ci`	When `true`, CI/CD pipelines can bypass manual approval for this gate
`require_ticket_reference`	Require a linked issue or ticket ID in the promotion note
`timeout`	Duration before a pending promotion request expires

Approval Flow¶

stateDiagram-v2
    [*] --> PendingApproval: Promotion requested
    PendingApproval --> Approved: Required approvals met
    PendingApproval --> Rejected: Reviewer rejects
    PendingApproval --> Expired: Timeout reached
    Approved --> Deploying: Artifact pushed to target ring
    Deploying --> Completed: Validation passed
    Deploying --> Failed: Validation failed
    Rejected --> [*]
    Expired --> [*]
    Completed --> [*]
    Failed --> [*]

Approve/reject API not yet wired

The promotion approval service layer is implemented. The POST /{promotion_id}/approve and POST /{promotion_id}/reject REST endpoints are not yet registered in the backend router and are only available through the Platform UI at this time.

Reviewing and Approving¶

Pending promotions appear in the Approvals section of the solution dashboard and in the reviewer's notification center. Click Review to see:

The deployment artifact details (version, components, Git SHA)
A diff of configuration changes between source and target rings
Health status in the source ring
The promotion note from the requester

Then click Approve or Reject with an optional comment.

Rollback Procedures¶

When a deployment in any ring exhibits problems after promotion, you can roll back to the previous active deployment.

Automatic Rollback¶

The platform can automatically roll back a deployment if post-promotion health checks fail. Configure automatic rollback in the ring settings:

rings:
  production:
    rollback:
      auto_rollback: true
      health_check_window: 5m    # time to wait for health checks after deploy
      failure_threshold: 3        # consecutive health check failures before rollback

When automatic rollback triggers, the platform:

Stops routing traffic to the new deployment
Restores the previous active deployment
Marks the failed deployment as RolledBack
Emits an alert to the configured notification channels
Records the rollback reason in the audit log

Manual Rollback¶

Platform UICLI

Go to Solution > Deployments
Select the ring with the problematic deployment
Click Rollback on the active deployment
Confirm the rollback target (defaults to the previous active version)
Add a rollback reason

# Roll back a deployment
flow-sdk rollback <deployment-id> --reason "Deployment causing errors"

# Roll back to a specific previous deployment
flow-sdk rollback <deployment-id> \
  --rollback-to <previous-deployment-id> \
  --reason "Reverting to last known good"

Rollback scope

Rollback restores the entire solution to the previous deployment artifact. It does not support rolling back individual components. If you need to revert a single component, create a new deployment with that component reverted and promote it through the rings.

Rollback vs. Revert¶

Action	What Happens	When to Use
Rollback	Restores the previous deployment artifact in the current ring. Fast -- no rebuild required.	Immediate incident response. The previous version is known-good.
Revert	Creates a new Git commit undoing specific changes, then deploys through the full ring pipeline.	The issue is in a specific change and you want a proper audit trail through all rings.

Promotion History and Audit¶

Every promotion event is recorded in the platform's audit system with full context, providing a complete history of what was deployed, when, by whom, and why.

Viewing Promotion History¶

The Deployments > History tab shows a timeline of all promotions for a solution, including:

Source and target ring
Deployment artifact version and Git SHA
Who requested the promotion
Who approved (and any rejection history)
Promotion notes and ticket references
Duration and outcome (completed, failed, rolled back)

Audit Trail Integration¶

Promotion events are first-class entries in the audit log. Each event includes:

Field	Description
`event_type`	`deployment.promotion.requested`, `deployment.promotion.approved`, `deployment.promotion.completed`, etc.
`actor`	The user or service account that initiated the action
`solution_id`	The solution being promoted
`artifact_version`	The immutable deployment artifact identifier
`source_ring`	Ring the artifact is promoted from
`target_ring`	Ring the artifact is promoted to
`approval_chain`	List of approvers and their decisions
`note`	Free-text note from the requester
`ticket_reference`	Linked issue or ticket ID (if required by gate policy)
`outcome`	`completed`, `failed`, `rolled_back`, `rejected`, `expired`
`timestamp`	ISO 8601 timestamp of the event

Compliance reporting

Promotion audit data feeds into the compliance reporting system. If your organization requires change management evidence for SOC 2 or ISO 27001, the promotion history provides the necessary paper trail. See Compliance for details.