GitHub y ramas

Cuando un agente ya está en live, cámbialo en una rama. Cada rama de git es un entorno propio, con su agente, el conocimiento que cambió, sus valores de secretos y sus chats, y nada de lo que hagas ahí llega a live ni a otra rama. Hacer merge de su pull request lo publica: el prompt y el conocimiento con el que se probó llegan a live juntos.

Eso es lo que permite que varias personas, o varios coding agents, arreglen varias conversaciones a la vez sin que sus cambios se crucen antes del merge.

El flujo

git worktree add ../fix-pagos -b fix/pagos   # un worktree por cambio
cd ../fix-pagos
$EDITOR vatio.yml                            # cambia el prompt o las tools
vatio push                                   # → entorno fix-pagos
vatio kb write docs pagos pagos.md           # conocimiento, solo en esta rama
vatio chat "¿Puedo pagar por transferencia?" # pruébalo
vatio env                                    # token, enlace para probar, cambios de conocimiento
git commit -am "Explica los medios de pago" && git push -u origin fix/pagos
gh pr create                                 # el pull request se despliega en fix-pagos

Haz merge del pull request cuando esté bien. Live recibe el prompt nuevo y la entrada pagos en el mismo paso, y el entorno de la rama se elimina.

Entornos por rama

Un workspace en una rama de git que no es la principal trabaja en el entorno de esa rama sin --env: fix/pagos pasa a ser fix-pagos. Todos los comandos lo usan —push, chat, kb write, secrets set, tokens, publish— y avisan cuál en stderr.

En la rama principal, y fuera de un repositorio de git, los comandos usan sus valores por defecto de siempre (preview para push y chat, live para tokens). --env NAME siempre gana. Los nombres usan minúsculas y dígitos separados por guiones o guiones bajos, hasta 40 caracteres.

Un entorno guarda solo lo que cambió y lee todo lo demás de live:

• El agente con el que se hizo push.
• Las entradas de conocimiento que escribió, encima de live. Las entradas que lee un sitio no se cambian en ramas. Ver Conocimiento.
• Valores de secretos definidos solo para él, como la URL de una API de staging. Ver Secretos.
• Chats, contactos y tokens propios, que se van con él.

vatio env list y la página Environments de la consola muestran todos los entornos.

Apunta todos los canales a una rama

Así una rama se prueba como la van a usar los visitantes:

Superficie	Cómo apunta a un entorno
CLI	La rama en la que estás, o --env NAME
Widget y SDKs	El token publicable de ese entorno (vatio env lo imprime)
Sandbox de WhatsApp	Cada teléfono de prueba: vatio whatsapp numbers point PHONE --env NAME
Sandbox de Instagram	Cada cuenta de prueba: vatio instagram accounts point ID --env NAME
Su página	https://vatio.ai/w/<slug>/<entorno>, para los miembros del workspace

Los teléfonos y cuentas de prueba apuntan a preview por defecto, pueden apuntar a cualquier entorno desplegado pero nunca a live, y vuelven a preview cuando se elimina el suyo. Una tool corre en los servidores de Vatio y no llega a localhost: para probar contra un backend en tu máquina, expónlo con un túnel y define esa URL como secreto de la rama.

Conecta un repositorio

Instala la GitHub App de Vatio y vincula un repositorio al workspace en la página Environments de la consola. El dueño del workspace elige este vínculo, y el vatio.yml del repositorio tiene que nombrar el mismo workspace. Define el directorio del workspace si el repositorio tiene más de un vatio.yml: un agente puede vivir en el repositorio del backend que llama.

Evento	Qué hace Vatio
Pull request abierto, actualizado o reabierto	Lo despliega en el entorno de su rama y comenta con el enlace para probarlo y sus cambios de conocimiento, si cambió el directorio del workspace
Push a la rama principal	Despliega y publica en live, con los cambios de conocimiento del pull request que se mergeó
Pull request mergeado	Publica los cambios de conocimiento que hayan quedado y elimina el entorno
Pull request cerrado sin merge	Elimina el entorno

Un pull request se despliega en el mismo entorno que usa vatio push en su rama, así que lo que se probó ahí antes de abrirlo sigue ahí. Los pull requests desde forks no se despliegan: su vatio.yml elegiría a dónde se envían los secretos del workspace.

Con GitHub conectado, live solo cambia al hacer merge a la rama principal. vatio publish y el botón de publicar de la consola se rechazan, igual que vatio push --env main. vatio push a preview o al entorno de una rama sigue funcionando, y vatio rollback queda como botón de emergencia.

Estados en cada commit

Vatio publica un estado en los commits sobre los que actúa, con el workspace entre paréntesis:

Estado	Indica
vatio/preview (slug)	Si se desplegó el entorno del pull request, con enlace a su pantalla para probar
vatio/knowledge (slug)	Si sus cambios de conocimiento todavía pueden llegar a live, con enlace a su diff de conocimiento
vatio/live (slug)	Si el merge llegó a live

Cuando dos merges terminan en desorden, el más viejo nunca reemplaza a uno más nuevo que ya está en live.

Recomendado: haz obligatorio vatio/knowledge

vatio/knowledge se pone en rojo cuando live cambió una entrada que la rama también cambió: otra rama hizo merge primero, o un supervisor la corrigió en el inbox. Hazlo un check obligatorio para que GitHub lo espere antes del merge:

1. En el repositorio, abre Settings → Rules → Rulesets → New branch ruleset (o Settings → Branches → Add branch protection rule).
2. Elige la rama principal como destino.
3. Activa Require status checks to pass y agrega vatio/knowledge (slug-de-tu-workspace).

GitHub solo ofrece un check en esa lista después de verlo una vez, así que primero abre un pull request que Vatio despliegue. Si la rama principal ya tiene una regla de protección, también puedes agregarlo con la CLI de GitHub:

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

Sin el check obligatorio no se pierde nada, pero el merge se adelanta a live. Un pull request con vatio/knowledge en rojo se puede mergear igual; Vatio entonces se niega a publicarlo —el prompt y el conocimiento de live quedan como estaban—, marca en rojo el vatio/live del commit y comenta en el pull request. El entorno se conserva hasta que resuelvas el conflicto y publiques su conocimiento con vatio kb publish. Mientras tanto, la rama principal tiene código que live no corre. El check obligatorio evita ese desfase, y importa sobre todo cuando varias personas o agentes hacen merge.

Resolver un conflicto de conocimiento

El enlace del estado abre el diff de conocimiento del entorno en la consola. Para cada entrada en conflicto muestra lo que cambió live y lo que cambió la rama, y lo resuelve ahí mismo: conservar la versión de la rama, usar la de live, o combinar las dos a mano. Desde la terminal, lee la entrada de live y escribe tu cambio encima:

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

De cualquiera de las dos formas, el estado pasa a verde cuando no queda nada por resolver.

Sin GitHub

Las ramas funcionan igual: todos los comandos usan el entorno de la rama. vatio publish desde la rama publica su agente y su conocimiento juntos, y se rechaza mientras quede un conflicto. Nada elimina un entorno cuando terminas, salvo vatio env rm NAME o la limpieza de abajo.

Limpieza

Un entorno sin cambios de conocimiento pendientes de publicar se elimina tras 14 días sin un push, una escritura de conocimiento ni un cambio de secreto, y cuando se cierra su pull request. Uno con conocimiento sin publicar se conserva sin importar su antigüedad. vatio env rm NAME elimina uno ahora, con sus chats, contactos, tokens, conocimiento sin publicar y valores de secretos.