Development

Branch-Based Deployments

Copy page

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

Code
 
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

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 and API key buckets for specific Preview environments to support this pattern.

Creating New Environments

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

Code
 
# 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:

Code
 
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 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

Next Steps

• Environments Overview - Learn about environment types
• Source Control Integration - Set up Git integration
• Custom CI/CD Pipelines - Build custom deployment workflows