> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.poly.ai/feedback

```json
{
  "path": "/learn/maintain/version-management",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Version management

> Publish, promote through environments, compare versions, and rollback safely when needed.

Use versions to track changes, test safely through Sandbox → Pre-release → Live, and rollback instantly if problems occur.

## Quick reference

| I need to...           | Action                                                            |
| ---------------------- | ----------------------------------------------------------------- |
| Publish a new version  | Click **Publish** → add description                               |
| Promote to Pre-release | **Deployments > Environments** → Options → Promote to Pre-release |
| Promote to Live        | **Deployments > Environments** → Options → Promote to Live        |
| Rollback               | Find the last good version → Promote to Live                      |
| Compare versions       | Select two versions → **Compare**                                 |
| View history           | **Deployments > Environments**                                    |

## Publishing

Publish a version when you've made changes in Sandbox and want to create a checkpoint, test in a clean environment, or prepare for promotion.

1. Make and test your changes in Sandbox
2. Click **Publish** in the top right
3. Add a clear version description
4. Click **Publish**

A published version includes: Managed Topics, Connected Knowledge configs, functions, agent settings, response controls, routing rules, API integrations, and test sets.

<Tip>Use descriptive version descriptions. Examples: "Added Spanish language support with new voice", "Fixed booking function timeout", "Updated holiday hours".</Tip>

<Note>Connected Knowledge content is synced separately. Sync sources before publishing to ensure the latest content is available.</Note>

## Promoting

### To Pre-release

1. Go to **Deployments > Environments**
2. Click the **Options Menu** next to the version
3. Select **Promote to Pre-release**

Use Pre-release for UAT, validation with select users, and final checks before production.

### To Live

1. Go to the **Pre-release** tab in **Deployments > Environments**
2. Click Options → **Promote to Live**
3. Confirm by checking the box and clicking **Promote**

<Warning>Promoting to Live affects real customers immediately. Always test in Pre-release first.</Warning>

You can promote directly from Sandbox to Live, but this is only recommended for emergency hotfixes.

## Comparing versions

1. Go to **Deployments > Environments**
2. Select two versions and click **Compare**
3. Review the diff:
   * <Icon icon="plus" iconType="solid" color="#2D8C66" /> Green – additions
   * <Icon icon="minus" iconType="solid" color="#D64F4F" /> Red – deletions
   * <Icon icon="rotate" iconType="solid" color="#3B73D1" /> Blue – edits

You can compare Managed Topics, function code, agent settings, response controls, and routing rules.

## Rolling back

Rollback when a new version has critical bugs, performance degrades, or customer complaints spike. Rollback is just promoting an older version:

1. Go to **Deployments > Environments**
2. Find the last known good version
3. Promote it to Live

**Time to rollback:** 2-5 minutes.

After rolling back, investigate the issue, fix it in Sandbox, and re-promote when ready.

## Deployment workflows

### Standard deployment

1. Develop and test in Sandbox
2. Publish with descriptive notes
3. Promote to Pre-release → validate
4. Promote to Live → monitor closely

### Hotfix

1. Reproduce the issue in Sandbox
2. Fix, test, publish
3. Promote through Pre-release briefly, then to Live
4. Monitor closely

### Seasonal updates

1. Apply seasonal changes in Sandbox (hours, policies, etc.)
2. Publish, promote, and schedule for the right date
3. Revert after the season ends

## Best practices

* **Publish regularly** – don't accumulate too many changes in a single version
* **Run [test sets](/analytics/test-suite/introduction) before promoting** – catch regressions early
* **Monitor after promotion** – watch the first 30 minutes closely, check metrics for 24 hours
* **Be ready to rollback** – know which version to revert to before promoting
* **Use consistent descriptions** – consider tags like `[HOTFIX]`, `[FEATURE]`, `[SEASONAL]`

<div className="developer-only">
  ## Automate with the Agents API

  If agent promotions belong inside a wider release pipeline, the same publish / promote / rollback actions are available over HTTP.

  <AccordionGroup>
    <Accordion title="Automate the deployment pipeline via the Agents API" icon="code">
      The [Agents API](/api-reference/agents/introduction) exposes [publish](/api-reference/agents/endpoint/deployments/publish-the-current-draft-to-an-environment), [promote](/api-reference/agents/endpoint/deployments/promote-a-deployment-to-the-next-environment), and [rollback](/api-reference/agents/endpoint/deployments/rollback-to-a-previous-deployment) so the same steps can run from CI alongside backend services or infrastructure.

      A typical CI job publishes to Sandbox, runs your [test suite](/analytics/test-suite/introduction), promotes to Pre-release on success, and blocks promotion to Live behind a manual approval gate.
    </Accordion>
  </AccordionGroup>
</div>

## Related pages

* [Environments](/environments-and-versions/introduction) – technical reference
* [Version diffs](/environments-and-versions/diffs) – comparing changes
* [Project history](/environments-and-versions/project-history) – viewing past versions
* [Test suite](/analytics/test-suite/introduction) – automated validation
* [Deployments endpoints](/api-reference/agents/endpoint/deployments/publish-the-current-draft-to-an-environment) – publish, promote, and rollback from code