Promote an app
Where your tenant has a production lane, a running app's page offers Promote. It sends the app to that lane through the same approval machinery every other artifact uses.
Who can use it: the Builder role or higher, with the publish capability. The button appears only where your tenant actually has a production lane to send the app to, so if you do not see it, there is nowhere to promote to yet.
Recorded on .
Promote an app in four steps
The video above promotes a running app and then shows a refusal; the sections below are the reference for what each message means.
- Open a running app
Promotion starts from the app, not from a branch. A running app's page offers Promote to Production in its header, only where the tenant has a production lane.
- Read the pin
The Deploys tab shows the current deploy and the commit it is pinned to. That exact commit is what the platform sends; it resolves the pin itself, and the app has to be healthy where it runs now.
- Confirm
The dialog says what happens: the commit is staged in the lane and health-checked, and the route switches only after the staged copy is healthy. Confirming opens a proposal, Promotion proposed, awaiting approval where approval is required.
- Read a refusal
A deploy made before commit pinning is refused: the message says the app has no recorded commit pin and that one redeploy records it. Every refusal names its own cause; only an unreadable health signal and an unreachable deployment service are worth a retry.
What it promotes
The exact commit the app is serving, and the platform resolves it rather than taking it from your browser. You cannot promote a different commit by accident, and the lane cannot end up on something ambiguous.
That is also why a deploy made before commit pinning is refused rather than promoted. If the platform never recorded which commit the running app resolved, there is nothing exact to send. The refusal says so by name, and the remedy is one redeploy, which records a pin.
What happens when you confirm
The dialog states it plainly before you agree: the exact commit is staged in the target lane and health checked, and the route switches only after the staged copy is healthy. The lane keeps serving its current version until then.
That order is the point. A staged copy that never becomes healthy never receives traffic, and the lane is untouched, so a bad promotion costs you a failed stage rather than an outage.
The app has to be healthy where it is now
This is a precondition the button does not hint at. The platform checks the app where it runs today before it will stage it anywhere else, and refuses if it is not serving properly.
Promoting a version that is already unhealthy would only move a known problem into another environment.
When it is refused
Each refusal names its own cause and what to do about it.
| The message says | What it means | What to do |
|---|---|---|
| The app is not healthy where it runs today, naming how many replicas are ready and its status | The app itself is unwell where it is now | Make it healthy there, then promote |
| The health signal could not be read, and this does not mean the app is unhealthy | The platform could not measure, so it declined to guess | Try again shortly |
| The app has no recorded commit pin | There is no exact version to send | Redeploy it once to record the pin, then promote |
| The deployment service could not be reached | The platform could not find out what the app is serving | Try again shortly |
| The app cannot be prepared for promotion | Something about the app's details is wrong | Check the app and try again |
| This app cannot be promoted right now | The catch-all, where nothing more specific applies | Check the app's status |
| This proposal was already submitted | The promotion is already in flight | Look for the existing one rather than raising another |
The second row is the one to read carefully. A health signal the platform could not read is reported as exactly that, and the message says outright that it does not mean the app is unhealthy. It is the difference between "I measured, and it is bad" and "I could not measure", and the platform refuses to collapse the two.
Retrying is the right response to that one and to the unreachable deployment service. Retrying will not help the other four, which need something changed first.
Approval
Promotion opens a proposal. Depending on how your tenant is set up, it either goes straight through or waits.
| The message reads | What it means |
|---|---|
| Promotion proposed, awaiting approval | Someone has to approve it before anything moves |
| Promotion created, naming the state | The proposal exists and is progressing |
Once approved, the staging, the health check and the route switch happen without you.
What promotion is not
It is not a redeploy of your current environment, and it does not change what your current environment serves.
It does not rebuild the app. The commit is already known, so the target lane resolves the same source rather than taking whatever your branch points at now.
It is not a traffic split. The staged copy takes no traffic until it is healthy, and then it takes all of it.
It does not change who can reach the app. The promoted copy keeps the app's access: a Private app still admits only its owner, a Shared app keeps its groups, and a Public app asks for no sign in.