# 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:

- 
- 
-

Each service's ordinary [variables](/docs/configuration/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

- 
- 
-

## The preview

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

- 
- 
- 
-

> **Warning:**
>
> A promote that deletes services or destroys volumes is irreversible — a destroyed volume's data is permanently lost. The console requires ticking an explicit confirmation before such a push applies.

## Promote from the console

1. 
2. 
3. 
4. 
5.

A promote pushes the source's **deployed** configuration only — [staged canvas changes](/docs/projects/staged-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](/api/environments); a dry run returns the same preview without changing anything.

## Promote vs clone

[Clone](/docs/projects/clone-an-environment) 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](/docs/collaboration/teams-and-roles).