Releases

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

A release is a versioned bundle that binds specific asset versions to a workload. Releases follow a governed state machine — they must be reviewed and approved before going live. This ensures that every change to a workload’s behavior passes through a controlled process with full auditability.

What Is a Release

A release answers the question: “What exact configuration is this workload running right now?” It bundles together specific asset versions (a prompt template at v3, a policy bundle at v1, a tool definition at v2) and transitions them through a review process before they become active.

Every release has:

Choosing the target lane

Both Portal release forms require an explicit Target lane selection. The available values are all, standard, guided, and restricted. When a workload has exactly one distinct, valid lane binding, the form preselects that lane. With zero, multiple, malformed, or unavailable bindings, the selection stays empty and the draft cannot be submitted until an operator chooses one.

The Portal sends the selected lane unchanged; it never infers all. The control plane validates the closed value and remains the authority for the release’s persisted lane. Cloning a release forwards its persisted valid lane; legacy or malformed responses reopen the explicit selection step before any new release is posted.

State Machine

Every release moves through a strict sequence of states:

                                    +-------------+
                                    |             |
  draft --> review_ready --> approved --> active --> superseded
                                              ^          |
                                              |          |
                                              +----------+
                                              (rollback)

State Descriptions

Transition Table

A release can only move forward through these states, with one exception: a superseded release can be reactivated to support rollback. There is no way to move a release backward from approved to draft. If changes are needed after approval, create a new release.

Asset Bindings and Roles

A release contains zero or more bindings, each attaching a specific asset version and assigning it a role. The role is a string that identifies what function the asset serves in the workload.

Roles are free-form strings. Typical conventions:

Bindings can only be modified while the release is in draft state. Once the release transitions to review_ready, the binding set is frozen.

Authority materialization

Adaptive releases persist a workspace-scoped, immutable authority materialization with bounded source pins and a candidate revision. Binding, connection, runtime, or policy changes increment the revision and replace the current materialization in the same transaction. Direct, queued, recovery, evaluation, and comparison dispatches fail closed when the materialization is missing, stale, foreign, or does not match the server-resolved constraint mode.

Activation always requires a policy_bundle binding. A model_policy binding is required only when the bound orchestration_flow contains provider-routed steps such as llm_call, agent, or embedding. Adapter-only flows that use task and return steps can activate without a model binding.

Activation on an operator-managed workload also requires the workload to be runtime-ready (the workload page’s readiness projection): an invocation mode, a PII/data classification, the workload profile / sandbox profile / harness authoring defaults, an effective service-lane binding, a declared release environment intent, satisfied required human oversight, and every declared connection requirement for the release’s environment. A missing item refuses activation with a typed 409 workload_not_ready whose kinds-only blockers list names every missing item — the release readiness preview shows the same workload_runtime_readiness gate before you activate. Lane-specific (non-all target-lane) candidates are refused: runtime dispatch resolves only all-lane releases. Releases managed by a use case are ungated here — their readiness is owned by the use-case lifecycle’s own publish/grant/activate guards.

For new provider-routed releases, bind an active model_policy asset version after the policy version has been approved in the model policy registry. If an activation or rollback attempt fails because provider posture no longer satisfies the workload, bind a different approved policy version or create and approve a corrected version on a new draft release.

The One-Active Invariant

Orqestra enforces a critical rule: only one release can be active per workload per environment at a time.

When you activate a new release:

1. The new release transitions to active.
2. The previously active release for the same workload and environment automatically transitions to superseded.
3. The supersedes_release_id field on the new release is set to the ID of the previously active release.

Before activation:
  Release A  [active]
  Release B  [approved]

After activating Release B:
  Release A  [superseded]  <-- automatic transition
  Release B  [active]      <-- supersedes_release_id = Release A

This guarantees there is never ambiguity about which configuration is serving a workload. At any point in time, you can answer “what is this workload running?” by looking at its single active release.

Cost Checks

The release readiness view includes an advisory cost gate that can warn about cost findings but never blocks activation, and it is only evaluated for workspaces with FinOps enabled and viewers who hold cost.view.

Approval Gates

The transition from review_ready to approved requires an explicit approval record. This is the governance checkpoint where a reviewer confirms that the release’s asset bindings are correct and safe to deploy.

Creating an Approval

An approval records a decision about a specific subject within the release:

Approval Flow

1. Author creates release (draft)
2. Author adds bindings (draft)
3. Author submits for review (draft -> review_ready)
4. Reviewer inspects bindings
5. Reviewer creates approval record (outcome: approved)
6. Operator transitions release (review_ready -> approved)
7. Operator activates release (approved -> active)

The approval record is separate from the state transition. Creating an approval does not automatically advance the release state — an explicit transition call is still required. This allows for multi-step review processes where multiple approvals may be needed.

Evidence Bundles

Every state transition, binding change, and approval creates an auditable record with:

• Who performed the action (created_by, actor_ref, transitioned_by)
• When it happened (created_at, transitioned_at)
• What changed (the before and after state, the binding details)

Combined with immutable asset versions, this means you can reconstruct the exact configuration of any workload at any point in time by querying the release history and its bindings.

Enriched release evidence bundles can also be exported as minimized proof packs:

orqestractl release evidence-bundle-export <release-id>

The export is read-only, resolves the owning workspace from the release, requires release.view there, and contains only bounded evidence summaries: release metadata, approvals, evaluations, execution cohort metrics, decision provenance, supersession chain, and a manifest. Timestamped section records and nested execution samples outside the requested window are omitted before the per-section cap is applied; the manifest reports top-level section omissions and nested execution-sample omissions separately. Aggregate cohort metrics retain the source window from the enriched evidence bundle. Secret-like values are redacted before serialization.

Sovereignty Evidence Packs

When a release binds a sovereignty_profile, activation validates provider and region posture against the pinned profile. The release detail page includes a Sovereignty tab that shows the applied profile, provider route decisions, recorded exceptions, and whether JSON export is available under the profile’s export policy.

Operators can also export the same release-scoped pack from automation surfaces:

orqestractl release sovereignty-evidence-pack <release-id>

pack = await client.releases.get_sovereignty_evidence_pack("release-id")

AI Dev Kit users can call the MCP tool:

get_sovereignty_evidence_pack(release_id="release-id")

The export is read-only and requires release.view on the release workspace. data_movement_decisions and operator_access_events are reserved, schema-stable buckets and remain empty until their matching audit producers ship.

Sandbox Posture Findings

Pre-activation validation runs a read-only posture scan over the release-bound sandbox profile and surfaces the results as evidence — a readiness input, not runtime enforcement. The structural errors/warnings are the enforcement channel; posture findings ride a separate posture_findings channel and never change the valid gate. Enforcement itself stays owned by the sandbox, policy, connector, and gateway contracts.

The release detail page shows a Sandbox posture panel listing each finding with a readiness disposition: block is fail-closed (for example, a sandbox that runs code with effectively unrestricted egress), downgrade / review / warn flag caution, and allow is informational.

Operators and automation read the same findings from the validation result:

orqestractl release validate <release-id>

result = await client.releases.validate("release-id")
findings = result["posture_findings"]

AI Dev Kit users can call the read-only MCP tool:

validate_release_readiness(release_id="release-id")

Validation is read-only and requires release.view on the release workspace; there is no surface for suppressing a finding or overriding its disposition. Each finding’s evidence_refs (always including its finding_id) join the readiness view back to the persisted posture evidence artifacts.

Rollback

If a newly activated release causes issues, you can reactivate a previously superseded release:

1. Identify the superseded release you want to restore.
2. Transition it from superseded to active.
3. The currently active release is automatically superseded.

Before rollback:
  Release A  [superseded]
  Release B  [active]      <-- causing issues

After reactivating Release A:
  Release A  [active]      <-- restored
  Release B  [superseded]

Because asset versions are immutable, rollback restores the exact same configuration that was previously live. There is no risk of content drift.

API Reference

Base URL: http://localhost:8000

Create a Release

curl -X POST http://localhost:8000/v1/releases \
  -H "Content-Type: application/json" \
  -d '{
    "workload_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "environment": "dev",
    "target_lane": "all",
    "policy_bundle_id": null
  }'

Response (201 Created):

{
  "release_id": "r1a2b3c4-0000-0000-0000-000000000001",
  "workload_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "environment": "dev",
  "state": "draft",
  "policy_bundle_id": null,
  "supersedes_release_id": null,
  "created_at": "2026-04-06T12:00:00Z",
  "created_by": "user:alice",
  "updated_at": "2026-04-06T12:00:00Z"
}

List Releases

curl http://localhost:8000/v1/releases

Supports query parameters:

Get a Release (with bindings)

curl http://localhost:8000/v1/releases/{release_id}

Response (200 OK):

{
  "release_id": "r1a2b3c4-0000-0000-0000-000000000001",
  "workload_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "environment": "dev",
  "state": "draft",
  "policy_bundle_id": null,
  "supersedes_release_id": null,
  "created_at": "2026-04-06T12:00:00Z",
  "created_by": "user:alice",
  "updated_at": "2026-04-06T12:00:00Z",
  "bindings": [],
  "valid_transitions": ["review_ready"]
}

The valid_transitions field lists the states this release can transition to from its current state.

Add a Binding

curl -X POST http://localhost:8000/v1/releases/{release_id}/bindings \
  -H "Content-Type: application/json" \
  -d '{
    "asset_version_id": "e5f6a7b8-0000-0000-0000-000000000001",
    "role": "orchestration_flow"
  }'

Response (201 Created):

{
  "binding_id": "b1a2b3c4-0000-0000-0000-000000000001",
  "release_id": "r1a2b3c4-0000-0000-0000-000000000001",
  "asset_version_id": "e5f6a7b8-0000-0000-0000-000000000001",
  "role": "orchestration_flow",
  "created_at": "2026-04-06T12:01:00Z",
  "created_by": "user:alice"
}

List Bindings

curl http://localhost:8000/v1/releases/{release_id}/bindings

Transition State

Submit for review:

curl -X POST http://localhost:8000/v1/releases/{release_id}/transition \
  -H "Content-Type: application/json" \
  -d '{"to_state": "review_ready"}'

Response (200 OK):

{
  "release_id": "r1a2b3c4-0000-0000-0000-000000000001",
  "state": "review_ready",
  "previous_state": "draft",
  "transitioned_by": "user:alice",
  "transitioned_at": "2026-04-06T12:02:00Z"
}

Approve:

curl -X POST http://localhost:8000/v1/releases/{release_id}/approvals \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "approved",
    "subject_kind": "release",
    "subject_ref": "{release_id}"
  }'

Then transition to approved:

curl -X POST http://localhost:8000/v1/releases/{release_id}/transition \
  -H "Content-Type: application/json" \
  -d '{"to_state": "approved"}'

Activate:

curl -X POST http://localhost:8000/v1/releases/{release_id}/transition \
  -H "Content-Type: application/json" \
  -d '{"to_state": "active"}'

Rollback (reactivate a superseded release):

curl -X POST http://localhost:8000/v1/releases/{superseded_release_id}/transition \
  -H "Content-Type: application/json" \
  -d '{"to_state": "active"}'

Create an Approval

curl -X POST http://localhost:8000/v1/releases/{release_id}/approvals \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "approved",
    "subject_kind": "release",
    "subject_ref": "r1a2b3c4-0000-0000-0000-000000000001"
  }'

Response (201 Created):

{
  "approval_id": "ap1a2b3c-0000-0000-0000-000000000001",
  "release_id": "r1a2b3c4-0000-0000-0000-000000000001",
  "outcome": "approved",
  "subject_kind": "release",
  "subject_ref": "r1a2b3c4-0000-0000-0000-000000000001",
  "actor_ref": "user:bob",
  "created_at": "2026-04-06T12:03:00Z",
  "created_by": "user:bob"
}

List Approvals

curl http://localhost:8000/v1/releases/{release_id}/approvals