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
| Flag | Meaning |
|---|---|
--evidence name=file | An evidence file (repeatable): a screenshot, an export. A bare path is named by its file name. |
--reference name=system:id | An identifier the external system minted (repeatable), e.g. operation_id=azure:6f1c…. |
--check-output name=file | The captured output of one of the step's declared checks (repeatable; at most 64 KiB). |
--step-output key=value | One 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
| Code | Meaning |
|---|---|
| 0 | Attested. |
| 1 | The 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. |
| 2 | Usage 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.