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

# Environments and releases: dev, staging and prod

> Turn on deployments to run versions in dev, staging and prod, promote and roll back, give each environment its own values, and choose where each channel lands.

With deployments on, an agent has three environments: dev, staging and prod. Each one runs one published version with its own environment variables, and prod is what callers hear. You publish into dev, check it, and promote it toward prod, all from **Releases**. This page explains the release path, who can move versions, and where each channel lands.

## Before you start

Promoting and editing values depend on the environment. These are the role defaults; an owner can change them per member in [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md).

| Action | Permission | Owner | Admin | Member |
| - | - | - | - | - |
| **Turn on deployments** | Manage versioning | Yes | Yes | No |
| Put a version in dev | Publish | Yes | Yes | No |
| Put a version in staging | Promote | Yes | Yes | No |
| Put a version in prod, roll prod back | Deploy | Yes | Yes | No |
| Start, change or stop an A/B test | Experiment | Yes | Yes | No |
| Edit dev values | Publish | Yes | Yes | No |
| Edit staging values | Promote | Yes | Yes | No |
| Edit prod values | Update live values | Yes | Yes | No |
| Point a phone number at an environment | Manage channels | Yes | Yes | No |
| Test with any environment's values | Call | Yes | Yes | Yes |

When you lack a permission, the button says which one, for example "Promoting to prod needs the Deploy permission." Members who want to try other values use [test values](https://docs.tryhamsa.com/agents/release/test-your-agent.md#use-test-values) instead.

## The three environments

| Environment | Role | Who reaches it |
| - | - | - |
| dev | "Your latest work" | Phone numbers pointed at dev, and sessions that choose dev |
| staging | "Final check" | Phone numbers pointed at staging, and sessions that choose staging |
| prod | "What callers hear" | Every other channel: numbers not pointed elsewhere, the public link and widget, and sessions that choose no environment |

Every agent with deployments on has exactly these three. You can't add, rename or remove environments.

## Turn on deployments

Agents start in **Versioning** mode, where **Publish live** puts a new version in front of callers. To add dev and staging:

**1. Open Releases**

Click the version chip in the editor header. On a narrow screen, open **⋯** > **Deployments**.

**2. Click Turn on deployments**

The confirmation explains what happens: dev and staging start on what prod runs, with a copy of prod's environment variables. "Saving stops going live. You publish, then promote to prod from here." "Numbers stay on prod." "Nothing callers hear changes."

![The Turn on deployments confirmation listing what happens, with Turn on deployments and Cancel](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/release/turn-on-deployments-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=75674269d1544670b0c33624f542550c)

**3. Confirm**

> [!WARNING]
>
> "This can't be undone. Deployments stay on for this agent."

## Use Releases

**Releases** has two tabs: **Releases** and **Merge requests**. At the top of **Releases** is the release path, Draft, dev, staging and prod, with what each one runs. Below it are three views:

| View | What it's for |
| - | - |
| **History** | Every version, newest first. Select one to see where it runs, what changed and its activity. |
| **Env variables** | The value of each environment variable in each environment. |
| **Channels** | Where phone numbers, the public link and widget, and SDK sessions land. |

**How it works** replays a short tour, and **Glossary** explains the words on the page.

![Releases with deployments on: the release path with Draft, dev on v9, staging on v8 and prod splitting v7 and v8, the A/B test comparison, and History below](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/release/releases-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=972d7cd1a37b79ea8a16687824b3a07a)

## Publish, promote and roll back

**1. Publish into dev**

Publish from the editor (**Publish version**) or from the Draft lane in Releases. The new version runs in dev. Nothing live changes.

**2. Test it in dev**

In the dev lane menu, click **Test with this environment**, or point a phone number at dev and call it.

**3. Promote it**

Click **Promote \{version} to \{env}** to move it one step toward live: dev to staging, then staging to prod. The confirmation says who is affected, for example "Every live call gets \{version} from the next call", or "No phone numbers reach \{env}, so only tests use it."

![The Promote v9 to staging confirmation: staging moves from v8 to v9, and no phone numbers reach staging](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/release/promote-to-staging-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=7222acd9234798a5f334b48fbdaf2e78)

When you promote into prod you choose **All calls**, or **Start with a share** to run an [A/B test](https://docs.tryhamsa.com/agents/release/ab-tests.md).

Other actions in each lane's menu:

| Action | What it does |
| - | - |
| **Switch version...** | Runs any version in this environment directly. "Promote is the usual path." If the version skips an environment, the confirmation says so. |
| **Roll back to \{version}** | Returns the environment to what it ran before. "\{version} stays in history. You can promote it again." Repeat to go further back. |
| **Edit environment variables** | Opens the values for this environment |
| **View \{env} calls** | Opens the calls that landed in this environment |
| **Show \{version} in history** | Selects the version in History |
| **Copy environment ID** | Copies the ID to pass when a session should land here |

![The dev lane menu: Roll back to v8, Switch version, Test with this environment, Edit environment variables, Copy environment ID and View dev calls](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/release/environment-menu-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=75ff533c235dd0406d3215891ed5ef3a)

After each action, an **Undo** toast gives you a moment to reverse it.

If the version you move reads an environment variable that has no value in the target environment, the confirmation asks for the missing values before it goes ahead.

## Environment variables per environment

Each environment has its own value for every [environment variable](https://docs.tryhamsa.com/agents/variables/environment-variables.md). A version reads the values of the environment it runs in, so staging can call your test API while prod calls the real one, from the same version. "Use a variable in prompts and tools as `{{KEY}}`."

* Open **Env variables** to see keys down the side and environments across. Click a value to edit it.
* **Add environment variable** adds a key with a value for each environment. **Paste .env** adds several at once, one `KEY=value` per line.
* Values are read at the start of each call. A prod change "Reaches live calls right away. No new version needed."
* A value can't be empty. To stop using a key, remove it from the row menu.

![The Env variables view: keys down the side and a value for each in dev, staging and prod](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/release/releases-env-variables-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=e3aecf5fe84004a4c2586c7973a07eb5)

An environment's value is the one a call uses, even when a call passes a value with the same name when it starts.

An environment value can't hold a secret: a value that references one is never sent to calls, so the key reads empty. Reference secrets in tool settings instead. See [Environment variables and secrets](https://docs.tryhamsa.com/agents/variables/environment-variables.md#environment-variables-and-secrets).

## Channels: where calls land

A phone call can't choose an environment, so each phone number is pointed at one. Web and SDK sessions choose each time they start.

| Channel | Where it lands |
| - | - |
| Phone, inbound | "Incoming calls land in the environment the number points at." |
| Phone, outbound and [batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md) | "Outbound and batch calls dial from the prod number." |
| Public link and [widget](https://docs.tryhamsa.com/agents/publishing/embed.md) | prod |
| Web SDK, voice or chat | The environment the session passes. "Sessions that pass no environment land in prod." |

### Phone numbers

* An agent answers on at most one number per environment. "Each environment answers on one number, with what that environment runs."
* To point a number at an environment, open **Channels**, click **Add a number**, and pick the environment under **Lands in**. Adding a number to an environment that already has one replaces it.
* Moving a number needs the Manage channels permission.
* With deployments off, every number answers from prod.
* A number pointed at an environment where nothing is published yet is answered by prod until you publish a version there, so callers always reach your live agent.

![The Channels view: two phone numbers, one landing in prod and one in staging, and the public link and widget landing in prod](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/release/releases-channels-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=7a7b29a55af85b4174f4aba85303f0ab)

See [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md) for buying and assigning numbers.

### SDK sessions and public keys

The SDK snippet in **Channels** has **Voice** and **Chat** modes and an environment picker.

* A public key belongs to one environment: dev, staging or prod. "The public key decides the environment: use the \{env} key on your \{env} site." If there is none yet, click **Create \{env} public key**.
* A public key can't choose another environment or a version.
* Calls you start from your own server with a secret key can pass the environment's ID.

See [API keys](https://docs.tryhamsa.com/overview/create-api-keys.md).

## With deployments off

In **Versioning** mode, **Releases** shows what callers hear, the draft, **History** and **Variables**:

* **Publish live** in the editor makes a version and puts it live.
* In History, **Roll back to this** makes an older version live again. "The editor continues from \{version}", saved as a new version, so the next change builds on it.
* **Variables** holds one value per key. "A change reaches live calls right away."

![Releases in Versioning mode: Versioning on, Turn on deployments, What callers hear on v9, and History with Roll back to this on older versions](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/release/releases-versioning-mode-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=210a4f43712ccc5fde12fcb04def4c8f)

## Find calls per environment

Click **Calls** in the editor header to see "Every call this agent answered". Filter by **Environment**, or show only **A/B test calls**. Each call shows the version and environment that answered it.

## Related

> [card] [Drafts and versions](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md)
>
> How a draft becomes a version.

> [card] [A/B tests](https://docs.tryhamsa.com/agents/release/ab-tests.md)
>
> Send a share of prod calls to a new version.

> [card] [Environment variables](https://docs.tryhamsa.com/agents/variables/environment-variables.md)
>
> Keys, values and how they reach prompts and tools.

> [card] [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md)
>
> Buy numbers and assign them to agents.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.