> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westyx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment promotion

> Move configs, feature flags and secret keys one environment up, by request and acceptance.

## What is environment promotion?

Environment promotion moves what you built in one environment to the next one: configs, feature flags and secret keys, per service. Someone requests the promotion, and someone who is allowed to accept into the target environment reviews it and accepts it. Every step is recorded in the audit log.

> [!NOTE]
>
> "Promote a version" on a secret is a different action: it makes an older version of that one secret the current value. Environment promotion moves items between environments. See [Secrets](https://docs.westyx.dev/features/secrets.md).

## The chain

A promotion always goes exactly one step up:

```
personal environment -> develop -> test -> staging -> prod
```

Environments your project's tier does not have are skipped:

| Tier | Steps |
| - | - |
| `free` | personal -> `develop` |
| `xs` | personal -> `develop` -> `prod` |
| `s` | personal -> `develop` -> `test` -> `prod` |
| `m` / `l` | personal -> `develop` -> `test` -> `staging` -> `prod` |
| `xl` | the same, and the `prod` step writes `prod`, `prod-blue` and `prod-green` together |

There is no way to skip a step. Work that starts in a personal environment reaches production only through the shared environments in between.

## Requesting a promotion

You can request a promotion from an environment you can edit: your own personal environment, or a shared environment where your role has full access.

**1. Open the wizard**

On the project's **Environments** tab, click **Promote to TEST** (or whichever environment is next) on the source environment's row. On your personal environment page, click **Promote to DEVELOP**.

**2. Select services**

Pick the services to promote. Each one shows whether it already exists in the target or will be created there. Selecting a service also selects the umbrella services it inherits from, so the link can be made in the target.

**3. Choose items**

For each selected service, decide what happens to every config, flag and secret:

* **Config** - `skip`, `use source value`, or `enter value` to type a different value for the target. If the key already exists in the target, turn on **overwrite existing** to replace it.
* **Flag** - **copy definition** takes the whole flag: its state, rules, schedule and rollout. **overwrite existing** replaces a flag the target already has.
* **Secret** - **declare key** creates the key in the target without a value.

Items the target does not have yet are selected by default; items that already exist are skipped unless you choose otherwise. **Select all new** picks every item of a service that is new in the target.

**4. Review and submit**

Add an optional note and submit. If your role can accept into the target, the promotion is applied immediately. Otherwise it waits for someone who can accept it.

> [!NOTE]
>
> Promote before you deploy. The code that reads a new config, flag or secret should find it already in the target environment.

## Accepting a promotion

Pending promotions are listed under **Promotions** on the project's **Environments** tab. The tab shows a count of the promotions waiting for you.

Who can accept depends on the target environment:

| Target | Roles that can accept |
| - | - |
| `develop` | `owner`, `manager`, `devops`, `lead_developer`, `developer` |
| `test` | `owner`, `manager`, `devops`, `lead_developer`, `developer`, `tester` |
| `staging` | `owner`, `manager`, `devops`, `lead_developer` |
| `prod`, `prod-blue`, `prod-green` | `owner`, `manager`, `devops` |

Click **Review** to open a promotion. The review shows the source environment as it is at that moment: that is exactly what will be written. For each config you can compare the value that will be written with the value the target has now.

* Turn off **accept** on any item you do not want; the rest is applied.
* **Accept selected** applies the promotion. Accepting into production also asks you to confirm that you reviewed the values.
* **Reject promotion** declines the whole request and requires a reason.

If the source changes while you are reviewing, the acceptance is refused and the review reloads with the new values, so nothing is written that you did not see.

The requester can withdraw a pending promotion with **Cancel request**. Members who can neither accept nor requested the promotion see its keys and statuses, but not the values.

## What is written

* **Configs** are written with the source's value at the moment of acceptance, or with the value typed in the request. A key that already exists in the target is replaced only when the request says **overwrite existing**; otherwise it is left as it is.
* **Flags** are written as their whole definition. An existing flag is replaced only with **overwrite existing**.
* **Services** that do not exist in the target are created there and linked to the same umbrella services.
* A key the target service only inherits from an umbrella does not count as existing: promoting it gives the service its own value.

## Secrets

A secret's value never leaves its environment. Promotion carries the key, the type and the description only, and creates the secret in the target as [not set](https://docs.westyx.dev/features/secrets.md#a-secret-without-a-value). Add the value in the target before the application needs it; the review lists every secret that was created this way.

A secret that already exists in the target is never changed by a promotion.

## Results and retry

After acceptance, every item shows a result for each target environment:

| Result | Meaning |
| - | - |
| `applied` | Written to the target |
| `skipped` | The key already exists and the request did not overwrite it |
| `failed` | Not written; the reason is shown next to the item |

A problem with one item, or with one of the production environments, does not stop the rest. When something failed, the promotion is **Partially applied** and anyone who can accept into the target can run **Retry failed items**, which writes only what failed.

## Audit

Each step is an audit log entry on the project, with the source and target environment and the actor:

| Action | When |
| - | - |
| `env_promotion_requested` | A promotion is requested |
| `env_promotion_accepted` | A promotion is accepted |
| `env_promotion_item_rejected` | An item is turned off at acceptance, one entry per item |
| `env_promotion_rejected` | The whole promotion is rejected |
| `env_promotion_cancelled` | The requester withdraws it |
| `env_promotion_applied` | The accepted items are written, with the counts per environment |
| `env_promotion_retried` | Failed items are retried |

Every config, flag, secret and service the promotion writes also appears in that service's own history, marked as written by an environment promotion.

## Where promotion is available

Environment promotion is done by a person in the admin console. It is not available through an API key or through the [MCP server](https://docs.westyx.dev/mcp/index.md): production is reached only by someone with the right role accepting a promotion.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.