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.

Last updated 18 November 2026View as Markdown

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.

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

  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.

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.
Did this page help you?