What you can do with a deployment in production and in preview.
Every has a production and a preview environment. Production has one live that you promote and roll back. Preview has many short-lived deployments that you can stop and start, and we stop them for you when they go quiet.
For a git-connected app, a push to the default branch creates a production deployment. A push to any other branch, or a pull request from a fork, creates a preview deployment. When you deploy from the API, CLI, or dashboard, you pick the environment.
An app has one live production deployment. The environment domain, the shorter live domain, and any verified custom domains all point at it. When a new production deployment reaches ready, it goes live and those domains move to it, unless the app is rolled back (see Rollback). The deployment it replaced keeps running for 30 minutes as a standby, then stops.
Promote in the dashboard, or deployments.promoteDeployment in the API, makes a ready production deployment the live one. Use it to ship a deployment that was built while the app was rolled back, or to move traffic to an earlier deployment on purpose. The deployment it replaces stops after 30 minutes.You can promote a deployment when it’s ready and not stopped, and the app already has a live deployment. Promoting the deployment that’s already live only works while the app is rolled back. That’s a confirm rollback: nothing moves, but the rolled-back state ends and new pushes go live again.
Rollback in the dashboard, or deployments.rollbackDeployment in the API, moves traffic back to the deployment you pick. The domains move in one step and the app is marked as rolled back.While an app is rolled back, new production deployments still build and reach ready, but they don’t go live. So a push can’t undo your rollback. To end the rolled-back state, promote the deployment you rolled back to (confirm rollback) or promote a newer one.You can roll back to a deployment that’s ready, not stopped, and not the live one. A stopped deployment, including an old live one after its 30 minute standby, can’t be a rollback target. To get back to it, click Redeploy on it, wait for ready, and promote it if the app is rolled back. Or roll forward with a fixed commit.You can’t stop or start production deployments by hand, because stopping the live one would take your app offline.
Stop deployment in the dashboard, or deployments.stopDeployment in the API, stops a ready preview deployment and frees its resources. It shows stopped once no instance is left.Wake deployment in the dashboard, or deployments.startDeployment in the API, starts a stopped preview deployment again. It goes through deploying and back to ready. You can’t start one while the workspace is suspended by its Compute spend budget.
Promote and rollback don’t restart anything. The domains move to the other deployment, and the old one keeps serving until they have. The switch reaches every region within a few seconds, so a few requests can still reach the old deployment right after. A request to a stopped deployment gets 503 with deployment_offline.
Last modified on September 29, 2026
Was this page helpful?
⌘I
Assistant
Responses are generated using AI and may contain mistakes.
