Certified Promotions & Rollout
The governed release control plane for config and strategy artifacts — promotion candidates, rollout-evidence packs, and runtime-conformance gates.
This is the change-governance plane for artifacts — routing tables, workflows, connector configs, and strategies — not for the binary or the cluster. A promotion moves an immutable artifact through preflight, guardrails, and a canary into activation, with a rollback handle at every step. Rollout evidence and runtime conformance are the proof that authorizes each move.
This is not Kubernetes deployment
Promotions govern config/strategy artifact releases inside a running Ductor tenant. Rolling out a new binary or chart is a different plane — see Production deployment and Kubernetes / Helm. The two are independent: you promote artifacts on a cluster that is already deployed.
Promotions: the candidate lifecycle
A promotion candidate wraps one or more immutable routing, workflow,
connector, or strategy artifacts and carries them through a fixed lifecycle.
Every stage is a separate, authenticated call under
/api/promotions/candidates, so an operator (or an automated release pipeline)
advances the candidate deliberately and can stop at any gate.
| Stage | Endpoint | What it does |
|---|---|---|
| Create | POST /api/promotions/candidates | Registers a governed candidate for immutable routing/workflow/connector/strategy artifacts |
| Inspect | GET /api/promotions/candidates/{candidate_id} | Returns the candidate, active canary state, check results, and approval evidence |
| Preflight | POST …/{candidate_id}/preflight | Runs impact checks without live connector actions or external side effects |
| Guardrails | POST …/{candidate_id}/guardrails/evaluate | Evaluates guardrails against durable evidence and low-cardinality metrics |
| Canary start | POST …/{candidate_id}/canary/start | Starts a deterministic sticky canary run |
| Canary stop | POST …/{candidate_id}/canary/stop | Stops new canary assignment while preserving recorded canary evidence |
| Approve | POST …/{candidate_id}/approve | Records an authenticated approval decision |
| Promote | POST …/{candidate_id}/promote | Activates artifacts through their artifact-specific activation paths |
| Rollback | POST …/{candidate_id}/rollback | Runs rollback through artifact-specific rollback handles |
| Abort | POST …/{candidate_id}/abort | Aborts the candidate and stops any active canary assignment |
Create the candidate
curl -X POST http://localhost:8080/api/promotions/candidates \
-H "X-Tenant-ID: $DUCTOR_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{ "environment_id": "prod", "artifacts": [ ... ] }'The candidate binds the exact artifact versions you intend to release. Artifacts are immutable — a new version is a new candidate.
Preflight before anything touches production
preflight computes per-artifact impacts and blocking reasons over the
candidate's artifacts and their dependents, and runs without executing live
connector actions or external side effects. Treat a non-empty set of blocking
reasons as a hard stop.
Evaluate guardrails, then canary
guardrails/evaluate scores the candidate against durable evidence and
low-cardinality metrics. canary/start then routes a deterministic, sticky
slice of traffic to the new artifacts so the same key always lands on the same
side of the canary.
Approve and promote — or roll back
approve records the authenticated decision; promote activates the artifacts
through their activation paths. If anything regresses, rollback reverses the
promotion through each artifact's rollback handle.
Rollout evidence: what authorizes a promotion
A promotion should not be approved on trust. A rollout-evidence pack is the governed, tenant/environment-scoped bundle of proof — attached artifacts and typed receipts — that a gate evaluates before a candidate is allowed forward. Packs and their gate are the machine-checkable answer to "is this promotion allowed to proceed?"
Advanced / enterprise surface
Rollout evidence is an advanced governance surface for organizations that require an auditable, redacted record for every promotion. Most tenants can use the standard promotion lifecycle without evidence packs.
A pack moves through its own lifecycle, all under
/api/rollout-evidence/packs:
| Operation | Endpoint |
|---|---|
| Create / list packs | POST · GET /api/rollout-evidence/packs |
| Get / update a pack | GET · PUT /api/rollout-evidence/packs/{environment_id}/{pack_id} |
| Attach a hash-addressed artifact | POST …/{pack_id}/artifacts |
| Attach one typed receipt | POST …/{pack_id}/receipts |
| Start / get / heartbeat / cancel a run | POST …/{pack_id}/runs · GET/:heartbeat/:cancel on /runs/{environment_id}/{run_id} |
| Evaluate the gate | POST …/{pack_id}/gate:evaluate |
| Explain failures | POST …/{pack_id}:explain |
| Expand requirements | POST /api/rollout-evidence/requirements:expand |
| Export redacted manifest | POST …/{pack_id}:export |
| Archive | POST …/{pack_id}:archive |
| Attach to a promotion | POST …/{pack_id}:attach-to-promotion |
Receipts are strictly typed — exactly one of a scenario, connector, strategy,
runtime, graph, or canary receipt per attachment. The gate evaluates the full
set for missing, failed, blocked, stale, expired, wrong-environment, and
wrong-candidate evidence; :explain returns the tenant-scoped reason set when
the gate is not green.
Evidence runs are leased
A run is started in an allowed environment mode and holds a lease you renew
with :heartbeat. Heartbeats never extend a run beyond its absolute deadline,
and :cancel stops a pending or running run. Exports are redacted — no
secrets, storage refs, raw provider payloads, or unrestricted PII leave the
pack.
Runtime conformance: gating the environment itself
Where evidence packs prove a candidate is safe, runtime conformance proves the environment is. A conformance suite runs against a tenant environment and produces a hash-addressed coverage report; that report is what gates whether the environment is fit to receive a promotion.
Advanced / enterprise surface
Runtime conformance is an advanced enterprise gate rather than a required step in the standard promotion lifecycle.
| Operation | Endpoint |
|---|---|
| List / get suites | GET /api/runtime-conformance/suites · GET …/suites/{suite_id} |
| Run a suite | POST …/suites/{suite_id}:run |
| List / get reports | GET /api/runtime-conformance/reports · GET …/reports/{environment_id}/{report_id} |
| Explain coverage | POST …/reports/{environment_id}:explain |
Suites cover the runtime, bridge, worker-protocol, MCP, connector-lifecycle, and
admission surfaces with stable case IDs. A run executes in a sandbox or dry-run
mode — running a suite against a live environment without dry-run is
rejected — and returns a hash-addressed report. :explain answers whether the
latest report covers the cases required for promotion or rollout evidence.
Related
Environments
The tenant environment a promotion targets and a conformance suite runs against.
Governance strategies
Certification and optimization evidence that feeds promotion guardrails.
Production deployment
The distinct plane that rolls out the binary and chart.
Enterprise activation
The fail-closed security posture for enterprise deployments.