# AI Gateway Source Control

Every AI Gateway project is backed by a Git repository that you own. The
repository contains the gateway's routes and policy declarations, so gateway
changes go through your normal review workflow, and custom policies are plain
TypeScript files you commit alongside them.

## Connecting a repository

A new AI Gateway project must be connected to a repository before it can deploy.
Zuplo supports GitHub, GitLab, Bitbucket, and Azure DevOps—see
[Source Control and Deployment](../concepts/source-control-and-deployment.mdx)
for what each provider supports.

The project shows a **Let's Get You Deployed** screen with two options:

- **Create New Repo** starts a new repository with the name prefilled. With
  GitHub, this opens GitHub directly; create the repository, then return to the
  portal to connect it.
- Connect an existing repository. Use an empty one so the gateway's source has
  the repository to itself.

When you connect, Zuplo adds the gateway's source to the repository, pushes it,
and starts the first production deployment.

:::note

If your default branch requires pull requests, Zuplo pushes the gateway source
to a setup branch and surfaces a pull request for you to merge. The first
deployment starts once the pull request lands on the default branch.

:::

## What the repository contains

The scaffolded gateway is a small, readable Zuplo project:

| File                   | Purpose                                                                         |
| ---------------------- | ------------------------------------------------------------------------------- |
| `config/ai.oas.json`   | The gateway's route, which the AI Gateway handler serves                        |
| `config/policies.json` | The menu of policies apps can add to their [policy chains](./policy-chains.mdx) |
| `zuplo.jsonc`          | Project configuration                                                           |
| `env.example`          | Example environment variables                                                   |
| `tsconfig.json`        | TypeScript configuration for custom policy modules                              |

Add custom policy modules under `modules/` and declare them in
`config/policies.json`—see [Custom Policies](./custom-policies.mdx).

## How deployments work

The repository's default branch is what production runs. With GitHub, every push
to it deploys automatically. With GitLab, Bitbucket, and Azure DevOps, your own
CI/CD pipeline deploys by calling `zuplo deploy`—see
[Source Control and Deployment](../concepts/source-control-and-deployment.mdx).

There is no in-portal code editor for AI Gateway projects—the repository is the
source of truth, and you edit it with your normal tools.

Three categories of changes take effect differently:

| Change                                                            | Takes effect                                         |
| ----------------------------------------------------------------- | ---------------------------------------------------- |
| Repository changes (routes, `policies.json`, custom policy code)  | On the next deploy of the default branch             |
| App policy chains, teams, budgets, and templates (portal changes) | Within about a minute, no deploy needed              |
| Provider settings and environment variables                       | Automatically, via a rebuild and deploy Zuplo starts |

:::note

Provider API keys are stored as
[environment variables](../articles/environment-variables.mdx), so saving
provider settings or environment variables triggers an automatic production
deployment.

:::

## Next steps

- [Policy Chains](./policy-chains.mdx): how apps select policies from
  `config/policies.json`
- [Custom Policies](./custom-policies.mdx): add your own policy to the
  repository