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

# Releases

> Cut a release from an ephemeral, a Xano branch of your workspace or a throwaway tenant, choose which table rows it carries, name it safely, and list, inspect, export and delete releases.

A **release** is a stored, named record of a backend that came up and answered on Xano's
cloud. It holds an archive of that backend, so it outlives the environment it was cut from,
and `promote v1.4.0` a week later lands exactly what was tested. `promote` and `tenant deploy`
take nothing else.

Every release is stored in **your workspace**, whatever it was cut from. `release list`,
`promote` and `tenant deploy` all read it there.

## Cut a release

Deploy to an ephemeral and run the tests, then cut the release from what is running there:

```bash theme={null}
npx xanosdk deploy ./xano/index.ts --ephemeral --test   # deploy to an ephemeral, then run its tests
npx xanosdk release create v1.4.0                        # cut from that ephemeral
```

```
  on your-instance.xano.io · workspace 3
i Workspace env: no env vars are declared and none were supplied.
  Confirming it was cut from e4f2-9ab1
✓ Cut release v1.4.0
  from ephemeral:e4f2-9ab1
  Carries no table rows — every table's schema and logic is included.
```

`--test` exits `5` if a test fails and `6` if the tests cannot be reached. The deploy stays in
place either way, so check the exit code before you cut.

With no `--from`, `release create` cuts from the backend this project last deployed to. If you
deployed to the Xano Engine since, name the ephemeral: `release create v1.4.0 --from ephemeral`.
A release cannot be cut from the Engine; see
[where the Engine differs today](/run/xano-engine#where-the-engine-differs-today).

Cutting reads the source and writes nothing to it, so the ephemeral expiring later takes
nothing with it. The cut also compares the source against a compile of your project and names
every object that differs. The release carries what is **running**, not what is on your disk,
so read that list before you promote.

## Choose the source

| `--from` | Cuts from |
| - | - |
| `ephemeral` | This project's ephemeral. `ephemeral:<name>` names another one. |
| `workspace` | The live Xano branch of your workspace. Add `--branch <label>` for another Xano branch. |
| `tenant:<name>` | A tenant, only when it is a throwaway one (an `ephemeral` or `sandbox` tenant). A `standard` or `run` tenant is a live deployment and is refused. |

To start from what a live tenant runs, pull it into the project, deploy that to an ephemeral,
and cut from there:

```bash theme={null}
npx xanosdk pull tenant:prod
npx xanosdk deploy ./xano/index.ts --ephemeral --test
npx xanosdk release create v1.4.1
```

## When ephemerals are off: stage on a Xano branch

Some instances have ephemerals turned off, and `deploy --ephemeral` says so. There, stage the
build on a new Xano branch of your workspace and cut the release from that branch:

```bash theme={null}
npx xanosdk deploy ./xano/index.ts --to workspace --branch staging --dry-run   # preview against a new Xano branch
npx xanosdk deploy ./xano/index.ts --to workspace --branch staging             # deploy to the Xano branch "staging"
npx xanosdk release create v1.4.0 --from workspace --branch staging            # cut from that Xano branch
npx xanosdk workspace branch delete staging                                    # optional: clear the label for next time
```

`deploy --to workspace --branch` creates the Xano branch as a copy of live and lands your build
there. The live Xano branch keeps serving. Know three things about this path:

* **The label must be new.** A label that already exists is refused (`SDK_BRANCH_TAKEN`,
  exit `2`). Delete the staging Xano branch after you cut, or use one label per release
  (`staging-v1.4.0`).
* **Table changes reach live at this step**, not at promote, because every Xano branch shares
  the same tables. The deploy refuses a table change (`SDK_SHARED_SCHEMA_CHANGE`) until you pass
  `--allow-shared-schema-changes`. See [Where code goes](/ship/where-code-goes#tables-are-shared-by-every-xano-branch).
* **`--test` is not available** beside `--to`. Run your tests on the Engine before you stage.
* **The release carries everything that branch runs**, not only your project: the Xano branch
  starts as a copy of live, so objects live already serves ride along. `release create` lists
  what differs from your project before it cuts.

## What a release carries

Every table's **schema**, always. A release cut with no flags has every table in it.

Table **rows** only when you ask. List the source's tables with their guids, then pass the guids
of the tables whose rows should ride along:

```bash theme={null}
npx xanosdk tables                                       # the tables of the backend you last deployed to
npx xanosdk tables workspace                             # ...or name the source you are cutting from
npx xanosdk release create v1.4.0 --seed                 # every table's rows
npx xanosdk release create v1.4.0 --seed=<guid>,<guid>   # only these tables' rows
```

List from the backend you are cutting from: a guid read off another backend is not proof of the
same table. Selection is by guid because a guid that does not match is refused before anything
is cut, where a stale id would silently select a different table. When a selected table has a
non-public column, the cut names it and asks first (`--yes` answers in advance).

Two things a release never carries:

* **File bytes.** A file column's value and an MCP icon declared with `hostedFile()` point into
  the source's file library, and the release would copy the pointer without the file. So
  `release create` refuses a cut whose source serves `hostedFile()` icons, or whose `--seed`
  selects a table with a file column while the source holds files
  (`SDK_RELEASE_FILES_NOT_CARRIED`, exit `2`). Land a project like that with a direct deploy,
  which ships its files: `npx xanosdk deploy ./xano/index.ts --to tenant:prod --seed`. See
  [Tenants](/ship/tenants#projects-with-files).
* **Env values.** A landing adds names the target lacks and never overwrites a value it holds.
  See [Env and secrets](/build/env-and-secrets).

Seeded password columns carry hashes, and each environment hashes with its own key. Logins
against those rows work only on the environment the release was cut from.

## Name a release

A name is used once. A name that is taken is refused (`SDK_RELEASE_NAME_TAKEN`, exit `2`),
because a tenant may be running the release that holds it. Cut a new name, such as `v1.4.1`.

**After exit `9`, read before you retry.** Exit `9` means the cut was sent and the answer was
lost (a timeout, a dropped connection, a server error). The release may exist. The platform
stores a write under a taken name with a dash and four hex characters added (`v1.4.0-a019`)
rather than refusing it, so a blind retry can leave two releases. List first:

```bash theme={null}
npx xanosdk release list
```

Look for `v1.4.0`, or `v1.4.0-` plus four hex characters, created after the run started. If the
server stored your cut under a suffixed name, `release create` refuses rather than reporting
success, and prints the `release delete` that removes the stray copy. The run's `--json`
document names the read to run (`resolveWith`) and the earliest time an "absent" answer is
proof (`resolveNotBefore`). [Exit codes and outcomes](/help/exit-codes-and-outcomes) covers
every code.

## Manage releases

| Command | What it does |
| - | - |
| `npx xanosdk release list` | Every release in your workspace. |
| `npx xanosdk release show v1.4.0` | One release: where it was cut from, and which tables' rows it carries. |
| `npx xanosdk release export v1.4.0 --path ./releases` | Writes the release out as XanoScript. `--path -` writes to stdout. |
| `npx xanosdk release delete v1.4.0` | Removes the release. Anything running it keeps running. `--yes` skips the prompt. |

To bring a release's code back into your project, use `npx xanosdk pull release:v1.4.0`.

## Next

[Promote and go live](/ship/promote-and-go-live): land the release on your workspace and serve
it.


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