Pull-request previews — sometimes called review apps, deploy previews, or ephemeral environments — are the part of a modern PaaS that closes the loop between "I opened a PR" and "my designer can click around the change". On Launchverse every open pull request on a connected repository gets its own fully-isolated environment, its own URL, and its own teardown lifecycle. This guide walks through what that means in practice and how to use it without surprises.
What a preview environment actually is
When a PR is opened (or reopened) on a repository connected to a Launchverse project, the platform:
- Creates a brand-new application in the build engine — not a clone of your production app, a dedicated app with its own container and hostname.
- Copies the parent project's environment variables onto the preview app so it boots in the same shape as production.
- Pins the preview to the PR's head branch and head commit.
- Builds the commit and serves it on a unique URL — typically
<project>-pr-<n>.launchverse.online. - Records the preview in the Previews tab on your project, where the URL, status, last commit, and a one-click promote-to-production button live.
A push to the same PR head branch (synchronize in GitHub terminology) redeploys the same preview app with the new commit. The URL stays stable across pushes, so reviewers can keep the tab open all day.
When the PR is closed or merged, the preview enters a 24-hour closing grace window so reviewers can still poke at a freshly-merged PR, and is then garbage-collected by a scheduled cron. On the Hobby cron tier this means a preview lives between 24 and 48 hours after the PR closes; on a higher cron tier we tighten it.
What's isolated, what's shared
Isolated from production:
- The container itself — a separate build, a separate runtime, separate memory and CPU budgets.
- The hostname — the preview URL points only at the preview container, never at the production container.
- The build artifact — promoting a preview does not "switch the active build slot", it kicks off a clean re-deploy on the production app pinned to the preview's commit.
Shared with production (deliberately):
- Environment variables. The preview reads your project's env vars at build time so you don't have to maintain a parallel
stagingset. Variables that should differ between preview and production should be split using the per-environment scoping in the Environment tab. - Attached resources. By default a preview talks to the same managed Postgres / Redis / marketplace services your production talks to. This is usually what you want for a five-minute design review and not what you want for destructive testing. See "When a preview should have its own data" below.
- Custom domains. Custom domains stay attached to production. Previews always use the platform
*.launchverse.onlinehostname.
When a preview should have its own data
Sharing the production database is fine for visual / UX review. It is not fine when the PR makes destructive schema changes, mutates data, or executes seeders. Two safe patterns:
- Read-only preview. Pass a
READ_ONLY=trueenv var (scoped to preview only) and have your application skip writes when it's set. Cheapest option; works for almost all front-end + display-side PRs. - Preview-only database. Provision a second managed database on the same project, expose its connection string as
DATABASE_URLonly on the preview environment, and let it diverge from production. This costs an extra resource but gives you a fully-isolated sandbox.
For migration-heavy PRs you almost certainly want pattern 2. Combine it with a pre-deploy hook (see the zero-downtime deployments guide) so the migration runs against the preview database before the preview container starts.
Lifecycle states
Every preview row in the Previews tab is in exactly one of these states:
| State | What it means |
|---|---|
creating | The first deploy of this PR has been queued but the engine hasn't acknowledged the build yet. Visible for seconds to ~a minute. |
active | The preview is live and reachable on its URL. Subsequent pushes redeploy it in place. |
closing | The PR closed/merged and the preview's grace window has started. Still reachable until garbage-collected. |
deleted | The engine application has been deleted. The row stays as audit history. |
failed | The first deploy hit a hard error. The row carries an error string explaining what went wrong. |
A preview can transition failed → active once the underlying bug is fixed and the PR is pushed again; the same row is reused.
Promoting a preview to production
When the preview build is the one you want live, open the preview row and hit Promote to production. What happens under the hood:
- We look up the exact commit SHA the preview was last built against.
- We re-deploy the project's main production application pinned to that commit (no rebuild loop — the engine reuses the cached image layers from the preview build).
- The promotion shows up in your Deployments feed as a normal deploy row, with realtime SSE logs, a status pill, a Cancel button, and the deploy-finished email.
The preview itself stays open so you can still reference it on the merged PR. If the PR then closes/merges, the preview goes through the same 24-hour grace + GC as any other closed-PR preview.
Caps, limits, billing
PR previews count against your plan's concurrent-deploy limit while they're building, and against a separate per-team cap on simultaneously-open preview environments. The cap exists so a single deployer hammering "Open PR" cannot bury your project's host with 50 preview apps. New PRs past the cap show a clear error in the Previews tab; the next PR can open as soon as an older one closes.
Builds for previews bill build minutes against your team exactly the same way production builds do. The container itself does not bill while it's idle — preview containers scale to zero idle CPU just like any other Launchverse application. The line item to keep an eye on is the per-team-month sum of preview build minutes, which the Usage tab breaks out alongside production build minutes.
Toggling previews off
If you don't want previews on a particular project, head to Settings → Engine and flip the toggle off. The toggle is two-state:
- Off — no preview is created when a PR opens. Pushes to the head branch are tracked in your Deployments tab as
Skipped. Production auto-deploy on the trigger branch is unaffected. - On (default for Student / Pro / Enterprise) — previews open and tear down automatically as described above.
The Free plan defaults previews off and the toggle is hidden; production-only auto-deploy is the only mode on Free.
Common questions
Does the preview URL persist after the PR is merged? For 24–48 hours, yes. After the GC sweep deletes the engine app the URL stops resolving.
Can I rebuild a preview manually? Yes — push a new commit to the PR head branch (or use the GitHub "Re-run workflows" button if your repo uses Actions). We deliberately don't expose a manual "rebuild preview" button because it nudges you off the git-as-source-of-truth model.
Why is the preview URL *.launchverse.online and not my custom domain? Custom domains route only to production. Wiring a preview to your real domain would either invalidate TLS or send live customers at a half-tested commit. If you genuinely need a customer-facing preview (e.g. for a stakeholder demo) attach a separate domain to a dedicated staging project rather than reusing production's domain.
What if my preview reads/writes the production database? That's the default. See the section above on isolated preview data.
Can I disable the 24-hour grace window? Not at the toggle level — it's there so a freshly-merged PR doesn't 404 while the reviewer's last tab is still open. If you have a regulatory reason to tear down preview state instantly, hit Delete on the preview row manually after merge; the engine app is deleted within the same request.