Before you begin
- A Forge project with
stagingandprodenvironments 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 --versioninside 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 Naming
delivery_policy to the forge.Bundle in prod’s environment file:deploy/kcl/prod/main.k
staging in after is the opt-in, and mode defaults to enforce. Check that the environment declares it:terminal
2
Ship the release to staging
Build the release once, then deploy it to staging:Keep traffic on staging for the next 15 minutes. Here, a
terminal
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
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 Prod’s own
health_gate gate:terminal
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:The release images stay in the project’s registry.
terminal
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_codeoflow_trafficorthin_baselinemeans the window closed with too few requests. A later check reads the same window, so do not poll. Send real traffic, or lowermin_requestsin staging’srelease_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.
--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
promote refused (health_gate_unproven)
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.
promote refused (health_gate_pending)
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.INCONCLUSIVE — no request telemetry
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
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.