Skip to main content
The console is great for building and trying things. For anything that runs in production, keep the definitions in git and deploy them with a script. You get review, history, the same setup in every environment, and an easy rollback.

What to keep in git

Leave environment-specific ids out of the files. Write placeholders such as {{function:decide_order}} in workflows and let the deploy script fill in the ids for the app it deploys to.

What the script should do

Every step is idempotent: matched by name, created if missing, updated if present. Running it twice does no harm. Order matters: configurations, queries and functions first, because workflows refer to them; agents before the workflows that reference them; chatbots last.
A new workflow or agent version is not used until it is promoted. A deploy script that saves new versions without promoting them deploys nothing.

A reference script

deploy.py

Good practice

  • A dedicated deploy user. Signing in ends a user’s other sessions; never deploy with a person’s account. Keep its credentials in your CI secrets, never in the repository.
  • One namespace per product area, so a deploy only touches what it owns.
  • Deploy to staging first, run a test case end to end, then deploy the same commit to production.
  • Roll back by promoting the previous workflow version (PATCH …/current-version?version=<previous>), or by deploying the previous commit. Functions have no versions, so redeploy the previous commit for those.
  • Keep test cases in git next to the workflow (sample inputs and the expected outcome), and run them after each deploy.