Build a Complete Preview Environment

Every open pull request needs one stable preview URL that runs the changed code together with every service required to exercise it. Pie Loop tests a web pull request against its preview deployment, so a frontend preview wired to an unrelated or incompatible backend is not ready for testing. Platform engineering sets the preview up once, and after that every Pie run starts from a known build at a known commit.

What you’ll need:

• A stable preview URL for each open PR
• The exact commit SHA deployed to that URL
• A list of runtime dependencies for the changed feature
• A health check for the frontend and each required service
• A teardown or retention policy

Step 1: Deploy the Whole Change Together

A preview is only useful when it holds 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. Do not 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 may replace the deployment behind the URL, but the URL should remain stable for the life of the PR.

Step 2: 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. Do not include secrets or internal connection strings.

Step 3: Handle Your Architecture

Four shapes come up often. Find yours.

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. Do not guess relationships from branch names alone.

A common pattern is to deploy the frontend preview and the backend preview together from matching branch names, with the frontend pointed at the matching backend revision, so the UI change and the API change it depends on are tested as one system.

Monorepos

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

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.

Third-Party Dependencies

Use supported sandboxes for payments, email, identity, and messaging. Ensure callbacks return to the preview host, not production.

Confirm the Preview Is Real

Before Pie runs, verify:

1. The preview reports the expected commit SHA.
2. The login and changed user path load without local overrides.
3. Browser requests do not call production endpoints unexpectedly.
4. Required workers and callbacks complete.
5. A fresh test account can repeat the path after data reset.

For a write path, perform one action through the frontend and confirm the resulting state in the preview backend. Repeat after a fresh deployment. This catches previews that look healthy but still route writes to the wrong service.

Troubleshooting

• The page loads but the feature fails: Check API base URLs, service revisions, CORS, and callback URLs.
• The preview works for a developer only: Remove local DNS, VPN, cookie, and environment-variable dependencies.
• The feature appears intermittently: Verify feature flags, deployment readiness, and cache invalidation.
• Old code appears during a run: Record the deployed SHA in the page or health response and block testing until it matches the PR head.

Once the preview is complete, give Pie a test identity and resettable data to start every run from the same state.

Need Help?

• Support: support@pie.inc