Copy page

GitLab CI/CD

GitLab CI/CD provides integrated pipelines right where your code lives. No external services to configure—define your deployment workflow in .gitlab-ci.yml and GitLab handles the rest.

Why GitLab CI/CD with Zuplo?

The Zuplo CLI works seamlessly with GitLab's pipeline model:

Everything in one place — Source code, CI/CD, environments, and deployments all in GitLab. See deployment history alongside merge requests and issues.

Built-in environments — GitLab tracks deployments automatically. Review environment history, roll back deployments, and see what's deployed where.

Merge request pipelines — Run pipelines on merge requests before merging. Deploy preview environments that reviewers can test directly.

Artifacts between jobs — Pass deployment URLs between stages using GitLab artifacts. Build once, test many times.

How It Works

The Zuplo CLI handles deployment and testing. GitLab CI/CD orchestrates your workflow:

Code
# Deploy to Zuplo (environment name from branch or --environment flag)
npx zuplo deploy --api-key "$ZUPLO_API_KEY"

# Run tests against any Zuplo environment
npx zuplo test --endpoint https://your-env.zuplo.dev

# Clean up environments you no longer need
npx zuplo delete --environment pr-123 --api-key "$ZUPLO_API_KEY"

# Test locally before deploying
npx zuplo dev  # starts local server on port 9000

Use artifacts to pass the deployment URL between jobs. Write the URL to a file in the deploy job and retrieve it in the test job.

Prerequisites

1. Disconnect Git integration — If you're using GitLab CI/CD for deployments, disconnect the native Git integration to avoid duplicate deployments. Open your project settings, select Source Control, and click Disconnect.

2. Add your API key — Store your Zuplo API key as a CI/CD variable. Go to Settings > CI/CD > Variables and add ZUPLO_API_KEY. Check Mask variable to hide it in logs.

Examples

Start with the workflow that matches your needs:

• Basic Deployment — Deploy on every push to main
• Deploy and Test — Run tests after deployment
• MR Preview Environments — Isolated environments for merge requests
• Local Testing in CI — Test with local Zuplo server before deploying
• Tag-Based Releases — Deploy only on tagged releases
• Multi-Stage Deployment — Staging to production with manual gates

Complete Example Repository

See all these patterns working together in the Zuplo CLI Example Project.