Starting a run means choosing which plan, which mode, and any variables it needs. The console then shows each step executing against each host, live.
Choose a mode#
| Mode | What it does |
|---|---|
| Automatic | Runs start to finish without stopping |
| Step through | Pauses at each step for you to continue, skip, retry or roll back |
| Dry run | Changes nothing; reports what would happen |
Automatic is the normal choice for a plan that has run before. Step through is for a plan you are still learning to trust, and it is a different thing from an approval gate: the gate asks somebody else once, before anything runs, while step through keeps you in the loop throughout.
Start with a dry run the first time a plan meets a host you care about.
Variables at start#
If the plan declares typed inputs, you are prompted for them, with defaults filled in and required ones enforced. Otherwise you can supply free-form variables that override the plan's own.
Values supplied here take precedence over plan variables, which take precedence over environment values. Environment values are resolved per host, so a run spanning staging and production gives each host its own.
What happens first#
Before the first step, Opafra resolves the plan's targets, works out which environments they belong to, and checks two things:
Concurrency. If the same plan is already running against any of the same hosts, the run is refused and the overlapping hosts are named. A plan can opt into concurrent runs where that is genuinely safe.
The approval gate. If any environment the run touches requires approval, the run pauses before its first step and waits. Dry runs skip this, because they change nothing.
Reading the console#
The console streams per step and per host. Each host shows its own status, output and duration, because the interesting information in a multi-host run is where the hosts disagree.
A step that calls a module expands into its items as it runs, so you see the actual work rather than an opaque single line.
When a step fails#
The run halts. Later steps do not execute, and the run is recorded as failed. This is the default in every mode, including the step-through ones, because the second half of a plan usually assumes the first half worked.
Three per-item settings, declared in the plan rather than chosen now, change this:
continue_on_error lets an item fail without failing the run, retries adds attempts,
and retry_delay_seconds spaces them out. See plan structure.
A failed item under continue_on_error is still recorded as failed. The setting stops it
halting the run; it does not make it invisible.
Aborting#
A run can be aborted while it is running or while it is paused. Aborting stops further steps; it does not undo what has already been done, because Opafra does not assume every step has an inverse.
Where a plan needs to undo something, that is a step in the plan.
Statuses#
| Status | Meaning |
|---|---|
| Pending | Created, not yet started |
| Running | Executing |
| Paused | Waiting at an approval gate or a step-through decision |
| Completed | Every step succeeded |
| Failed | A step failed and the run halted |
| Aborted | Someone stopped it |
A paused run is durable. The checkpoint is written to the database rather than held in memory, so a run waiting overnight is still waiting after a restart.
The run record#
Every run keeps what was asked for, who started it, who approved it and against which plan revision, what each step did on each host, the output, and the result. It survives the plan being edited or deleted afterwards.
That record is the answer to "what actually happened", and it is why a run is worth starting from Opafra rather than from a terminal.
Next steps#
- Dry runs for previewing before you run for real
- Scheduling for running a plan on a timer