Environment Promotion

Builder includes an approval-gated promotion workflow for moving projects between environments.

Promotion flow

development  ──►  staging  ──►  production

Each transition requires:

1. A promotion request
2. An approval from a user with the appropriate role
3. An execution that deploys to the target environment

Full rollback is available at any point.

Request a promotion

POST /promotion/request
{
  "project_name": "customer-portal",
  "from_env": "development",
  "to_env": "staging",
  "notes": "All tests passing (87% coverage), QA sign-off received"
}

Approve

Requires lead, admin, or super_admin role:

POST /promotion/approve
{ "request_id": "prm_x1y2z3", "notes": "Approved for staging" }

Execute

POST /promotion/execute
{ "request_id": "prm_x1y2z3" }

Rollback

POST /promotion/rollback
{ "project_name": "customer-portal", "environment": "staging" }

Rollback redeploys the previous version and records the rollback event in the promotion history.

Check readiness before requesting

POST /promotion/check
{ "project_name": "customer-portal", "to_env": "staging" }

Returns a readiness report — CTQ score, test coverage, open checkpoints, and any blocking issues.

View promotion history

GET /promotion/status
GET /promotion/environments