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 theexit_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_trafficorthin_baselinemeans 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, lowermin_requestsin itsrelease_healthdeclaration, pass--threshold min_requests=20, or widen--window.window_openmeans the after window has not finished. Check again, or use--wait.no_request_telemetrymeans 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: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 indeploy/kcl/prod/main.k:
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:
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 aReleaseRegressed 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:
--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 reasonbelow_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.
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:obs:read scope and deploys with deploy:read,deploy:write.
Related topics
- Releases and promotion covers releases, plans, approvals, deploy exit codes, and the health gate’s place in the delivery path.
- Querying with forge obs is the full reference for
obs check,statusand the verbs that find the cause of a FAIL. - Hosted dashboards, alerts and issues describes the built-in alerts,
ReleaseRegressedincluded. - Observability for agents shows these verdicts in an agent’s loop.
- Environments covers the declarations
release_healthanddelivery_policylive in. - Workflows overview covers running a deploy-and-check loop as a Reliant workflow.