Promote an environment

Promoting pushes one environment's deployed configuration onto another in the same project, until the target matches the source. Use it to flow a tested setup from staging to production without rebuilding it by hand.

What a promote changes

The target's services are rewritten to match the source:

• Services only in the source will be created on the target.
• Services in both will be updated to the source's configuration and image.
• Services only in the target will be deleted.

Each service's ordinary variables — plain values, connection variables, and aliases — are pushed with it; environment-scoped variables are not touched, so the target keeps its own. A service whose image, source, or mode changes redeploys.

What the target keeps

• Its sensitive variable values. A sensitive value never crosses environments: the source's sensitive values are not pushed, and the target's own are preserved. The preview lists sensitive names the target is missing so you can set a value there.
• Its custom domains. They stay routed on the target — unless their target service is deleted, in which case the preview flags them as left without a target.
• Its data. A database that exists in both environments keeps its data; only its configuration is updated. A database only in the source is created empty on the target.

The preview

Picking a target always shows a full preview before anything changes — one card per affected service:

• will be created / will be deleted cards name the service and its type.
• will be updated cards list every field-level change (before → after), with a redeploys badge when the image, source, or mode changes; a card with no field rows syncs variables only.
• Volumes that will be destroyed and domains left without a target are flagged on their service's card.
• Blockers stop the promote entirely — for example a service that has the same name but a different type on each side. Resolve the conflict, then preview again.

Promote from the console

1. Open the source environment — the one whose configuration you want to push.
2. Open the environment switcher in the header and choose Apply changes to….
3. In the "Push changes from …" dialog, pick the target environment under To. The preview loads automatically.
4. Review the preview. If the push deletes services or destroys volumes, tick the confirmation checkbox.
5. Press the push button — it counts the changes it will make, for example "Push 3 changes". The target's services are created, updated, and deleted to match, and the target redeploys. The console takes you to the target environment's board so you can watch it happen.

A promote pushes the source's deployed configuration only — staged canvas changes you haven't deployed don't ride along, and the dialog notes this when your draft has staged work.

You can also promote via the Environments API; a dry run returns the same preview without changing anything.

Promote vs clone

Clone mints a new environment from an existing one — use it once, to stand up staging from production. Because it creates an environment, cloning requires the admin role.

Promote flows configuration between existing environments — use it repeatedly, whenever the source has changes worth shipping. The editor role suffices: a promote only changes services, the same permission as editing them directly. See Teams & roles.