Governed delivery
The mutation lifecycle and deployment state machine behind every deploy, gate, approval, promotion, and rollback.
Every state change in Runway (deploy, gate, approve, promote, roll back, sync secrets) is a governed mutation. It flows through the same pipeline whether the caller is a human developer, a CI job, or an AI agent. Handlers never write anything directly. They return pending domain events, and the runtime appends them to the org-stamped event log only after every check passes.
The mutation pipeline
Each stage can reject the request, and the stage that rejected it is reported back.
- Schema: malformed or disallowed input (for example, a direct
proddeploy request, or a preview deploy without a PR number) is rejected before anything else runs. - Policy: org scoping, provenance, freshness, separation of duty, and trusted-worker execution are enforced here, and gates and evidence has the detail.
- State machine: a transition with no edge (promote without approval, execute before a gate) fails structurally, because there is no code path to "just do it anyway."
Event phases
Most actions emit their event in the before_adapters phase, the event records intent, and
the adapter step (a Databricks call) follows. Production execution is different.
promotion_execute and rollback_execute emit in the after_adapters phase. A
PromotionExecuted or RollbackExecuted event therefore attests that the Databricks deployment
actually succeeded. A failed attempt leaves the deployment recoverable and never produces a
false completion event.
The deployment state machine
A deployment is an entity that moves through a fixed set of states. Illegal moves simply have no edge.
Two consequences fall out of this shape.
- Re-evaluation is allowed while collecting approvals. A fresh gate verdict clears prior endorsements and returns the release to evidence review, so approvals can never outlive the evidence they covered.
- The evidence base freezes at approval. There is no edge from
approvedorpromotedback into gating, so a late verdict cannot silently change a release that a human already approved. An approved preview may still be destroyed instead of executing production. - Approval policy freezes per cycle. The first endorsement captures the effective thresholds,
gates, freshness, provenance, and agent eligibility.
promotion_reopenis the explicit audited edge that discards endorsements and adopts current policy on the next approval.
Who can do what
| Move | Allowed initiator |
|---|---|
deploy_request (dev / preview) | developer, CI, or agent |
gate_evaluate | authorized caller (async request only) |
gate_record | trusted Experiments system actor only |
promotion_approve | a permitted human or registered Harness agent who is not the requester |
promotion_reopen | reviewer/admin or authorized Harness agent, with a reason |
promotion_finalize | a trusted worker after total/human thresholds pass |
promotion_execute / rollback_execute | a trusted worker service principal only |
The public API, CLI, MCP surface, and generated CI workflow can request deploys and approvals,
but they can never execute production. That is reserved for the trusted worker, enforced by the
runway.system_execution.v1 policy.
Org isolation
Every event envelope and projection row is stamped with the tenant (organizationId), taken
from the authenticated context, never from a caller parameter. Projections are folded per
organization up front, so cross-tenant reads are impossible by construction, and a cross-org
write attempt is recorded as a ComplianceBlocked event in the attacker's own audit view.