Break-glass record
Included from Basic tier
A break-glass record is the declared home for a change made by hand, outside any run — the console action, the one-off command, the reboot taken to resolve an incident or to rescue a change mid-flight. It records who did it, why, when, against what, and the evidence that it happened, and it stays unreconciled until a human closes it with a note. Every production change is then exactly one of: an automated step, an attested step, or a break-glass record.
A record is either on a run — the run the act rescued and the step it
followed (--run … --after-step …); its events land on that run's chain
at that step — or on a node, a change made outside any run
(--node …); its events root a chain of their own.
Served by BreakglassService on /api/v2 (opschain docs api-v2) and
opschain breakglass record|list|show|close
(opschain docs cli/breakglass). Records live in the server's store —
PostgreSQL or SQLite — and, in the local lane, in the home's store.
The v2 OpenAPI document declares this resource's schemas (BreakglassRecord,
BreakglassEvidence, BreakglassFilter); the resource-field coverage gate
holds this page to them.
Attributes (BreakglassRecord)
Timestamps are RFC3339 in UTC.
| Field | Type | Meaning |
|---|---|---|
id | string | The record's id (UUIDv7). |
project_path | string | The project the record's node belongs to (/projects/<code>). |
node_path | string | The node the act changed — the run's node for a record on a run. |
run_id | string | The run the act rescued; empty for a record on a node. |
run_kind | string | The kind of that run — change or workflow — stamped when the record is made, so a reader opens the run's own page. Empty for a record on a node, and for a record made before the kind was kept. |
after_step | string | The full path of the step of run_id the act followed. |
reason | string | Why the act could not wait for a run. Required, at most 4000 bytes. |
activity | string | What was done, in free text (at most 8000 bytes) — most break-glass acts are a console or a portal, not a command. |
command | string | The command that was run, when the act was a command. Optional. |
window_from | timestamp | The start of the act's own window. Required — taken from the change record's window when the record names a change record and declares none. |
window_to | timestamp | The end of the act's window; never before window_from, never in the future (a record is declared after the act; 5 minutes of clock skew are allowed). |
correlation_kind | string | The strongest correlation present: change_record, run, window (a maintenance window), change_reference, or none. |
maintenance_window_id | string | The maintenance window the act happened under, when named (PostgreSQL store). |
change_reference | object | The external change the act belongs to: system, record_type (change, incident, issue, problem, release, request, task), id, url, relationship (implements, resolves, caused, relates_to) — the change-governance external-reference vocabulary. |
change_record_id | string | The change record the act belongs to (opschain docs resources/change_record) — the first correlation: named with --change / change_record_id, or taken from the rescued run's record when the run is under one. Naming a different record from the run's is refused by name. The change record must not be pending, and attaching to it needs update on its <owner>/change_records rule path. A record that names a change record but declares no window takes the change record's window, cut at now. |
uncorrelated | bool | True when nothing correlates the record (correlation_kind none): its window may span at most 24 hours and the record is flagged on the listing for review. An uncorrelated record is never refused — an incident at 03:00 with nothing open is what break-glass is for. |
correlation_id | string | The chain the record's events are on: the run's chain for a record on a run, the record's own id otherwise (opschain chains show <id>). |
evidence_class | string | The strongest evidence kind present (below). |
evidence | array | The evidence items, in declared order, the statement always present. |
recorded_by | string | The recording principal's id — never a username. |
recorded_at | timestamp | When the record was declared. |
state | string | unreconciled until a human closes it, then closed. |
closed_by | string | The closing principal's id; empty while unreconciled. |
closed_at | timestamp | When the record was closed; unset while unreconciled. |
close_note | string | Why it was closed (required at close, at most 4000 bytes). |
Evidence (BreakglassEvidence)
Evidence has four kinds, each honest about what it proves. The record's
evidence_class is the strongest kind present, strongest first:
| Kind | Fields | What it proves |
|---|---|---|
reference | system, external_id | An identifier the external system minted — an operation or correlation id, a ticket number, an audit event id. The strongest: it can be matched exactly against the system's own log. |
command | command, output, expect, expect_result | A read-only check whose captured output (at most 64 KiB) satisfied expect — a substring, or /a regular expression/. An output that does not satisfy its expect is refused. expect_result is server-derived: matched, or not_checked when no expect was given. |
file | artifact_id, digest, content_type, size_bytes | A screenshot or an export, stored as an artifact on the record's node and digest-sealed on the record. Weak evidence: a screenshot proves presence, not correctness. digest, content_type and size_bytes are read from the stored artifact, never taken from the caller. |
statement | text | The recorder's own words — always present: the explicit statement, else the activity, else the reason. A record with a reason, a window and a statement alone is a valid record, and its evidence class says so. |
Every item has a kind and a name (1–64 letters, digits, dots, dashes
or underscores, unique within the record; statement is reserved for the
record's own statement). A record carries at most 32 items.
An evidence file is bounded by the two stored settings
breakglass.evidence_max_mb (default 10) and breakglass.evidence_types
(default image/png, image/jpeg, application/pdf, application/json,
text/plain) — opschain docs settings-reference. A file over the budget
or outside the accepted types is refused by name. The server also reads the
first 512 bytes of the stored file and refuses it by name
(evidence[N].content_type: the file's content reads as "…", not the declared "…") unless its content agrees with its type: an image or a PDF
must read as exactly that type, a JSON or plain-text file as plain text — an
executable or an HTML page uploaded as notes.txt is refused. Files ride the artifact
store (opschain docs artifacts), never the log pipe, so the log maskers
never see them: a console screenshot can carry a secret in plain sight —
redact before you attach.
Listing filter (BreakglassFilter)
| Field | Meaning |
|---|---|
project_path | Only this project's records. |
node_path | Only records on exactly this node. |
run_id | Only records on this run. |
change_record_id | Only records attached to this change record. |
state | unreconciled or closed. |
window_from | Only records whose act window ends at or after this instant. |
window_to | Only records whose act window starts at or before this instant. |
The listing is newest first (recorded_at desc, id desc), keyset-paged
(default 100 rows, at most 1000); a record on a node the caller cannot read
never appears and never consumes a page slot. One request scans at most
10,000 rows; a page that bound cuts short (even an empty one) still carries
next_page_token, resuming after the last row scanned, so only a response
without a token ends the list.
The listing response also carries the evidence policy a record's files are
held to — evidence_max_bytes (int64, the breakglass.evidence_max_mb
budget in bytes, 10485760 when unset) and evidence_types (the accepted
media types, the five defaults when unset) — so a form can refuse a file
before uploading it. Exactly the values the record verb enforces.
Who may
Every verb is deny-by-default on the record's node, 404-on-deny:
- read (
GetBreakglassRecord,ListBreakglassRecords) — read on the node and read on its<node>/breakglassrule path; - record (
RecordBreakglass) — read on the node and update on<node>/breakglass(the run's node for a record on a run); - close (
CloseBreakglassRecord) — the read right above plus update on<node>/breakglass_close, so the right to close can be held apart from the right to record, and the close verb never returns a record its caller cannot read; - import (
ImportGovernedActivity,opschain governance activity import) — the record right, per record of a local home's export; a record on a node the importer may not record on is reportednot_foundand the others still land.
Recording, importing and closing are human verbs: an agent, a service account or
a step's credential is refused by name (permission_denied, "break-glass
records are a human verb"). On a server that authenticates, a call carrying no principal at all is
refused the same way.
Events
Recording writes security:breakglass:recorded (an imported record's
carries source: local_import, the exporting home_id and the
local_id), closing writes
security:breakglass:closed, each in the same transaction as the record
and carrying principal ids only (opschain docs events). With the
packs:security-governance entitlement the events match subscriptions,
team subscriptions and mandates on the breakglass object kind — the
security route (opschain docs notifications); without it they stay on
the event ledger only.
Retention
A record — and every artifact it names as evidence — is never pruned while
it is unreconciled, however old. Once closed, a record ages out on the
evidence ledger's horizon (retention.evidence_ledger_days, default 730
days), archived with its evidence items before deletion
(opschain docs retention).
Postures
- Local lane (
--local, or no server targeted): records are written to the home's store under the lane's one implicit principal (local), evidence files to the home's artifact store with the default budget and types. Nobody reviews a local record until it reaches a server — the CLI says so with every record it writes: export the home's activity (opschain governance activity --local --out <file>) and import the file on the server (opschain governance activity import <file>). There the record lands once per home as a record of the importing human, keeping its act window andrecorded_at,unreconcileduntil a reviewer closes it, with alocal_importstatement naming the home and the local record (opschain docs cli/governance-activity-import). The home's runs and change records are not the server's, so the imported record is correlated only by its external change reference, and its file evidence arrives as statements naming each file's type, size and digest. Maintenance-window correlation is server-only. - Server on the SQLite store: records, references, command evidence and
statements work; evidence files and maintenance-window correlation need
the PostgreSQL store's artifacts and windows and are refused by name; the
events stay on the ledger (notifications are PostgreSQL-only). This
posture has no users, so
recorded_byandclosed_byreadanonymous. - Server on PostgreSQL: everything on this page.
Not yet
Reconciliation closes by a human's note only.
What changes it
opschain breakglass record/RecordBreakglasscreates it;--changeattaches it to a change record.opschain breakglass close/CloseBreakglassRecordcloses it.opschain governance activity import/ImportGovernedActivitylands a local home's record on a server.- Retention ages out a closed record past the evidence ledger's horizon.