Deployments · Promote

Promote

Put the exact image you tested in one environment into another — for example from dev to production — without rebuilding it. Same bytes, same digest, with the target environment's own configuration.

What moves and what stays

What	Comes from
Image — code, dependencies, digest	Source
Commit, branch, and commit message shown on the build	Source
Values baked in at build time — build args and browser-bundle variables	Source
Variables and secrets the running service reads	Target
Pre-deploy command	Target
Spherelet shape and count, domains, volumes	Target

Environment names don't matter. Promote works between any two environments in the same project that run the same service.

How a promotion runs

1. A new build appears on the target, marked Promoted from <environment>. No build runs — its log reads "No build ran: this image was promoted from <environment> (build <id>). Its build log is on that build."
2. The target's pre-deploy command runs against the image, with the target's variables and secrets — so migrations run against the target's database.
3. The image rolls out on the target with the usual zero-downtime rollout. The source environment isn't touched.

Starting a promotion supersedes any build already in progress on the target.

Promote a build

Open the service in the source environment, then either:

• Latest build — click Promote to… on the Deploy card in Settings, or in the service header menu. This promotes the newest succeeded build.
• A specific build — open the Builds tab, select a succeeded build, and click Promote.

Pick the target environment and click Promote to <environment>. The dialog lists only environments where the service already runs.

Build-time values that differ

Some values are fixed into the image when it's built. A Next.js or Vite app inlines its public variables into the JavaScript bundle; a Dockerfile can copy a build arg into a file. A promoted image keeps the source environment's values for those — the target's variables can't change what's already in the image.

So before promoting, the platform compares the image's build-time values with the target's. When a baked-in value differs, the promotion stops and names the variables — never their values:

	Console	API
What you see	"These values are baked into the image at build time and differ in <environment>:" followed by the variable names	409 with one entry per variable in errors[], code: build_arg_differs
Promote anyway	Click Promote anyway. The image ships with the source environment's values.	Resend with "acknowledge_build_args": true
Use the target's values instead	Build in the target environment instead of promoting	Trigger a build on the target deployment

Which values count:

Build type	Compared
From your Dockerfile	Variables named NEXT_PUBLIC_*, VITE_*, REACT_APP_*, or PUBLIC_* that the Dockerfile declares with ARG. An undeclared build arg never reaches the image, so it isn't compared.
From source, no Dockerfile	Variables named NEXT_PUBLIC_*, VITE_*, REACT_APP_*, or PUBLIC_* that were in the build's scope.

Runtime values — database URLs, API keys, log levels — aren't compared. They come from the target when the image starts, which is the point of promoting.

Honest limits

• Same service, same project. The target must be another environment's deployment of the same service. Promote doesn't create the service in a new environment — deploy it there once first.
• Only images the platform built. A build from a Git repository or Dockerfile can be promoted. A service that runs your own prebuilt image can't be a source or a target; switch the target to build from Git first.
• Static sites can't be promoted yet. Build them in each environment.
• The build-time check covers the four public prefixes only. If your build bakes any other build-scoped value into the image — a plain variable copied into a config file, for example — the promoted image carries the source environment's value without a warning. Rebuild in the target environment when those values differ.
• Console and API only. The csph CLI doesn't have a promote command yet.
• Promote rolls forward. To go back, use Rollback on the target — it restores the target's previous revision.

What's next

• Pre-deploy commands — the target's migrations run before the promoted image takes traffic
• Environment variables — build and runtime scopes, and which values end up in the image
• Service actions — Deploy, Redeploy, Restart, Rollback, and when to use each
• Concepts — projects, environments, services, and how they nest