Build and deploy
Deployments and releases
Changes to an environment are staged, then released together. Each release starts one deployment per changed service, and every deployment is kept as history you can inspect, redeploy, or roll back to.
Staged changes
Editing a service changes its draft: source, build, variables, resources, ports, health check, restart policy, volume mount, and sleep setting. New services and volumes are staged too. Nothing that runs changes until you release. The replica count is the exception: scaling applies at once.
The console's release bar counts staged changes. Review shows each one as
a diff and lets you discard it. Through the API, Service.pending_changes
and unapplied_changes report the same.
Release an environment
Deploy in the release bar releases the environment: every staged change becomes an immutable service revision, and each changed service starts a deployment. Deployments then progress independently, so a failing worker does not hold back a healthy API.
curl -X POST https://mesh.example.com/v1/environments/$ENVIRONMENT_ID/releases \
-H "Authorization: Bearer $MESH_TOKEN"Deployment stages
| Stage | What happens |
|---|---|
| Waiting for builder | The build waits for a free builder. |
| Building | The image is built. Image services skip this. |
| Deploying | Replicas start. |
| Waiting for readiness report | Replicas run; Mesh waits for their health checks to pass. |
| Active | The deployment serves traffic. The previous one drains and is removed. |
Exactly one deployment of a service is active at a time. While a new
deployment builds and starts, the previous one stays active and keeps
serving; the moment the new one becomes active, the previous one moves to
history as removing — draining while a configured draining period
lets it finish in-flight work — and ends as removed (state completed
in the API). A deployment also ends as failed (the build or health
check failed), crashed (the process kept exiting), cancelled, or
superseded (replaced before it ever ran). When a new deployment fails,
the previous active deployment keeps serving.
Zero-downtime replacement
New replicas start beside the old ones. Traffic moves only after the new replicas pass their health checks, and the old replicas keep serving in-flight requests for the service's draining time before they stop. Set the health check and timing in Settings → Deploy. See Services.
A service with a volume is the exception: its one disk cannot be mounted twice, so the old replica stops before the new one starts.
Deployment actions
Open a deployment's menu in the Deployments tab:
| Action | Effect |
|---|---|
| Restart | Restarts the deployment's replicas, all or one, with the same image. |
| Redeploy | Starts a new deployment of the exact image and configuration. |
| Rollback | Makes an earlier deployment's image and configuration current again. |
| Retry | Tries a failed build or deployment again. |
| Cancel | Stops a deployment that is still building or starting. |
| Remove | Stops the deployment's replicas. |
Through the API, POST /v1/services/{serviceId}/deployments/{deploymentId}/actions
takes the action and an idempotency_key, so a retried request never runs
an action twice.
Auto-deploy
When auto-deploy is on for an environment, a push to a repository service's tracked branch builds and deploys it without a release. Turn it off from the environment menu to collect commits and deploy them by hand.