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

# Promote a release from staging to production by digest

> Move the exact release staging runs to production without a rebuild, approve the plan you read by its digest, and see a stale promotion refused.

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](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md) explains the model. This guide is the procedure.

## Before you begin

* A forge project with `staging` and `prod` both bound to [Reliant hosting](https://docs.reliantlabs.io/hosting/overview.md), and a release already deployed to `prod` once. [Deploy a Go API with managed Postgres](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md) 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:

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

```text theme={null}
Rollout of v2.8.0 to staging: SUCCEEDED
  web: serving sha256:d121bc6…
  promotion d379077a-9357-430a-b49f-90620ee58e7c
```

Test staging as you normally do.

**2. Plan the promotion**

Name the release and the environment it comes from. `--plan-only` writes nothing:

```bash terminal theme={null}
reliant forge env deploy prod v2.8.0 --from staging --plan-only
```

```text theme={null}
  plan digest: sha256:740d56ef3acbf7d48d7147076bd561e7e492c6d49e5420aded04b78340f47402
PLAN (dry run — nothing was written): promote env "prod" → release v2.8.0
  current   v2.7.3 (promoted 2026-11-20T08:21:00Z, promotion 12558557-7819-48f0-9759-fb28e0ada29a)
  expected  12558557-7819-48f0-9759-fb28e0ada29a  (compare-and-set: the write is refused if the env moved since)
  target    v2.8.0 (cut 2026-11-20T08:26:25Z)
  direction AHEAD  FORWARD — v2.8.0 is 1 release(s) NEWER than v2.7.3 (by commit ancestry)
  floor     admitted (no rollback floor)

Images (0 unchanged, 2 changed, 0 added, 0 removed)
  CHANGED    …/guides-sandbox-promote/web/static.v1
      from  sha256:e52ee239ef47…
      to    sha256:d121bc6307c1…

Commits  COMPUTED
  1 commit(s) arriving in prod (4de8a2605fe0..0c93bdc550cd)
    0c93bdc v2.8.0

--plan-only: NO promotion was written.
```

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.

```bash terminal theme={null}
reliant forge env deploy prod v2.8.0 --from staging \
  --approve sha256:740d56ef3acbf7d48d7147076bd561e7e492c6d49e5420aded04b78340f47402
```

```text theme={null}
Rollout of v2.8.0 to prod: SUCCEEDED
  web: serving sha256:d121bc6…
  promotion d256a003-1d5f-44ae-b6e7-d70a39c8dec0 (from staging)
  waited 1m50.964s
Promoted env "prod": v2.7.3 → v2.8.0
```

In CI, add `--json` to the plan and read `.deploy_plan.digest`; [Releases and promotion](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md#the-plan-and-approving-it) shows the two-stage script.

**4. Verify production runs the release**

```bash terminal theme={null}
reliant forge env releases list prod
```

```text theme={null}
AT                    RELEASE        WHAT                   WHO                       COMMITS  ROLLOUT       GATES  HEALTH
2026-11-20 08:32:32Z  v2.8.0 (live)  promote (from v2.7.3)  you@example.com via cli   1        succeeded 5s  -      inconclusive
2026-11-20 08:21:00Z  v2.7.3         first promote          you@example.com via cli   2        succeeded 5s  -      inconclusive
```

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:

```text theme={null}
the plan for env "prod" is not the one --approve named (plan_stale), so NO promotion was written.
  approved: sha256:1518b0bcef0ccdd63826a48906b57f3377bf986b54000bc8fa2155bcf9bb21bd
  current:  sha256:199733cda8eb568362c2c342c27344dc13c9cbdec81c7b2d460554c5665031a5
  fix: re-plan and re-approve — forge env deploy prod --plan-only
```

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:

```text theme={null}
  direction BEHIND  BEHIND — v2.9.0 is 1 release(s) OLDER than v2.8.1 (by cut time). …
Commits  COMPUTED
  1 commit(s) REVERTED OUT OF prod (e36f889cb8d0..4fea64987646)
    e36f889 v2.8.1 hotfix
REFUSED (promotion_conflict — nothing was written): promote env "prod" → release v2.9.0
```

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.

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

## 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](https://docs.reliantlabs.io/guides/hosting/gate-production-deploy-release-health.md) 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

> [accordion] 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`).

> [accordion] 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`.

> [accordion] 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

> [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] [Gate prod on release health](https://docs.reliantlabs.io/guides/hosting/gate-production-deploy-release-health.md)
>
> Refuse a promotion until staging proves the release good.

> [card] [How release promotion works](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md)
>
> Releases, plans, compare-and-set and exit codes.

> [card] [Release gates](https://docs.reliantlabs.io/forge/deploy/release-gates.md)
>
> `obs check`, health gates and rollback floors.


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