Policy rollout
How a policy's content and its reach change on separate paths — versions, second-person review, simulation over past work, the monitor, pilot and enforce stages, and rollback.
Writing a policy is on Policies. This page is about putting one into force without surprising anyone: every publication is versioned, a second person can be required to publish, a draft can be replayed over the last 90 days before it blocks anything, and enforcement is staged.
Versions
Every publication writes a policy version — the whole snapshot (name, description, severity, scope, rules, actions), with who proposed it, who published it and why. History can be compared version against version. A policy that predates history gets a baseline version before its first change.
Rollback publishes an earlier version's content as the next version. History is only ever appended to.
Second-person review
An organization setting, off by default. When it is on:
- create, edit, YAML import and rollback become proposals with a reason;
- someone else with
governance.manage_policiespublishes or rejects the proposal; - the proposer can only withdraw their own;
- a proposal written against an older version is refused as stale.
Stages
A policy's reach is its rollout stage:
| Stage | What it does |
|---|---|
| Monitor | Fires and is recorded — violations are stored as monitored, which nothing that stops work reads. Agents are briefed that it is monitored. It appears on the change and as a policy_monitor:<key> item on the compliance verdict, with what it would require once enforced. It adds no evidence requirement, no gate and no block. |
| Pilot | Enforced in the workspaces you pick; monitored everywhere else. |
| Enforce | The behaviour before stages existed, and the default for the API. |
One rule engine decides all of it — change evaluation, the evidence gate, compliance, risk, the allow-lists and simulation read the same function — so a policy cannot be enforced in one place and monitored in another by accident. A stage change is audited and re-evaluates open pull requests.
New policies created in the interface default to monitor. The API default stays enforce.
Simulation
Before enforcing, replay it. A draft, a proposal or an earlier version is run as if enforced over the last 7, 30 or 90 days of reported change sets and mirrored pull requests, against every other policy as enforced today. The result, by workspace: what it would have added or blocked, and which pull requests that are compliant today would have failed.
Pull requests whose changed paths were never read are counted, not guessed. Every simulation is recorded (totals only), and the latest one is shown on the governance journey.
Choices worth knowing about
These are how the feature currently behaves, recorded here so they can be reviewed rather than discovered:
- A stage change needs no second person, even with review on. It is audited.
- Retiring or deleting a policy skips review.
- New policies default to monitor in the interface; the API default stays enforce.