Skip to main content
The rest of these guides are organized by concept. This page is organized by situation — find yours, do the three or four things it names, and skip everything else until you need it.

Building something new

Alone, from an empty folder.

Joining a team

The repo and the workspace already exist.

Migrating a workspace

Built in the UI, and you want it as code.

New to git

Read this before the team pages.

​
Building something new

Working alone, nothing exists yet. You can ignore almost everything — no branches, no pull requests, no CI.
1

Get something live

Follow the Quickstart — four commands, and you have a running backend and frontend.
2

Learn the two-command loop

xanots deploy pushes to a disposable ephemeral you can break freely. xanots release promotes to your real workspace. Iterate on the first; use the second when you mean it.
3

Form one habit

xanots release --dry-run before any real release. It prints exactly what would change and sends nothing — including any table column your code no longer defines, which takes its data with it.
Come back for: Working outside git when you first edit something in the Xano builder, and Git, locks & merges when a second person joins.
You do not need branches or pull requests to use XanoTS alone. Committing straight to main is a legitimate way to work — most of what the team pages describe exists to solve problems you do not have yet.

​
Joining a team

The repo exists and so does the workspace. The one thing to establish before you touch anything:
1

Ask where the truth lives

The repo, or the workspace? It decides how you contribute, what review means, and what a merge is. Development workflows explains both in two minutes.If nobody knows, look: a committed xano.lock and a CI job running xanots release means the repo is authoritative.
2

Read your team's flow, not both

Repo is the truth — you work in git and open pull requests.Workspace is the truth — you pull a copy, push it back as a Xano branch, and promoting the branch is the merge. Still in development, so most teams are on the first one today.
3

Sign in and confirm where you are pointed

One credential addresses exactly one workspace — there is no --workspace flag.
4

Deploy to your own ephemeral before anything else

Everyone gets their own, so this cannot affect a teammate or production. It is the safest possible first command.
Then read the PR review checklist — it covers the things a normal code review misses, which is most of what a XanoTS reviewer needs to know.

​
Migrating an existing workspace

You built it in the UI and want it as code. One step here is irreversible if you skip it, so do these in order.
1

Pull it down

2

Read two files before you go further

xano/README.md lists anything that did not translate cleanly. xano/workspace.ts carries your environment variable values inline — move real secrets out before that commit reaches a shared repo.
3

Capture the identities — do not skip this

The engine gave your existing objects random identities, and nothing in your code can re-derive them. Without this step your first release matches nothing and duplicates every object instead of updating it.
4

Decide what the workspace is now

Repo is the truth is the flow to use today, and it works even if some people still edit in the Xano builder — those edits get pulled back into git rather than lost.Workspace is the truth is the better long-term fit for a builder-led team, but the branch releases it depends on are still in development. Read it to plan for it; do not adopt it as your process yet.
Full detail: Pulling an existing workspace.

​
New to git

XanoTS does not require git — you can deploy and release without ever making a commit, and building something new above works fine that way. You need git the moment a second person is involved, because it is how two people change the same thing without overwriting each other.
1

Learn the eight commands

Git, locks & merges opens with a collapsible primer covering exactly the commands these flows use, what a branch is, and how a pull request works — plus both the GitHub and GitLab CLIs.
2

Then learn the one XanoTS-specific part

Same page: xano.lock is a file XanoTS maintains that pins your objects’ identities. You commit it like any other file, and the only unusual thing is what to do when it conflicts (take both sides, re-run xanots export).
For git itself, the GitHub “Hello World” guide is ten minutes and Learn Git Branching teaches the branch model interactively.

​
When something breaks

Troubleshooting maps the CLI’s refusals and exit codes to causes and fixes. Two worth knowing before you need them:
  • A release that refuses is protecting you. Dropped columns, unscoped prunes and unreadable workspaces all stop and ask rather than proceeding.
  • A rollback is just releasing an earlier commit — but it does not bring back data from a dropped column. See when a release goes wrong.

​
Unfamiliar word?

Glossary — instance vs workspace vs environment, ephemeral vs branch, deploy vs release, bundle, guid, canonical, and the pairs that are easy to confuse.