# Branch-Based Deployments

Zuplo uses a branch-based deployment model that automatically maps Git branches
to environments. This GitOps approach allows teams to manage API deployments
using familiar version control workflows.

## How Branch-Based Deployments Work

When you connect your Zuplo project to a Git repository (GitHub, GitLab,
Bitbucket, or Azure DevOps), Zuplo automatically deploys your API whenever
changes are pushed to a branch. The deployment model follows these rules:

1. **One branch = One environment**: Each Git branch creates a corresponding
   Zuplo environment
2. **Default branch = Production**: The repository's default branch (typically
   `main` or `master`) deploys to the **Production** environment
3. **All other branches = Preview**: Any branch that's not the default branch
   deploys to a **Preview** environment

```
Git Repository                    Zuplo Environments
─────────────────                 ──────────────────
main          ─────────────────►  Production (main)
staging       ─────────────────►  Preview (staging)
feature/auth  ─────────────────►  Preview (feature/auth)
bugfix/123    ─────────────────►  Preview (bugfix/123)
```

## Environment Names and URLs

When Zuplo deploys an environment from a branch, the environment name matches
the branch name. For example:

| Branch Name    | Environment Name | Example URL                                         |
| -------------- | ---------------- | --------------------------------------------------- |
| `main`         | main             | `https://my-project-main-abc1234.zuplo.app`         |
| `staging`      | staging          | `https://my-project-staging-def5678.zuplo.app`      |
| `feature/auth` | feature/auth     | `https://my-project-feature-auth-ghi9012.zuplo.app` |

:::note

The environment URL includes a unique identifier to ensure each deployment has a
distinct address. Configure [custom domains](./custom-domains.mdx) for your
environments.

:::

## Production vs Preview Environments

### What Determines the Production Environment

The **Production** environment is determined by your repository's **default
branch** setting. This is configured in your Git provider (GitHub, GitLab,
etc.), not in Zuplo. When you change your repository's default branch, Zuplo
automatically treats the new default branch as Production.

To change which branch is your Production environment:

1. Go to your Git repository settings (for example, GitHub > Settings >
   General > Default branch)
2. Change the default branch to your desired branch
3. Zuplo will now treat deployments from this branch as Production

### Technical Differences

There is **no technical difference** between Production and Preview
environments. Both:

- Have identical performance characteristics
- Support all Zuplo features
- Run on the same infrastructure

The distinction is primarily for:

- **Environment variable management**: You can set different values for
  Production vs Preview environments
- **API key buckets**: Production and Preview environments use separate API key
  buckets by default
- **Organization**: Helps teams distinguish between live and test deployments

### Using Preview Environments as Production

Some customers choose to use Preview environments as additional "production"
deployments. For example, you might have:

- `main` → Production (US customers)
- `eu-production` → Preview, but serving EU customers
- `staging` → Preview for testing

This works because Preview environments have identical capabilities to
Production. You can override
[environment variables](./environment-variables.mdx) and
[API key buckets](./api-key-buckets.mdx) for specific Preview environments to
support this pattern.

## Creating New Environments

Creating a new environment is as simple as creating a new Git branch:

```bash
# Create and push a new branch
git checkout -b my-new-feature
git push -u origin my-new-feature
```

Within seconds, Zuplo deploys a new environment named `my-new-feature`. You can
see the new environment in the Zuplo portal's environment selector.

## Deleting Environments

When you delete a branch in your Git repository, the corresponding Zuplo
environment is **not automatically deleted**. To delete an environment:

1. Go to the Zuplo portal
2. Navigate to **Settings** > **Environments**
3. Select the environment and delete it

Alternatively, use the [Zuplo CLI](../cli/delete.mdx):

```bash
npx zuplo delete --url https://your-environment-url.zuplo.app --api-key $ZUPLO_API_KEY
```

## Automatic Deployments on Push

With the Git integration enabled, every push to a branch triggers an automatic
deployment:

1. **Push to default branch**: Updates the Production environment
2. **Push to other branches**: Updates the corresponding Preview environment
3. **Create new branch**: Creates a new Preview environment
4. **Merge pull request**: Updates the target branch's environment

This enables powerful GitOps workflows:

- **Feature branches**: Each feature gets its own testable environment
- **Pull request previews**: Review changes in a live environment before merging
- **Protected branches**: Use branch protection rules to gate Production
  deployments

## Environment Variables Per Branch

Environment variables can be scoped to specific environments:

| Scope            | Description                                                |
| ---------------- | ---------------------------------------------------------- |
| Production       | Only applies to the Production environment                 |
| Preview          | Applies to all Preview environments                        |
| Specific Preview | Applies to a specific Preview environment (by branch name) |
| Working Copy     | Only applies to development environments                   |

See [Environment Variables](./environment-variables.mdx) for configuration
details.

## Switching the Production Branch

If you need to change which branch serves as Production:

1. **Update your Git repository's default branch**:
   - GitHub: Settings > General > Default branch
   - GitLab: Settings > Repository > Branch defaults
   - Bitbucket: Repository settings > Branching model
   - Azure DevOps: Project settings > Repositories > Default branch

2. **Verify the change in Zuplo**: The environment deployed from your new
   default branch will now be labeled as Production

:::caution

Changing the default branch affects which environment receives Production
environment variables and uses the Production API key bucket. Plan this change
carefully to avoid service disruption.

:::

## Next Steps

- [Environments Overview](./environments.mdx) - Learn about environment types
- [Source Control Integration](./source-control.mdx) - Set up Git integration
- [Custom CI/CD Pipelines](./custom-ci-cd.mdx) - Build custom deployment
  workflows