Skip to main content
Version: v5.8.0

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.

FieldTypeMeaning
idstringThe record's id (UUIDv7).
project_pathstringThe project the record's node belongs to (/projects/<code>).
node_pathstringThe node the act changed — the run's node for a record on a run.
run_idstringThe run the act rescued; empty for a record on a node.
run_kindstringThe 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_stepstringThe full path of the step of run_id the act followed.
reasonstringWhy the act could not wait for a run. Required, at most 4000 bytes.
activitystringWhat was done, in free text (at most 8000 bytes) — most break-glass acts are a console or a portal, not a command.
commandstringThe command that was run, when the act was a command. Optional.
window_fromtimestampThe 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_totimestampThe 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_kindstringThe strongest correlation present: change_record, run, window (a maintenance window), change_reference, or none.
maintenance_window_idstringThe maintenance window the act happened under, when named (PostgreSQL store).
change_referenceobjectThe 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_idstringThe 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.
uncorrelatedboolTrue 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_idstringThe 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_classstringThe strongest evidence kind present (below).
evidencearrayThe evidence items, in declared order, the statement always present.
recorded_bystringThe recording principal's id — never a username.
recorded_attimestampWhen the record was declared.
statestringunreconciled until a human closes it, then closed.
closed_bystringThe closing principal's id; empty while unreconciled.
closed_attimestampWhen the record was closed; unset while unreconciled.
close_notestringWhy 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:

KindFieldsWhat it proves
referencesystem, external_idAn 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.
commandcommand, output, expect, expect_resultA 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.
fileartifact_id, digest, content_type, size_bytesA 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.
statementtextThe 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)​

FieldMeaning
project_pathOnly this project's records.
node_pathOnly records on exactly this node.
run_idOnly records on this run.
change_record_idOnly records attached to this change record.
stateunreconciled or closed.
window_fromOnly records whose act window ends at or after this instant.
window_toOnly 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>/breakglass rule 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 reported not_found and 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 and recorded_at, unreconciled until a reviewer closes it, with a local_import statement 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_by and closed_by read anonymous.
  • Server on PostgreSQL: everything on this page.

Not yet​

Reconciliation closes by a human's note only.

What changes it​

  • opschain breakglass record / RecordBreakglass creates it; --change attaches it to a change record.
  • opschain breakglass close / CloseBreakglassRecord closes it.
  • opschain governance activity import / ImportGovernedActivity lands a local home's record on a server.
  • Retention ages out a closed record past the evidence ledger's horizon.