> For the complete documentation index, see [llms.txt](https://docs.codemash.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codemash.io/cloud/project/settings/environments.md).

# Environments

**Where:** Project → Settings → Environments · `/projects/<project>/settings?tab=Environments`

Environments keep separate sets of integrations, users, templates and campaigns — for example a **TEST** environment that never touches production. **PROD** always exists, cannot be deleted, and is the top of the promotion ladder.

{% hint style="info" %}
Screenshot TODO — capture comes from testing-plan area **17-project-settings**.
{% endhint %}

## The ladder

Each environment is listed with its rank (lower = further from PROD) and badges: **top of ladder** on PROD and **current** on the environment the dashboard is showing. Per row you can:

* **Switch to this** — the whole dashboard switches to that environment's data.
* **Move up / move down** (arrow buttons) — reorder non-PROD environments on the ladder. Promotion only flows up.
* **Delete** (trash icon, non-PROD only) — the confirmation modal makes you tick a checkbox first, because the delete cascades and removes the environment's data.

## New environment

**New environment** opens a full-screen create form (the same layout as the new-project wizard's Database step):

1. **Environment name** — e.g. `TEST`.
2. A database for the new environment: pick the provider, then either a cluster tier (managed) or a **Connection string** (e.g. `mongodb+srv://user:password@cluster.mongodb.net`), an **Integration name** (e.g. `Primary database`) and an optional **Database name** (defaults to the database in the connection string).

On some plans creating extra environments is gated — the server's rejection (for example the trial gate) is shown inside the form.

## Promote

When more than one environment exists, the **Promote** button copies content up the ladder:

1. Pick the source and target environments.
2. **Preview** runs a dry run and shows the plan: **Mirrored (created / overwritten)**, **Deleted in target**, **Integrations seeded**, **Integrations skipped (kept)** — plus any **blockers**.
3. **Apply** runs the real promotion. It stays disabled while blockers exist.

Content (schemas, templates, triggers) is mirrored into the target. Integrations the target is missing are seeded with their own copy; once an integration exists in both environments, each keeps its own config and secrets — promotion never overwrites or removes them.

After a successful apply the tab shows a card like *Promoted **TEST** → **PROD** (at version 12)* with a **Roll back** button that restores the target to its state before that promotion.

## API reference

Endpoints: [create-project-environment](/api-reference/account/projects/create-project-environment.md), [get-project-environments](/api-reference/account/projects/get-project-environments.md), [delete-project-environment](/api-reference/account/projects/delete-project-environment.md), [set-environment-rank](/api-reference/account/projects/set-environment-rank.md), [promote-environment](/api-reference/account/projects/promote-environment.md), [rollback-promotion](/api-reference/account/projects/rollback-promotion.md).