Marking an environment as requiring approval means every run whose targets land in it pauses before its first step, and waits for a person to approve it. One approval per run, taken before anything happens.
The gate is a property of the environment, not of the plan and not of a step. That distinction decides everything else on this page.
Why the environment owns the gate#
If a gate is a node in a plan, then a plan without that node has no gate. Whoever writes the next plan has to remember, and the plan that skips the gate is the plan that reaches production unreviewed.
Attaching the rule to the environment inverts that. production is protected once, and
from then on every plan that touches a host in it is gated, including plans written
afterwards by people who never heard of the policy, including a plan targeting one host by
name that happens to be in production, and including a plan someone wrote specifically to
avoid the gate.
One gate, before anything runs#
The gate opens once, at the start, and it gates the whole run.
That is a deliberate choice against per-step approval. A gate on every step trains approvers to click through without reading, which is a policy that produces an audit trail and no scrutiny. One approval at the point where it can still prevent something is worth more than twenty after the fact.
Once approved, the run proceeds in whatever mode it was started in. Approval decides whether the run happens; it does not change how it happens. If you want per-step pauses, start the run in a step-through mode, and the two are independent.
The flow#
- Someone starts a run whose targets include a protected environment.
- The run is created and immediately pauses. Status is
PAUSED; no step has executed. - The plan's current revision is recorded as the revision being asked about.
- The run appears in the approvals inbox for everyone entitled to decide.
- An approver approves or rejects, optionally with a reason.
- On approval, the run resumes from the beginning in its chosen mode. On rejection, it ends without having run anything.
The pause is durable. It survives a restart of Opafra, because the checkpoint is written to the database rather than held in memory, so a run left waiting overnight is still waiting in the morning.
Who can approve#
Approval requires the Operator role or above, so Operator, Admin and Owner. A Viewer cannot approve. The check is on the role, and the run has to belong to the approver's organisation: a pending approval in another tenant is not visible and cannot be resolved, even by id.
Opafra does not currently prevent the person who started a run from approving it. If your policy needs four eyes, that is a policy you enforce, not a rule the product applies.
What the approver is shown#
The plan, the environments the run touches, the mode it will proceed in, and the targets.
It also records which revision of the plan was being approved. If the plan is edited between the request and the decision, the two revisions differ and the discrepancy is surfaced rather than quietly honoured. Both numbers go into the audit record, so "what exactly did they approve" has an answer months later.
Dry runs are never gated#
A dry run changes nothing, so it is never held at the gate, even against a protected production environment. Anyone who can start a run can preview one.
This is the intended pairing: preview freely, and let the gate stand where changes happen. An approver looking at a gated run has usually already seen what it would do.
Protected is not the same as restricted#
Two separate flags, often confused because both sound like "locked down":
- Requires approval gates runs. People can see the environment and start runs against it; the runs wait for a decision.
- Restricted gates access. Even an Operator needs an explicit grant to view, run against, or manage the environment at all.
An environment can have either, both, or neither. Approval is about the change; restriction is about the people.
Environments with the Production tier default to requiring approval when created. It is a default, not a lock, and it can be turned off.
What lands in the audit log#
The decision, who made it, when, the action taken, any reason given, and both revision numbers. A rejection is recorded as a rejection: Opafra does not stamp approval fields on a run that was refused, so the trail never reads as though a rejected run had been approved.
Next steps#
- Dry runs for what to look at before approving
- Core concepts for how environments and targets relate