zuplo 6.67.32 → 6.68.0

package/docs/articles/custom-ci-cd-circleci.mdx

@@ -0,0 +1,78 @@
+---
+title: "CircleCI"
+sidebar_label: CircleCI
+---
+
+CircleCI offers powerful, flexible CI/CD with advanced workflow capabilities.
+Build complex deployment pipelines with parallel jobs, workspaces, and orbs for
+reusable configuration.
+
+## Why CircleCI with Zuplo?
+
+The Zuplo CLI integrates naturally with CircleCI's workflow model:
+
+**Powerful workflows** — Fan-out/fan-in patterns, conditional jobs, and manual
+approval gates. Build exactly the pipeline you need.
+
+**Workspaces and caching** — Share files between jobs efficiently. Cache
+dependencies for faster builds. Pass deployment URLs through workspaces.
+
+**Reusable configuration** — Create orbs to share deployment patterns across
+projects. Define commands once, use everywhere.
+
+**Parallelism and performance** — Run tests in parallel. Split by timing data
+for optimal speed. Get fast feedback on every change.
+
+## How It Works
+
+The Zuplo CLI handles deployment and testing. CircleCI orchestrates your
+workflow:
+
+```bash
+# 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 workspaces to pass the deployment URL between jobs. Write the URL to a file
+in the deploy job and attach the workspace for the test job.
+
+## Prerequisites
+
+1. **Disconnect Git integration** — If you're using CircleCI for deployments,
+   disconnect the native Git integration to avoid duplicate deployments. Go to
+   **Settings** > **Source Control** and click **Disconnect**.
+
+2. **Add your API key** — Store your Zuplo API key as an environment variable.
+   Go to **Project Settings** > **Environment Variables** and add
+   `ZUPLO_API_KEY`.
+
+## Examples
+
+Start with the workflow that matches your needs:
+
+- **[Basic Deployment](./ci-cd-circleci/basic-deployment.mdx)** — Deploy on
+  every push to main
+- **[Deploy and Test](./ci-cd-circleci/deploy-and-test.mdx)** — Run tests after
+  deployment
+- **[PR Preview Environments](./ci-cd-circleci/pr-preview-environments.mdx)** —
+  Isolated environments for pull requests
+- **[Local Testing in CI](./ci-cd-circleci/local-testing.mdx)** — Test with
+  local Zuplo server before deploying
+- **[Tag-Based Releases](./ci-cd-circleci/tag-based-releases.mdx)** — Deploy
+  only on tagged releases
+- **[Multi-Stage Deployment](./ci-cd-circleci/multi-stage-deployment.mdx)** —
+  Staging to production with approval jobs
+
+## Complete Example Repository
+
+See all these patterns working together in the
+[Zuplo CLI Example Project](https://github.com/zuplo/zup-cli-example-project).

package/docs/articles/custom-ci-cd-github.mdx

@@ -0,0 +1,99 @@
+---
+title: Custom GitHub Actions
+sidebar_label: Custom CI/CD
+---
+
+:::note
+
+Most GitHub users don't need custom CI/CD. The
+[built-in GitHub integration](./source-control-setup-github.mdx) deploys
+automatically on every push. Add
+[deployment testing](./github-deployment-testing.mdx) to run tests after each
+deploy.
+
+Use custom GitHub Actions when you need approval gates, multi-stage deployments,
+or tests that must pass before deploying.
+
+:::
+
+GitHub Actions gives you complete control over when, how, and where your API
+gateway deploys. Instead of automatic deployments on every push, you decide
+exactly what triggers a release — whether that's a pull request approval, a
+tagged release, or a successful test suite.
+
+## Why GitHub Actions with Zuplo?
+
+The Zuplo CLI integrates seamlessly into GitHub Actions workflows, giving you:
+
+**Full pipeline control** — Run linting, security scans, and integration tests
+before any deployment. Gate production releases behind manual approvals. Deploy
+to staging, validate, then promote to production—all automated.
+
+**Environment per pull request** — Every PR gets its own isolated Zuplo
+environment. Reviewers can test changes against a live API before merging.
+Environments clean up automatically when PRs close.
+
+**Test before you ship** — Run your test suite against a local Zuplo development
+server in CI before deploying anywhere. Catch issues before they reach any
+environment.
+
+**Tag-based releases** — Deploy only when you're ready. Tag a release in Git and
+let your pipeline handle the rest. No accidental deployments from work in
+progress.
+
+## How It Works
+
+The Zuplo CLI handles deployment, testing, and environment management. Your
+GitHub Actions workflow orchestrates when these happen:
+
+```bash
+# 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
+```
+
+Capture the deployment URL from the deploy command output to pass to subsequent
+test steps. The CLI outputs `Deployed to https://...` which you can parse and
+use throughout your workflow.
+
+## Prerequisites
+
+1. **Disconnect the GitHub integration** — Custom CI/CD replaces automatic
+   deployments. Go to **Settings** > **Source Control** and click **Disconnect**
+   to prevent double deployments.
+
+2. **Add your API key** — Store your Zuplo API key as a GitHub secret named
+   `ZUPLO_API_KEY`. Find your key in the Zuplo portal under your account
+   **Settings** > **API Keys**.
+
+## Examples
+
+Start with the workflow that matches your needs:
+
+- **[Basic Deployment](./ci-cd-github/basic-deployment.mdx)** — Deploy on every
+  push to main
+- **[Deploy and Test](./ci-cd-github/deploy-and-test.mdx)** — Run tests after
+  deployment
+- **[PR Preview Environments](./ci-cd-github/pr-preview-environments.mdx)** —
+  Isolated environments for every pull request
+- **[Local Testing in CI](./ci-cd-github/local-testing.mdx)** — Test with local
+  Zuplo server before deploying
+- **[Tag-Based Releases](./ci-cd-github/tag-based-releases.mdx)** — Deploy only
+  on tagged releases
+- **[Multi-Stage Deployment](./ci-cd-github/multi-stage-deployment.mdx)** —
+  Staging to production with approval gates
+- **[Automatic Cleanup](./ci-cd-github/cleanup-on-branch-delete.mdx)** — Delete
+  environments when branches are deleted
+
+## Complete Example Repository
+
+See all these patterns working together in the
+[Zuplo CLI Example Project](https://github.com/zuplo/zup-cli-example-project).

package/docs/articles/custom-ci-cd-gitlab.mdx

@@ -0,0 +1,79 @@
+---
+title: "GitLab CI/CD"
+sidebar_label: 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:
+
+```bash
+# 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. Go to **Settings** > **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](./ci-cd-gitlab/basic-deployment.mdx)** — Deploy on every
+  push to main
+- **[Deploy and Test](./ci-cd-gitlab/deploy-and-test.mdx)** — Run tests after
+  deployment
+- **[MR Preview Environments](./ci-cd-gitlab/mr-preview-environments.mdx)** —
+  Isolated environments for merge requests
+- **[Local Testing in CI](./ci-cd-gitlab/local-testing.mdx)** — Test with local
+  Zuplo server before deploying
+- **[Tag-Based Releases](./ci-cd-gitlab/tag-based-releases.mdx)** — Deploy only
+  on tagged releases
+- **[Multi-Stage Deployment](./ci-cd-gitlab/multi-stage-deployment.mdx)** —
+  Staging to production with manual gates
+
+## Complete Example Repository
+
+See all these patterns working together in the
+[Zuplo CLI Example Project](https://github.com/zuplo/zup-cli-example-project).

package/docs/articles/custom-ci-cd.mdx

@@ -0,0 +1,82 @@
+---
+title: Custom CI/CD Pipelines
+sidebar_label: Custom CI/CD
+---
+
+Custom CI/CD pipelines give you complete control over your deployment workflow.
+Use them when you need approval gates, multi-stage deployments, or tests that
+must pass before any deployment.
+
+:::tip{title="GitHub Users"}
+
+If you use GitHub, you likely don't need custom CI/CD. The
+[built-in integration](./source-control-setup-github.mdx) deploys automatically,
+and you can add [deployment testing](./github-deployment-testing.mdx) to run
+tests after each deploy.
+
+:::
+
+Custom pipelines unlock:
+
+- **Pre-deployment testing** — Tests must pass before anything deploys
+- **Approval gates** — Require human approval for production
+- **Tag-based releases** — Deploy only when you tag a release
+- **Multi-stage workflows** — Staging → production with validation between
+
+## Choose Your CI/CD Provider
+
+- **[GitHub Actions](./custom-ci-cd-github.mdx)** — Workflows with approval
+  gates and multi-stage deployments
+- **[Azure Pipelines](./custom-ci-cd-azure.mdx)** — Enterprise pipelines with
+  environment approvals
+- **[GitLab CI/CD](./custom-ci-cd-gitlab.mdx)** — Integrated pipelines with
+  protected environments
+- **[Bitbucket Pipelines](./custom-ci-cd-bitbucket.mdx)** — Repository-native
+  deployments with manual triggers
+- **[CircleCI](./custom-ci-cd-circleci.mdx)** — Flexible workflows with approval
+  jobs
+
+## How It Works
+
+Every Zuplo project can be deployed via the [Zuplo CLI](../cli/overview.mdx).
+The CLI commands integrate into any CI/CD system:
+
+- `zuplo deploy` — Deploy your API to Zuplo
+- `zuplo test` — Run your test suite against any endpoint
+- `zuplo delete` — Remove an environment when no longer needed
+- `zuplo dev` — Start a local server for testing in CI
+
+Branch names become environment names automatically. Push to `feature-auth` and
+you get a `feature-auth` environment. This
+[branch-based model](./branch-based-deployments.mdx) makes preview environments
+trivial to implement.
+
+:::warning{title="GitHub Users: Disconnect Automatic Deployments"}
+
+If you're using GitHub with custom CI/CD, disconnect the built-in integration to
+prevent double deployments:
+
+**Settings** > **Source Control** > **Disconnect**
+
+GitLab, Bitbucket, and Azure DevOps don't have automatic deployments, so no
+disconnection is needed.
+
+:::
+
+## Getting Your API Key
+
+The CLI authenticates with an API key:
+
+1. Go to [portal.zuplo.com](https://portal.zuplo.com)
+2. Select your account
+3. Navigate to **Settings** > **API Keys**
+
+Store this as a secret in your CI/CD provider (typically `ZUPLO_API_KEY`). Never
+commit API keys to your repository.
+
+## Related Resources
+
+- [Branch-Based Deployments](./branch-based-deployments.mdx) — How branches map
+  to environments
+- [Zuplo CLI Reference](../cli/overview.mdx) — Complete CLI documentation
+- [Testing](./testing.mdx) — Writing tests for your API