Preview environments let a team deploy a temporary version of an application for each pull request, so reviewers can test the proposed change before it reaches a shared staging or production system. This guide provides a provider-neutral preview deployment setup, including branch and URL design, data safety, environment variables, access control, cleanup, status checks, reviewer handoffs, and a troubleshooting checklist.
Overview
A preview environment is an isolated deployment created from a pull request branch. It normally includes a build of the application, a temporary URL, and enough configuration for a reviewer to exercise the relevant feature. Depending on the application, the environment may use a shared database, a disposable database, mocked services, or read-only production-like data.
The basic workflow is:
- A developer opens or updates a pull request.
- CI validates the code and starts a deployment.
- The hosting system builds the branch and assigns a unique URL.
- The deployment reports a success or failure status back to the pull request.
- Reviewers test the URL and leave feedback in the pull request.
- The environment is updated when new commits arrive and removed when the pull request is closed or merged.
The important design decision is not simply how to deploy every pull request. It is deciding what each preview is allowed to access. A useful preview should be realistic enough to review while remaining isolated from production credentials, customer data, billing systems, email delivery, and destructive background jobs.
Checklist by scenario
For a first preview deployment
- Choose the deployment trigger: pull request opened, synchronized, reopened, or manually approved.
- Define a stable naming convention, such as
pr-123, for the branch, deployment, database namespace, and logs. - Generate a unique URL for every pull request. A provider-generated URL or a controlled subdomain pattern is usually safer than manually assigning names.
- Confirm which runtime version, package manager, build command, output directory, and start command the platform should use.
- Store deployment credentials and application secrets in the CI or hosting platform's secret manager, not in the repository.
- Configure a pull request status check that clearly distinguishes build, deployment, and smoke-test failures.
- Document how reviewers find the URL, test seeded data, sign in, and report a problem.
For an application with a database
- Prefer a disposable database or isolated schema when the feature changes data models or writes user-generated data.
- Use a migration step that is safe to run repeatedly and fails clearly when the schema is incompatible.
- Seed only synthetic or sanitized data. Never copy production records into a preview without an approved data-handling process.
- Disable scheduled jobs, payment actions, outbound email, webhooks, and other side effects by default.
- Give the preview database a clear expiration policy and remove it when the pull request is closed.
For a private application
- Require authentication before the preview can be viewed.
- Use preview-specific accounts or identity-provider settings rather than production administrator credentials.
- Restrict access to the repository team, approved reviewers, or an allowlist where the platform supports it.
- Check whether assets, API responses, error pages, and source maps could expose confidential information.
- Verify that search engines and public crawlers cannot index the temporary URL. Access control is more reliable than relying on a robots directive alone.
For a static or frontend-only project
- Build the branch with the same framework and dependency versions used by the main deployment.
- Point API requests to a preview-safe backend or mock service.
- Test client-side routing, asset paths, redirects, and environment-specific base URLs.
- Confirm that a pull request update replaces the old build instead of creating an ambiguous second URL.
Provider-neutral configuration template
Adapt the following variables to your CI/CD and hosting system. The names are illustrative; the important part is separating repository metadata, deployment settings, and secrets.
PREVIEW_ID=pr-${PULL_REQUEST_NUMBER}
PREVIEW_URL=https://${PREVIEW_ID}.preview.example.test
BRANCH=${PULL_REQUEST_HEAD_REF}
BUILD_COMMAND=ci/build-preview
DEPLOY_COMMAND=ci/deploy-preview
DATABASE_TARGET=isolated-${PREVIEW_ID}
PREVIEW_MODE=true
ALLOW_OUTBOUND_EMAIL=false
ALLOW_EXTERNAL_WEBHOOKS=false
EXPIRES_AT=${PULL_REQUEST_CLOSED_OR_TTL}A deployment script should validate required variables before building, use the pull request identifier in resource names, and return the final URL to the CI job. The pull request should receive that URL as a status, comment, or deployment detail. Avoid putting tokens, database passwords, or signed URLs in comments or build logs.
For the surrounding pipeline, see the reusable workflow patterns in How to Deploy a Web App with GitHub Actions. If the preview is hosted on a Linux server, the operational guidance in Docker Deployment on a Linux Server and Nginx Reverse Proxy Setup can help with containers, routing, HTTPS, and health checks.
What to double-check
Security and data
- Are production API keys, signing keys, payment credentials, and administrator accounts excluded?
- Can a preview send real email, trigger a webhook, create a charge, or modify production records?
- Are logs and error tracking separated so test data does not enter production observability systems?
- Does authentication work without weakening the access controls on the main application?
URLs and DNS
- Does each pull request receive a predictable, collision-resistant URL?
- Are wildcard DNS and HTTPS configured for the preview domain if custom subdomains are used?
- Does the application generate links using the preview URL rather than the production URL?
- Does closing a pull request remove or invalidate the associated deployment?
If a custom preview domain is involved, keep DNS changes separate from application deployment and verify the record type, target, and certificate coverage. The DNS propagation checker guide is useful when a newly created preview hostname does not resolve as expected.
Review quality
- Does the deployment run a health check after startup?
- Does the status check explain the failure and link to useful logs?
- Can reviewers identify the commit currently running at the preview URL?
- Are test instructions included for authentication, seeded data, feature flags, and expected behavior?
Common mistakes and troubleshooting
| Problem | Likely cause | Practical check |
|---|---|---|
| No preview appears | The trigger is disabled, the workflow does not run for the event, or permissions prevent deployment. | Inspect the CI event logs, repository permissions, and deployment status. Confirm that the pull request comes from an allowed branch or repository source. |
| Build succeeds but the URL fails | The start command, port, health check, routing rule, or runtime version is wrong. | Compare the preview process with the local production-like command. Check startup logs, listening ports, and the health endpoint. |
| Secrets are missing | Preview jobs use a different environment scope from production jobs, or the secret is unavailable to the pull request context. | List required variable names without printing values. Add safe defaults where possible and fail early with a clear message. |
| Every preview shows the same data | All branches point to one shared database or cache. | Include the preview identifier in database, schema, cache, and object-storage namespaces, or explicitly document the shared-data risk. |
| URLs collide or show stale builds | Resources are named from a mutable branch name, or deployment updates are not associated with the pull request. | Use the pull request number plus commit metadata where needed. Confirm that old deployments are replaced or clearly labeled. |
| DNS does not resolve | The record target, wildcard configuration, delegation, or certificate does not match the requested hostname. | Query the authoritative DNS response and compare it with the hosting target. Avoid treating a local cached response as proof of a global failure. |
For broader build, artifact, secret, and rollback diagnosis, use the CI/CD Deployment Troubleshooting Matrix. Keep deployment logs long enough to investigate failures, but avoid logging secret values or sensitive request payloads.
When to revisit
Review the preview workflow before a major framework or runtime migration, when changing hosting providers, when introducing a database or third-party integration, and before seasonal planning cycles that change repository or review volume. Recheck platform settings whenever deployment events, secret scopes, runtime support, domain configuration, or pull request permissions change.
At minimum, revisit the workflow twice a year. Confirm that old environments are actually cleaned up, temporary databases and storage objects are deleted, access lists are current, and cleanup limits still match team usage. Review whether preview builds are consuming unnecessary resources and whether the team still needs every preview to run automatically.
Use this final pre-merge checklist:
- Open a test pull request and verify that the expected deployment starts.
- Confirm the URL, commit identifier, authentication, and test data.
- Attempt a prohibited action, such as sending email or calling a production endpoint, and verify that it is blocked.
- Push a second commit and confirm that the preview updates without creating confusion.
- Close the pull request and verify that the deployment, database, DNS mapping, and temporary storage follow the cleanup policy.
- Record the owner, escalation path, and last review date in the repository documentation.
A preview environment is successful when it shortens review time without becoming an ungoverned copy of production. Keep the deployment path repeatable, isolate its data and credentials, make its status visible in the pull request, and treat cleanup as part of the deployment rather than an optional afterthought.