# 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](/docs/deploy-from-git.md)): 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//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/`). 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](/docs/environment.md)). 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](/docs/deploy-from-git.md): connecting a repository through the GitHub App. - [Environment](/docs/environment.md): the variables Kilby sets, `KILBY_PREVIEW` and `KILBY_PULL_REQUEST` among them. - [Limits](/docs/limits.md): what each plan runs.