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. On the project's Overview it is a box of its own, drawn dashed, beneath the environment its pull request targets and indented under it — unless an environment that uses that one stands between them, which is drawn first so its line passes through no other box; the preview then follows at full width; right-click the box, or open the ellipsis in its header, for Open preview, View pull request and Preview settings. Nothing can be added to it there.
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. |
| Success, something to look at | Deployed · needs attention | The preview is live, and something this pull request reads is not configured for it. The check stays green; the body says what. |
| 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. |
Beneath the summary, the check's body lists what the pull request changed about the application — a variable it began reading, a service it started using, a database it now requires — and what each means for the preview. It is written as soon as the commit has been analysed, which happens beside the build, and written again when you set a variable on the preview, so a check that said Deployed · needs attention reads Deployed once everything is configured. A push whose analysis finishes after the deployment does the same: the title changes, the conclusion never does.
The check needs the GitHub App's Checks: write permission. Without it, previews still deploy; only the check is missing.
What changed in this pull request
Every push is analysed beside its build and compared with the commit the pull request branched from. On the Overview, the preview's box says how much changed and how much of it needs attention beside its branch — feature · 3 changes · ⚠ 2 need attention — and the cards inside it wear New, Changed or Removed for what the pull request did to them: a service the pull request began using, a component whose variables changed, a service it stopped using. A resource card says no more than that; the box's count and its panel say what needs attention. The count and the chips appear only inside a preview's box, because they say what the pull request did relative to its base; Production and named environments keep their findings in their panels. Until every service's commit has been analysed the box reads Analysing, and a missing name is as loud as it was.
A variable is referenced by a service, never required by it: reading a name proves the code reads it, not that the application cannot run without it. Only a resource the code connects to is required.
Select the box to read the whole account: what the code began reading or using, what that means for this preview, and Set variable beside anything the preview is missing. Application changes has the details, and what Kuppit does and does not decide for you.
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. A variable the pull request begins reading that the preview does not have — or one Production has that the preview did not inherit — is listed under the preview's Application changes, with Set variable beside it.
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.