zuplo 6.70.69 → 6.70.71

package/docs/analytics/tabs/consumers.md

@@ -0,0 +1,73 @@
+---
+title: "Consumers"
+sidebar_label: "Consumers"
+---
+
+The **Consumers** tab breaks traffic down by API consumer: anyone calling your
+gateway, whether authenticated or anonymous. Use it to see who your noisiest
+callers are, who's hitting errors, and which consumers experience the slowest
+latency.
+
+## When to use this
+
+- Find the top API consumers by request volume.
+- Identify which consumer is responsible for a 4xx or 5xx surge.
+- Compare latency experience across consumers (for example, paid vs free tier).
+
+## Summary KPIs
+
+| Name              | What it measures                                                                                                                          |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| **Requests**      | Total requests across all consumers in the window.                                                                                        |
+| **Client Errors** | Request-weighted 4xx rate across consumers (high-traffic consumers count more). See [Metrics glossary](../reference/metrics-glossary.md). |
+| **Server Errors** | Request-weighted 5xx rate. Secondary: count of consumers with at least one 5xx.                                                           |
+| **Consumers**     | Distinct consumers (authenticated plus anonymous).                                                                                        |
+| **Total Errors**  | Combined 4xx + 5xx count. Secondary: consumers affected.                                                                                  |
+
+## Charts
+
+**Request Volume.** Stacked bars by status class. The chart title updates to
+reflect the active consumer filter so you can tell at a glance whether you're
+looking at one consumer or all of them.
+
+**Consumer Error Rates.** 4xx and 5xx over time. _What to look for:_ a sustained
+4xx rate from one consumer usually points to a broken integration on their side.
+
+**Consumer Latency Over Time.** P50, P95, P99 lines.
+
+## Consumer table
+
+| Column          | Notes                                                               |
+| --------------- | ------------------------------------------------------------------- |
+| User            | Consumer identity. Anonymous requests show **Anonymous · No auth**. |
+| Requests        | Count with an inline volume bar.                                    |
+| Client Errors % | 4xx percentage.                                                     |
+| Server Errors % | 5xx percentage.                                                     |
+| Avg / P95 / P99 | Latency percentiles.                                                |
+| 4xx sparkline   | Inline trend over the window.                                       |
+| 5xx sparkline   | Inline trend over the window.                                       |
+
+The table is searchable and sortable on any column (default: requests
+descending). Clicking a row filters the entire tab to that consumer. **Show
+more** loads the next 50.
+
+## Filters
+
+The filter bar applies. `originHost` is not applicable on this tab. See
+[Shared controls](../shared-controls.md#filters).
+
+## Troubleshooting
+
+**Everything is showing as Anonymous.** If your gateway isn't authenticating
+requests, or your auth policy isn't attaching a consumer identity, every request
+falls into the **Anonymous · No auth** bucket. Check your API key or JWT policy
+configuration.
+
+**I clicked a row but the charts didn't change.** A row click adds a consumer
+filter pill. If you don't see the pill in the sticky bar, your click landed on a
+non-row element. Try clicking the user cell directly.
+
+**The 5xx rate here is higher than on Requests.** The Consumers KPI is
+request-weighted across consumers, while the Requests KPI is a flat rate over
+all requests. They diverge when high-error consumers are a small share of total
+volume. See [Metrics glossary](../reference/metrics-glossary.md).

package/docs/analytics/tabs/graphql.md

@@ -0,0 +1,77 @@
+---
+title: "GraphQL"
+sidebar_label: "GraphQL"
+---
+
+The **GraphQL** tab breaks traffic down by GraphQL operation: the queries,
+mutations, and subscriptions clients send through routes you've marked as
+GraphQL endpoints. Use it to find your most-used operations, separate validation
+and resolver errors, and see how much of each operation's latency falls in your
+upstream resolvers. It's visible when the project proxies a GraphQL API.
+
+## When to use this
+
+- Find the highest-volume operations and the ones clients call most.
+- Separate resolver, validation, and auth errors when a GraphQL endpoint
+  misbehaves.
+- Compare total round-trip latency against resolver-only time to see whether the
+  gateway or the upstream owns a slowdown.
+
+## Summary KPIs
+
+| Name              | What it measures                                                                              |
+| ----------------- | --------------------------------------------------------------------------------------------- |
+| **Operations**    | Total GraphQL operations in the window.                                                       |
+| **Success Rate**  | Share of operations that completed without error. Secondary: ok / err split.                  |
+| **p95 Latency**   | Total P95 across operations. Secondary: resolver P95.                                         |
+| **Error Classes** | Total errored operations. Secondary: resolver / validation / auth split (`res · val · auth`). |
+
+See [Metrics glossary](../reference/metrics-glossary.md) for error-class and
+resolver-latency definitions.
+
+## Charts
+
+**GraphQL Operations Over Time.** Operation volume per interval. Populates once
+a client sends a query, mutation, or subscription.
+
+**Operation Types.** A donut splitting operations across **query**,
+**mutation**, and **subscription**.
+
+**Latency — Total vs Resolver.** Total P95 and resolver P95 over time, with P50
+total, P95 total, P99 total, and P95 resolver summary cards. _What to look for:_
+a total P95 well above the resolver P95 means the operation spends its time
+outside your resolvers — in parsing, validation, or gateway policies — rather
+than in the upstream.
+
+## Operations table
+
+| Column               | Notes                                          |
+| -------------------- | ---------------------------------------------- |
+| Operation            | The GraphQL operation name.                    |
+| Type                 | query, mutation, or subscription.              |
+| Operations           | Count with an inline volume bar.               |
+| Errors               | Errored-operation count.                       |
+| Error Rate           | Errors ÷ operations.                           |
+| Complexity (avg/max) | Average and maximum computed query complexity. |
+| p95                  | P95 latency for the operation.                 |
+
+The table is searchable and sortable on any column (default: operations
+descending).
+
+## Filters
+
+The filter bar applies. See [Shared controls](../shared-controls.md#filters).
+
+## Troubleshooting
+
+**The GraphQL tab is empty.** No GraphQL operations arrived in the selected
+window. Operations appear once a client sends a query, mutation, or subscription
+through a route you've marked as a GraphQL endpoint. See
+[GraphQL on Zuplo](../../articles/graphql.mdx) for how to mark a route.
+
+**The tab isn't visible.** Visibility requires at least one route you've marked
+as a GraphQL endpoint. See [GraphQL on Zuplo](../../articles/graphql.mdx).
+
+**Total latency is high but resolver latency is low.** The operation spends its
+time outside your resolvers. Check the gateway policies on the GraphQL route —
+parsing, validation, complexity analysis, or auth — rather than the upstream.

package/docs/analytics/tabs/mcp.md

@@ -0,0 +1,80 @@
+---
+title: "MCP"
+sidebar_label: "MCP"
+---
+
+The **MCP** tab shows Model Context Protocol traffic through Zuplo: OAuth and
+auth decisions, virtual-server routing, capability and tool invocations,
+JSON-RPC method usage, and upstream MCP server health. It covers both traffic
+that flows _to_ an MCP fleet through Zuplo's gateway and activity _inside_ MCP
+servers you host on Zuplo. It's visible when the project type is **standard**
+and MCP is in use.
+
+## When to use this
+
+- See which virtual servers, capabilities, and tools clients call most, and
+  who's calling them.
+- Track auth and policy decision outcomes across OAuth flows.
+- Identify whether failures originate in the gateway, the upstream, or the
+  client.
+- Investigate the JSON-RPC error codes clients receive.
+
+## Summary KPIs
+
+| Name                    | What it measures                                                                             |
+| ----------------------- | -------------------------------------------------------------------------------------------- |
+| **Events**              | Total MCP events in the window.                                                              |
+| **Success Rate**        | Share of events with outcome = success. Secondary: success / error split.                    |
+| **Client Errors (4xx)** | Count of client-side errors. Secondary: share of all errors.                                 |
+| **Server Errors (5xx)** | Count of server-side errors. Secondary: share of all errors.                                 |
+| **Failure Origins**     | Combined gateway + upstream + client failures. Secondary: per-origin split (`gw · up · cl`). |
+
+See [Metrics glossary](../reference/metrics-glossary.md) for the failure-origin
+and outcome-class definitions.
+
+## Charts
+
+**MCP Events Over Time.** Stacked area showing the top event types over the
+window.
+
+**Event Families.** A donut distributing events across families: **Requests**,
+**Capabilities**, and **Auth**.
+
+**Latency — Gateway vs Upstream.** Total, gateway, and upstream P95 over time,
+with P50 total, P95 total, P95 gateway, and P95 upstream summary cards. _What to
+look for:_ a P95 that the upstream slice dominates points to a slow MCP backend;
+a gateway-heavy P95 points to policy or auth overhead.
+
+## Breakdown tables
+
+| Table                | Columns                                                                                                                |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Capabilities         | Server, Capability, Type, Calls, Client (4xx), Server (5xx), Error Rate, P95.                                          |
+| Consumers            | Consumer, Events, Client (4xx), Server (5xx).                                                                          |
+| Virtual Servers      | Virtual Server, Events, Client (4xx), Server (5xx).                                                                    |
+| Upstream Servers     | Upstream, Events, Client (4xx), Server (5xx), P95.                                                                     |
+| MCP Methods          | Method (for example `tools/call`, `tools/list`, `resources/list`, `prompts/list`, `resources/templates/list`), Events. |
+| Clients              | Client, Kind (from the `initialize` handshake), Events.                                                                |
+| JSON-RPC Error Codes | Code, Errors — the JSON-RPC error codes clients receive.                                                               |
+| Failure Origins      | Origin (gateway / upstream / client), Errors, Client (4xx), Server (5xx).                                              |
+| Reason Codes         | Class, Code, Events, Errors, Client (4xx), Server (5xx).                                                               |
+
+Most tables sort on any column and show the top values by volume. Click **Show
+more** to load the next page.
+
+## Filters
+
+The filter bar applies. See [Shared controls](../shared-controls.md#filters).
+
+## Troubleshooting
+
+**The MCP tab is empty.** No MCP events arrived in the selected window. Once a
+client connects and invokes a capability or tool, the dashboard populates.
+
+**The tab isn't visible.** Visibility requires project type **standard** with
+MCP in use — either an MCP gateway that routes to upstream servers, or an MCP
+server you host on Zuplo.
+
+**Errors show but Failure Origins is empty.** Zuplo classifies failure origins
+server-side from event metadata. Events without a clear origin classification
+land in Errors but in none of the gateway / upstream / client buckets.

package/docs/analytics/tabs/origins.md

@@ -0,0 +1,82 @@
+---
+title: "Origins"
+sidebar_label: "Origins"
+---
+
+The **Origins** tab shows backend performance: how each upstream host you proxy
+to is performing in terms of volume, error rate, and latency. It's visible when
+the project uses managed-edge origins.
+
+## When to use this
+
+- Identify which backend is slow or returning errors.
+- Compare the latency contribution of DNS, TCP, TLS, and application time.
+- Audit traffic distribution across direct origins and service tunnels.
+
+## Summary metrics
+
+The header strip shows totals derived from the time series:
+
+| Name                 | What it measures                                                                                                                            |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Total requests       | All requests served against any origin in the window.                                                                                       |
+| 4xx rate             | Client error rate across all origins.                                                                                                       |
+| 5xx rate             | Server error rate across all origins.                                                                                                       |
+| Weighted avg latency | Origin response time weighted by request count, so high-traffic origins dominate. See [Metrics glossary](../reference/metrics-glossary.md). |
+
+## Charts
+
+**Backend Request Time Series.** Stacked bars by status class, aggregated across
+origins by default. Apply a host filter to scope to one origin.
+
+**Backend Latency.** Average and P95 over time. _What to look for:_ a P95 climb
+while the average stays flat usually points to a few slow origins or routes
+inside an otherwise healthy fleet.
+
+**Backend Error Rate.** 4xx and 5xx rates over time.
+
+**Request Lifecycle.** Stacked time spent in each phase of an origin request:
+**DNS time**, **TCP time**, **TLS time**, and **application time**. A high TLS
+slice indicates handshake overhead; a high application slice indicates the
+origin is slow.
+
+## Tables
+
+Two tables sit side by side in a 2-column grid.
+
+### Direct Origins
+
+| Column          | Notes                            |
+| --------------- | -------------------------------- |
+| Host            | The origin hostname.             |
+| Requests        | Count with an inline volume bar. |
+| Client Errors   | 4xx percentage.                  |
+| Server Errors   | 5xx percentage.                  |
+| Avg / P95 / P99 | Latency percentiles.             |
+| 4xx sparkline   | Inline trend over the window.    |
+| 5xx sparkline   | Inline trend over the window.    |
+
+Clicking a row toggles a host filter. Click again to remove it.
+
+### Service Tunnels
+
+Same columns and behavior as Direct Origins, scoped to tunnel-routed origins.
+The table is hidden when no tunnel traffic is present.
+
+## Filters
+
+The filter bar applies, with one exception: `userSub` is not applicable on this
+tab. See [Shared controls](../shared-controls.md#filters).
+
+## Troubleshooting
+
+**The Origins tab isn't visible.** It appears only when the project uses
+managed-edge origins. If your project routes traffic differently, the tab is
+hidden.
+
+**Service Tunnels table is missing.** That table only renders when at least one
+origin is reached over a service tunnel.
+
+**A 5xx spike on one origin doesn't match the Requests tab.** If you've filtered
+the Requests tab to a different route or status class, totals won't match. Clear
+filters or compare with the same filters applied on both tabs.

package/docs/analytics/tabs/requests.md

@@ -0,0 +1,96 @@
+---
+title: "Requests"
+sidebar_label: "Requests"
+---
+
+The **Requests** tab is the default Analytics overview: every request through
+your gateway in the selected time window, with charts and breakdowns for volume,
+latency, and errors.
+
+## When to use this
+
+- Spot-check overall traffic and error rate across a project or the whole
+  account.
+- Investigate a spike in 4xx or 5xx responses.
+- Drill from a route, status code, or geographic breakdown into the underlying
+  requests.
+
+## Summary KPIs
+
+| Name              | What it measures                                              | When it's useful                          |
+| ----------------- | ------------------------------------------------------------- | ----------------------------------------- |
+| **Requests**      | Total request count. Secondary value: successful (2xx) count. | Quick health check on volume and success. |
+| **Client Errors** | 4xx rate (4xx ÷ total). Secondary value: raw 4xx count.       | Spot bad-input or auth issues.            |
+| **Server Errors** | 5xx rate (5xx ÷ total). Secondary value: raw 5xx count.       | Spot gateway or upstream failures.        |
+| **Avg Latency**   | Mean response time. Secondary value: min to max.              | Detect broad latency regressions.         |
+| **Consumers**     | Distinct API consumers (authenticated + anonymous).           | Gauge active audience.                    |
+
+See [Metrics glossary](../reference/metrics-glossary.md) for how rates and
+percentiles are computed.
+
+## Charts
+
+**Request Time Series.** Stacked bars per interval, broken down by status class
+(2xx / 3xx / 4xx / 5xx). Drag to select a region to zoom; the time range picker
+updates to match.
+
+**Request Locations Map.** A world map with a heatmap of request volume by
+location. Shown only when geolocation data is present.
+
+**Latency Over Time.** P50, P95, and P99 lines. _What to look for:_ a widening
+gap between P50 and P95 typically signals a tail-latency problem affecting a
+subset of requests.
+
+**Error Rate.** 4xx and 5xx rates plotted over time.
+
+**Latency Distribution.** A histogram of P10, P50, P90, P95, and P99 buckets.
+Click a band to filter the rest of the tab to requests in that duration range.
+
+**Active Instances.** Distinct active edge instances over time. A rough
+indicator of how widely your traffic is distributed across gateway workers.
+
+## Breakdowns
+
+Each breakdown shows the top 10 values by request count. Click **Show more** to
+load the next 50.
+
+**Primary breakdowns:**
+
+- **HTTP Method**
+- **HTTP Status**
+- **Route Path**
+
+**Account scope only:**
+
+- **Project Name**: click to drill into project-scope analytics.
+- **Deployment Name**: click to drill into a specific deployment.
+
+**Secondary breakdowns:**
+
+- **Country**, **City**, **Colo**
+- **User Sub**
+- **Client IP**
+- **AS Organization**
+
+Clicking any value applies an `equals` filter for that field.
+
+## Filters
+
+The full filter bar applies. `originHost` is not applicable on this tab. See
+[Shared controls](../shared-controls.md#filters) for match modes and the filter
+pill UI.
+
+## Troubleshooting
+
+**The map is missing.** The Request Locations Map only renders when geolocation
+data is present in the time window. Short windows for low-traffic projects may
+not include any geolocated requests.
+
+**Show more doesn't load anything.** You may already be viewing every value for
+that breakdown. Top-10 plus 50 covers up to 60 distinct values; beyond that,
+narrow the time range or add a filter.
+
+**My charts look sparse.** If your account is new, the trial banner across the
+top calls this out. Click **View demo →** in the banner to see what a fully
+populated dashboard looks like. See
+[Access and entitlements](../access-and-entitlements.md).

package/docs/articles/api-key-buckets.mdx

@@ -11,10 +11,12 @@ credentials across different environments. Learn more in the
 
 Zuplo automatically creates three buckets for each project:
 
-- **Working copy**: Stores API keys for the working-copy environment
 - **Production**: Stores API keys for the production environment (your default
   Git branch)
-- **Shared**: Stores API keys shared across all other environments
+- **Preview**: Stores API keys shared across all preview environments
+  (non-default Git branches)
+- **Development**: Stores API keys for the development (working copy)
+  environment
 
 For more information on how environments relate to Git branches, see
 [Branch-Based Deployments](./branch-based-deployments.mdx).

package/docs/articles/archiving-requests-to-storage.mdx

@@ -30,7 +30,7 @@ can generate one of these on the `Shared access tokens` tab.
 Note, you should minimize the permissions - and select only the `Create`
 permission. Choose a sensible start and expiration time for your token. Note, we
 don't recommend restricting IP addresses because Zuplo runs at the edge in over
-200 data-centers world-wide.
+300 data centers worldwide.
 
 ![shared access tokens](../../public/media/guides/archiving-requests-to-storage/Untitled_1.png)
 
@@ -46,7 +46,7 @@ You'll need another environment variable called `BLOB_CONTAINER_PATH`.
 We'll write a policy called `request-archive-policy` that can be used on all
 routes.
 
-```ts title="file-archive-policy.ts"
+```ts title="modules/request-archive-policy.ts"
 import { ZuploRequest, ZuploContext } from "@zuplo/runtime";
 
 export type RequestArchivePolicyOptions = {
@@ -102,7 +102,7 @@ example below:
   "policyType": "code-policy",
   "handler": {
     "export": "default",
-    "module": "$import(./modules/archive-request-policy)",
+    "module": "$import(./modules/request-archive-policy)",
     "options": {
       "blobCreateSas": "$env(BLOB_CREATE_SAS)",
       "blobContainerPath": "$env(BLOB_CONTAINER_PATH)"
@@ -111,7 +111,7 @@ example below:
 }
 ```
 
-Don't forget to reference the `file-archive-policy` in the policies.inbound
+Don't forget to reference the `request-archive-policy` in the policies.inbound
 property of your routes.
 
 Here's the policy in action:

package/docs/articles/branch-based-deployments.mdx

@@ -34,17 +34,19 @@ bugfix/123    ─────────────────►  Preview (b
 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` |
+| 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-au-ghi9012.zuplo.app` |
 
 :::note
 
-The environment URL includes a unique identifier to ensure each deployment has a
-distinct address. Configure [custom domains](./custom-domains.mdx) for your
-environments.
+Zuplo normalizes the branch name in the deployment URL — lowercasing it,
+replacing special characters with hyphens, and truncating it to 10 characters —
+which is why `feature/auth` appears as `feature-au`. The URL also includes a
+unique identifier to ensure each deployment has a distinct address. Configure
+[custom domains](./custom-domains.mdx) for your environments.
 
 :::
 

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

@@ -27,7 +27,9 @@ jobs:
         run: npm install
 
       - name: Deploy to Zuplo
-        run: npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+        run:
+          npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "${{
+          github.ref_name }}"
         env:
           ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
 ```
@@ -41,6 +43,13 @@ This workflow:
 
 Since this deploys from `main`, it updates your production environment.
 
+Passing `--environment` is technically optional here — without it, the CLI
+infers the environment name from the checked-out git ref — but inference can
+pick the wrong name in CI (detached HEAD checkouts, commits that exist on more
+than one branch, or `pull_request` merge refs). Passing the branch name
+explicitly makes every workflow deploy a predictable environment. See the
+[deploy command reference](../../cli/deploy.mdx) for details.
+
 ## Next Steps
 
 - Add [testing after deployment](./deploy-and-test.mdx)

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

@@ -34,24 +34,29 @@ jobs:
         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
+          # Deployment names use the format {project}-{branch}-{hash}, where
+          # the branch segment is normalized (lowercase, special characters
+          # replaced by hyphens) and truncated to 10 characters
+          ENV_NAME=$(echo "$BRANCH_NAME" | tr '/_' '--' |
+            tr '[:upper:]' '[:lower:]' | cut -c1-10 | sed 's/-*$//')
+
+          # Find the deployment for the deleted branch and delete it by URL
+          npx zuplo list --api-key "$ZUPLO_API_KEY" \
+            --output json --show-details |
+            jq -r --arg env "$ENV_NAME" \
+              '.[] | select(.name | test("-" + $env + "-[a-z0-9]+$")) | .url' |
+            while read -r URL; do
+              echo "Deleting environment: $URL"
+              npx zuplo delete --url "$URL" --api-key "$ZUPLO_API_KEY" --wait || true
+            done
 ```
 
 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
+2. Converts the branch name to the deployment-name branch segment format
+3. Looks up the matching deployment and deletes it by URL
+4. Continues without error if no matching environment exists
 
 ## Combining with PR Cleanup
 
@@ -95,24 +100,40 @@ jobs:
 
       - 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
+          # Get all remote branches, converted to the deployment-name branch
+          # segment format: lowercase, special characters replaced by hyphens,
+          # truncated to 10 characters
+          BRANCHES=$(git branch -r | sed 's|origin/||' | tr -d ' ' |
+            tr '/_' '--' | tr '[:upper:]' '[:lower:]' |
+            cut -c1-10 | sed 's/-*$//')
+
+          # List deployed environments as JSON. Each entry has the shape
+          # {"projectName": "...", "name": "...", "url": "..."}
+          npx zuplo list --api-key "$ZUPLO_API_KEY" \
+            --output json --show-details > environments.json
+
+          # Deployment names follow the format {project}-{branch}-{hash}
+          jq -r '.[] | "\(.name) \(.url)"' environments.json |
+            while read -r NAME URL; do
+              # Skip protected environments
+              case "$NAME" in
+                *-main-* | *-production-* | *-staging-*) continue ;;
+              esac
+
+              # Delete only if no branch matches the deployment name
+              STALE=true
+              for BRANCH in $BRANCHES; do
+                if [[ "$NAME" == *"-$BRANCH-"* ]]; then
+                  STALE=false
+                  break
+                fi
+              done
+
+              if [[ "$STALE" == "true" ]]; then
+                echo "Deleting stale environment: $NAME"
+                npx zuplo delete --url "$URL" --api-key "$ZUPLO_API_KEY" --wait || true
+              fi
+            done
 ```
 
 ## Next Steps

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

@@ -34,9 +34,14 @@ jobs:
       - name: Deploy to Zuplo
         id: deploy
         shell: bash
+        env:
+          # head_ref is the source branch on pull_request events (where the
+          # checkout is the pull/<number>/merge ref, not the branch);
+          # ref_name covers push events
+          ENVIRONMENT: ${{ github.head_ref || github.ref_name }}
         run: |
           # Capture deployment output
-          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" 2>&1)
+          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "$ENVIRONMENT" 2>&1)
           echo "$OUTPUT"
 
           # Extract the deployment URL
@@ -53,6 +58,14 @@ This workflow:
 2. Runs your test suite against the live deployment
 3. Fails the workflow if any tests fail
 
+The deploy step passes `--environment` explicitly because this workflow runs on
+both `push` and `pull_request` events. The expression
+`${{ github.head_ref || github.ref_name }}` resolves to the branch name on
+either trigger, so every run for a branch updates the same environment. Without
+it, `pull_request` runs create a second environment named after the PR merge ref
+instead of your branch — see
+[PR Preview Environments](./pr-preview-environments.mdx) for details.
+
 ## Writing Tests
 
 Place test files in the `tests` folder with the `.test.ts` extension: