DEPLOYING

Preview environments

Give every pull request its own running copy of the application, with its own URL, torn down on merge.

A preview environment is a running copy of your application built from a pull request’s branch, on its own URL, created when the PR opens and destroyed when it closes. Reviewers click a link instead of checking out a branch.

A preview is a real application

It is not a special lightweight mode. DockBoard duplicates the source application’s configuration into a new application, so a preview inherits the same build pipeline, the same permission checks, the same quota admission and the same teardown path.

That reuse is the design. A bespoke “preview deploy” would be a second implementation of build-and-run that drifts from the real one — and the first thing to drift is always a security check.

The only things the preview layer adds on top: which branch it builds, what hostname it answers on, and when it dies.

The shared database

Environment variables are copied along with the configuration, which means a preview points at the same database as its source application. This is a review environment for a branch, not an isolated stage.

The alternative — stripping the environment — sounds safer and is worse: an application whose configuration was emptied usually fails to boot, and “previews are broken” is the conclusion everybody reaches.

Say it out loud to your team: an unreviewed branch can write to real data through its preview. If that is unacceptable for a given application, point its previews at a separate database with a per-environment variable set, or do not enable previews on it.

That shared database is exactly why previews are created with their cron jobs disabled. A schedule copied along would run an unreviewed branch’s migration or purge against the real data — once per open pull request. See schedules and cron.

Creation and teardown

01Enable previews on the application and connect the Git provider.
02A pull request opens. DockBoard clones the configuration, builds the PR’s branch and assigns a hostname derived from the PR number.
03Each new push to that branch redeploys the preview, exactly like a normal application.
04The pull request merges or closes. The preview and its DNS entry are removed.

A preview can also be destroyed by hand at any time — from its own page, or from the source application’s Previews tab.

Limits

Ten previews per source application. A repository with sixty open pull requests must not be able to turn one merge storm into sixty concurrent builds. The project quota would stop it eventually, but with an opaque error at pull request number forty-one.
Previews consume the project’s quota like any other application — CPU, memory, application count. Ten previews of a heavy application is a real budget.
They land on the same server as their source application.

Previews or a CI deploy?

These solve different problems, and picking the wrong one costs you a pipeline nobody needed:

You want	Use
A running copy per pull request, for review	Previews. DockBoard creates and destroys them itself — no CI wiring at all.
A push to `main` to redeploy production, and the pipeline to fail when the deploy fails	Deploy from CI with a two-scope API key.