> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Release gates: obs check, release health, rollback floors

> How forge gates a release: forge obs check judges each deploy, a health gate holds prod until staging passes, and rollback floors block older releases.

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:

| Question | Mechanism | Where it runs |
| - | - | - |
| Did this release make things worse? | `forge obs check`, the release health verdict | CLI, and the platform for every promotion on Reliant hosting |
| May this release go to prod? | The health gate, `delivery_policy.health_gate` | The control plane, inside the promotion |
| May this environment ever go back to an older release? | Rollback floors, `forge env floor` | The control plane or machine ledger, before anything is built |

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.

```bash theme={null}
forge env deploy prod
forge obs check prod --wait --json      # 0 PASS · 1 FAIL · 2 cannot tell · 8 check again later
```

`--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 | Verdict | What a script does |
| - | - | - |
| 0 | PASS | The release did not make things worse. Continue. |
| 1 | FAIL | Forge looked and the release made things worse. Stop and read `findings[]` and `suggested[]`. |
| 2 | INCONCLUSIVE, or forge could not look | The release is **not proven good**. Never treat it as a pass. |
| 8 | Nothing final learned | `--wait` ran out before the after window finished, or the control plane refused the read for quota or rate-limit reasons (`retry_at` says when). Check again later. |

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:

```python theme={null}
release_health = forge.ReleaseHealth {
    window = "15m"                      # 1m to 6h
    min_requests = 50                   # below this a service is not judged
    max_error_rate_increase = 0.01      # a fraction: one percentage point
    max_p95_ratio = 1.5
    new_issue_min_events = 3
    fail_on = ["new_issue", "regressed_issue", "error_rate", "alert_firing"]
}
```

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](https://docs.reliantlabs.io/hosting/observability/forge-obs.md#obs-check-did-the-deploy-work).

If you want the verdict recorded on the promotion rather than only read by your script, write it as evidence and attach it:

```bash theme={null}
forge obs check prod --wait --gate-json check.json && forge release gate record prod --from check.json
```

## 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`:

```python theme={null}
delivery_policy = forge.DeliveryPolicy {
    health_gate = forge.HealthGate {after = ["staging"]}     # mode defaults to enforce
}
```

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.

| Staging's verdict for the release | Prod promotion |
| - | - |
| PASS | Admitted, with a `health_gate` gate recorded on the promotion. |
| FAIL | Refused: `health_gate_regressed`, deploy exit 1. |
| INCONCLUSIVE, or the release never ran on staging | Refused: `health_gate_unproven`, deploy exit 4. |
| Not judged yet | Refused: `health_gate_pending`, deploy exit 4. Run `forge obs check staging --release <v> --wait`, then retry. |

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:

```bash theme={null}
forge env deploy prod v1.4.2 --override-health-gate "staging window is closed and the fix is time-critical"
```

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](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md).

## 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:

```bash theme={null}
forge obs check prod --release v1.4.2
```

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](https://docs.reliantlabs.io/hosting/observability/dashboards-and-alerts.md).

## 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:

| Kind | Admits a target that | Set by |
| - | - | - |
| `order` | was not cut before the floor's release | `forge env floor set`, or `forge env deploy --floor` |
| `declared` | carries every declaration the floor requires | Automatically, when the environment is promoted to a release that declares something it cannot be rolled back past |

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.

```bash theme={null}
forge env floor show prod                              # active floors; --all adds lifted ones
forge env floor check prod v1.8.3                      # would the floors admit it? reads only: exit 0 / 1 / 2
forge env floor set prod v1.9.0 --reason "v1.8 corrupts invoices"
forge env floor set prod --current --reason "roll forward only from here"
forge env deploy prod v2.1.0 --floor "migration dropped the legacy column"
forge env floor lower prod v1.8.0 --reason "..."       # lift order floors above v1.8.0, set one at it
forge env floor clear prod --reason "..."              # lift every order floor
forge env floor lift prod flr_8c1e --reason "..." --acknowledge <source>:<id>
```

`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.

> [!NOTE]
>
> `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.

```bash theme={null}
forge env floor check prod v1.8.3              # is going back allowed?
forge env deploy prod v1.8.3 --note "v1.9.0 regressed error rate"
```

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](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md#there-is-no-rollback-command) 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:

```bash theme={null}
set -u
forge env floor check prod "$RELEASE"            || exit 1   # below a floor, or could not tell
forge env deploy staging "$RELEASE" --yes        || exit 1
forge obs check staging --release "$RELEASE" --wait --json > check.json
case $? in
  0) forge env deploy prod "$RELEASE" --yes ;;   # the health gate re-checks this on the server
  1) echo "regressed on staging"; jq -r '.suggested[]' check.json; exit 1 ;;
  *) echo "not proven good: $(jq -r .reason check.json)"; exit 1 ;;   # 2 or 8
esac
forge obs check prod --wait --json
```

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](https://docs.reliantlabs.io/hosting/observability/agents.md) and [Workflows overview](https://docs.reliantlabs.io/workflows/overview.md). A CI token reads verdicts with the `obs:read` scope and deploys with `deploy:read,deploy:write`.

## Related topics

* [Releases and promotion](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md) covers releases, plans, approvals, deploy exit codes, and the health gate's place in the delivery path.
* [Querying with forge obs](https://docs.reliantlabs.io/hosting/observability/forge-obs.md) is the full reference for `obs check`, `status` and the verbs that find the cause of a FAIL.
* [Hosted dashboards, alerts and issues](https://docs.reliantlabs.io/hosting/observability/dashboards-and-alerts.md) describes the built-in alerts, `ReleaseRegressed` included.
* [Observability for agents](https://docs.reliantlabs.io/hosting/observability/agents.md) shows these verdicts in an agent's loop.
* [Environments](https://docs.reliantlabs.io/forge/deploy/environments.md) covers the declarations `release_health` and `delivery_policy` live in.
* [Workflows overview](https://docs.reliantlabs.io/workflows/overview.md) covers running a deploy-and-check loop as a Reliant workflow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.