Deploy a version to an environment

Deploying a version makes an environment serve it. You deploy from the Deployments dialog, where you also add environments and choose the release target. Every change in the dialog is staged until you select Apply changes.

Before you begin

The agent has at least one published version. See Publish a version.
Every variable the version uses has a default or a value on the environment you deploy to.

Deploy a version

To change the version an environment serves:

In the portal, go to Web Agents and select your agent.
In the agent's header, select the control that lists each environment with the version it serves. The Deployments dialog opens.
Under the environment, select the version. Versions are listed from oldest to newest, and the one the environment serves is marked Live.
Select Yes, serve with the version number to confirm.
Select Apply changes.

The header shows the new version next to the environment. Pages of that environment get it on their next load.

Add an environment

To add an environment such as Staging:

In the Deployments dialog, select Add environment.
Enter a name and select Add. The new environment is set to serve the latest version. To serve another one, select it.
Select Apply changes.

To load the environment from your app, pass its name in the install snippet: env: 'Staging' in Faustine.init, or &env=Staging on the script URL. A new environment has no allowed domains and its own variable values, which start empty and fall back to each variable's default.

Change the release target

The release target is the environment that serves every new version as soon as you publish it. To publish to Staging first and deploy to Production yourself, make Staging the release target.

To change it:

In the Deployments dialog, under Release target, select the environment.
Select Yes, use with the environment's name to confirm.
Select Apply changes.

The next publish is served on the new release target. The previous one keeps the version it serves.

Deploy the latest version to the release target

When the release target does not serve the latest version, the agent's header says which version it still serves and shows a Deploy button with the version and the environment, for example Deploy v5 to Staging. Select it to serve the latest version there without opening the dialog.

Remove an environment

In the Deployments dialog, select the remove control of the environment, then Apply changes. The release target cannot be removed, and an agent keeps at least one environment.

A page that names the removed environment stops loading the agent. Change the install snippet of every site that loads an environment before you remove it.

Troubleshooting

Symptom	Cause	Fix
The dialog shows `No published versions yet`	The agent has no version.	Publish a version first.
Apply changes is not available and the dialog says `Confirm or dismiss the highlighted change first.`	A version or a release target is selected and not confirmed.	Confirm it, or keep the current one.
Applying fails for one environment	A variable of the version has no default and no value on that environment.	Set the value in the Variables tab, then apply again.
`An environment with that name already exists.`	Environment names are unique within an agent, ignoring letter case.	Enter another name.

Next steps

Roll back to an earlier version: serve the previous version on an environment.
Set variables for each environment: give the new environment its values.
Restrict the domains that can load the agent: set the allowed domains of the environment.
Versions, environments and deployments: how publishing and deploying relate.