Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.compartment.dev/llms.txt

Use this file to discover all available pages before exploring further.

Every time you run compartment deploy, Compartment creates a candidate deployment alongside your currently active one. The candidate progresses through a series of stages before it ever receives live traffic. If anything goes wrong — at any stage — you can roll back to the previous active deployment without any downtime.

​
The promotion lifecycle

A deployment moves through these promotionStage values in order:
StageWhat is happening
buildingCompartment is building the container image for the new deployment.
starting_candidateThe new container has started and Compartment is waiting for it to initialize.
checking_readinessCompartment is polling the readiness endpoint (if configured) until the service reports healthy.
switching_routeTraffic is being atomically moved from the previous active container to the new one.
draining_previousThe old container is finishing any in-flight requests before it is stopped.
activeThe new deployment is fully live and serving all traffic.
rolled_backA rollback was triggered; a previous deployment has been restored to active.
The deployment reported by compartment status always reflects the latest promotionStage. A deployment does not receive any live traffic until it reaches switching_route.

​
Check deployment history

List recent deployments for a project to see their stages and IDs: 
compartment deployment list --project my-app
Add --service to filter by a single service, or --limit to control how many records are returned: 
compartment deployment list --project my-app --service web --limit 10
Use --output json if you need machine-readable output for scripting: 
compartment deployment list --project my-app --output json

​
Promote a deployment across environments

compartment deploy deploys to production by default. To move a build that is already active in one environment into another — for example from staging to production — use promote: 
compartment promote --from staging --to production --project my-app
--from and --to are both required. Compartment finds the currently active deployment in the source environment and promotes it through the full candidate lifecycle in the target environment. Add --verbose to stream stage-by-stage progress: 
compartment promote --from staging --to production --project my-app --verbose
To promote a single service rather than every service in a project: 
compartment promote --from staging --to production --project my-app --service api
Promotion creates a new deployment record in the target environment and runs the full readiness check cycle. It does not simply re-tag an existing container — the candidate goes through every stage as if it were a fresh deploy.

​
Roll back to the previous deployment

If the active deployment is behaving incorrectly, roll back immediately: 
compartment rollback --project my-app
Compartment promotes the most recent previously-active deployment back to active in the target environment, going through switching_route and draining_previous to maintain zero downtime. To roll back in a specific environment: 
compartment rollback --project my-app --env production
To roll back a single service: 
compartment rollback --project my-app --service web
To roll back to a specific historical deployment by ID (obtained from compartment deployment list): 
compartment rollback --project my-app --to dep_abc123
Rollback targets the most recently-succeeded deployment by default. If you need to roll back further, pass --to with an explicit deployment ID from compartment deployment list.

​
Next steps

  • Set up environment-specific deployments — see Environments.
  • Configure readiness checks so the candidate stage works correctly — see Build options.
  • Promote builds as part of a CI pipeline by passing --output json and parsing the result.