Preview environments

What you get

Turn previews on for a site and every pull request against its repository gets a deployment of its own, on its own subdomain, torn down when the pull request closes. The preview is a real site. It copies the parent's repository, runtime, build settings, deploy hooks, and health check, and builds the pull request's own branch.

The hostname is the pull request number, never the branch name. A branch name can contain anything a Git ref can contain, and a hostname cannot.

pr-482.shop.example.com   # pull request #482 against the site at shop.example.com

Four things are not copied from the parent. The preview gets no aliases, because sharing the parent's hostname list would let it capture production traffic. It runs as its own Unix account, never the parent's. It does not deploy on push to the parent's branch. The pull request drives it. And it gets its own environment file, never production's.

The preview environment file

Previews are off until you write one, and the switch stays disabled until you do. A preview built from production's .env would put a throwaway environment behind your live database, your live payment keys, and your live mail sender, on a hostname anybody who can open a pull request can create.

The file is write-only. You can replace it, but nothing can read it back, and there is no endpoint that returns it: not the app, not a token, not Provisore. It is encrypted the same way a site's own environment versions are, and it is capped at 64 KB.

APP_ENV=preview
APP_DEBUG=true
DB_DATABASE=preview
DB_PASSWORD=throwaway
MAIL_MAILER=log

Limits and expiry

Two of these are yours to set and two are fixed. The per-team and per-server caps exist to stop one misconfigured repository filling a server, and a number anybody can raise would not do that.

Per site        5 by default, up to 20        # yours
Time to live    72 hours, 1 to 720           # yours, measured from the last push
Per team        20                           # fixed
Per server      10                           # fixed
Absolute life   14 days from creation        # fixed, and overrides the time to live

The time to live runs from the last activity (opening the pull request, pushing to it, or redeploying it by hand), so an environment somebody is still using does not expire underneath them. The absolute lifetime does not reset, which stops a long-lived pull request holding a slot for a month.

Pull requests from forks are refused by default. A fork pull request is code from outside your organisation, and deploying it runs that code on your server. You can allow them per site.

When a request cannot be met (a cap reached, a fork not allowed, a hostname that would not be valid, no environment file, the server not active), the pull request is listed as blocked with the reason.

HTTPS, when the parent has a wildcard

A preview does not issue a certificate of its own. One per pull request would spend your Let's Encrypt rate limit on environments that live for three days. Instead it uses the parent site's wildcard certificate, when the parent has an active one that covers the preview hostname.

When the parent has no such certificate, the preview serves plain HTTP and says so, rather than serving a vhost that names certificate files that are not there. A vhost pointing at missing files fails Nginx's configuration test, and a failed test takes down every other site on that server. So a missing certificate costs this preview its HTTPS and nothing else.

Teardown

Closing the pull request destroys the environment, merged or not. So does the expiry, and so does the Destroy button under Preview environments in the site’s Settings. All three go through one path, which refuses to act on anything that is not a preview. The site's kind is written once when it is created and can never be changed, and the delete path re-reads it from the database and stops if it disagrees.

Teardown keeps working if your subscription lapses. Destroying frees resources, and an environment that stopped being cleaned up would fill your disk over an unpaid invoice.

Limits

• GitHub only. Previews are driven by GitHub pull request events through the Provisore GitHub App. There is no GitLab or Bitbucket path.
• A draft pull request is treated like any other. Opening one deploys an environment and takes a slot. Marking a pull request ready for review, or converting it back to a draft, changes nothing.
• Nothing is posted back to GitHub. No comment carries the preview URL. The hostname is listed under Preview environments in the site’s Settings.
• DNS is best effort. If Provisore manages your DNS it creates and removes the record, but a provider outage at that moment leaves a preview that does not resolve until the next push, or a record left behind after teardown.
• On the Pro and Scale plans.