Before you begin
- A forge project with
stagingandprodboth bound to Reliant hosting, and a release already deployed toprodonce. Deploy a Go API with managed Postgres gets you there. - Billing on your organization. One static site is free, and each environment’s site counts, so a second hosted environment needs billing. Without it the deploy is queued with exit 7 and prints the billing link.
- Forge v1.6.1 or later (
reliant forge --versioninside the project).
1
Cut a release and deploy it to staging
Build once and record the release, then deploy it to staging:Test staging as you normally do.
terminal
2
Plan the promotion
Name the release and the environment it comes from. Read the direction, the images and the commits. The
--plan-only writes nothing:terminal
to digest is the one staging serves.3
Approve the plan you read
Pass the digest back with In CI, add
--approve, and keep --from staging. The printed “Approve it with” line leaves --from out; with it, the deploy is also refused if staging moved since the plan.terminal
--json to the plan and read .deploy_plan.digest; Releases and promotion shows the two-stage script.4
Verify production runs the release
terminal
inconclusive because the sandbox had no traffic.5
See a promotion refused after a hotfix
Suppose staging now runs v2.9.0 and you planned its promotion (digest A pipeline that captured the promotion id instead (Merge the hotfix, cut a release that carries both (v2.9.1 here), and repeat the steps above. Its plan read
sha256:1518b0bc…). Before you approve, someone ships a hotfix, v2.8.1, straight to prod. Your approval no longer describes what prod runs, so it is refused with exit 3:--expect-current <id> --yes) is refused too, and its plan shows what the write would have dropped:2 commit(s) arriving in prod.6
Clean up a sandbox
If you followed along in a throwaway project, delete its environments. The project’s release images stay in the registry.
terminal
What this does not do
- It does not require staging to pass first. Promotion order is yours until you declare a health gate; Gate a production deploy on release health does that.
- It does not merge or rebase a hotfix for you. The refusal stops the overwrite; you cut the release that carries both changes.
- It works within one control plane.
--fromcannot promote between organizations or from a machine-ledger environment.
Troubleshooting
No plan digest to approve (none could be computed for this env)
No plan digest to approve (none could be computed for this env)
You ran
--from staging without a version. With forge v1.6.1 that form computes no plan on a hosted environment, and the --yes it suggests is then refused with plan_required (exit 1). Name the release: reliant forge env deploy prod v2.8.0 --from staging --plan-only. The same happens when prod has never been deployed: deploy a named version to it first (env deploy prod <version> --yes).CutRelease failed (HTTP 404, not_found) … release, environment or deployment not found
CutRelease failed (HTTP 404, not_found) … release, environment or deployment not found
Another project in your organization already cut a release with that version name. Pick a different version for
--release.plan_stale or promotion_conflict (exit 3)
plan_stale or promotion_conflict (exit 3)
Prod moved after you planned. Do not retry the same command: re-plan, read what landed, then approve the new digest.
Next steps
Recover from a bad deploy
Redeploy an earlier release and set a rollback floor.
Gate prod on release health
Refuse a promotion until staging proves the release good.
How release promotion works
Releases, plans, compare-and-set and exit codes.
Release gates
obs check, health gates and rollback floors.