Skip to main content
Prompt Promotion lets you move prompt versions from staging to production through automated eval checks, with drift-based rollback when the post-promotion metrics you post regress. Rollback is not autonomous — see Auto-rollback for exactly what fires it. Pricing: Read-only (view active version + history) on Builder $29**. Full promotion workflow — create, gate, promote, drift-based rollback — on **Team $229+.

​
Core concepts

​
Workflow overview

Prompt promotion flow: author → staging → eval gate → production → monitor → auto-rollback

​
Create and version prompts

Versions are authored through the API (or the Prompts page in the dashboard). A new version is created and lands in staging:
The 201 response carries the prompt_version_id and the content sha256_hex — the id you pass to promote and rollback. The tlane CLI covers the read and promotion side of the workflow:

​
Eval gates

Eval gating is live. Run a suite with POST /v1/prompts/{name}/evals, then pass the returned eval_run_id to promote: a run recorded passed opens the gate, and anything else — failed, errored, still running, or an id the gate cannot resolve — refuses the promotion with 409 and leaves the production pointer where it was. The gate fails closed, so an unreadable run blocks rather than waves through.Still on the roadmap: the tracelane.yaml gate config and the streaming eval panel. Assertions are code rules plus an optional LLM judge — see Evals and prompt promotion. And a promotion is never gated automatically — you choose to supply a run id, or to record an attributed override instead.
Eval gating is live. A staging → production promotion requires a passing eval run; without one the non-override path returns 409. Start a run with POST /v1/prompts/{name}/evals. Declarative per-prompt thresholds in tracelane.yaml are still roadmap:
The eval suite referenced here is the same format as the CI merge-gate suite. See Eval gates.

​
Promote via dashboard

  1. Open Prompts → [prompt name].
  2. The panel shows the active version for each environment.
  3. Click Promote staging → production.
  4. The version is atomically swapped in production and a tamper-evident promotion record is written. (The panel does not run or stream an eval yet, so a promotion made from this button is a recorded manual-override. The gate itself is live over the API — supply an eval_run_id to promote and a non-passing run refuses with 409. The panel does not stream an eval.)

​
Promote via API

Promote against the gateway, not the dashboard origin. The dashboard route authenticates with a WorkOS session cookie and ignores an Authorization header; the gateway takes a Bearer credential. to_version_id is required and is a UUID — get it from the 201 body of POST /v1/prompts/{name}/versions, or from GET /v1/prompts/{name}.
This example uses override_reason, which records an explicit, attributed bypass in the tamper-evident chain. To promote through the eval gate instead, run POST /v1/prompts/{name}/evals and pass the returned eval_run_id in place of override_reason. The key needs the admin scope; keys minted before scoping (scope unset) are unaffected.
Response on success — every id is a UUID:
If you supply an eval_run_id instead of an override_reason, the gate resolves the run: a run recorded passed promotes, and any other outcome — failed, errored, still running, or an id the gate cannot resolve — blocks with 409 Conflict and the routing pointer does not move. A gate that cannot resolve its run fails closed. A blocked promotion looks like this:
Omitting eval_run_id and override_reason returns 409 with "decision": "blocked_by_policy".

​
Auto-rollback

How it works today: rollback decisions are computed from metric observations you report to the observe endpoint. When you post an observation, Tracelane compares it to the pre-promotion baseline and, if it drifts more than sigma_threshold standard deviations within the observation window, returns a rollback decision (and reverts, under rollback_mode: auto). Autonomous background monitoring — Tracelane firing a rollback with no observation pushed to it — is not built; today the drift math runs on the observations you feed it, not on a standalone monitor loop.
When an observation drifts more than sigma_threshold standard deviations from the pre-promotion baseline within the observation window, the rollback fires per rollback_mode. The history entry on the prompt detail page shows the trigger metric, observed value, sigma drift, and the version pair:

​
Canary splits (Team+)

A split assigns a percentage of prompt resolutions to a candidate version. Fetching once at process boot and reusing that prompt counts as one resolution. The configured percentage is a deterministic bucket threshold, not a measured outcome; repeated identities and small populations can produce different proportions. Start or update a split from the prompt detail page, or send:
Supply your chosen percentage, greater than zero and at most 100; there is no default. The candidate must be a different version of this prompt and production must already have a stable version. Writes require Team+, an admin-capable key or workspace role, available entitlement verification, and no promotion freeze. GET /v1/prompts/{name}/canary reads the split; DELETE stops it. Resolution uses the first bounded identity available: x-tracelane-user-id (alias x-user-id), then x-conversation-id (alias x-session-id), then x-agent-id. Missing usable identity during an active split returns 400 canary_identity_required. The same identity stays in the same arm until the configuration changes. The response includes arm, canary_id, and resolution_trace_id; its prompt.resolve span records the same arm and version. There are no automatic graduation thresholds or inferred per-arm model outcomes.
Workspace response caching is suspended while any split is active. The gateway cannot observe how your application uses a resolved prompt, so it cannot safely reuse a similar response across arms. Explicit cache opt-in then returns 409 response_cache_suspended_for_canary; default calls continue to providers. Stopping a split, promoting, rolling back or deleting invalidates prior cache namespaces, including responses still in flight. Provider-native caching is separate.
Splits persist across restarts. A production move or deletion durably stops the split first. If the following move fails, the error says the split was stopped; reload before retrying. If startup cannot load valid lifecycle state, production resolution returns 503 canary_state_unavailable and response caching stays suspended. Operators must apply the canary schema before enabling this release. The dashboard reads /v1/prompts/{name}/configuration to inspect environment pointers without drawing an assignment.

​
Read the active version from your agent

The gateway caches prompt versions in memory, so resolving a prompt does not query the database on each request.

​
Audit trail

Every promotion, block, and rollback is written to the tamper-evident audit ledger with the version SHA-256, eval run ID, and actor. Use tlane verify to confirm the log has not been altered.