Deploying
Preview environments
An app built from a repo can get a preview app per open pull request (GitHub) or merge request (GitLab), built and deployed at every push and deleted when the request is closed or merged.
Turning them on
In the app's Settings tab (GET/PUT /api/apps/{id}/previews): on or off,
a domain, and variables that differ in previews.
Each preview is served at <app>-pr-<n>.<domain>, so point a wildcard DNS
record (*.preview.example.com) at the servers. Each preview gets its own
Let's Encrypt certificate like any domain, or, when the preview domain is a
wildcard domain, one wildcard certificate for all of them
(Domains), which spares Let's Encrypt's
weekly limit.
Turning previews on updates the app's webhook to send pull (merge) request events as well as pushes; like push webhooks, it needs the panel's public URL (Builds). Turning them off deletes the previews open.
What a preview is
When a request is opened (or reopened), an app named <app>-pr-<n> is
made (the app's name cut short so the host fits 63 characters) with:
- the app's repo, at the request's branch, its directory, Dockerfile and build template;
- the app's variables with the preview ones on top;
- the app's variable groups, copied again at every push so it follows changes to them;
- the app's port and health check, one replica;
- its domain under the preview domain.
Not its database links, processes, release command or volumes: a preview reaches the app's data only if its variables say so, and its migrations don't run against the app's database. Point it at a test database with the preview variables.
It's built at the request's head right away, and again at every push to
the request (a change of title alone builds nothing), and deployed when
built. A comment on the request says where it is, once, when it's made:
the git account's token needs to write to pull requests for that (a
classic GitHub token with repo does; a fine-grained one needs Pull
requests: write), and it's skipped quietly otherwise.
When the request is closed or merged, the preview's app is deleted like any app: its containers stopped, its domain released. Deleting the app deletes its previews.
Forks
Requests from a fork are ignored: the preview would run the fork's code with the app's variables, which hold its secrets. Only branches of the repo itself, pushed by people who can push to it, get previews.
In the panel
Previews are apps like any other, marked as previews in the apps list and on their page (with a link to their request); the app's Settings tab lists those open. They're in the app's project (Roles and projects) and show in alerts like any app.