Skip to main content
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 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 gets you one. Two hosted environments need 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).
  • 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:
deploy/kcl/prod/main.k
Naming staging in after is the opt-in, and mode defaults to enforce. Check that the environment declares it:
terminal
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:
terminal
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:
terminal
4

Check the release in staging

--wait polls until the after window closes, then prints one JSON document:
terminal
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 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:
terminal
6

Verify the gate admitted it

The admission is recorded on the promotion as a health_gate gate:
terminal
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:
terminal
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.

Troubleshooting

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

Promote a release from staging to production

Plan and approve a promotion by digest.

Recover from a bad deploy

Redeploy an earlier release and set a rollback floor.

Release gates

How the verdict is computed, and every threshold.

Querying with forge obs

Read findings, traces and issues from the terminal.