Promote a release

Promoting moves an agent's configuration one step along the path. From Development it makes a numbered release and runs it in the next environment; from Staging it moves the same release on to Production. A promotion takes effect on the next message, everywhere that environment is used.

Before you start

• You're an editor or admin in the workspace. Production (and any other protected environment) takes promotions and rollbacks from admins only.
• The agent answers well in Development: the Build tab's test chat or the Playground.

Steps

1. 1

   Open the agent

   The environment bar under its name shows the path: Development · Draft with its unreleased changes, then Staging and Production with the release each runs, or Not released.

2. 2

   Choose Promote to Staging

   The button promotes from the environment you're looking at to the next one. From the Releases tab, the draft row and each release row have a Promote button too.

3. 3

   Check the dialog

   From is Development (the draft) or an environment running a release; To lists the environments after it, with the ones that can't take it greyed out and why ("admins only", "needs Staging first", "already runs it"). What changes in Staging compares what it runs now with what it will run, field by field, the instructions as a line diff.

4. 4

   Add release notes

   When a new release is being made, Release notes (optional, up to 2,000 characters) are kept with it, so everyone sees why it was made.

5. 5

   Confirm

   The button says exactly what happens: Create v3 and promote to Staging when the draft changed since the last release, or Promote v3 to Staging when it didn't and the latest release moves on. A toast confirms: "Created v3. Staging runs it now."

6. 6

   Test Staging

   In the Playground, pick Staging · v3 in the environment picker. On the Deploy tab, pick Staging to get a widget tag, chat link and API call that name it.

7. 7

   Promote to Production

   Click the Staging pill, then Promote to Production and Promote v3 to Production. By default Production only takes a release that Staging runs, and only from a workspace admin.

The rules

• Releases only move forward along the path. To run an older release again, roll back. See Roll back a release.
• From Development, a new release is made only when the draft differs from the latest release. Otherwise the latest release moves on, and the button says so.
• An environment that requires the previous environment first only takes a release that's running in the environment before it. The dialog offers Promote to Staging instead.
• A protected environment takes promotions and rollbacks from workspace admins only. For editors its button is off, with the reason on hover.
• Promote to Staging is also off when Staging already runs what Development would make: "Change the agent in Development to make a new release."
• From the Releases tab, only a release that's running somewhere can be promoted. To use an older release, roll an environment back to it first.
• Each environment keeps its own rate-limit window, because the rate limit is part of the release.
• An environment added later works the same: pick it in To, or click its Not released pill and promote into it from Development.

If something goes wrong