Skip to main content
Version: v5.8.0

opschain runs attest

Included from Basic tier

opschain runs attest <run-id> <step> [--evidence name=file]... [--reference name=system:id]... [--check-output name=file]... [--step-output key=value]... [--note <text>] [--statement <text>]

Attests a manual step the run is holding: you performed the activity the step names — a console, a portal, a vendor UI, a registrar, a change board, or a command — and here is the evidence. The run continues once the attestation is recorded, with your principal id on its chain (audit:runs:attested). <step> is the step's id, its full path, or its name (runs show <run-id> lists the run's manual steps, their rendered activity and when an unattested step fails).

Evidence takes four kinds (opschain docs resources/step_attestation):

  • references the external system minted (--reference operation_id=azure:6f1c…) — the strongest;
  • the output of one of the step's own read-only checks (--check-output name=file) — the command and its expect are the step's, sealed by its author; an output that does not satisfy the expect is refused;
  • files such as screenshots or exports (--evidence name=file, or a bare path named by its file name) — uploaded to the run's node and digest-sealed; weak evidence;
  • your statement (--statement, else --note) — always recorded.

A step may require some of them and may declare outputs you fill with --step-output key=value; later steps read them as ${{ steps.<name>.outputs.<key> }}. A file over the evidence budget (10 MB by default) or outside the accepted types is refused before anything is uploaded; the server re-checks the stored file's size, type and content.

Against a server, the attest grant (execute on <run node>/attest), each capability the step declares (execute on <run node>/attest/<capability>) and the step's declared attesters decide who may answer; agents, service accounts and step credentials are refused by name. In the local lane (--local) the attached run waits for the answer: run this command from another terminal; the answer is recorded in the home's store under the lane's one implicit principal and the attached run picks it up.

Flags​

FlagMeaning
--evidence name=fileAn evidence file (repeatable): a screenshot, an export. A bare path is named by its file name.
--reference name=system:idAn identifier the external system minted (repeatable), e.g. operation_id=azure:6f1c….
--check-output name=fileThe captured output of one of the step's declared checks (repeatable; at most 64 KiB).
--step-output key=valueOne of the step's declared outputs (repeatable); every declared output is required.
--note <text>A note recorded with the attestation.
--statement <text>Your statement of what was done; the note stands in when empty.

Output​

attested manual step release/verify-domain of run 0199c81e-… (evidence class reference) — the run continues

-o json|yaml prints the stored attestation in the StepAttestation shape (opschain docs resources/step_attestation): id, run_id, step_id, step_path, outcome, principal_id, answered_at, title, activity, command, where, evidence_class, evidence (the BreakglassEvidence keys), note, outputs, correlation_id; empty fields omitted. In the local lane a notice on stderr says the answer is in the local store only.

Exit codes​

CodeMeaning
0Attested.
1The attestation was refused — the step is not awaiting attestation, required evidence or a declared output is missing, a check's output does not satisfy its expect, a file is over budget, of the wrong type or of the wrong content, or you hold no attest grant.
2Usage error (a malformed --reference, --step-output or --check-output, a file over the default budget or type).

Named errors​

  • run <id> has no manual step "<step>" (its manual steps: …) — exit 1.
  • "<step>" names <n> manual steps of run <id>: give the full path or the step id — exit 1.
  • manual step <step> of run <id> was not found (or you hold no attest grant on the run's node) — exit 1.
  • The manual step is not awaiting attestation: it is in the "<state>" state — exit 1.
  • evidence: the step requires its reference evidence "<name>" — exit 1.
  • outputs.<key>: the step declares output "<key>" for later steps: the attestation fills it — exit 1.
  • the step demands the "<capability>" capability: … — exit 1.
  • attesting or refusing a manual step is a human verb: … — exit 1.