Skip to main content
Version: v5.8.0

Step attestation

Included from Basic tier

A manual step is a step a human performs inside a run — a console, a portal, a vendor UI, a registrar, a change board, or a command — stated in advance in the action file (manual:, opschain docs orchestration) and rendered from the run's facts. The run holds at the step until a human answers it: an attestation (what was done, with typed evidence) lets the run continue; a refusal (with a reason) fails the step by name, and its on_error: applies. An unattested step past its timeout fails. Every production change is then exactly one of: an automated step, an attested step, or a break-glass record (opschain docs resources/breakglass_record).

A step attestation is that answer, stored with the run: who answered it (a principal id), when, the activity and command exactly as the run rendered them, the evidence and its class, the note or the reason, and the outputs the attester filled for later steps.

Served by StepService on /api/v2 — AttestStep, RefuseStep, ListStepAttestations (opschain docs api-v2) — and opschain runs attest|refuse (opschain docs cli/runs-attest, opschain docs cli/runs-refuse); opschain runs show lists a run's manual steps with their answers. Answers live in the server's store — PostgreSQL or SQLite — and, in the local lane, in the home's store.

The v2 OpenAPI document declares this resource's schemas (StepAttestation, ManualStep, ManualEvidenceDemand); the resource-field coverage gate holds this page to them.

Attributes (StepAttestation)​

Timestamps are RFC3339 in UTC.

FieldTypeMeaning
idstringThe answer's id (UUIDv7).
run_idstringThe run (change) the manual step belongs to.
step_idstringThe manual step.
step_pathstringThe step's full path in the run's tree.
outcomestringattested or refused.
principal_idstringThe answering principal's id — never a username. On a server with no users (the SQLite store) it reads anonymous; in the local lane, local.
answered_attimestampWhen the answer was recorded.
titlestringThe step's title as rendered for this run.
activitystringThe activity as rendered for this run — what the human was asked to do.
commandstringThe command as rendered, when the activity is a command.
wherestringWhere the activity is performed (a portal, a console, an account), as rendered.
evidence_classstringThe strongest evidence kind present: reference, command, file or statement.
evidencearrayThe evidence items (the break-glass record's BreakglassEvidence shape, opschain docs resources/breakglass_record), the statement always present.
notestringThe attester's note, or the refusal's reason (required for a refusal, at most 4000 bytes).
outputsmapThe outputs the attester filled — every output the step declares, single-line values of at most 4096 bytes — published as the step's outputs (${{ steps.<name>.outputs.<key> }}).
correlation_idstringThe chain the answer's event is on: the run's (opschain chains show <id>).

Manual step (ManualStep)​

ListStepAttestations answers a run's manual steps:

FieldTypeMeaning
step_idstringThe manual step's id.
step_pathstringIts full path.
statestringpending (not yet reached), awaiting_attestation, attested, refused, timed_out, or the step's own state when it never reached waiting (skipped, cancelled, aborted).
titlestringThe declared title, as rendered once the step is reached.
activitystringThe declared activity, as rendered once the step is reached.
commandstringThe declared command, as rendered.
wherestringWhere the activity is performed, as rendered.
evidencearrayThe evidence the step demands (ManualEvidenceDemand, below).
attester_principalsarrayPrincipal ids that may attest; with attester_groups empty too, every holder of the attest grant may.
attester_groupsarrayGroups whose members may attest.
capabilitiesarrayCapability grants the attester must hold, each an execute grant on <run node>/attest/<capability>.
outputsarrayThe outputs the attestation fills.
waiting_sincetimestampWhen the step entered waiting.
deadlinetimestampWhen an unattested step fails (waiting_since plus the step's timeout:, else the server's step timeout). Set while it waits.
attestationobjectThe answer (StepAttestation), once given.
can_attestboolWhether the caller may answer this step — attest or refuse it: exactly the decision AttestStep and RefuseStep make (below, "Who may"), taken from the caller's grants without a store read. False for an agent, a service account or a step's credential. It says nothing about the step's state: a step not awaiting attestation is still refused by state.

The response also carries the evidence policy the answer's files are held to, so a form can refuse a file before uploading it:

FieldTypeMeaning
evidence_max_bytesint64The per-file budget in bytes: breakglass.evidence_max_mb (a value outside 1–512 is ignored), 10 MB (10485760) when unset.
evidence_typesarrayThe accepted media types: breakglass.evidence_types, lower-cased, a value without a / dropped; the five defaults when unset. A step's accept: narrows them further.

Evidence demand (ManualEvidenceDemand)​

FieldTypeMeaning
kindstringreference, command, file or statement.
namestringThe item's name, unique within the step.
requiredboolThe attestation is refused without it. A refusal never needs declared evidence.
commandstringA command item's read-only check, as rendered. The attester supplies only its output; the command and the expect are the action author's, sealed with the action's version.
expectstringWhat the output must contain — a substring, or /a regular expression/. An output that does not satisfy it is refused.
acceptarrayA file item's accepted media types, narrowing the server's evidence policy.

Evidence​

Evidence has four kinds, each honest about what it proves — the same kinds, shape and policy as a break-glass record: a reference the external system minted (the strongest: it can be matched exactly against the system's own log), a command check whose output satisfied its expect, a file — a screenshot or an export, stored as an artifact on the run's node and digest-sealed on the answer (weak: a screenshot proves presence, not correctness) — and the attester's statement, always present. An attestation on a statement and a screenshot is recorded as exactly that.

An evidence file is uploaded first (ArtifactService.UploadArtifact on the run's node; opschain runs attest --evidence does it for you) and is bounded by the same two stored settings as break-glass evidence — breakglass.evidence_max_mb (default 10) and breakglass.evidence_types (default image/png, image/jpeg, application/pdf, application/json, text/plain), opschain docs settings-reference — narrowed by the step's accept:. The server reads the stored artifact's digest, type and size (never the caller's word) and the first 512 bytes of its content, refusing by name a file whose content disagrees with its type. Files ride the artifact store, never the log pipe: a console screenshot can carry a secret in plain sight — redact before you attach.

Who may​

Every verb is deny-by-default, 404-on-deny on the run's node:

  • read (ListStepAttestations) — read on the run's node.
  • attest and refuse (AttestStep, RefuseStep) — read on the run's node and execute on its <node>/attest rule path; then, answered permission_denied by name, an execute grant on <node>/attest/<capability> for every capability the step declares, and — when the step names attesters: — the caller is one of its principals or a member of one of its groups.

Attesting and refusing are human verbs: an agent, a service account or a step's credential is refused by name (permission_denied, "attesting or refusing a manual step is a human verb"). continue, approve and --approve-all never answer a manual step.

Events​

An attestation writes audit:runs:attested, a refusal audit:runs:refused — on the run's chain at the step, in the same transaction as the answer, the step's transition and its outputs, carrying principal ids only (opschain docs events). A refusal also fails the step with manual step refused by <principal id>: <reason>; a timeout fails it with manual step <path> was not attested within its <timeout> timeout. Attested steps join the governed-activity export and the coverage query as kind attested_step (opschain docs resources/governed_activity).

Retention​

An answer ages out on the evidence ledger's horizon (retention.evidence_ledger_days, default 730 days), archived with its evidence items before deletion; every artifact it names as evidence is kept while the answer is (opschain docs retention).

Postures​

  • Local lane (--local, or no server targeted): the attached run prints the rendered activity and the verbs that answer it, and holds; opschain runs attest --local (or refuse) from another terminal records the answer in the home's store under the lane's one implicit principal (local), its files in the home's artifact store with the default budget and types, and the attached run picks it up. The CLI says a local answer reaches a server only through the governed-activity export.
  • Server on the SQLite store: manual steps hold and answer; references, command evidence and statements work; evidence files need the PostgreSQL store's artifacts and are refused by name. This posture has no users, so principal_id reads anonymous.
  • Server on PostgreSQL: everything on this page.

Not yet​

approval: on a manual step — an approval-policy hold on one step — is refused by name in this release; an approval policy matching the action holds the whole run before it starts (opschain docs change-governance).

What changes it​

  • A run reaching a manual step holds it (awaiting_attestation).
  • opschain runs attest / AttestStep records an attestation; the run continues.
  • opschain runs refuse / RefuseStep records a refusal; the step fails.
  • The step's timeout passing fails an unattested step (no answer is stored).
  • Retention ages out an answer past the evidence ledger's horizon.