Skip to main content
Version: v5.8.0

Governed activity

Included from Basic tier

Governed activity is the claim OpsChain makes about change: for a node and a window, which change runs and which break-glass records say they changed it, and how exactly each can be matched against the target system's own audit log. It answers the auditor's question — "what covers this scope in this window?" — with or without an observer of the external audit streams.

A run is matched exactly when its steps reported external references: the identifiers the target system minted for what the step did — an ARM deployment or operation id, a Cloudflare rule or audit entry id, a commit, a GitHub run id, an issue key, a request id. A step reports them with opschain step add-reference (opschain docs cli/step-add-reference) or by writing $OPSCHAIN_EXTERNAL_REFERENCES. OpsChain never writes its own ids into the target system: the join key is held on OpsChain's side, so an auditor starting from an entry in the target's log finds the step by that entry's id (opschain governance references --external-id …). A run whose steps reported none — a target that returns nothing durable — is matched by its window only, and its attribution says so.

Served by GovernanceService on /api/v2 (opschain docs api-v2): GetCoverage (the coverage query), ListGovernedActivity (the export's pull lane), ListExternalReferences and ImportGovernedActivity (a local home's export landing on a server); on the CLI by opschain governance coverage|activity|references and opschain governance activity import (opschain docs cli/governance-coverage, opschain docs cli/governance-activity-import).

The v2 OpenAPI document declares this resource's schemas (GovernedActivity, GovernedExternalReference, ImportedGovernedActivity, RunSettingRead); the resource-field coverage gate holds this page to them.

Attributes (GovernedActivity)​

Timestamps are RFC3339 in UTC.

FieldTypeMeaning
kindstringrun (a change run), breakglass (a break-glass record) or attested_step (a human's answer to a manual step — an attestation or a refusal, opschain docs resources/step_attestation).
idstringThe run's, the record's or the answer's id.
node_pathstringThe node the activity changed.
project_pathstringThe node's project.
principal_idstringThe principal id that created the run, recorded the record or answered the manual step — never a username.
correlation_idstringThe activity's chain (opschain chains show <id>).
started_attimestampA run's creation; a record's act window start; an answer's time.
ended_attimestampA run's finish (unset while it runs); a record's act window end; an answer's time.
attributionstringreference when the activity carries an identifier the target system minted — exact against that system's log — or window when it can be matched by its window only. A break-glass record or an attested step is reference when it carries reference evidence.
statusstringA run's status; a record's reconciliation state (unreconciled, closed); an answer's outcome (attested, refused).
actionstringA run's action; an attested step's full path.
external_referencesarrayThe references the run's steps reported (GovernedExternalReference, below), at most 50.
external_references_truncatedboolTrue when the run reported more than 50; ListExternalReferences with the run id reads every one.
external_scopesarrayThe distinct external scopes those references name — the subscriptions, zones, repositories the run touched as its steps reported them.
evidence_classstringA record's or an answer's evidence class (opschain docs resources/breakglass_record).
breakglassobjectFor kind breakglass, the record with its evidence — reference ids and the digests of evidence files.
attestationobjectFor kind attested_step, the answer with its evidence (StepAttestation, opschain docs resources/step_attestation).
settings_readarrayFor kind run, the settings document versions the run read (RunSettingRead, below), at most 100; empty when it read none.
settings_read_truncatedboolTrue when the run read more settings document versions than listed.

An activity covers the window [from, to) when it overlaps it: a run created before to that had not finished before from (a running run covers every window after it started); a record whose act window starts before to and ends at or after from; an attested step whose answer falls inside the window. Workflow runs are not listed: their changes are.

External references (GovernedExternalReference)​

FieldTypeMeaning
systemstringThe target system, a lowercase name (azure, cloudflare, github, git, jsm, http, …).
kindstringThe kind of record the system minted (deployment, operation, rule, commit, run, issue, request, …).
idstringThe id the target system minted. At most 500 bytes, one line.
urlstringA link to the record in the target system: absolute http(s), never with credentials.
scopestringThe external scope the record lives in, e.g. /subscriptions/<id>/resourceGroups/<name>, a zone, owner/repo.
run_idstringThe run whose step reported it.
step_idstringThe reporting step.
step_namestringThe reporting step's reference name.
node_pathstringThe node the run changed.
correlation_idstringThe run's chain.
principal_idstringThe run's creating principal id — never a username.
recorded_attimestampWhen the step's result was applied.

A step reports at most 64 references; a malformed one, or one whose id, URL or scope carries a secret of the run's mask set or of the same step's own sensitive outputs, fails the step by name — checked on the runner and again on the server, so nothing of it is stored, chained or exported. A reference is an identifier, never a credential. The URL contract refuses user information; 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. A retried step's references replace its earlier attempt's.

Settings read (RunSettingRead)​

A run records the version of every settings document it read, beside the commit it ran under, so "what did this run see" is answerable without the setting's own history — and a setting changed by hand between two runs shows on the run that read the new value. The documents are the ones the run's settings ladders resolve over for its target (runner placement, the retry, fan-out and change-depth defaults, the repository folder): the global settings, every node of the target's path that holds a settings document, and an asset's template and template-version layers. Each step's enqueue stamps the versions then in force; a version the run already holds is not written again, so a document edited while the run is in flight appears once per version its steps saw.

FieldTypeMeaning
pathstringThe document's node path — the system configuration node for the global settings; a template layer carries the path of the asset whose chain it sits in.
ownerstringThe document's place in the ladder: global, the owning node's type (project, environment, asset), template or template_version.
versionintegerThe document version read.
read_attimestampWhen the run first read that version.

The same list is on the change and workflow-run reads (settings_read, opschain docs resources/change) and in opschain runs show. A server on SQLite stamps the same way, from its own settings documents (it has no global settings document). A local-lane run reads no versioned settings — its ladders read the home's config.yaml orchestration: block (opschain docs config) — so its list is empty. The rows live as long as their run and are removed with it when its project is purged. A stamp that fails is reported on the server's console naming the run, and never holds the step.

Queries​

  • Coverage (GetCoverage, opschain governance coverage --scope <node> --from <t> [--to <t>]): the scope — a node and its subtree — is required; the window is required and spans at most 366 days. Oldest first (started_at, then id), keyset-paged (default 50, at most 200 per page).
  • Export (ListGovernedActivity, opschain governance activity --from <t> [--scope <node>] [--out <file>]): the same activities, estate-wide when no scope is given — the CLI writes one JSON document per line. In the local lane every line also carries home_id, the home's identity (a UUID minted once per home, kept in <home>/local/home_id), which is what makes the file importable.
  • References (ListExternalReferences, opschain governance references): every reference one run reported, or every step that reported a target system's id (optionally narrowed to one system). Default 100, at most 1000 per page.

A request scans at most 10,000 rows, read in batches of 500 whatever the page size; a page that bound cuts short still carries next_page_token, so only a response without a token ends the listing. A resume token encodes the scan position, which may be a row the caller cannot read (its id and instant); it resolves to nothing elsewhere. (A recorded deviation from the API's rule that a token names the last row served: stepping back to the last served row would never progress through a scan of rows the caller cannot read.) Reads are indexed: references by external id, by run and by node; runs by node and last update; break-glass records by node and act window.

Import (ImportGovernedActivity)​

A local home's export lands on a server with opschain governance activity import <file> — at most 100 lines per call, each judged on its own, dry_run reporting the same outcomes and writing nothing:

  • a break-glass record lands as a record of the importing human (recorded_by), keeping its act window and recorded_at, unreconciled until a reviewer closes it, correlated only by its external change reference (the home's runs and change records are not the server's), its file evidence turned into statements naming each file's type, size and digest, and a local_import statement naming the home, the local record and its local run, change record and closure. The server keys it by the home and the local id, so the same record imported again lands nothing (already_imported);
  • a run's references attach to the run of the same id on the server, to the steps it holds, skipping a reference that step already has; a run the server does not hold is skipped;
  • an attested step is skipped.

ImportedGovernedActivity is one line's outcome:

FieldTypeMeaning
indexintThe line's position in the call's activities.
kindstringThe line's kind.
idstringThe id the line carries — the local record's or run's.
outcomestringimported, already_imported, attached, already_attached, skipped, not_found or invalid; on a dry run imported and attached say what would land.
record_idstringThe record's id on the server, for imported and already_imported.
detailstringWhy the line did not land, for skipped and invalid.
references_attachedintThe references attached to the run (or that would be), for attached.

Who may​

Read-only, deny-by-default, on both server stores:

  • GetCoverage — read on the scope node (404-on-deny), then per row;
  • every listing filters per row before paging: a run needs read on its node; a break-glass record needs read on its node and on its <node>/breakglass rule path, exactly as its own reads do;
  • ListExternalReferences with a run id needs read on the run's node (404-on-deny); an external-id lookup filters per reference.
  • ImportGovernedActivity is a write: per line, read on the record's node and update on its <node>/breakglass rule path — the rights recording a break-glass record needs — and the same on a run's node for its references. A denied record answers not_found (a denied run skipped, as if absent) and the other lines still land; agents, service accounts and step credentials are refused by name.

Events and the SIEM stream​

A step's reported references write audit:steps:external_references on the change's chain in the same transaction (opschain docs events). A SIEM connection forwards it with every other chain event — the run lifecycle and security:breakglass:* events beside it — when its event_filter is empty, or selects it by prefix (audit:steps:, security:breakglass:); the governed activity reaches a SIEM with principal ids only. Approval decisions travel as the audit:approvals:* events and are read back over a scope and window with opschain approvals history (opschain docs change-governance). An import writes security:breakglass:recorded per record and audit:steps:external_references per run step with source: local_import and the home's id, and one audit:governance:activity_imported per call with its counts.

Retention​

External references age out on the evidence ledger's horizon (retention.evidence_ledger_days, default 730 days, by recorded_at), archived before deletion (opschain docs retention). They are kept when a node is destroyed — the join key outlives the run it points at — and deleted by opschain state reset --project.

Postures​

  • Local lane (--local, or no server targeted): steps record their references into the home's store; opschain governance coverage, activity and references query the home's runs and break-glass records. opschain governance activity --local --out <file> is the home's export — the file a server's reviewers receive through opschain governance activity import. The import itself is refused by name in the local lane: it lands on a server.
  • Server on the SQLite store: references are stored and every query and the import work. This posture has no users: run principal ids are empty and an imported record's recorded_by is anonymous; any well-formed node path is accepted, as recording is.
  • Server on PostgreSQL: everything on this page. A run created without a recorded principal takes its change's creator.

What changes it​

  • A step reports a reference: opschain step add-reference, $OPSCHAIN_EXTERNAL_REFERENCES.
  • A run is created or finishes; a break-glass record is recorded or closed (opschain docs resources/breakglass_record).
  • A local home's export is imported: opschain governance activity import.
  • Retention ages out references past the evidence ledger's horizon.