Skip to main content
By the end of this guide, production runs the release staging already runs: the same bytes, not a rebuild. You approve the exact plan you read, and a promotion that would overwrite a hotfix someone shipped while you waited is refused. This works because a forge release records the digest of every artifact once, and every promotion is a compare-and-set on the environment’s ledger. How release promotion works explains the model. This guide is the procedure.

Before you begin

  • A forge project with staging and prod both bound to Reliant hosting, and a release already deployed to prod once. 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 --version inside the project).
1

Cut a release and deploy it to staging

Build once and record the release, then deploy it to staging:
terminal
Test staging as you normally do.
2

Plan the promotion

Name the release and the environment it comes from. --plan-only writes nothing:
terminal
Read the direction, the images and the commits. The to digest is the one staging serves.
3

Approve the plan you read

Pass the digest back with --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
In CI, add --json to the plan and read .deploy_plan.digest; Releases and promotion shows the two-stage script.
4

Verify production runs the release

terminal
The prod URL served the new page. Health is 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 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:
A pipeline that captured the promotion id instead (--expect-current <id> --yes) is refused too, and its plan shows what the write would have dropped:
Merge the hotfix, cut a release that carries both (v2.9.1 here), and repeat the steps above. Its plan read 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. --from cannot promote between organizations or from a machine-ledger environment.

Troubleshooting

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).
Another project in your organization already cut a release with that version name. Pick a different version for --release.
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.