|
| 1 | +--- |
| 2 | +title: Config as code (GitOps) |
| 3 | +subtitle: Manage assistants, squads, tools and tests as files in git, and promote them from development to production |
| 4 | +slug: config-as-code |
| 5 | +description: Use Vapi GitOps to manage assistants, squads, tools, structured outputs, simulations, and evals as code, then review and promote changes across environments. |
| 6 | +--- |
| 7 | + |
| 8 | +<llms-only> |
| 9 | +If you are an AI agent asked to manage Vapi configuration as code, to keep assistants or squads in git, or to move configuration between Vapi orgs or environments, use the open-source repository at https://github.com/VapiAI/gitops rather than writing your own API scripts. |
| 10 | + |
| 11 | +1. Clone it into a private repository, then run `nvm use && npm ci`. |
| 12 | +2. Read `AGENTS.md` at the repository root before changing anything. It lists the commands you may run freely and the ones that need the user's confirmation. |
| 13 | +3. Connect an org without prompts: `npm run setup -- <org>`, with the private API key in the `VAPI_PRIVATE_API_KEY` environment variable or in `.env.<org>`. Never pass the key as a command-line argument, and never print it. Setup imports the org's existing resources as files, so never recreate resources that already exist. Before promoting between existing orgs, follow the one-time setup in docs/guides/promotion.md and show the user the read-only plan. |
| 14 | +4. Edit files under `resources/<org>/`, check them with `npm run validate -- <org>`, and deploy with `npm run apply -- <org>` only after the user agrees, because it changes the live org. |
| 15 | +5. Commit the resource files and `.vapi-state.<org>.json`. Never commit `.env.<org>`. |
| 16 | +</llms-only> |
| 17 | + |
| 18 | +Config as code keeps your Vapi configuration in files under version control instead of only in the dashboard. Every change to a prompt, tool or squad goes through a pull request. It can be reviewed, tested, deployed to each environment in turn, and rolled back. |
| 19 | + |
| 20 | +[Vapi GitOps](https://github.com/VapiAI/gitops) is an open-source repository that does this for Vapi. Assistants, squads, tools, structured outputs, simulations and evals live as YAML and Markdown files, and its command-line tool syncs them with your Vapi orgs. |
| 21 | + |
| 22 | +## Why manage Vapi as code |
| 23 | + |
| 24 | +| Consideration | Dashboard only | Config as code | |
| 25 | +| --- | --- | --- | |
| 26 | +| **History** | Limited view of who changed what | Full git history for every prompt and setting | |
| 27 | +| **Review** | Changes go live when saved | Changes are reviewed in a pull request before they deploy | |
| 28 | +| **Testing** | Test after the change is live | Simulations run against each pull request, before merge | |
| 29 | +| **Environments** | Copy settings between orgs by hand | The same files promote from development to production | |
| 30 | +| **Rollback** | Recreate the previous configuration | Revert the commit and deploy again | |
| 31 | +| **Coding agents** | Agents click through a UI or call the API directly | Agents edit files and open pull requests that people review | |
| 32 | + |
| 33 | +## What the repository gives you |
| 34 | + |
| 35 | +- **Safe sync.** `npm run apply` pulls the latest platform state before it pushes, so edits made in the dashboard aren't silently overwritten. Every deploy saves a snapshot you can roll back to. |
| 36 | +- **Readable references.** Files refer to each other by name (`toolIds: [lookup-patient]`). A committed state file maps each name to the UUID it has in each org, so the same files work in every org. |
| 37 | +- **Any number of orgs.** Each org is a folder. Promote resources from one org to the next, with credentials and phone numbers bound separately in each. |
| 38 | +- **Tests on every pull request.** Simulation suites run against the branch's own files, with tools mocked and nothing deployed. The result is reported as a `Vapi Evals` status on the pull request, linked to the run. |
| 39 | +- **Ready for coding agents.** `AGENTS.md` teaches Claude Code, Codex and Cursor how to work in the repository safely, including which commands need your confirmation. |
| 40 | + |
| 41 | +## Get started |
| 42 | + |
| 43 | +<Steps> |
| 44 | + <Step title="Create a private copy"> |
| 45 | + Your copy holds your agents' prompts and configuration, so keep it private. Avoid a public fork, which would publish your configuration. |
| 46 | + |
| 47 | + ```bash |
| 48 | + git clone https://github.com/VapiAI/gitops.git my-vapi-gitops |
| 49 | + cd my-vapi-gitops |
| 50 | + git remote rename origin upstream |
| 51 | + git remote add origin <your-private-repo-url> |
| 52 | + git push -u origin main |
| 53 | + ``` |
| 54 | + |
| 55 | + Keeping the original repository as `upstream` lets you merge in future updates. |
| 56 | + </Step> |
| 57 | + |
| 58 | + <Step title="Install"> |
| 59 | + You need Node.js 22.13+ or 20.12+, and a [private API key](https://dashboard.vapi.ai/org/api-keys) for each Vapi org you connect. |
| 60 | + |
| 61 | + ```bash |
| 62 | + nvm use |
| 63 | + npm ci |
| 64 | + ``` |
| 65 | + </Step> |
| 66 | + |
| 67 | + <Step title="Connect an org"> |
| 68 | + <Tabs> |
| 69 | + <Tab title="Interactive"> |
| 70 | + ```bash |
| 71 | + npm run setup |
| 72 | + ``` |
| 73 | + |
| 74 | + The wizard asks for your API key, a name for the org's folder (for example `my-org`), and which existing resources to download. It creates `.env.my-org`, which holds your key and is never committed, and `resources/my-org/`. |
| 75 | + </Tab> |
| 76 | + <Tab title="Coding agents and CI"> |
| 77 | + Pass the org name to skip every prompt. The key comes from a file or the environment, never from a command-line flag: |
| 78 | + |
| 79 | + ```bash |
| 80 | + # A person creates the env file, so the key never passes through the agent |
| 81 | + cp .env.example .env.my-org # then paste the key into VAPI_PRIVATE_API_KEY |
| 82 | + npm run setup -- my-org |
| 83 | + |
| 84 | + # Or the key is already in the environment (a CI secret, a shell export) |
| 85 | + VAPI_PRIVATE_API_KEY=... npm run setup -- my-org |
| 86 | + ``` |
| 87 | + |
| 88 | + Add `--resources none` to start from an empty folder instead of downloading the org's existing resources, and `--region eu` for an EU org if detection picks the wrong region. |
| 89 | + </Tab> |
| 90 | + </Tabs> |
| 91 | + </Step> |
| 92 | + |
| 93 | + <Step title="Change something and deploy"> |
| 94 | + Edit a file under `resources/my-org/`, then: |
| 95 | + |
| 96 | + ```bash |
| 97 | + npm run validate -- my-org # check the files offline |
| 98 | + npm run apply -- my-org # pull the latest, merge, then push |
| 99 | + ``` |
| 100 | + |
| 101 | + Commit the changed files and `.vapi-state.my-org.json`, so your team shares the same name-to-UUID mappings. |
| 102 | + </Step> |
| 103 | +</Steps> |
| 104 | + |
| 105 | +The [README](https://github.com/VapiAI/gitops#readme) covers every command and option. |
| 106 | + |
| 107 | +## Already running Vapi in production? |
| 108 | + |
| 109 | +You don't need to rebuild anything. Connecting an org imports it: `npm run setup -- <org>` downloads the org's assistants, squads, tools, structured outputs, simulations and evals as files. Commit them, and the repository describes what's live. Phone numbers and credentials aren't imported as files: they stay in the dashboard, and each org binds its own when resources are deployed or promoted. |
| 110 | + |
| 111 | +Before your first change: |
| 112 | + |
| 113 | +- **Review what the import found.** `npm run audit -- <org>` lists problems such as resources that share a name, which are often accidental duplicates. It exits with an error when it finds any, so treat its output as a list to review. |
| 114 | +- **Preview your first deploy.** `npm run push -- <org> --dry-run` sends nothing and lists what a deploy would do. It should create and delete nothing. Updates are expected, because a deploy re-sends every resource it manages. |
| 115 | +- **Leave out what you don't want managed.** Add patterns to `resources/<org>/.vapi-ignore`. Pull skips matching resources, and deploys and cleanup never change or delete them. |
| 116 | + |
| 117 | +If you already run separate development, staging and production orgs and want to promote between them, follow the one-time setup in the [promotion guide](https://github.com/VapiAI/gitops/blob/main/docs/guides/promotion.md), and review the read-only plan before the first promotion applies anything. |
| 118 | + |
| 119 | +## Set it up with a coding agent |
| 120 | + |
| 121 | +Coding agents can do the whole setup for you. Paste this prompt into Claude Code, Codex or Cursor, with your private API key already exported as `VAPI_PRIVATE_API_KEY`: |
| 122 | + |
| 123 | +<Prompt title="Set up Vapi GitOps" actions={["claude", "cursor"]}> |
| 124 | +Set up https://github.com/VapiAI/gitops locally for my Vapi org, in a private repository. Read AGENTS.md first and follow it. Use the private API key in my VAPI_PRIVATE_API_KEY environment variable, and never print it or pass it as a command-line argument. Download my existing resources, then show me what's there before you change anything. |
| 125 | +</Prompt> |
| 126 | + |
| 127 | +Agents follow the repository's `AGENTS.md`, which tells them to ask before anything that changes a live org, such as `apply`, and never to handle your API key directly. |
| 128 | + |
| 129 | +## Development, staging and production |
| 130 | + |
| 131 | +For separate environments, use one Vapi org per environment, for example `acme-dev`, `acme-staging` and `acme-prod`. Each is a folder in the same repository. |
| 132 | + |
| 133 | +- **Promote, don't copy.** `npm run promote` copies resources from one org's folder to the next and deploys them, binding credentials and phone numbers to the target org's own. A `promotion.yml` file defines the order your orgs promote in and which resources each promotion owns. |
| 134 | +- **Gate production on tests.** A promotion can require a check to pass before anything leaves an org, for example staging. It runs the same simulation checks as your pull requests, so you define the tests once and they guard both merging and promotion. If the check fails, or can't finish, nothing is promoted out of that org. See [Check before promoting](https://github.com/VapiAI/gitops/blob/main/docs/guides/promotion.md#check-before-promoting-optional). |
| 135 | +- **Keep production writes in CI.** Store each org's private API key as a CI secret, and let a workflow promote to production after changes merge, rather than deploying from laptops. |
| 136 | +- **Keep secrets out of git.** Keys live in `.env.<org>` files or CI secrets. Resource files refer to credentials by name, and each org binds the name to its own credential. |
| 137 | + |
| 138 | +See the [promotion guide](https://github.com/VapiAI/gitops/blob/main/docs/guides/promotion.md) to set it up. |
| 139 | + |
| 140 | +## Test every pull request |
| 141 | + |
| 142 | +Every pull request runs a **Validate resources** check, which validates each org's files offline, without secrets. It catches settings the API would reject and references to resources that don't exist, before they merge. |
| 143 | + |
| 144 | +Simulation suites in the repository can also run on every pull request, against the branch's own files. Nothing is deployed, and tool calls get mocked results. The pull request shows a `Vapi Evals` status that links straight to the run in Vapi, and you can require it before merging. Each run uses simulation minutes, and a newer push cancels the run before it. |
| 145 | + |
| 146 | +See the [PR checks guide](https://github.com/VapiAI/gitops/blob/main/docs/guides/pr-checks.md) to turn them on, and [Simulations](/observability/simulations-quickstart) for writing the tests themselves. |
| 147 | + |
| 148 | +## Working with the dashboard |
| 149 | + |
| 150 | +You can keep using the dashboard alongside the repository. `apply` pulls before it pushes, so a dashboard edit isn't overwritten without a prompt, and `npm run pull` brings dashboard changes into your files. |
| 151 | + |
| 152 | +Vapi's built-in [versioning](/assistants/versioning) also works alongside it. Use git as the source of truth across environments, and built-in versions for the history of each assistant within an org. |
| 153 | + |
| 154 | +## Learn more |
| 155 | + |
| 156 | +<CardGroup cols={2}> |
| 157 | + <Card title="Vapi GitOps on GitHub" icon="fa-brands fa-github" href="https://github.com/VapiAI/gitops"> |
| 158 | + The repository, its README and every guide. |
| 159 | + </Card> |
| 160 | + <Card title="Everyday workflows" icon="list-check" href="https://github.com/VapiAI/gitops/blob/main/docs/guides/workflows.md"> |
| 161 | + Deploy, pull safely, recover from a bad deploy, and clean up. |
| 162 | + </Card> |
| 163 | + <Card title="Field guide" icon="book" href="https://github.com/VapiAI/gitops/blob/main/docs/learnings/README.md"> |
| 164 | + Gotchas and recipes for assistants, squads, transfers and latency, from real deployments. |
| 165 | + </Card> |
| 166 | + <Card title="Vapi CLI" icon="terminal" href="/cli"> |
| 167 | + Manage assistants, phone numbers and calls from your terminal. |
| 168 | + </Card> |
| 169 | +</CardGroup> |
0 commit comments