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:PromoteSecreton the secret, and on the target:secrets:RotateSecreton the target's secret of that name, orsecrets:CreateSecretwhen it has none. - For a synced secret,
secrets:UseSecretSourceon its source. - To see in the plan whether values already match,
secrets:CompareSecretValueson both secrets. - In the console, also
secrets:ListSecretEnvironmentsto open Environments (without it the page says your policies do not grant it), andsecrets:ListSecretsfor 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
- Open Environments (in the Secrets navigation).
- 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.
- 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.
- Select the names to promote. New and changed names are selected already. For a synced one, check the reference and select its row.
- 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.
dcloud secrets environments promote 5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e \
--to-environment-id 7c6d5e4f-3a2b-4c1d-9e8f-7a6b5c4d3e2fFor many, dcloud secrets environments promote-many with --dry-run first.
Ask for the plan, then send the same items without dryRun:
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)
409withsuggestedReferencefor a synced secret sent withoutreference.400"It is already in that environment".404"Environment not found" for an unknowntoEnvironmentId.403"Forbidden: needs secrets:CreateSecret", "Forbidden: needs secrets:RotateSecret on … in …" or "Forbidden: needs secrets:UseSecretSource on …".409when the target is a stored secret and the source synced, or the other way round, or syncs from another source.409for 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,
400when the reference is malformed. - For a synced secret,
422"… did not resolve: …". - For a synced secret,
502when the source itself fails.