Promote from one environment to another

Promoting copies the configuration of one environment onto another and replaces what the target had. Use it when what you set up in Staging is ready for Production, or to bring Staging back to what Production serves.

Before you begin

The gateway has at least two environments. See Environments.

What a promotion changes

Replaced in the target	Kept in the target
The served APIs and their versions	API keys and users, and their sessions
The exposed operations	Connected clients
The policies: MCP mode, limits, IP restrictions, repeated writes	Variables
The docs settings and the log settings	Logs
The connections and their routing, if you choose to copy them	The name and the URL

Promote an environment

To promote one environment onto another:

In the portal, go to Agent Gateway and select your gateway.
Switch to the environment to copy from with the environment button in the header.
Select the environment button again, then Promote followed by the environment's name.
Under To, select the environment that receives the configuration. To reverse the direction, select Swap direction.
Read Before you promote, if it appears, and What changes in the target. The changes are grouped under APIs, Operations, Connections, Policies and Docs.
If Connections offers a choice, select one:
- Keep the target's connections. This is the default. An API that both environments serve keeps the target's connections and routing.
- Use the source's connections. The target gets the source's connections and routing, and calls the same backends as the source.
If the target is the default environment, type its slug to confirm.
Select Promote to followed by the target's name.

Warning

A promotion cannot be undone. To have a way back, add an environment as a copy of the target before you promote. Promoting that copy onto the target restores it.

The portal switches to the target environment, which now has the source's configuration.

What to check in the review

Before you promote lists the changes that break something or are not obvious from the list of changes:

An API that is new in the target and arrives with the source's connection, or with none.
Keys and users that lose access to an API the target stops serving. Their scope on that API is removed. A credential left with an empty scope is refused on every call.
The target is the environment that Faustine Chat uses.
Variables that the source has and the target does not. Set them in the target after the promotion, or the recipes that read them fail there.

Troubleshooting

Symptom	Cause	Fix
The review says the target already matches the source	The two environments have the same configuration.	Nothing to do.
The promotion is refused and the review reloads	One of the two environments changed while you were reviewing.	Read the new review and promote again.
The Promote button is missing from the Environments dialog	The gateway has one environment.	Add a second environment.
A recipe fails in the target after a promotion	A variable the recipe reads is not set in the target.	Add it in the target's Variables tab.

Next steps

Environments: what each environment owns.
Set gateway variables: add the variables the target lacks.
Logs: check the first requests on the target after a promotion.