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

# Workspace is the truth

> The flow for a team that lives in Xano: take a copy, work on it against an ephemeral, push it back as a branch, and promote the branch — which is the merge.

<Warning>
  **Branch releases are still in development.** The commands on this page — `xanots release --branch`, `--backup-branch`, and `xanots workspace branch …` — are built and tested, but the
  instance-side support they need is still rolling out. They are deliberately not listed in
  `xanots help` or shell completion yet, and on an instance without support a branch release
  **refuses outright rather than writing to your live branch**.

  Read this page to understand the model and plan for it; check with us before adopting it as
  your team's process. If you need a workflow you can rely on today, use
  [Repo is the truth](/guides/workflow-repo).
</Warning>

The workspace is authoritative. Nobody keeps a long-lived repo; a working copy is a folder you
delete when you are done. This is the arrangement that works when **not everyone writes
code** — a no-code builder user cannot open a pull request, but they can work on a branch.

Everyone — whether they write TypeScript, read XanoScript, or build in the Xano UI — does the
same four things:

1. **Take a copy** of what is live.
2. **Work on it**, trying it out on a disposable ephemeral.
3. **Push it back as a branch**, which stages it without serving it.
4. **Promote the branch**, which is the merge.

The whole team meets at the same place — a branch, promoted to live. That is why this
arrangement works and a mixed git/UI one does not.

<Note>
  New here? Read [Development workflows](/guides/development-workflows) first — it covers the
  choice between this and letting your repo be authoritative.
</Note>

## Before anything else: what a branch isolates

<Warning>
  **Branches scope logic, not data.** Tables and microservices are **shared by every branch** of
  the workspace. So a release that adds or drops a column reaches production the moment it
  lands, even on a branch.

  Read [the full explanation and the refusal message](/guides/development-workflows#what-a-xano-branch-actually-isolates)
  before your first `release --branch`. It is the one thing on this page that can lose data.
</Warning>

## The TypeScript developer, and the XanoScript developer

One flow, two artifacts. No repo — the working copy is disposable.

<Steps>
  <Step title="Pull the live branch">
    ```bash theme={null}
    xanots init orders-work --from workspace
    cd orders-work
    ```

    The pull preserves each object's `guid`, so what you push back matches in place rather
    than duplicating. `xano/README.md` lists anything that did not translate cleanly — read it
    before you start editing.
  </Step>

  <Step title="Work on it against an ephemeral">
    ```bash theme={null}
    # edit xano/…
    xanots deploy ./xano/index.ts        # → a disposable environment with its own URL
    xanots test run-all
    ```

    Nothing here can reach production. Deploy as many times as you like.

    Reading XanoScript rather than TypeScript? The deployed ephemeral exports as a multidoc:

    ```bash theme={null}
    xanots ephemeral export <tenant> --format multidoc --name backend   # → backend.xs
    ```
  </Step>

  <Step title="Push it back as a branch">
    ```bash theme={null}
    xanots release ./xano/index.ts --branch orders --backup-branch
    ```

    Nothing serves `orders` yet — the live branch is untouched. `--backup-branch` snapshots the
    live branch's logic first, so the promote in the next step has something to go back to.

    The release refuses outright unless the instance confirms it planned against the branch you
    named, so an instance without branch support fails closed instead of overwriting
    production.
  </Step>

  <Step title="Review it in the builder">
    Open the branch in Xano and click through it. **This is the review step** — there is no
    diff to read, so someone has to look.
  </Step>

  <Step title="Promote — this is the merge">
    ```bash theme={null}
    xanots workspace branch list                    # which one is live right now?
    xanots workspace branch set-live orders
    ```

    A production cutover: the runtime stops serving the old branch and starts serving this one.
    Table data is unaffected either way, because it was always shared. The CLI names the
    outgoing branch and prompts before doing it (`--yes` in a script).
  </Step>

  <Step title="Clean up">
    ```bash theme={null}
    cd .. && rm -rf orders-work
    xanots workspace branch delete <old-branch> --yes
    ```

    Keep the branch you just replaced until you are confident — it is your rollback. The live
    branch cannot be deleted; promote another one first.
  </Step>
</Steps>

## The builder developer

Someone building in the Xano no-code UI does steps 1, 2 and 3 **in the builder itself**: they
work on a branch in Xano rather than on the live one, and click through it there. They never
pull, never install anything, and never touch an ephemeral.

Then the last step is identical, from the builder or the CLI:

```bash theme={null}
xanots workspace branch list
xanots workspace branch set-live their-branch
```

## Working at the same time as someone else

There is no merge tool here, so the discipline is to **avoid the merge instead of resolving
one**. Three rules that keep a team out of trouble:

* **One branch per change, named for the change** — `orders`, `billing-webhooks`. Not per
  person, and not long-lived.
* **Promote soon after you branch.** A branch that sits for a week diverges from the live one,
  and there is nothing that will tell you it has.
* **Two people staging changes to the same object at once will lose one of them.** The second
  `release --branch` writes the whole object, not a merge of the two. Split the work by object,
  or take turns.

<Tip>
  Re-pull before you start each piece of work — `xanots init <fresh-dir> --from workspace` — so
  your copy starts from what is actually live rather than from what was live last time you
  looked.
</Tip>

## Rolling back

The branch you replaced is still there, so undoing a promote is one command:

```bash theme={null}
xanots workspace branch set-live <previous>
```

<Warning>
  That restores **logic**. It does not restore tables, because tables were never on a branch — a
  dropped column is gone from every branch at once, and no promote brings it back. Read the
  shared-schema report *before* you release, not after.
</Warning>

<Note>
  `v1` is the label every workspace starts with, and it is reserved — `--branch v1` is refused
  rather than silently writing to whatever is live. Pick your own labels.
</Note>

## Moving to a repo later

If everyone ends up writing code, this workspace can become repo-authoritative. That is a
one-way door and it has a required step — capturing the engine's random guids — before your
first release. See [day one of the repo flow](/guides/workflow-repo#day-one).