Preview environments
A preview environment is a copy of your Production service, deployed from a pull request's branch on a hostname of its own. Kuppit creates it when the pull request opens, redeploys it on every push, and removes it when the pull request closes. Nothing about it is configured by hand.
What a preview contains
A preview is deliberately smaller than Production:
- One web service, copied from Production: the same name, the same build settings, the same Dockerfile path, deploying the pull request's head branch.
- No database. Previews are created from pull requests and are meant to be disposable, and copying production data into every pull request is the accident this rule prevents. A service in a preview that references a database therefore has nothing to reference; see variables below.
- Nothing else. Every other component of the project is recorded as deliberately absent, and a resource cannot be added to a preview from the dashboard.
The preview is named after the pull request, PR #42, and appears in the environment selector as #42 · <branch> while it exists.
Hostname
A preview's hostname is Production's hostname with the environment's slug in front. For a project named acme whose service is web:
acme-a1b2c3.kuppit.app Production
pr-42-acme-a1b2c3.kuppit.app PR #42
The pr-<number>- prefix is reserved, so a project name can never collide with a preview. The hostname is kept when the pull request closes, and a reopened pull request comes back on the same URL.
The check on the pull request
Kuppit reports through a GitHub check run named Kuppit Preview on the pull request's commit, updated in place as the deployment moves. It never posts a comment.
| State | Title | Summary |
|---|---|---|
| In progress | Deploying… | Kuppit is building and deploying this pull request. |
| Success | Deployed | The preview for this pull request is live at https://pr-42-….kuppit.app. |
| Failure | Build failed, or Deployment failed | Which phase failed. Open the deployment in Kuppit for the logs. |
| Refused | No preview | Why no preview was created, for example that previews are turned off for the project. |
The check needs the GitHub App's Checks: write permission. Without it, previews still deploy; only the check is missing.
Variables in a preview
When a preview is created, or a closed pull request is reopened, Kuppit copies the service's variables from Production:
- Non-secret literals are always copied.
- Secrets are not, unless the project's Give previews the production secrets setting is on. Code in an open pull request can read anything the preview receives, which is why the default is off.
- References are dropped, because a reference can only target a resource in the same environment and a preview has no database.
The copy happens once, at creation. A variable changed in Production afterwards does not change the preview, and a variable set directly on the preview's service survives every later push. Turning the secrets setting on applies to previews created or reopened afterwards, never to one already running.
Settings
The project's Settings has two switches:
- Create previews for pull requests. On by default. Every pull request gets its own environment and its own URL, cleaned up when the pull request closes.
- Give previews the production secrets. Off by default, as above.
Pull requests from forks never get a preview, whatever the settings say. The check on the pull request says so.
When the pull request closes
Closing or merging the pull request removes the preview immediately: routing is withdrawn first, then the service and its images are destroyed, and the environment disappears from the selector. The cleanup runs even if previews have since been turned off, and a push to the branch after the close does not bring the preview back. Only reopening the pull request does.
Deployment history and the hostname are kept. Kuppit learns about a close from GitHub's delivery, so a pull request closed while the GitHub App was uninstalled is not discovered later.
Limits
Each plan allows a number of preview environments to exist at once in a project. A pull request opened beyond that number gets a No preview check saying so. Only a preview that does not already exist counts, so a push to an open pull request is never refused. The numbers are provisional during the alpha.