# Environment promotion

Move a configuration from one environment to the next with the diff, who approved it and what can be rolled back.

For: The people who move an agent's or an app's configuration from staging to production, and the approvers who sign it off.

Web page: https://candor.themethodic.com/screens/environment-promotion

## Layouts

### One promotion, read in full

Pick it when: The default: one configuration moves to the next environment, and the person reads the change before promoting it.

Layout: Where from and where to across the top in each environment's colour, the diff in the middle, approvals and rollback beneath, and Promote or Don't promote at the foot.

Items:

- **Environment promotion** (`environment-promotion`, Pro; https://candor.themethodic.com/docs/environment-promotion.md): From and to, the diff, who asked, who approved and when, what can and can't be rolled back; Promote stays locked, saying why, until it can run.
- **Environment band** (`environment-band`, Pro; https://candor.themethodic.com/docs/environment-band.md): The environment in scope, in its own colour, above the page.
- **Change hash** (`change-hash`, Pro; https://candor.themethodic.com/docs/change-hash.md): The sha256 of the change, the same in the browser and on the server, so the promotion applies exactly the diff the person read.

```bash
npx candor-ui add environment-promotion environment-band change-hash
```

### Approved by someone else first

Pick it when: Production needs a second person: the promotion waits in the approvals queue, and the requester promotes once it is approved.

Layout: The approvals queue on the left; the selected promotion on the right with its approvals filled in and the ones still missing.

Items:

- **Approval queue** (`approval-queue`, Pro; https://candor.themethodic.com/docs/approval-queue.md): Promotions waiting for approval, by what they need from the viewer.
- **Approval request** (`approval-request`, Pro; https://candor.themethodic.com/docs/approval-request.md): The approver's view: what changes, where, and the hash the decision is tied to.
- **Environment promotion** (`environment-promotion`, Pro; https://candor.themethodic.com/docs/environment-promotion.md): The requester's view, with each approval as it is given and the ones still missing.

```bash
npx candor-ui add approval-queue approval-request environment-promotion
```

## Rules that matter most here

- **Approve the exact change** (https://candor.themethodic.com/principles#approve-the-exact-change): Promote sends the hash of the diff the person read, and the server refuses it when the target has changed since.
- **A control that can't be used says why** (https://candor.themethodic.com/principles#locked-says-why): Promote stays locked, saying why, while approvals are missing, the diff is out of date or nothing differs.
- **Nothing is pre-selected in a decision** (https://candor.themethodic.com/principles#nothing-preselected): Promote and Don't promote look the same, and the box saying the person read a production change starts unticked.
- **Say what can and can't be undone** (https://candor.themethodic.com/principles#say-what-can-be-undone): What can and can't be rolled back is listed before Promote, not after.

## Patterns that cover part of it

- Human-in-the-loop approval UI for AI agents: https://candor.themethodic.com/patterns/ai-approval-ui.md

## Brief for a coding agent

Paste this to the agent that builds the screen.

```text
Build an environment promotion screen with Candor UI: a configuration moves from one environment to the next only when a person promotes it.
Use EnvironmentPromotion with the two environments, the diff your server took, who asked, the approvals your rules require and what can and can't be rolled back.
Pass your server's change hash as hash; onPromote gives it back, and your server recomputes it and refuses a promotion whose target has changed since the diff.
Promote stays locked, saying why, while approvals are missing, while the diff is out of date (pass stale), and for production until the person ticks that they've read what changes.
Neither Promote nor Don't promote is chosen for the person.
Where a second person must approve, list waiting promotions in ApprovalQueue and show each to the approver as an ApprovalRequest; pass the approvals given back to EnvironmentPromotion.
Put EnvironmentBand above the page so the environment in scope is never in doubt.
Pass state "promoted" and the decision (who and when) only once your server has recorded the promotion; until then, nothing has moved.

Start from the "One promotion, read in full" layout: Where from and where to across the top in each environment's colour, the diff in the middle, approvals and rollback beneath, and Promote or Don't promote at the foot.
Candor items: environment-promotion (https://candor.themethodic.com/docs/environment-promotion.md), environment-band (https://candor.themethodic.com/docs/environment-band.md), change-hash (https://candor.themethodic.com/docs/change-hash.md).
Install: npx candor-ui add environment-promotion environment-band change-hash
Read each item's docs before using it and take its props from there; don't guess them. Pro and Premium items need the person's licence key, which they add with `npx candor-ui key <key>`; don't ask for it.
```