Environment release (staging ↔ production)

How to ship copy safely when staging and production diverge — normal releases, urgent hotfixes, and back-sync.

Related: Staging overlay · Getting started · Deploy release (CI)

---

Environments at a glance

Environment	Typical use	SDK init()
Staging	WIP copy, QA, overlay editing	environment: "staging"
Production	Live user traffic	environment: "production"

Published values in each environment are independent until you promote or sync between them. The admin Keys workspace shows a Staging vs production diff before you release.

---

Scenario A — Normal release

Use when staging copy is validated and ready for live users.

Edit staging → Publish staging → Promote (all or selected keys) → Publish production

Steps in admin

1. Keys — edit and review staging values (overlay or Keys editor).
2. Publish staging — rebuild staging CDN bundles.
3. Open Staging vs production diff — confirm staging-ahead rows look correct.
4. Promote to production (all keys) or Promote selected to production (key-scoped).
5. Publish production — or use Promote & publish production for one combined action.

Key-scoped release

When staging has unreleased WIP on other keys, select only the keys you want in the diff table or keys list, then promote selected keys. Unselected staging WIP stays on staging only.

---

Scenario B — Release on app deploy (CI)

When your team ships the app to production, automate promote + publish with deploy-release (opt-in per application, deploy token dpt_…).

See the full guide: Deploy release.

Until CI deploy-release is enabled for the application, use Scenario A manually in admin.

---

Scenario C — Production hotfix (urgent)

Use when live copy must change now and staging still has unrelated work in progress.

Hotfix production (admin) → Save → Publish production

Steps in admin

1. Keys → switch to Hotfix production (paid plans; enable Production hotfix in Settings → Billing).
2. Select the key — edit published production values.
3. Save production hotfix or Save & publish production.

Live traffic

You are editing copy served to production SDK clients. After a hotfix, run Scenario D so a later full promote does not revert live text.

Production hotfix requires a paid plan and owner/admin role. Owners can disable hotfix in Settings → Billing.

Admin hotfix vs production overlay

Path	When to use	Who	Plan
Staging overlay	Day-to-day editing on staging sites	Editors+ with edit token	All
Admin hotfix	Urgent live copy fix without staging promote	Owners/admins	Paid + Production hotfix enabled
Production overlay	In-context edit on live site (optional)	Editors+ with edit token	Business+ + Production overlay + project Translation approvals

Prefer admin hotfix for urgent one-off fixes; use production overlay only when Business+ teams need in-context editing on production URLs.

---

Roles (production release)

Action	Owner	Admin	Editor	Reviewer
Edit staging keys / overlay	✓	✓	✓	—
Publish staging	✓	✓	✓*	—
Promote / sync environments	✓	✓	—	—
Production hotfix (admin)	✓	✓	—	—
Publish production	✓	✓	—	—
Toggle Production hotfix	✓	✓	—	—
Toggle Production overlay	✓	✓	—	—

*Publish staging follows Translation approvals when enabled on the project.

---

Scenario D — Back-sync staging after hotfix

After a production hotfix, staging may still hold older text for the same keys. A full Promote to production would overwrite your hotfix.

Production hotfix → Sync staging from production → continue WIP on staging → promote when ready

Steps in admin

1. Open Staging vs production diff — look for Production only (target_ahead) rows.
2. Sync staging from production — selected keys from the diff checkboxes, or Sync all production-ahead keys.
3. Confirm the preview — staging text for those keys will be overwritten with production values.
4. Resume normal staging edits; use key-scoped promote for the next release.

Regression case (why back-sync matters)

  BEFORE hotfix
  staging:  "Pay now"          production: "Checkout"
  team hotfixes production →   production: "Pay securely"

  WITHOUT back-sync
  staging still: "Pay now"
  full promote → production reverts to "Pay now"  ← regression

  WITH back-sync
  sync prod → staging → staging: "Pay securely"
  next promote is safe (or use key-scoped promote for other keys)

---

Scenario E — Parallel development / key-scoped ship

Staging is ahead on feature keys and behind or equal on others. Ship only what is ready:

1. Use the diff panel to filter Staging only (source_ahead).
2. Select keys to promote (checkboxes).
3. Promote selected to production or Promote & publish production with Selected keys only.

Unselected keys keep independent staging WIP without touching production.

---

Scenario F — Staging-only experiments

Edit and publish staging freely. Production stays unchanged until you promote. The diff panel shows Staging only rows while experiments are in progress.

---

Promote guardrails

Before Promote all to production, admin checks whether production is newer on any overlapping keys (common after a hotfix). If so, you see a blocking dialog:

Action	When to use
Cancel	Review diff; sync staging from production first
Promote selected staging-ahead only	Ship new copy without touching production-ahead keys
Force overwrite all	Rare; you accept overwriting production hotfixes

---

Troubleshooting

“Promote reverted my hotfix”

Cause: Staging still had old text; full promote copied staging → production.

Fix:

1. Re-apply the hotfix on production if needed, or restore from audit history.
2. Sync staging from production for affected keys.
3. Use key-scoped promote or sync before the next full promote.

Diff shows Conflict

Both environments have different non-empty values for the same key/locale. Often follows a hotfix while staging was edited separately. Resolve by choosing sync direction (usually prod → staging after hotfix), then key-scoped promote for new staging work.

Production hotfix button disabled

Upgrade from the free plan, or ask an owner to confirm billing. Production publish and hotfix share the same plan gate.

SDK still shows old production string

Confirm Publish production ran after hotfix or promote. Hard-refresh the app; bundles are versioned and cached by the CDN.

---

Quick reference

Goal	Admin action
Ship validated staging copy	Promote → Publish production
Ship one feature’s keys	Select keys → Promote selected
Fix live copy urgently	Hotfix production → Publish production
Prevent promote regression	Sync staging from production
See divergence before acting	Staging vs production diff