Skip to main content
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.
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.
New here? Read Development workflows first — it covers the choice between this and letting your repo be authoritative.

​
Before anything else: what a branch isolates

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 before your first release --branch. It is the one thing on this page that can lose data.

​
The TypeScript developer, and the XanoScript developer

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

Pull the live branch

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.
2

Work on it against an ephemeral

Nothing here can reach production. Deploy as many times as you like.Reading XanoScript rather than TypeScript? The deployed ephemeral exports as a multidoc:
3

Push it back as a 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.
4

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.
5

Promote — this is the merge

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).
6

Clean up

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

​
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:

​
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.
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.

​
Rolling back

The branch you replaced is still there, so undoing a promote is one command:
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.
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.

​
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.