Skip to main content
Version: v5.8.0

opschain step add-reference

Included from Basic tier

opschain step add-reference --system <system> --kind <kind> --id <id>
[--url <url>] [--scope <scope>]

Records, from inside a running step, one external reference: the id a target system minted for what this step changed — an ARM deployment or operation id, a Cloudflare rule or audit entry id, a commit, a GitHub run id, a JSM issue key, an HTTP request id. The reference is appended as a JSON line to the file named by $OPSCHAIN_EXTERNAL_REFERENCES; the engine stores it on the step when the step succeeds, with the run, node, chain and creating principal id, and writes audit:steps:external_references on the change's chain.

The reference is held on OpsChain's side only — nothing is written into the target system. It is the join key an auditor follows from the target's own audit log to the step (opschain docs cli/governance-references), and what makes a run's coverage attribution reference rather than window (opschain docs resources/governed_activity). A step that records none is attributable by its run's window only.

Flags​

FlagMeaning
--system <system>The target system, a lowercase name matching ^[a-z0-9][a-z0-9_.-]{0,63}$ (azure, cloudflare, github, git, jsm, http). Required.
--kind <kind>The kind of record the system minted, same grammar (deployment, operation, rule, commit, run, issue, request). Required.
--id <id>The id the target system minted: one line, at most 500 bytes. Required.
--url <url>A link to the record in the target system: an absolute http(s) URL without user information, at most 2000 bytes.
--scope <scope>The external scope the record lives in, e.g. /subscriptions/<id>/resourceGroups/<name>, a zone, owner/repo. One line, at most 500 bytes.

A step reports at most 64 references; a retried step's references replace its earlier attempt's. A reference whose id, URL or scope carries a secret of the run's mask set or of the same step's sensitive outputs fails the step by name, on the runner and again on the server — a reference is an identifier, never a credential. --url refuses user information only: a credential in a URL's query string (a SAS signature, a token parameter) is the pack author's responsibility, refused only when it matches a masked value.

The server must be at v5.8.0 or later for a reference to be recorded: an older server ignores the field, records nothing, and the step still succeeds.

Environment​

VariableMeaning
OPSCHAIN_EXTERNAL_REFERENCESThe external-references file this command appends to (set by the executor). Each line is {"system": …, "kind": …, "id": …, "url": …, "scope": …}; a step may write it directly.

Exit codes​

CodeMeaning
0Reference recorded.
1The references file could not be written.
2Usage error — a malformed reference, or not inside a step.

Named errors​

  • external reference system "<s>" must match ^[a-z0-9][a-z0-9_.-]{0,63}$ (same for kind)
  • external reference (<system> <kind>) needs the id the target system minted
  • external reference url "<url>" must be an absolute http(s) URL
  • external reference url must not carry credentials (user information before the host)
  • $OPSCHAIN_EXTERNAL_REFERENCES is not set: opschain step subcommands only work inside a running OpsChain step

All exit 2. At collection, the same checks plus step_external_references line N matches a masked secret value and … over the 64 per step fail the step.

Examples​

opschain step add-reference --system azure --kind deployment \
--id "$DEPLOYMENT_ID" --scope "/subscriptions/$SUB/resourceGroups/$RG" \
--url "https://portal.azure.com/#resource$DEPLOYMENT_ID"
opschain step add-reference --system git --kind commit --id "$(git rev-parse HEAD)" --scope LimePoint/site