Skip to main content

Promotion Gates

Workflows carry an env (dev / staging / prod); POST /api/v1/workflows/{id}/promote moves a workflow to a new one, snapshotting the current version first so the promotion is reversible. Promoting to prod also sets status to pending_approval, so an admin/owner must explicitly approve before its webhook accepts real traffic.

A promotion gate adds a second, automated condition on top of that: staging/prod promotion is refused unless a named evaluation's most recent run passed at or above a minimum rate. dev is never gated — that's where iteration happens, and forcing a passing evaluation before a workflow even reaches dev would add friction without protecting anything real.

This is the same idea as a CI check blocking a deploy, applied to workflow promotion instead of a git merge.

Configuring a gate​

On a workflow's editor, open Settings → Eval Gate:

  • Evaluation name — the evaluation to check (autocompletes from evaluations already run against this workflow). Leave blank to disable the gate.
  • Minimum pass rate — the pass_pct threshold, 0-100%.

Or set it directly via the API:

PUT /api/v1/workflows/{id}/eval-gate
{
  "evaluation_name": "Gate Suite",
  "min_pass_pct": 90
}

GET /api/v1/workflows/{id}/eval-gate reads the current config back.

What blocks a promotion​

When a gate is configured and the target environment is staging or prod, POST /api/v1/workflows/{id}/promote looks up the most recent run of that evaluation for this workflow (evaluations sharing a name on a different workflow don't count) and refuses with 412 Precondition Failed if:

ConditionError
The named evaluation has never been run for this workflowevaluation "X" has never been run — run it first
Its latest run hasn't finished (pending/running)the latest run of evaluation "X" is "running", not completed
Its latest pass_pct is below the thresholdevaluation "X" last passed N% of rows, below the required M%

The workflow editor surfaces this as a dismissible error banner at the promote attempt, with the exact reason — so the fix is always obvious: go run the evaluation, wait for it to finish, or fix whatever's failing.

A typical loop​

  1. Attach a gate to a workflow: evaluation "Regression Suite", threshold 95%.
  2. Make a change, then Run again on Regression Suite from its evaluation detail page.
  3. If a row regressed, fix the workflow and run again — the comparison view shows exactly which test case broke.
  4. Once the pass rate clears the threshold, promote to staging or prod succeeds.

Because the gate reads the evaluation's last run rather than re-running it inline, promotion itself stays fast — the cost of actually exercising the workflow against the whole dataset is paid when you choose to run the evaluation, not on every promotion attempt.

Next​