opschain maintenance
maintenance
Manage node maintenance windows. A window quiesces exactly one node's subtree (a project, environment or asset path) while declared maintenance work runs: non-allowlisted creates targeting the subtree answer a named 422, and trigger firings whose action targets the subtree settle deferred — parked, never lost — until the window ends. Everything else is untouched: siblings proceed normally, and in-flight work already running when the window starts finishes on its own terms. All verbs are server-targeted.
| Subcommand | Does |
|---|---|
opschain maintenance start | Start a window now (manual: advisory end intent, never auto-closes) — opschain docs cli/maintenance-start |
opschain maintenance schedule | Create a window that starts and ends by itself, optionally running workflows and auto-extending — opschain docs cli/maintenance-schedule |
opschain maintenance status | Show a node's window: reason, allowlists, deferred work — opschain docs cli/maintenance-status |
opschain maintenance extend | Move an active window's end later — opschain docs cli/maintenance-extend |
opschain maintenance end | End a window and release the deferred firings — opschain docs cli/maintenance-end |
opschain maintenance cancel | Remove a scheduled window before it starts — opschain docs cli/maintenance-cancel |
opschain maintenance list | All windows across the estate, with recent history on request — opschain docs cli/maintenance-list |
Lifecycle
Only one window — active or scheduled — can exist per node at a time. A
manual window (start) opens immediately and only end closes it;
its --until is declared intent, nothing enforces it. A scheduled
window (schedule) opens at --from and is closed by the server at its
hard end (--to, pushed later by auto-extension or extend); cancel
removes it while it is still pending.
The window's own work goes through on allowlists (--allow-workflow,
--allow-action, --allow-user) and is stamped as allowed. Trigger
lineage is never allowlisted — automation defers even when the deferring
event came from allowlisted maintenance work. Starting and ending emit the
triggerable api:nodes:maintenance_started / api:nodes:maintenance_ended
events on the node path.
Ending releases the still-deferred firings in original event order,
re-evaluating each against the world as it now is; a deferral parked past
a manual window's declared end intent expires as suppressed instead of
firing into an unwatched estate. The parked work is listed and selectively
discarded through opschain triggers (see opschain learn 5.6 –4),
and a create can override the gate — audited — via the
override_maintenance key of the -f payload of
opschain runs create change and opschain runs create workflow
(opschain docs cli/runs-create).
See also
opschain learn 5.6— the guided maintenance-window runbook.opschain learn 5.2— triggers, whose firings are what a window defers.