On this page
Pull request previews
A web service built from a GitHub repository connected to Kilby can have a preview of every pull request into the branch it deploys. A preview is a service of its own: it runs the pull request's code at its own address, so the change can be tried before it is merged.
Previews need a repository connected through the GitHub App (see Deploy from Git): pull requests reach Kilby through the App's webhook. A service built from a public repository by its address cannot have previews.
Turn them on#
Open the service, then Previews, and switch on Deploy a preview for every pull request. With the REST API: PATCH /api/v1/services/<id>/previews with {"enabled": true}.
From then on, for every pull request into the service's branch:
- Kilby builds the tip of the pull request's branch and runs it as a new service named after the service and the pull request, such as
my-api-pr-42, at an address likemy-api-pr-42-x7k2.apps.kilby.neuramorphic.ai. - It writes one comment on the pull request with the preview's address and state (building, live, failed), and keeps that comment up to date.
- Every new commit to the pull request is built and deployed to the same preview.
- The preview is removed when the pull request is closed or merged, after 7 days without a new commit, when previews are turned off, or when you remove it (Remove in the Previews tab, or
DELETE /api/v1/previews/<id>). The comment then says why.
The workspace's Previews page lists every preview of every service.
What a preview copies, and what it never does#
A preview starts from the service's settings, on the safe side of every choice:
| In a preview | |
|---|---|
| Code | The tip of the pull request's branch. |
| Variables | The service's variables, except the ones that look secret: a name with KEY, TOKEN, SECRET, PASSWORD, PRIVATE, DSN or CREDENTIAL in it, or a value such as an API key or a URL with a password in it. The Previews tab lists the ones left out. Turn on Copy the secret ones too to copy them all. |
| Variables for previews | Optional variables that every preview gets on top of the copied ones, and that win over them: a DATABASE_URL of a staging database, for example. |
| Databases | None of the service's, unless a copied variable or a variable for previews points to one. A database URL with its password is one of the secret-looking variables, so by default a preview reaches no database. Kilby never copies a database's data into a preview. |
| Environment groups, secret files, disks, custom domains | Never copied. |
| Instance type | Starter, unless you choose another for previews. One instance, no autoscaling. |
| Pre-deploy command | Not run, unless you turn on Run it in previews: it would run against whatever the preview's variables point to. |
| Build variables | Copied like the variables: without the secret-looking ones unless you copy secrets. |
Kilby also sets KILBY_PREVIEW=true and KILBY_PULL_REQUEST (the pull request's number) in a preview, and with Render compatibility on, IS_PULL_REQUEST=true (see Environment).
The settings apply to previews made after you save them; a preview that runs keeps what it was made with.
Pull requests from forks#
A pull request from a fork never gets a preview: its code would run with the service's variables, and anyone can open one. The pull request gets a comment that says so. To get a preview, push the branch to the repository itself.
Limits and price#
| Plan | Previews running at once |
|---|---|
| Hobby | None: previews are part of Pro and Scale |
| Pro | 5 |
| Scale | 20 |
| Beta | 2 |
A pull request that would go over the limit gets a comment that says so, and no preview. Previews count toward the workspace's CPU and memory, but not toward its number of services. Each preview runs and is metered like a service while it exists, at the price of its instance type. The pull requests of one service can start at most 30 builds an hour.
Related#
- Deploy from Git: connecting a repository through the GitHub App.
- Environment: the variables Kilby sets,
KILBY_PREVIEWandKILBY_PULL_REQUESTamong them. - Limits: what each plan runs.