Agent release
packs:agentspacks:agent-governance
An agent release is one immutable, signed agent build: name + semver
version, the frozen manifest document, the content-addressed artifact
identity, and an Ed25519 signature over both — verified against a registered
ACTIVE signing key before the row lands, and re-verified at every promotion
up the estate's stage ladder (default dev → test → prod). Agents may
declare a release at enrolment, and registration then verifies it against
this registry. Served by the v2 AgentReleaseService: CreateAgentRelease,
ListAgentReleases, GetAgentRelease, PromoteAgentRelease,
RetireAgentRelease and RevokeAgentRelease for releases;
GetAgentReleaseStages, SetAgentReleaseStages and
RenameAgentReleaseStage for the ladder; RegisterAgentSigningKey,
ListAgentSigningKeys and SetAgentSigningKeyStatus for the signing-key
registry. Responses carry key fingerprints, never key material. Beyond the
ladder a release carries a one-way lifecycle — active → retired → revoked — and the instances running it move between releases through the
agent rollover (opschain docs resources/agent).
AgentRelease
AgentRelease is one signed release row.
| Field | Type | Meaning |
|---|---|---|
agent_type | string | Declared agent type ("service" or "ai", empty untyped); enrolment cross-checks the enrolling manifest's type against it. |
artifact | string | Content-addressed artifact identity: git sha or image digest. |
created_at | timestamp | When the release was registered. |
created_by | string | Username of the registering identity. |
id | string | The release's identity. |
key_fingerprint | string | The signing key's fingerprint. |
key_id | string | The signing key's id and fingerprint; the signature itself is verified server-side and never echoed. |
manifest_json | string | The frozen manifest document (JSON) the signature covers. |
name | string | The release's name; versions of the same agent share it. |
stage | string | Current promotion stage: a rung of the estate's ladder (dev, test or prod on the default ladder) — a validated string, never a fixed enumeration. A retired or revoked release keeps the rung it reached; its lifecycle is status. |
status | string | Lifecycle state: active | retired (the ladder's last rung — no new enrolment or rollover to it, running instances untouched) | revoked (every instance running it halted with the typed release-revoked reason, and admitted nowhere a stage floor or condition applies). One way. |
status_changed_at | timestamp | When the lifecycle state last moved. |
status_changed_by | string | Who moved it. |
status_reason | string | The stated reason for the retirement or revocation. |
version | string | The release's semver version; (name, version) identifies one immutable release. |
AgentReleasePromotion
AgentReleasePromotion is one promotion attestation.
| Field | Type | Meaning |
|---|---|---|
decided_at | timestamp | When the promotion was decided (completed, rejected or expired). |
decided_by | string | Who decided it — the completing approver(s) context, or the system on expiry. |
from_stage | string | The stage the promotion moves from. |
id | string | The attestation's identity. |
reason | string | The requester's stated reason for the promotion. |
release_id | string | The release being promoted. |
requested_at | timestamp | When the promotion was requested. |
requested_by | string | Who requested it. |
status | string | pending | completed | rejected | expired. |
to_stage | string | The target stage — the next rung of the ladder only; empty on the request means the next rung. |
A promotion into a governed rung on a composition carrying the approval
fabric lands HELD as a strict checklist in the same approval funnel
human-created governed change enters: quorum completion promotes, rejection
and quorum-TTL expiry refuse. A governed promotion is never approver-less —
explicit approvers on the request, falling back to the configured agent
approvers. A rung rename records a completed attestation from the old name
to the new on every release at the rung.
AgentReleaseStage
AgentReleaseStage is one rung of the estate's promotion ladder, as
GetAgentReleaseStages lists them lowest first and SetAgentReleaseStages
replaces them wholesale (opschain docs agent-releases, "The stage ladder
is the estate's").
| Field | Type | Meaning |
|---|---|---|
governed | boolean | Whether a promotion INTO this rung is held in the approval funnel on a composition carrying the approval fabric. |
name | string | The rung name (lowercase alphanumeric with - and _); never the implicit retired state past the top. |
SetAgentReleaseStages refuses, by name, a ladder that drops or reorders a
rung any release sits on, or that strands the estate floor, an environment
floor or a grant condition on a missing name. RenameAgentReleaseStage
answers the new ladder and releases_attested, the number of releases
moved with an attestation.
AgentReleaseAttestation
AgentReleaseAttestation is one durable attestation on a release beyond the promotion ladder: a rollover step — rollover_started, rollover_held, instance_drained, instance_restart_instructed, instance_restart_refused, instance_restarted, canary_held, continued, aborted, rolled_back, finished, rollover_refused, rollover_rejected — or the release's retired / revoked move. GetAgentRelease lists them newest first.
| Field | Type | Meaning |
|---|---|---|
attested_at | timestamp | When the step happened. |
attested_by | string | The actor; empty for a step the platform took on its own (an instance re-enrolling, the governance sweep). |
correlation_id | string | The correlation chain the rollover ran under — one chain per rollover. |
detail | string | Human detail: the release moved to or from, the restart mode, the refusal text, the reason. |
id | string | The attestation's identity. |
instance_id | string | The instance the step concerns; empty for whole-rollover and lifecycle steps. |
kind | string | The attestation kind (the step vocabulary above, retired or revoked). |
release_id | string | The release the attestation sits on — the target while rolling forward, the source while returning. |
rollover_id | string | The rollover the step belongs to; empty for a lifecycle attestation. |
status | string | The rollover's status after the step, or the release's lifecycle state. |
AgentSigningKey
AgentSigningKey is one registered verification key, fingerprint-only.
| Field | Type | Meaning |
|---|---|---|
algorithm | string | The key algorithm — "ed25519" (the only accepted value; empty on registration defaults to it). |
created_at | timestamp | When the key was registered. |
created_by | string | Username of the registering identity. |
fingerprint | string | The public key's fingerprint — how every response identifies the key; the key material is never echoed. |
id | string | The key's identity. |
name | string | The key's display name. |
note | string | Free-text operator note, recorded at registration or with a status change. |
status | string | active | retired | revoked (lifecycle). |
status_changed_at | timestamp | When the key's lifecycle state last moved. |
status_changed_by | string | Who moved it. |
Key lifecycle semantics: an active key verifies; a retired key keeps signatures of releases created before the retirement acceptable; a revoked key verifies nothing at any date.
What settings change this
agents.approvers— the fallback approver set for a funnel-held prod promotion when the request names none.
Related pages
opschain docs agent-releases— the component page: the signing ceremony, promotion ladder and enrolment verification.opschain docs resources/agent— the enrolled agent carrying its release identity.opschain docs resources/approval— the funnel a held prod promotion waits in.