Skip to the page
KilbyDocs
Build and run View as Markdown
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:

  1. 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 like my-api-pr-42-x7k2.apps.kilby.neuramorphic.ai.
  2. 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.
  3. Every new commit to the pull request is built and deployed to the same preview.
  4. 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
CodeThe tip of the pull request's branch.
VariablesThe 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 previewsOptional 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.
DatabasesNone 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 domainsNever copied.
Instance typeStarter, unless you choose another for previews. One instance, no autoscaling.
Pre-deploy commandNot run, unless you turn on Run it in previews: it would run against whatever the preview's variables point to.
Build variablesCopied 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#

PlanPreviews running at once
HobbyNone: previews are part of Pro and Scale
Pro5
Scale20
Beta2

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.

  • Deploy from Git: connecting a repository through the GitHub App.
  • Environment: the variables Kilby sets, KILBY_PREVIEW and KILBY_PULL_REQUEST among them.
  • Limits: what each plan runs.