# Promote a secret

Copy a secret's active value, or for a synced secret its source reference, into the same name in another environment, without the value ever reaching you.

Replace _5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e_ with the id of the secret to promote (in the
environment it comes from) and _7c6d5e4f-3a2b-4c1d-9e8f-7a6b5c4d3e2f_ with the target environment's
id.

## Prerequisites

- Permission for `secrets:PromoteSecret` on the secret, and on the target: `secrets:RotateSecret`
  on the target's secret of that name, or `secrets:CreateSecret` when it has none.
- For a synced secret, `secrets:UseSecretSource` on its source.
- To see in the plan whether values already match, `secrets:CompareSecretValues` on both secrets.
- In the console, also `secrets:ListSecretEnvironments` to open **Environments** (without it the
  page says your policies do not grant it), and `secrets:ListSecrets` for its table (without it
  "The matrix did not load."). Rows show only secrets you may describe (`secrets:GetSecret`).
- A free unit of the secrets quota for each name the target does not have yet; see
  [Quotas](quotas.md).

## What a promotion does

- **A stored secret**: its active value becomes a new version of the same-named secret in the
  target, or a new secret there (under the same key) if it has none. An equal value writes nothing.
  The read is recorded in the source secret's access log.
- **A synced secret**: no value is copied out of the source. The target syncs from a reference you
  confirm. The suggestion swaps a path segment that names the source environment (its name or
  slug, in any case) for the target's: `op://Staging/db/password` → `op://Production/db/password`.
  When no segment names it, or either side is Default, the suggestion is the target's current
  reference, else the same reference unchanged.
- Grants are not copied. Grant the target to its consumers.

## Promote

**Console**
1. Open **Environments** (in the Secrets navigation).
2. To promote every name one environment holds into the next, choose that step's button beside
   **Promote** (such as Staging → Production). It covers the names of the group you picked (and,
   with **Show them** on, only the names missing in a later environment); the search box and the
   **Show** filter do not narrow it. For one name, choose its row, then **Promote from …** on the
   environment that lacks it. That button appears only when the name has no Default value and an
   earlier environment has its own.
3. Read the plan. Each name is **New in target**, **Value changes**, **Already the same**,
   **Exists, not compared**, **Synced: confirm the reference** or, for one that cannot be promoted,
   the reason.
4. Select the names to promote. New and changed names are selected already. For a synced one,
   check the reference and select its row.
5. Choose **Promote** (the button shows the number selected, such as `Promote 3`).

The sheet says how many were promoted ("2 of 3 promoted.") and, for each name, `created`,
`new version`, `already the same` or why it was not. Choose **Close**.

**CLI**
```sh
dcloud secrets environments promote 5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e \
  --to-environment-id 7c6d5e4f-3a2b-4c1d-9e8f-7a6b5c4d3e2f
```

For many, `dcloud secrets environments promote-many` with `--dry-run` first.

**API**
Ask for the plan, then send the same items without `dryRun`:

```http
POST /secrets/api/environments/promote
{ "toEnvironmentId": "7c6d5e4f-3a2b-4c1d-9e8f-7a6b5c4d3e2f", "items": [{ "secretId": "5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e" }], "dryRun": true }
```

For one secret, `POST /secrets/api/secrets/{id}/promote` with `toEnvironmentId` (`null` for
Default) and, if synced, `reference`.

Each item's `plan` is `create`, `update`, `unchanged`, `not-compared` (you lack
`secrets:CompareSecretValues`; a run writes only if the value differs), `needs-reference` (synced:
send the item again with `reference`, starting from `suggestedReference`) or `blocked` (`error`
says why). A batch of up to 500 items always answers `200`; each item is authorized and answered on
its own, and the batch is not atomic.

## Refusals (one secret)

- `409` with `suggestedReference` for a synced secret sent without `reference`.
- `400` "It is already in that environment".
- `404` "Environment not found" for an unknown `toEnvironmentId`.
- `403` "Forbidden: needs secrets:CreateSecret", "Forbidden: needs secrets:RotateSecret on … in …"
  or "Forbidden: needs secrets:UseSecretSource on …".
- `409` when the target is a stored secret and the source synced, or the other way round, or syncs
  from another source.
- `409` for a secret managed by Error Tracking.
- `409` "Its key is not enabled" (or the target's key), or when the secrets quota is full.
- For a synced secret, `400` when the reference is malformed.
- For a synced secret, `422` "… did not resolve: …".
- For a synced secret, `502` when the source itself fails.

## Related

- [Compare environments](compare-environments.md)
- `secrets.environments.promote` · `secrets.environments.promote-many`
