Screens / Approving and controlling

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.

Markdown

2 ways to lay it out

1. 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.

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.

Environment promotionProFrom 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 bandProThe environment in scope, in its own colour, above the page.
Change hashProThe sha256 of the change, the same in the browser and on the server, so the promotion applies exactly the diff the person read.

Install one promotion, read in full

Pro and Premium items need a licence key; free ones install as they are.

2. 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.

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

Approval queueProPromotions waiting for approval, by what they need from the viewer.
Approval requestProThe approver's view: what changes, where, and the hash the decision is tied to.
Environment promotionProThe requester's view, with each approval as it is given and the ones still missing.

Install approved by someone else first

Pro and Premium items need a licence key; free ones install as they are.

Rules that matter most here

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
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
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
What can and can't be rolled back is listed before Promote, not after.

Already covered elsewhere

Pattern: Human-in-the-loop approval UI for AI agents

Brief for a coding agent

Paste this into the agent that builds the screen. The docs MCP server returns the same text from get_screen.

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.