Skip to main content
A deploy that applied cleanly is not a release that works. Forge has three separate mechanisms for the gap between “the rollout finished” and “this release is good”, and they answer different questions: None of them rolls anything back. A failed deploy never replaces what is serving, and a regressed release stays live until you deploy something else. What the gates give you is a verdict you can script against, and a refusal in the places where shipping the wrong thing is expensive.

The verdict: forge obs check

forge obs check judges one promotion. It compares the window of time after the release went live with an equal window before it, per service, and lists what the release opened: new and regressed issues, alerts still firing, workload restarts. The result is PASS, FAIL or INCONCLUSIVE.
--wait polls until the after window has finished, which is how you run it straight after a deploy. --release <version> and --promotion <id> judge an earlier promotion instead of the current one, and --window 30m widens the windows. The windows never cross into a neighbouring promotion, so a release is judged only on the traffic it served.

What each exit code means

The exit code is the contract, and it matches the exit_code field of the JSON document. Exit 2 covers two different situations that must not be read as green: not enough traffic to judge, and telemetry that could not be read at all (control plane unreachable, auth refused, telemetry off). Missing telemetry is never PASS. The JSON document names the cause in reason_code:
  • low_traffic or thin_baseline means the window closed with too few requests to compare. That is final for the promotion, because a later check reads the same window, so do not poll it. For an environment that is always quiet, lower min_requests in its release_health declaration, pass --threshold min_requests=20, or widen --window.
  • window_open means the after window has not finished. Check again, or use --wait.
  • no_request_telemetry means no service sent a request span in either window. An app that does not export OpenTelemetry traces has no request data however much traffic it serves.
--allow-inconclusive makes exit 2 exit 0, for a pipeline that has decided a quiet environment is acceptable. It is an explicit choice for that one call, and it changes nothing on the server.

What counts as worse

The thresholds are declared per environment, so the CLI, the console and the alert all judge a release the same way:
A service is compared only when it has min_requests in both windows, and require_baseline sets how many services need that baseline before a release can pass (any, every or none). --threshold name=value and --fail-on override one call, and the JSON document says where each effective value came from. For the full list of findings and how traces are weighted, see Querying with forge obs. If you want the verdict recorded on the promotion rather than only read by your script, write it as evidence and attach it:

The gate: prod waits for staging

By default prod takes whatever release you promote. To make the order binding, declare that prod follows staging in deploy/kcl/prod/main.k:
Naming an environment in after is the opt-in. A project that declares no order is never gated, and no staging environment is required. With the gate declared, a promotion of release R to prod is refused until staging holds a PASS verdict for R. The check is made by the control plane inside the promotion’s transaction, against a verdict the control plane computed itself with the environment’s declared policy. A client cannot supply or skip it. It is enforced on a control plane that supports it; a self-hosted environment with no control plane records the declaration but nothing refuses the promotion. A release prod itself already ran with a PASS is admitted without staging, so going back to a known-good release needs no detour. During an incident you can override this gate and only this gate:
The override records who did it, why, and what staging showed. Setting mode to audit records what enforce would have refused without blocking, which is the safe way to try the gate first. Other required checks use the same promotion machinery. required_gates makes an environment refuse a promotion that lacks named checks (forge env deploy prod v1.4.0 --gate name=e2e,status=passed), and approval_hook asks your own approval system before the promotion is written. Both are described under Releases and promotion.

ReleaseRegressed: the alert that names the release

For an environment on a control plane, the platform judges every promotion itself once its window closes, with the environment’s declared policy and no client overrides. A FAIL raises a ReleaseRegressed alert that names the findings, the release and its commit range. That ties a regression to the change that shipped it without anyone running a command. The alert and the health gate read the same stored verdict, and you can reproduce it from your terminal:
Loosening a threshold locally with --threshold or --allow-inconclusive changes what your command prints. It does not change the verdict the platform stored. How alerts reach you is in Hosted dashboards, alerts and issues.

Rollback floors

A rollback floor refuses every deploy of a release older than it, to one environment. A deploy below a floor is refused with exit 1 and the reason below_rollback_floor, before anything is built, confirmed or written. There is no flag that skips it. The only way past a floor is to lower or lift it, which is its own recorded act. There are two kinds: Order floors are about time: “never go back past v1.9.0”. Declared floors are about what the environment’s schema, API or data now is. A migration whose header says -- forge:breaks-rollback <why> raises one when the environment is promoted to that release, and so does a checked-in deploy/rollback-floors/<id>.yaml file of kind api, feature or data. A release cut later from a branch without the declaration is still refused, which a plain “older than” comparison would miss. Agents can run forge agent skill load db/deploy-migrations for how a migration declares whether the previous release survives it.
floor check makes a good first step in a release pipeline, because it asks the question without building or writing anything. A declared floor lifts only by id, and the lift must acknowledge every declaration the floor requires with --acknowledge <source>:<id>, vouching that it does not apply. The usual reason is that the rollout which raised the floor failed before it ran its migrator. floor show prints the declarations, and a refused lift prints the exact flags. Anyone who may promote may change floors, and every change carries its reason and who made it, on the ledger and in the activity stream. A floor the environment’s current release would itself fail is refused.
forge env floor and forge env deploy --floor need a control plane that supports floors. Forge does not send them to one that does not, and --floor against such a control plane is refused rather than silently dropped.

What there is not: automatic rollback

Forge has no rollback command and no down migration, and nothing here reverts a release for you. A rollout that fails to become healthy leaves the previous version serving, and a migration that fails stops the deploy before any workload changes. A release that rolls out fine and then regresses stays live until you act, because by then it has applied its migrations and written data in its new shape. Recovery is one of two ordinary deploys:
  • Roll forward. Cut a release with the fix and deploy it.
  • Deploy an earlier release, when it is above every floor. It is a normal promotion, the plan labels it BEHIND, and --note "<why>" records the reason on the ledger.
The floors are what keep “deploy an earlier release” honest: once a migration or API change cannot be undone, the floor stops anyone redeploying a release that cannot run on the data as it now is. If a bad release takes the control plane itself down, forge env deploy <env> --offline-ledger --to previous --yes redeploys from this machine’s cached copy; Releases and promotion explains it.

Composing the gates in a pipeline

Because every step has a stable exit code, a CI job or an agent can branch on them. Forge does not ship a built-in auto-promotion workflow, so this is a script you write:
Treat exit 2 and exit 8 as “not proven good”, never as success. The same loop works from a Reliant workflow, where an agent step runs these commands and a later step branches on the result; see Observability for agents and Workflows overview. A CI token reads verdicts with the obs:read scope and deploys with deploy:read,deploy:write.