Build a complete preview environment

Deploy the whole change together

The preview needs every revision the changed path touches.

1. Identify the affected services. Trace the changed user path from the browser or app through APIs, workers, databases, queues, and third-party sandboxes.
2. Deploy compatible revisions together. If a frontend PR depends on a backend change, deploy both revisions into the same preview. For changes across repositories, use one shared preview identifier such as the branch name or PR number.
3. Route dependencies explicitly. Point the preview frontend at the preview API. Point the preview API at the matching workers and sandbox services. Don’t rely on a developer’s local configuration.
4. Publish readiness. Expose a small health endpoint or deployment status that reports the deployed SHA and the readiness of required services.
5. Keep the URL stable. A new commit can replace the deployment behind the URL, but the URL itself should stay the same for the life of the PR. Pie finds it in an @pie-pr-bot test <url> comment, a deploy bot’s comment on the PR, or a fixed pattern Pie sets up for your app.

Publish a deployment manifest

Give the preview one identifier and record the exact revision of every component:

{
  "deploymentGroup": "pr-123",
  "frontend": {
    "sha": "<FRONTEND_SHA>",
    "url": "https://pr-123.preview.example.com"
  },
  "services": [
    {
      "name": "api",
      "sha": "<API_SHA>",
      "health": "https://api-pr-123.preview.example.com/health"
    }
  ],
  "dataProfile": "order-ready-for-refund",
  "flags": {"refund-workflow": true},
  "ready": false
}

Set ready to true only after every component reports the expected SHA and passes its health check. Leave out secrets and internal connection strings.

Handle your architecture

Four setups come up often:

1. Changes across repositories. Use the same preview key in each repository. Resolve the related revisions through linked PRs, a committed deployment manifest, or a merge queue. Don’t guess relationships from branch names alone.

   A common pattern: deploy the frontend and backend previews together from matching branch names, and point the frontend at the matching backend revision. Pie then tests the UI change and the API change it depends on as one system.

2. Monorepos. Build only the affected services, but publish one manifest that records every deployed component and commit SHA.

3. Shared services. Use an isolated namespace, tenant, or database schema when the feature writes data. If isolation is not possible, use unique test identifiers and a cleanup job.

4. Third-party dependencies. Use supported sandboxes for payments, email, identity and messaging. Make sure callbacks return to the preview host, not production.