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

# Gate a production deploy on release health

> Hold production until staging proves a release healthy: declare a health gate in prod's KCL, judge staging with forge obs check, then promote the release.

By the end of this guide, prod will refuse any release that staging has not proved healthy, and you will have promoted one that it did prove. The control plane enforces the rule inside the promotion itself, so no script, teammate or CI token can skip it.

The proof is the release-health verdict: Forge compares the window after a promotion with the window before it, per service, and calls the release PASS, FAIL or INCONCLUSIVE. [Release gates](https://docs.reliantlabs.io/forge/deploy/release-gates.md) explains how that verdict is computed. This guide is the task.

## Before you begin

* A Forge project with `staging` and `prod` environments on Reliant hosting. [Deploy a Go API with managed Postgres](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md) gets you one. Two hosted environments need [billing](https://docs.reliantlabs.io/hosting/overview.md#billing).
* Forge v1.7.0 or later. Run `reliant forge --version` inside the project.
* A service that exports OpenTelemetry traces. Services Forge builds do this already. An app built from its own Dockerfile needs an OpenTelemetry SDK, or every verdict is INCONCLUSIVE (see [Bring an existing app](https://docs.reliantlabs.io/guides/forge/bring-existing-app-any-language.md)).
* Real traffic on staging. With fewer than 50 requests in each 15-minute window, a service is not judged.

**1. Declare the gate in prod**

Add a `delivery_policy` to the `forge.Bundle` in prod's environment file:

```kcl deploy/kcl/prod/main.k theme={null}
_bundle = forge.Bundle {
    project = "guides-sandbox-healthgate"
    observability = forge.Observability {}
    control_plane = forge.ControlPlane {}
    # Prod takes a release only once staging has proved it good.
    delivery_policy = forge.DeliveryPolicy {
        health_gate = forge.HealthGate {after = ["staging"]}
    }
    # ...workloads, databases, identity as before
}
```

Naming `staging` in `after` is the opt-in, and `mode` defaults to `enforce`. Check that the environment declares it:

```bash terminal theme={null}
reliant forge env shape prod --json
```

```json theme={null}
"health_gate": {
  "mode": "enforce",
  "after": [
    "staging"
  ]
}
```

> [!WARNING]
>
> The control plane reads the gate from the declaration prod was last deployed with. A prod environment that does not exist yet has none, so the deploy that created prod promoted a release staging had never judged. Deploy prod once before you rely on the gate.

**2. Ship the release to staging**

Build the release once, then deploy it to staging:

```bash terminal theme={null}
reliant forge env build staging --release v6.2.0
reliant forge env deploy staging v6.2.0 --yes
```

Keep traffic on staging for the next 15 minutes. Here, a `curl` loop sent about 1.5 requests a second to a public RPC.

**3. Watch the gate refuse an unproven release**

Promote too early and nothing is written. Before staging ran v6.2.0, the deploy exited 4 with `health_gate_unproven`. While the window was still open it exited 4 with `health_gate_pending`:

```bash terminal theme={null}
reliant forge env deploy prod v6.2.0 --yes
```

```text theme={null}
REFUSED (health_gate_pending — nothing was written): promote env "prod" → release v6.2.0
  current   v6.1.0 (promoted 2026-11-20T08:52:48Z, promotion e39a9c3a-…)
promote refused (health_gate_pending): prod's health gate (delivery_policy.health_gate.after = [staging])
refuses v6.2.0 until it is proven good there first: staging runs v6.2.0 (promotion 6e0d3e54-… at
2026-11-20T09:02:12Z) but has no verdict yet: …wait with `forge obs check staging --release v6.2.0 --wait`,
then retry.
```

**4. Check the release in staging**

`--wait` polls until the after window closes, then prints one JSON document:

```bash terminal theme={null}
reliant forge obs check staging --wait --json
```

```json theme={null}
{
  "schema": "forge.obs.check/v1",
  "exit_code": 0,
  "verdict": "PASS",
  "subject": { "release": "v6.2.0", "previous_release": "v6.1.0", "promoted_at": "2026-11-20T09:02:12.640867Z" },
  "services": [
    {
      "service": "api",
      "before": { "requests": 928, "error_rate": 0, "p95_ms": 4.838699 },
      "after": { "requests": 1396, "error_rate": 0, "p95_ms": 4.635139 }
    }
  ],
  "findings": [],
  "waited": "11m47s"
}
```

Branch on the exit code, never on the text. 0 is PASS. 1 is FAIL: read `findings[]` and `suggested[]`. 2 is INCONCLUSIVE, meaning not proven good, and never a pass. 8 means `--wait` ran out before the window closed, so check again later. [What each exit code means](https://docs.reliantlabs.io/forge/deploy/release-gates.md#what-each-exit-code-means) lists the `reason_code` values behind exit 2.

The previous release, v6.1.0, served no traffic during its own windows, so its verdict is INCONCLUSIVE with `reason_code` `no_request_telemetry`. Missing telemetry is never green.

**5. Promote the proven release to prod**

The control plane stores its own verdict a few minutes after the window closes. A promote one minute after the PASS was still refused `health_gate_pending`. The same command three minutes later was admitted:

```bash terminal theme={null}
reliant forge env deploy prod v6.2.0 --yes
```

```text theme={null}
Rollout of v6.2.0 to prod: SUCCEEDED
  promotion 4ae8072f-5e6d-4780-aa9d-abb25b456382
Promoted env "prod": v6.1.0 → v6.2.0
```

**6. Verify the gate admitted it**

The admission is recorded on the promotion as a `health_gate` gate:

```bash terminal theme={null}
reliant forge env releases show prod v6.2.0
```

```text theme={null}
v6.2.0  promote (from v6.1.0) in prod
  promotion  4ae8072f-5e6d-4780-aa9d-abb25b456382
  state      live now
  health     inconclusive the after window is still open

gates (passed)
WHEN      GATE         STATUS  SUMMARY
recorded  health_gate  passed  v6.2.0 — staging: pass
```

Prod's own `health` line is a separate verdict. It is judged once prod's window closes.

**7. Clean up**

If you made these environments only to try this, delete them. This also deletes their databases:

```bash terminal theme={null}
reliant forge env delete staging --yes
reliant forge env delete prod --yes
```

The release images stay in the project's registry.

## What this does not do

* **It does not roll anything back.** A FAIL or INCONCLUSIVE on staging refuses the prod promotion. Staging keeps serving the release it judged, and prod keeps what it had. To move an environment back, deploy an earlier release.
* **Low traffic is final for that promotion.** A `reason_code` of `low_traffic` or `thin_baseline` means the window closed with too few requests. A later check reads the same window, so do not poll. Send real traffic, or lower `min_requests` in staging's `release_health`.
* **It needs a control plane.** A self-hosted environment with none records the declaration and refuses nothing.
* **It has no synthetic traffic of its own.** The verdict judges the requests your environment served.

During an incident, `--override-health-gate "<why>"` overrides this gate only, and records who did it and why. `mode = "audit"` records what `enforce` would refuse without blocking anything. See [the health gate](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md#the-health-gate-opt-in).

## Troubleshooting

> [accordion] promote refused (health\_gate\_unproven)
>
> The release never ran on staging, or staging judged it INCONCLUSIVE. The gate reads the verdict of the release's newest promotion to staging. Deploy it to staging while it gets traffic, wait for the verdict, then retry. In an incident, override with a reason.

> [accordion] promote refused (health\_gate\_pending)
>
> Staging runs the release, but the control plane has not stored a verdict yet. Run `reliant forge obs check staging --release <version> --wait`, wait a few more minutes, then retry the deploy.

> [accordion] INCONCLUSIVE — no request telemetry
>
> No service sent a server span in either window. Either the release served no traffic during its window, or the app exports no traces. Hosting sets `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_SERVICE_NAME` on every workload, so an OpenTelemetry SDK only has to export to them.

## Next steps

> [card] [Promote a release from staging to production](https://docs.reliantlabs.io/guides/hosting/promote-release-staging-to-production.md)
>
> Plan and approve a promotion by digest.

> [card] [Recover from a bad deploy](https://docs.reliantlabs.io/guides/hosting/recover-from-bad-deploy.md)
>
> Redeploy an earlier release and set a rollback floor.

> [card] [Release gates](https://docs.reliantlabs.io/forge/deploy/release-gates.md)
>
> How the verdict is computed, and every threshold.

> [card] [Querying with forge obs](https://docs.reliantlabs.io/hosting/observability/forge-obs.md)
>
> Read findings, traces and issues from the terminal.


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