Source Control and Deployment

Zuplo uses a GitOps model where your API configuration lives in source control and deployments happen automatically when you push code. This page explains how the working copy, source control, branches, environments, and deployment options fit together.

Working copy

Every developer gets a personal working copy environment when they use the Zuplo Portal. The working copy is a cloud-hosted development environment that deploys instantly when you save a file. You can think of it as your personal cloud sandbox.

Working copy environments use a .dev URL (for example, my-project-abc123.zuplo.dev) and are optimized for rapid iteration rather than production traffic.

Before connecting source control

When you first create a project, your working copy is standalone. You can edit files in the portal, and Zuplo saves them. There is no Git repository involved yet. This is fine for prototyping and exploring Zuplo, but for team collaboration and production deployments you need source control.

After connecting source control

When you connect a Git repository, the portal gains push/pull capabilities. You can commit your working copy changes to Git and pull changes from teammates. Your working copy becomes a personal branch-like workspace layered on top of the repository.

Connecting source control

Zuplo supports four Git providers: GitHub, GitLab, Bitbucket, and Azure DevOps. The integration has two parts, and which parts you get depends on your provider.

GitHub provides the most complete experience with both portal integration and automatic deployments on every push.

GitLab, Bitbucket, and Azure DevOps provide portal integration for pushing and pulling code but do not include automatic deployments. You must set up CI/CD pipelines that call the Zuplo CLI to deploy. See Custom CI/CD for details.

Branch to environment mapping

Every Git branch maps to a Zuplo environment. The repository's default branch (typically main) maps to the Production environment. Every other branch maps to a Preview environment.

The environment name matches the branch name. For example, pushing to a branch called staging creates an environment named staging with a URL like https://my-project-staging-abc1234.zuplo.app.

For full details on branch-based deployments, see Branch-Based Deployments.

Deployment options

Zuplo offers two ways to deploy your API: the built-in GitHub integration and the Zuplo CLI.

GitHub integration (automatic)

With GitHub connected, every push to any branch triggers an automatic deployment. Push to main and your Production environment updates within seconds. Push to a feature branch and a Preview environment is created or updated automatically.

This is the recommended setup for most teams. No CI/CD configuration is required.

Set up GitHub integration

CLI deployment (for all other providers)

For GitLab, Bitbucket, Azure DevOps, or any other Git provider, use the Zuplo CLI in your CI/CD pipeline to deploy.

Code
npx zuplo deploy --api-key $ZUPLO_API_KEY

See the provider-specific CI/CD guides:

• GitLab CI/CD
• Bitbucket Pipelines
• Azure DevOps Pipelines
• CircleCI

CLI deploy and environment naming

When you run zuplo deploy, the CLI determines the environment name using the following logic:

1. If you pass --environment my-env, the CLI uses my-env as the environment name.
2. If you do not pass --environment, the CLI uses the current Git branch name as the environment name.

This means in a typical CI/CD pipeline, the deploy command automatically names the environment after the branch being built without any extra configuration.

Code
# On the "staging" branch, this creates/updates the "staging" environment
npx zuplo deploy --api-key $ZUPLO_API_KEY

# Override the environment name explicitly
npx zuplo deploy --api-key $ZUPLO_API_KEY --environment production

For full CLI deploy reference, see CLI: deploy.

Environment URLs

Each environment gets a unique URL based on the project name, environment name, and a unique identifier:

Production and Preview environments use the .zuplo.app domain. Working copy environments use the .zuplo.dev domain. You can configure custom domains for any non-working-copy environment.

Putting it all together

The typical workflow from development to production looks like this:

1. Develop locally with zuplo dev or in your project's working copy in the Zuplo Portal.
2. Push your changes to a feature branch. If using GitHub, a Preview environment deploys automatically. If using another provider, your CI/CD pipeline runs zuplo deploy.
3. Test against the Preview environment URL.
4. Merge to the default branch. The Production environment updates automatically (GitHub) or via your CI/CD pipeline (other providers).

Next steps

• Environments -- Environment types and configuration
• Source Control & Deployments -- Provider setup guides
• Custom CI/CD -- Build your own deployment pipeline
• CLI: deploy -- Full CLI deploy reference