zuplo 6.67.32 → 6.68.0

package/docs/articles/ci-cd-circleci/tag-based-releases.mdx

@@ -0,0 +1,38 @@
+---
+title: "CircleCI: Tag-Based Releases"
+sidebar_label: Tag-Based Releases
+---
+
+Deploy only when tags are pushed for controlled releases.
+
+```yaml title=".circleci/config.yml"
+version: 2.1
+
+jobs:
+  deploy:
+    docker:
+      - image: cimg/node:20.0
+    steps:
+      - checkout
+      - run: npm install
+      - run:
+          npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment
+          "$CIRCLE_TAG"
+
+workflows:
+  release:
+    jobs:
+      - deploy:
+          filters:
+            tags:
+              only: /^v.*/
+            branches:
+              ignore: /.*/
+```
+
+This workflow triggers only on tags matching `v*` (like `v1.0.0`) and creates an
+environment named after the tag.
+
+## Next Steps
+
+- Add [multi-stage deployment](./multi-stage-deployment.mdx) with approval

package/docs/articles/ci-cd-github/basic-deployment.mdx

@@ -0,0 +1,48 @@
+---
+title: "GitHub Actions: Basic Deployment"
+sidebar_label: Basic Deployment
+---
+
+The simplest workflow deploys your API to Zuplo on every push to main.
+
+```yaml title=".github/workflows/deploy.yaml"
+name: Deploy to Zuplo
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Deploy to Zuplo
+        run: npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+        env:
+          ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
+```
+
+This workflow:
+
+1. Triggers on pushes to the `main` branch
+2. Checks out your code
+3. Installs dependencies (including the Zuplo CLI)
+4. Deploys to Zuplo using the branch name as the environment name
+
+Since this deploys from `main`, it updates your production environment.
+
+## Next Steps
+
+- Add [testing after deployment](./deploy-and-test.mdx)
+- Set up [PR preview environments](./pr-preview-environments.mdx)
+- Implement [tag-based releases](./tag-based-releases.mdx) for more control

package/docs/articles/ci-cd-github/cleanup-on-branch-delete.mdx

@@ -0,0 +1,123 @@
+---
+title: "GitHub Actions: Automatic Cleanup"
+sidebar_label: Automatic Cleanup
+---
+
+Delete Zuplo environments automatically when branches are deleted. This keeps
+your environment list clean and avoids accumulating unused preview environments.
+
+```yaml title=".github/workflows/cleanup-on-branch-delete.yaml"
+name: Cleanup on Branch Delete
+
+on:
+  delete:
+
+jobs:
+  cleanup:
+    # Only run for branch deletions, not tag deletions
+    if: github.event.ref_type == 'branch'
+    runs-on: ubuntu-latest
+    env:
+      ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Delete environment
+        run: |
+          # The deleted branch name
+          BRANCH_NAME="${{ github.event.ref }}"
+          # Convert slashes to hyphens
+          ENV_NAME="${BRANCH_NAME//\//-}"
+
+          echo "Deleting environment: $ENV_NAME"
+
+          # Ignore errors if env doesn't exist
+          npx zuplo delete \
+            --environment "$ENV_NAME" \
+            --api-key "$ZUPLO_API_KEY" \
+            --wait || true
+```
+
+This workflow:
+
+1. Triggers when any branch is deleted
+2. Converts the branch name to the environment name format
+3. Deletes the corresponding Zuplo environment
+4. Continues without error if the environment doesn't exist
+
+## Combining with PR Cleanup
+
+Use this as a backup for
+[PR preview environments](./pr-preview-environments.mdx). The PR workflow
+handles cleanup when PRs close, but this catches cases where:
+
+- Someone deletes a branch without closing the PR first
+- A branch was pushed but never had a PR opened
+- The PR cleanup job failed
+
+## Scheduled Cleanup
+
+For additional safety, run periodic cleanup to catch any orphaned environments:
+
+```yaml title=".github/workflows/scheduled-cleanup.yaml"
+name: Scheduled Cleanup
+
+on:
+  schedule:
+    # Run daily at midnight UTC
+    - cron: "0 0 * * *"
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    env:
+      ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all branches
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Cleanup stale environments
+        run: |
+          # Get all remote branches
+          BRANCHES=$(git branch -r | sed 's|origin/||' | tr '/' '-' | tr -d ' ')
+
+          # List Zuplo environments and delete stale ones
+          npx zuplo list --api-key "$ZUPLO_API_KEY" --json > environments.json
+
+          cat environments.json | jq -r '.[] | .name' | while read ENV; do
+            # Skip protected environments
+            if [[ "$ENV" == "main" || "$ENV" == "production" || "$ENV" == "staging" ]]; then
+              continue
+            fi
+
+            # Delete if no matching branch exists
+            if ! echo "$BRANCHES" | grep -q "^$ENV$"; then
+              echo "Deleting stale environment: $ENV"
+              npx zuplo delete --environment "$ENV" --api-key "$ZUPLO_API_KEY" --wait || true
+            fi
+          done
+```
+
+## Next Steps
+
+- Set up [PR preview environments](./pr-preview-environments.mdx) with built-in
+  cleanup
+- Implement [multi-stage deployment](./multi-stage-deployment.mdx) for
+  production

package/docs/articles/ci-cd-github/deploy-and-test.mdx

@@ -0,0 +1,82 @@
+---
+title: "GitHub Actions: Deploy and Test"
+sidebar_label: Deploy and Test
+---
+
+Run your test suite against the deployed environment to validate changes before
+considering them complete.
+
+```yaml title=".github/workflows/deploy-and-test.yaml"
+name: Deploy and Test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  deploy-and-test:
+    runs-on: ubuntu-latest
+    env:
+      ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Deploy to Zuplo
+        id: deploy
+        shell: bash
+        run: |
+          # Capture deployment output
+          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" 2>&1)
+          echo "$OUTPUT"
+
+          # Extract the deployment URL
+          DEPLOYMENT_URL=$(echo "$OUTPUT" | grep -oP 'Deployed to \K(https://[^ ]+)')
+          echo "url=$DEPLOYMENT_URL" >> $GITHUB_OUTPUT
+
+      - name: Run tests
+        run: npx zuplo test --endpoint "${{ steps.deploy.outputs.url }}"
+```
+
+This workflow:
+
+1. Deploys to Zuplo and captures the deployment URL
+2. Runs your test suite against the live deployment
+3. Fails the workflow if any tests fail
+
+## Writing Tests
+
+Place test files in the `tests` folder with the `.test.ts` extension:
+
+```typescript title="tests/api.test.ts"
+import { describe, it, expect } from "@zuplo/test";
+
+describe("API", () => {
+  it("returns 200 for health check", async () => {
+    const response = await fetch(`${ZUPLO_TEST_URL}/health`);
+    expect(response.status).toBe(200);
+  });
+
+  it("requires authentication", async () => {
+    const response = await fetch(`${ZUPLO_TEST_URL}/protected`);
+    expect(response.status).toBe(401);
+  });
+});
+```
+
+The `ZUPLO_TEST_URL` variable is automatically set to the `--endpoint` value.
+
+## Next Steps
+
+- Add [PR preview environments](./pr-preview-environments.mdx) with automatic
+  cleanup
+- Run [local tests](./local-testing.mdx) before deploying

package/docs/articles/ci-cd-github/local-testing.mdx

@@ -0,0 +1,102 @@
+---
+title: "GitHub Actions: Local Testing in CI"
+sidebar_label: Local Testing in CI
+---
+
+Run tests against a local Zuplo development server before deploying anywhere.
+Catch issues earlier and avoid deploying broken changes.
+
+```yaml title=".github/workflows/local-test-then-deploy.yaml"
+name: Local Test Then Deploy
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  local-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Start local server and run tests
+        run: |
+          # Start the local dev server in the background
+          npx zuplo dev &
+          DEV_PID=$!
+
+          # Wait for server to be ready
+          echo "Waiting for local server to start..."
+          sleep 10
+
+          # Run tests against local server
+          npx zuplo test --endpoint http://localhost:9000
+
+          # Stop the dev server
+          kill $DEV_PID
+
+  deploy:
+    needs: local-test
+    runs-on: ubuntu-latest
+    # Only deploy on push to main, not on PRs
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    env:
+      ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Deploy to Zuplo
+        run: npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+```
+
+This workflow:
+
+1. Starts a local Zuplo server in the CI environment
+2. Runs your test suite against localhost
+3. Only proceeds to deployment if local tests pass
+4. Deploys to Zuplo (only on pushes to main)
+
+## Why Test Locally First?
+
+- **Faster feedback** — Local tests run without waiting for deployment
+- **Catch syntax errors** — The local server validates your configuration
+- **Test policies** — Verify authentication, rate limiting, and other policies
+  work correctly
+- **No wasted deployments** — Don't deploy changes that will fail tests
+
+## Combining with Remote Tests
+
+For maximum confidence, test both locally and against the deployed environment:
+
+```yaml
+jobs:
+  local-test:
+    # ... local testing job ...
+
+  deploy-and-test:
+    needs: local-test
+    # ... deploy and run tests against live environment ...
+```
+
+## Next Steps
+
+- Add [PR preview environments](./pr-preview-environments.mdx) for review
+- Set up [multi-stage deployment](./multi-stage-deployment.mdx) with staging

package/docs/articles/ci-cd-github/multi-stage-deployment.mdx

@@ -0,0 +1,136 @@
+---
+title: "GitHub Actions: Multi-Stage Deployment"
+sidebar_label: Multi-Stage Deployment
+---
+
+Deploy to staging first, run tests, then promote to production with manual
+approval. This pattern ensures changes are validated before reaching production.
+
+```yaml title=".github/workflows/multi-stage.yaml"
+name: Multi-Stage Deployment
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy-staging:
+    runs-on: ubuntu-latest
+    env:
+      ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
+    outputs:
+      staging-url: ${{ steps.deploy.outputs.url }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Deploy to staging
+        id: deploy
+        shell: bash
+        run: |
+          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment staging 2>&1)
+          echo "$OUTPUT"
+          DEPLOYMENT_URL=$(echo "$OUTPUT" | grep -oP 'Deployed to \K(https://[^ ]+)')
+          echo "url=$DEPLOYMENT_URL" >> $GITHUB_OUTPUT
+
+  test-staging:
+    needs: deploy-staging
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run tests against staging
+        run:
+          npx zuplo test --endpoint "${{
+          needs.deploy-staging.outputs.staging-url }}"
+
+  deploy-production:
+    needs: test-staging
+    runs-on: ubuntu-latest
+    env:
+      ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
+    # Require manual approval
+    environment: production
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Deploy to production
+        run:
+          npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment production
+```
+
+This workflow:
+
+1. **Deploy to staging** — Every push to main deploys to staging
+2. **Test staging** — Run your full test suite against staging
+3. **Wait for approval** — The production job waits for manual approval
+4. **Deploy to production** — After approval, deploy to production
+
+## Setting Up Manual Approval
+
+Create a GitHub environment with required reviewers:
+
+1. Go to **Settings** > **Environments** > **New environment**
+2. Name it `production`
+3. Check **Required reviewers** and add approvers
+4. Save the environment
+
+When the workflow reaches the production job, it pauses until an approver clicks
+**Review deployments** in the Actions UI.
+
+## Adding More Stages
+
+Add additional environments like QA or UAT:
+
+```yaml
+jobs:
+  deploy-staging:
+    # ...
+
+  test-staging:
+    # ...
+
+  deploy-qa:
+    needs: test-staging
+    environment: qa
+    # ...
+
+  test-qa:
+    needs: deploy-qa
+    # ...
+
+  deploy-production:
+    needs: test-qa
+    environment: production
+    # ...
+```
+
+## Next Steps
+
+- Combine with [tag-based releases](./tag-based-releases.mdx) for version
+  control
+- Add [local testing](./local-testing.mdx) before any deployment

package/docs/articles/ci-cd-github/pr-preview-environments.mdx

@@ -0,0 +1,106 @@
+---
+title: "GitHub Actions: PR Preview Environments"
+sidebar_label: PR Preview Environments
+---
+
+Give every pull request its own Zuplo environment. Reviewers can test changes
+against a live API, and environments clean up automatically when PRs close.
+
+```yaml title=".github/workflows/pr-workflow.yaml"
+name: PR Workflow
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+
+jobs:
+  deploy-and-test:
+    # Run on PR open/update, not on close
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    env:
+      ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Deploy to Zuplo
+        id: deploy
+        shell: bash
+        run: |
+          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" 2>&1)
+          echo "$OUTPUT"
+          DEPLOYMENT_URL=$(echo "$OUTPUT" | grep -oP 'Deployed to \K(https://[^ ]+)')
+          echo "url=$DEPLOYMENT_URL" >> $GITHUB_OUTPUT
+
+      - name: Run tests
+        run: npx zuplo test --endpoint "${{ steps.deploy.outputs.url }}"
+
+      - name: Comment PR with deployment URL
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `🚀 Deployed to: ${{ steps.deploy.outputs.url }}`
+            })
+
+  cleanup:
+    # Only run when PR is closed (merged or not)
+    if: github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    env:
+      ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Delete environment
+        run: |
+          # Environment name is based on branch name
+          BRANCH_NAME="${{ github.head_ref }}"
+          # Convert slashes to hyphens (Zuplo convention)
+          ENV_NAME="${BRANCH_NAME//\//-}"
+
+          npx zuplo delete \
+            --environment "$ENV_NAME" \
+            --api-key "$ZUPLO_API_KEY" \
+            --wait
+```
+
+This workflow:
+
+1. **On PR open/update**: Deploys to an environment named after the branch, runs
+   tests, and comments the URL on the PR
+2. **On PR close**: Deletes the preview environment
+
+## How It Works
+
+- The environment name comes from the branch name (`feature/auth` becomes
+  `feature-auth`)
+- Each push to the PR updates the same environment
+- Closing the PR (merge or abandon) triggers cleanup
+- The PR comment lets reviewers quickly access the preview
+
+## Next Steps
+
+- Add [automatic cleanup on branch delete](./cleanup-on-branch-delete.mdx) as a
+  backup
+- Implement [multi-stage deployment](./multi-stage-deployment.mdx) for
+  production releases