Websites
Preview Deploys For Pull Requests
Preview deploys give every pull request its own live URL, built from that branch's code, so reviewers can click through the actual change instead of reading a diff and guessing. Each preview updates when you push a new commit and is cleaned up automatically when the pull request closes.
Where Preview Deploys Live
Open Websites, click the site, open the Environments menu in the site tab strip, and choose Preview. The page is titled Preview deploys.
Previews are separate from staging. Staging is one long-lived copy of the site that you push to deliberately; a preview is a short-lived environment created per pull request and thrown away afterwards. Many teams use both. See Staging Environments for the other half.
Set Up Git Deploy First
Previews are not a standalone feature. They reuse the production site's deploy key and build command, so the site needs a working Git Deploy configuration before previews can be enabled.
If Git Deploy is not configured, the page says Set up Git deploy first and offers a Go to Git deploy button rather than the enable form. Work through Deploying a Site From Git, then come back.
If Git Deploy is connected but has no build command, the Preview page shows a warning. Previews will assume the repository is already built, with static files at the root. That is correct for a plain HTML site and wrong for anything that compiles, so set a build command on the Git Deploy page if your project needs one.
Enabling Previews
- In the Enable preview deploys card, type the repository in
owner/repoform. Not a URL, not an SSH address: just the two segments, for exampleacme/marketing-site. - Click Enable.
Anything that does not match owner/name is rejected with Repo must be in owner/name format.
Immediately after enabling, KPanel shows the webhook signing secret in a card headed Copy your webhook secret now, with a warning that you will not see it again.
Copy the secret before you leave the page. It is generated once and is not retrievable afterwards. If you lose it, the fix is to regenerate it, which invalidates the old one and means updating your repository webhook anyway.
Adding the Webhook To Your Repository
The configured card shows a Webhook URL to paste into your repository settings, under Webhooks. Configure it with:
- Payload URL: the webhook URL shown on the page.
- Secret: the value you just copied.
- Content type: JSON.
- Events: pull request events, plus pushes, so that new commits on an open pull request rebuild the preview.
Once that is in place, opening a pull request builds a preview within a few minutes. A background job checks for new preview work every minute, so there is no need to press anything in KPanel.
Preview URLs
Each preview gets its own hostname of the form pr-<pull-request-number>-<site-id>.kapsulecloud.app, covered by a wildcard certificate so it is served over HTTPS with no certificate step of your own.
The reliable way to open one is the Open button on the preview's row in Recent previews, which carries the exact URL that was provisioned for that build. Paste that link into the pull request so reviewers do not have to find KPanel at all.
Reading the Recent Previews List
The Recent previews section lists the most recent previews, newest first. Each row shows the pull request number and title, the branch, the commit, and a status:
| Status | Meaning |
|---|---|
| BUILDING | Cloning and building now |
| LIVE | Serving at its preview URL |
| FAILED | The build errored; expand the log to see why |
| DESTROYED | Cleaned up, usually because the pull request closed |
Click Toggle build log on a row to expand its build output inline. That log is the first place to look when a preview fails, and it is the same output your build would produce locally.
If the list is empty, the page says so: open a pull request on the repository and a preview will be built within minutes.
Rotating the Webhook Secret
Click Regenerate secret in the configured card. KPanel asks you to confirm, and is explicit that the current secret stops working immediately and you will need to update it in your repository's webhook settings afterwards.
The new secret is shown once, in the same one-time card as before. Copy it, then update the webhook in your repository. Between those two moments, incoming webhook deliveries are rejected, so do the two steps back to back.
Regenerate the secret when someone with repository admin access leaves, or if the secret has ever been pasted somewhere it should not have been, such as a shared chat channel or a ticket.
Turning Previews Off
Click Disable. The configuration is switched off and the stored secret is cleared. Existing previews stop being rebuilt.
Tidy up by deleting the webhook in your repository as well. It will start failing rather than doing anything harmful, but a webhook that returns errors forever is noise in your repository's delivery log.
Costs and Housekeeping
Previews build and serve real code, so they use the same resources as any other deploy on the site. Two habits keep that under control:
- Close pull requests you are no longer working on. A closed pull request has its preview cleaned up automatically.
- Do not point previews at production credentials. Give them test keys through the Secrets tab's preview environment, which exists precisely so preview and production configuration cannot be confused.
A preview URL is not private. It is a real, publicly reachable hostname with a valid certificate, and anyone who has the link can open it. Do not use a preview to review anything containing real customer data, and do not seed preview environments from a production database dump.
Troubleshooting
Nothing is built when a pull request is opened. Check the webhook's recent deliveries in your repository. A 401 or 403 means the secret does not match, so regenerate it and update both ends. No delivery at all means the webhook is not subscribed to pull request events.
The preview builds but shows a directory listing or a 404. The output directory on the Git Deploy page does not match where your build actually writes. Previews inherit that setting from production.
The build fails only in the preview. The most common cause is a dependency or an environment variable that exists in production but was never added to the preview environment. Check the preview tab on the Secrets page.
A preview URL stops working. Look at the status on its row. DESTROYED means the pull request closed and the environment was reclaimed, which is the intended behaviour.
Where To Go Next
- Deploying a Site From Git, the prerequisite configuration.
- Storing App Secrets For a Site for per-environment credentials.
- Staging Environments for a persistent pre-production copy.