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.
| Field | Type | Meaning |
|---|---|---|
kind | string | run (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). |
id | string | The run's, the record's or the answer's id. |
node_path | string | The node the activity changed. |
project_path | string | The node's project. |
principal_id | string | The principal id that created the run, recorded the record or answered the manual step — never a username. |
correlation_id | string | The activity's chain (opschain chains show <id>). |
started_at | timestamp | A run's creation; a record's act window start; an answer's time. |
ended_at | timestamp | A run's finish (unset while it runs); a record's act window end; an answer's time. |
attribution | string | reference 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. |
status | string | A run's status; a record's reconciliation state (unreconciled, closed); an answer's outcome (attested, refused). |
action | string | A run's action; an attested step's full path. |
external_references | array | The references the run's steps reported (GovernedExternalReference, below), at most 50. |
external_references_truncated | bool | True when the run reported more than 50; ListExternalReferences with the run id reads every one. |
external_scopes | array | The distinct external scopes those references name — the subscriptions, zones, repositories the run touched as its steps reported them. |
evidence_class | string | A record's or an answer's evidence class (opschain docs resources/breakglass_record). |
breakglass | object | For kind breakglass, the record with its evidence — reference ids and the digests of evidence files. |
attestation | object | For kind attested_step, the answer with its evidence (StepAttestation, opschain docs resources/step_attestation). |
settings_read | array | For kind run, the settings document versions the run read (RunSettingRead, below), at most 100; empty when it read none. |
settings_read_truncated | bool | True 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)
| Field | Type | Meaning |
|---|---|---|
system | string | The target system, a lowercase name (azure, cloudflare, github, git, jsm, http, …). |
kind | string | The kind of record the system minted (deployment, operation, rule, commit, run, issue, request, …). |
id | string | The id the target system minted. At most 500 bytes, one line. |
url | string | A link to the record in the target system: absolute http(s), never with credentials. |
scope | string | The external scope the record lives in, e.g. /subscriptions/<id>/resourceGroups/<name>, a zone, owner/repo. |
run_id | string | The run whose step reported it. |
step_id | string | The reporting step. |
step_name | string | The reporting step's reference name. |
node_path | string | The node the run changed. |
correlation_id | string | The run's chain. |
principal_id | string | The run's creating principal id — never a username. |
recorded_at | timestamp | When 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.
| Field | Type | Meaning |
|---|---|---|
path | string | The 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. |
owner | string | The document's place in the ladder: global, the owning node's type (project, environment, asset), template or template_version. |
version | integer | The document version read. |
read_at | timestamp | When 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, thenid), 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 carrieshome_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 onesystem). 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 andrecorded_at,unreconcileduntil 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 alocal_importstatement 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:
| Field | Type | Meaning |
|---|---|---|
index | int | The line's position in the call's activities. |
kind | string | The line's kind. |
id | string | The id the line carries — the local record's or run's. |
outcome | string | imported, already_imported, attached, already_attached, skipped, not_found or invalid; on a dry run imported and attached say what would land. |
record_id | string | The record's id on the server, for imported and already_imported. |
detail | string | Why the line did not land, for skipped and invalid. |
references_attached | int | The 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>/breakglassrule path, exactly as its own reads do; ListExternalReferenceswith a run id needs read on the run's node (404-on-deny); an external-id lookup filters per reference.ImportGovernedActivityis a write: per line, read on the record's node and update on its<node>/breakglassrule path — the rights recording a break-glass record needs — and the same on a run's node for its references. A denied record answersnot_found(a denied runskipped, 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,activityandreferencesquery 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 throughopschain 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_byisanonymous; 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.