# Pull request preview environments

Pull request preview environments need their own variables, a database that is not production, and cleanup when the pull request closes.

Canonical URL: https://unbroker.cloud/blog/pull-request-preview-environments
Published: 2026-10-31
Reviewed: 2026-10-31
Author: Unbroker

## The short answer

Give each pull request its own preview, with variables that are not production secrets, a database that is not production, and a cleanup when the pull request closes.

The usual failure is not a preview that will not start. It is a preview that works because it is talking to production. The three questions below are how you keep that from happening. How to turn the feature on for a Next.js app is on [Deploy Next.js with pull request previews](https://unbroker.cloud/deploy/nextjs). If you are leaving Railway, the [Railway alternative](https://unbroker.cloud/alternatives/railway) is the comparison, and previews on Unbroker require Pro.

## What a preview environment is

A preview environment runs the code from a pull request so a person can open it before merge. Staging is one shared environment for the release you are about to ship. A preview is disposable and belongs to that pull request.

### Preview per pull request vs one shared staging

One staging environment is easy to keep, and every open pull request shares its data and its variables. A preview per pull request lets two changes stay apart, and you have to clean each one up. On Unbroker, a project has production, custom, and preview environments. Names such as staging, qa, and dev are colored as their own environments. Since October 14, 2026, pull request previews are preview environments of the project, not separate projects.

### Other names

Heroku calls the same idea review apps: a disposable app that runs the code in a GitHub pull request and has a URL you can share. Other hosts say preview deployments or ephemeral environments. Those names are not a price comparison. This post does not restate anyone else's rates.

## 1. Variables: what a preview should and should not get

A preview should get test API keys, sandbox webhook URLs, and a database that is safe to wipe. It should not get production passwords.

On Unbroker, a service or project variable is All, Production, or Preview. A value scoped to an environment overrides All for the same key. Existing variables stay on All until you change them. A new preview copies All and Preview, and it never copies Production-only values. An existing preview keeps the copy it already has. Changing the label to Production does not pull a secret back out of a preview that already received it. Remove it there, or recreate the preview, and rotate the credential if it may have leaked. Service variables, shared project variables, public build prefixes, and rotation are in [environment variables and secrets](https://unbroker.cloud/blog/environment-variables-and-secrets).

GitHub Actions, except for `GITHUB_TOKEN`, does not pass secrets to a workflow that a fork triggers. Unbroker does not create automatic pull request previews for branches outside the connected repository, because that code could read the preview's secrets. You can still review a fork by other means. Do not solve that by putting production secrets in All.

<aside class="plan-box">
<p><strong>On Unbroker.</strong> Scope production credentials to Production. Point previews at a staging database or a test API key with Preview. Pull request previews require Pro. The rules are in the <a href="https://docs.unbroker.cloud/deployments/environment-variables">environment variable docs</a>.</p>
</aside>

## 2. Databases: what your preview talks to

The preview runs whatever connection string you gave it. Private traffic inside Unbroker stays in the same organization and the same environment, so a preview cannot reach production pods that way. A URL you paste into a variable is not that private network. If the string is production, the preview is on production data.

### A shared staging database

Every preview talks to one database you are willing to break. Setup is one variable. A migration in any pull request changes that schema for all of them. Seed data gets messy as soon as two branches write.

### A fresh database per pull request

Each pull request gets an empty database and a seed. Schema changes stay in that pull request. You have to create the database, load the seed, and delete it with the pull request. Unbroker's docs do not say the product creates that database for you. The home page draws a new database on a pull request. That picture is not a documented behavior, so this post does not claim it.

### Migrations

Run a migration only against the database that preview is allowed to change. Pointed at the shared staging database, it changes staging for everyone. Pointed at production, it changes production. [Postgres in production](https://unbroker.cloud/blog/postgres-in-production) is where restore and rollback of data are separated from a code rollback. Running that migration once, before the release is live, is [database migrations on deploy](https://unbroker.cloud/blog/database-migrations-on-deploy).

<aside class="plan-box">
<p><strong>On Unbroker.</strong> Choose the database with a Preview-scoped variable. Do not put the production connection string in All. The product does not document a database created per pull request.</p>
</aside>

## 3. Lifecycle: builds, cleanup, and what is left behind

Opening or updating a pull request creates or updates the preview when previews are enabled on the service. Closing the pull request tears the stack down. Merging removes it too. A preview that stopped halfway is picked up again. A cleanup task also removes expired previews. Activity on a preview refreshes a seven-day expiration.

Manual deploys, deploy hooks, and pull request previews ignore watch paths. A preview still builds when the pull request updates, even if the change sits outside the paths that would skip a push to the production branch. Which branch that push deploys, and when it waits for GitHub checks, is in [Deploy on git push](https://unbroker.cloud/blog/deploy-on-git-push). Previews inherit the service's access protection and its Wait for CI setting. They only run code from branches in the connected repository.

Unbroker does not publish a separate price for a preview. Previews require Pro. This post does not invent a charge per hour or per pull request.

Traffic for a project can be filtered to production or to preview. That view requires a paid plan and a cell that collects traffic.

<aside class="plan-box">
<p><strong>On Unbroker.</strong> Previews are preview environments of the project. Close or merge the pull request and the preview is removed. The Git deployment note is in <a href="https://docs.unbroker.cloud/deployments/git">Deploy from Git</a>, and the October 14 changelog is the one that moved previews onto the project.</p>
</aside>

## Previews and coding agents

An agent can open a pull request that looks finished and still points at the wrong database. Review that pull request in a preview that cannot read production. Then merge.

How to give the agent a token, and what that token must not see, is in [Letting a coding agent deploy safely](https://unbroker.cloud/blog/coding-agent-deploy-safely). The production checklist for the app itself is on [Deploy an app built with Cursor](https://unbroker.cloud/deploy/cursor). Neither page is repeated here.

## Preview environment checklist

Do these before the first pull request from someone other than you. Each line is one check.

1. Turn on pull request previews only on a plan that includes them.
2. Put production secrets in Production, not in All.
3. Give the preview test API keys and sandbox webhooks.
4. Point the preview at a database you can wipe.
5. Do not paste the production connection string into a Preview variable.
6. Decide whether previews share a staging database or get a database you create per pull request.
7. Run migrations only against that chosen database.
8. Close a test pull request and confirm the preview is gone.
9. Rotate any secret that an old preview already copied.
10. Review an agent's pull request in that preview before you merge it.

## How it works on Unbroker

Pull request previews require Pro. Variables are All, Production, or Preview, and a new preview copies All and Preview only. Previews are environments of the project, not separate projects. Closing or merging the pull request removes the preview. A preview interrupted halfway is picked up again. What Pro includes is on [pricing](https://unbroker.cloud/pricing). The deployment map is the [deployments overview](https://docs.unbroker.cloud/deployments/overview). The Git tutorial is [Deploy from Git](https://docs.unbroker.cloud/guides/deploy-from-git).

## FAQ

### What is a pull request preview environment?

It is a running copy of the branch in a pull request, kept apart from production, so you can open that change before you merge it. On Unbroker, opening or updating a GitHub pull request creates or updates that preview when previews are enabled for the service. Closing or merging the pull request removes it.

### What's the difference between a preview environment and staging?

Staging is one shared place for the next release. A preview is tied to one pull request and goes away with that pull request. On Unbroker, staging is a named environment of the project. Pull request previews are preview environments of that same project, not separate projects.

### Should preview environments use production environment variables?

No. A preview that can read production secrets can also be read by whoever can open the pull request. On Unbroker, a new preview copies All and Preview variables and does not receive Production-only values. Put a production database credential in Production, not in All, unless you mean for previews to see it.

### What database should a preview environment use?

Not production. A shared staging database is simple and can be damaged by one pull request's migration. A fresh database per pull request, loaded with seed data, stays isolated and you have to create it. Unbroker's docs do not say that each preview receives its own database. You choose the database with a Preview-scoped variable.

### How do I run database migrations in a preview environment?

Run them only against the database that preview is allowed to change. A migration pointed at a shared staging database changes that schema for every other preview. A migration pointed at production changes production. The docs do not describe an automatic database per pull request.

### What happens to a preview environment when the pull request is closed?

On Unbroker, closing the pull request tears down that preview's stack, and merging removes it too. A preview that was interrupted halfway is picked up again. Activity on the preview refreshes a seven-day expiration, and a cleanup task removes expired previews.

### Do preview environments cost money while they run?

Unbroker does not publish a separate preview price. GitHub pull request previews require Pro. This page does not invent a per-preview charge.

### How do I review a coding agent's pull request safely before merging?

Open the agent's pull request in a preview that has no production credentials and no production database. Read what changed, then merge. The steps for giving an agent a token are in the coding-agent post, not repeated here.

## Related reading

- [Deploy Next.js with pull request previews](https://unbroker.cloud/deploy/nextjs)
- [What Pro includes](https://unbroker.cloud/pricing)
- [Production checklist for AI-built apps](https://unbroker.cloud/deploy/cursor)
- [Letting a coding agent deploy safely](https://unbroker.cloud/blog/coding-agent-deploy-safely)
- [Postgres in production](https://unbroker.cloud/blog/postgres-in-production)
