Pull request preview environments: a live URL for every PR

A pull request preview environment is a temporary, running copy of your service built from a pull request’s branch, with its own URL. On Voroa, you turn previews on once per service. After that, every pull request from a branch in the same repository gets a preview automatically, every push to it updates the same URL, and Voroa removes the preview when the pull request is closed or merged.

Reviewers click a link and use the change, instead of reading a diff and imagining what it does.

The short version:

1. Open your service and go to Previews.
2. Turn the switch on.
3. Add any preview variables the app needs, such as a test database URL.
4. Open a pull request against the branch the service deploys.
5. Copy the preview URL from the Previews tab and share it with your reviewers.

Why use preview environments

• Review the running app, not just the code. Designers, product managers and clients can check a change without cloning the repository.
• Catch problems before they reach main. A broken build or a page that will not load shows up in the preview, before the change is merged, not in production.
• No shared staging queue. Each pull request gets its own copy, so two changes never overwrite each other on one staging server.
• Nothing to clean up. Previews disappear on merge, on close, or when their lifetime ends.

Preview environment vs staging environment

Many teams use both: previews to review each change, and a long-lived staging service for release testing. On Voroa, a staging setup is a second environment in your project, with a service that deploys a staging branch.

What you need

• Your service is connected to a GitHub repository.
• Your plan includes preview environments. Each plan sets how many can run at once; the Free plan does not include them.
• Preview environments are turned on for that service (they are off by default).

Turn previews on

1. Open your service and go to Previews.
2. Read the summary — how many your plan allows, how long a preview lives, and what it does and does not receive from your real service.
3. Turn the switch on.

Nothing happens immediately. The next pull request you open creates the first preview.

Open a pull request

Open a pull request whose target is the branch this service deploys (usually main). Within a few minutes the Previews tab shows the pull request number, its branch, and a link.

Push another commit to the same pull request and the same URL updates with the new code. The address never changes while the pull request is open, so you can paste it into the PR description or a chat once and it keeps working.

What a preview does and does not have

This is deliberate: a preview runs code that has not been reviewed yet, so it must not hold production credentials.

Because previews carry no production configuration, a preview may fail to start where your real service runs fine. That is usually a missing setting, not a broken build — add what it needs as a preview variable.

Preview variables

Your service’s previews often need a little configuration to run: a database to talk to, a test API key. Preview variables are values you set once, on the service, that are given to every preview of that service and to nothing else. Your real service never sees them.

Add them on the Previews tab, under Preview variables:

1. Type the name (for example DATABASE_URL) and the value.
2. Tick Needed at build time if your build reads it, not just the running app.
3. Select Add variable.

Add many at once

• Paste .env: select Paste .env, paste the contents of a .env file (one KEY=value per line; comments and export are fine), then select Save pasted variables. Everything is saved in one go.
• Import from live service: copies your service’s own environment variables into its preview variables. The copy happens on Voroa’s side; no value is sent to your browser, and only the names are shown. By default a preview variable you already set is kept; tick Import replaces existing preview variables to overwrite it. Variables from shared environment groups and secret files are not imported.

Your Voroa database URLs are not imported. If a value is a connection URL for one of your Voroa databases, it is skipped and named in the result, so a preview never starts out pointed at your real data. Add a test database value yourself. Only full connection URLs are recognised: separate settings such as a database host or password are copied like any other variable, and so is a URL for a database hosted elsewhere. Check them after importing.

If previews are already running, they rebuild straight away with the new value. Otherwise it is used the next time a preview builds.

A few things worth knowing:

• Values cannot be read back. They are stored encrypted, and nothing can show you one again. You can replace a value or remove it, but you cannot look at it. Only the names are shown.
• PORT is managed for you and cannot be set. Read the port from your environment as usual.
• These are separate from your service’s own environment variables. Changing one never affects the other.

Point previews at a test database, never your production one

A preview runs the code from a pull request. That code has not been reviewed yet, and it may run migrations, delete rows, or write test data. If you give it your production database, it will do those things to your real data.

Use a separate database for previews — a spare Voroa database, or a test database with your existing provider.

If the value points at a database on your Voroa account, we recognise it and ask you to confirm, naming the database so you can tell whether you meant it. If your database is hosted somewhere else we have no way to tell a production database from a test one — the connection string looks the same either way — so there is no warning in that case. Please check the value before you save it.

When a preview goes away

A preview is removed when any of these happens, whichever comes first:

• the pull request is closed or merged;
• it reaches its lifetime (72 hours after the last push, by default), whether or not the pull request is still open;
• you remove it yourself from the Previews tab.

Removal is permanent. If you need it back, push a commit to the pull request — or reopen the pull request — and a fresh preview is created.

Limits

Each plan sets how many preview environments can run at once. When you are at that number, a new pull request will not create one and the Previews tab says so. Close or remove a preview you no longer need, or move to a plan with a higher allowance.

Previews run on the smallest service size and are not charged separately.

Things previews do not do yet

• Pull requests from forks do not get previews. A fork’s code comes from outside your repository, so Voroa will not build it.
• Preview URLs are not password-protected. They are not listed anywhere public, but anyone with the address can open one. Do not use a preview to review something confidential.
• Voroa does not post a comment on your pull request. Copy the URL from the Previews tab.

Troubleshooting

Nothing appears after I open a pull request. Check three things: the switch is on for this service; the pull request targets the branch this service deploys; and the pull request comes from a branch in the same repository, not a fork. If all three are right and you are at your plan’s limit, the tab will say so.

The tab says new previews are paused for this workspace. Previews have been paused on your workspace by Voroa. Anything already running stays listed and you can still remove it. Contact support if this is unexpected.

My preview starts but cannot connect to its database. A preview does not inherit your service’s environment variables, so it has no connection string unless you gave it one. Add a preview variable with the details of a test database, then push a commit or save the variable to rebuild.

The preview says it needs attention. The preview is running, but its secure connection is not ready. It usually clears itself within a few minutes. If it does not, contact support — the preview keeps running in the meantime and will be removed at the end of its lifetime as usual.

A setting I changed on the preview did not save. Previews are managed by Voroa and cannot be edited: their branch, build settings, environment variables, domains and size all come from the service they were created from. Change the service instead, then push to the pull request.

Frequently asked questions

Which plans include preview environments?

Paid plans do; the Free plan does not. Each plan sets how many previews can run at the same time, and the Previews tab shows your limit.

Do preview environments cost extra?

No. Previews run on the smallest service size and are not charged separately. The only limit is how many can run at once on your plan.

Do previews get my production environment variables?

No. A preview receives no environment variables or secret files from your service, because it runs code nobody has reviewed yet. Give previews what they need with preview variables, and point them at a test database, never your production one.

Can a preview environment have its own database?

Voroa does not create one automatically. Create a separate test database, for example a spare managed PostgreSQL database, and add its connection URL as a preview variable named DATABASE_URL.

Do pull requests from forks get previews?

No. A fork’s code comes from outside your repository, so Voroa does not build it on your account. Previews are created only for pull requests from branches in the same repository.

How long does a preview environment last?

Until the pull request is closed or merged, or 72 hours after its last push, whichever comes first. Each new push restarts the 72-hour clock. Push a commit or reopen the pull request to get a fresh preview after it is removed.