GitHub and branches

Once an agent is live, change it on a branch. Every git branch is an environment of its own — its agent, the knowledge it changed, its secret values, its chats — and nothing done there reaches live or another branch. Merging its pull request publishes it: the prompt and the knowledge it was tried with go live together.

That is what lets several people, or several coding agents, fix several conversations at once without their changes meeting before they merge.

The workflow

git worktree add ../fix-pagos -b fix/pagos   # a worktree per change
cd ../fix-pagos
$EDITOR vatio.yml                            # change the prompt or the tools
vatio push                                   # → environment fix-pagos
vatio kb write docs pagos pagos.md           # knowledge, only on this branch
vatio chat "¿Puedo pagar por transferencia?" # try it
vatio env                                    # token, test link, knowledge changes
git commit -am "Explain payment methods" && git push -u origin fix/pagos
gh pr create                                 # the pull request deploys to fix-pagos

Merge the pull request when it is right. Live gets the new prompt and the pagos entry in the same step; the branch's environment is removed.

Branch environments

A workspace checked out on a git branch other than the default one works in that branch's environment without --env: fix/pagos becomes fix-pagos. Every command uses it — push, chat, kb write, secrets set, tokens, publish — and prints which one on stderr.

On the default branch, and outside a git repository, commands keep their usual defaults (preview for push and chat, live for tokens). --env NAME always wins. Names use lowercase letters and digits separated by hyphens or underscores, up to 40 characters.

An environment holds only what it changed and reads everything else from live:

• The agent it was pushed with.
• Knowledge entries it wrote, on top of live. Entries a site reads are not changed on branches. See Knowledge.
• Secret values set only for it, such as a staging API URL. See Secrets.
• Chats, contacts and tokens of its own, which go with it.

vatio env list and the Environments page in the console show every environment.

Point every channel at a branch

So a branch is tried the way visitors will use it:

Surface	How it points at an environment
CLI	The branch you are on, or --env NAME
Widget and SDKs	That environment's publishable token (vatio env prints it)
WhatsApp sandbox	Each test phone: vatio whatsapp numbers point PHONE --env NAME
Instagram sandbox	Each test account: vatio instagram accounts point ID --env NAME
Its page	https://vatio.ai/w/<slug>/<environment>, for the workspace's members

Test phones and accounts default to preview, can point at any deployed environment but never live, and go back to preview when theirs is removed. A tool runs on Vatio's servers and cannot reach localhost: to test against a backend on your machine, expose it through a tunnel and set that URL as the branch's secret.

Connect a repository

Install the Vatio GitHub App and bind a repository to the workspace on the Environments page in the console. The workspace owner chooses this binding, and a repository's vatio.yml must name the same workspace. Set the workspace directory if the repository holds more than one vatio.yml — an agent can live in the repository of the backend it calls.

Event	What Vatio does
Pull request opened, updated or reopened	Deploys it to its branch's environment and comments with the test link and its knowledge changes, when the workspace directory changed
Push to the default branch	Deploys and publishes to live, with the merged pull request's knowledge changes
Pull request merged	Publishes any knowledge change still left, then removes the environment
Pull request closed without merging	Removes the environment

A pull request deploys to the same environment vatio push uses on its branch, so whatever was tried there before the pull request existed is still there. Pull requests from forks are not deployed: their vatio.yml would choose where the workspace's secrets are sent.

With GitHub connected, live changes only by merging to the default branch. vatio publish and the console's publish button are refused, and so is vatio push --env main. vatio push to preview or a branch's environment still works, and vatio rollback remains the emergency button.

Statuses on each commit

Vatio posts a status on the commits it acts on, with the workspace in parentheses:

Status	Says
vatio/preview (slug)	Whether the pull request's environment deployed, linking to its test screen
vatio/knowledge (slug)	Whether its knowledge changes can still go live, linking to its knowledge diff
vatio/live (slug)	Whether the merge reached live

When two merges finish out of order, the older one never replaces a newer one that is already live.

Recommended: require vatio/knowledge

vatio/knowledge turns red when live changed an entry the branch also changed — another branch merged first, or a supervisor fixed it in the inbox. Make it a required check so GitHub waits for it before merging:

1. In the repository, open Settings → Rules → Rulesets → New branch ruleset (or Settings → Branches → Add branch protection rule).
2. Target the default branch.
3. Turn on Require status checks to pass and add vatio/knowledge (your-workspace-slug).

GitHub offers a check in that list only after it has seen it once, so open a pull request that Vatio deploys first. With the rule already in place on the default branch, the GitHub CLI adds it too:

gh api -X POST repos/OWNER/REPO/branches/main/protection/required_status_checks/contexts \
  -f 'contexts[]=vatio/knowledge (your-workspace-slug)'

Without it, nothing is lost, but the merge runs ahead of live. A pull request with a red vatio/knowledge can still be merged; Vatio then refuses to publish it — the prompt and the knowledge stay as they were on live — marks the commit's vatio/live red and comments on the pull request. The environment is kept until you resolve the conflict and publish its knowledge with vatio kb publish. Until then the default branch holds code live does not run. Requiring the check avoids that gap, which matters most when several people or agents merge.

Resolving a knowledge conflict

The status's link opens the environment's knowledge diff in the console. For each conflicting entry it shows what live changed and what the branch changed, and resolves it in place: keep the branch's version, take live's, or combine both by hand. From the terminal, read the entry from live and write your change on top:

vatio kb cat docs pagos --env live > pagos.md
$EDITOR pagos.md
vatio kb write docs pagos pagos.md

Either way the status turns green once nothing is left to resolve.

Without GitHub

Branches work the same: every command uses the branch's environment. vatio publish from the branch publishes its agent and its knowledge together, and is refused while a conflict is left. Nothing removes an environment when you finish, other than vatio env rm NAME or the cleanup below.

Cleanup

An environment with no knowledge changes left unpublished is removed after 14 days without a push, a knowledge write or a secret change, and when its pull request closes. One with unpublished knowledge is kept however old it is. vatio env rm NAME removes one now, with its chats, contacts, tokens, unpublished knowledge and secret values.