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.“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.
The chain
A promotion always goes exactly one step up:
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, orenter valueto 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.
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.
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:
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.
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. 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:
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:
Every config, flag, secret and service the promotion writes also appears in that service’s own history, marked as written by an environment promotion.
