docs Preview Deployments
Preview Deployments
Automatic ephemeral environments for pull requests and merge requests.
How Preview Deployments Work
Preview deployments create an isolated copy of your application for each pull request (GitHub) or merge request (GitLab). When a PR is opened, DeployKit builds and deploys its head branch as a separate application with its own container and URL, redeploys it on every new push to the PR, and removes it when the PR is closed.
Enabling Previews
- In the application's General tab, check 'Auto-deploy pull requests as preview environments' and save
- Optionally set a Base domain such as example.com — each PR then gets pr-<number>.example.com (e.g. pr-42.example.com)
- Create a wildcard DNS record (*.example.com) pointing to the server that runs the app
- Make sure PR events reach DeployKit: automatic with the GitHub App; otherwise enable 'Pull requests' (GitHub) or 'Merge request events' (GitLab) on the repository webhook
Webhook setup is covered in Webhooks & CI/CD. Applications connected through the GitHub App receive PR events only through the App.
Heads up: preview domains are served over plain HTTP — wildcard certificates would need a DNS challenge. Previews also copy the parent's environment variables as-is, so a preview of a production app runs with production secrets and connects to the same databases. Use a staging application as the parent if that is not acceptable.
Lifecycle
| Event | Result |
|---|---|
| PR opened / reopened, MR opened / reopened | Preview app created and deployed |
| New commits pushed to the PR / MR | Existing preview updated to the new head and redeployed |
| PR closed or merged, MR closed or merged | Container stopped and preview app deleted |
Previews are driven only by PR / MR events — regular push events never deploy a preview app.
Parent-Child Relationship
A preview is a regular application linked to its parent and named <app-name>-pr<number>. When it is created it copies from the parent:
- Repository, build type, Dockerfile path and root directory
- Environment variables and port
- Target server and health check settings
- Source credentials — the GitHub App connection if the parent has one (no secret is stored on the preview), otherwise the parent's access token
Volumes, resource limits, replicas, autoscaling and the parent's domains are not copied. Changes to the parent apply only to previews created afterwards. Previews are never included in a configuration export.
GitHub App: PR Comments and Commit Statuses
When the parent is connected through the GitHub App, DeployKit keeps one comment on the pull request — "Deploying preview", then "Preview ready" with the URL (or "Preview failed") and a link to the deployment logs, and "Preview removed" when the PR is closed. Redeploys edit that comment instead of posting new ones. Each preview deploy also publishes a commit status under the parent's context (deploykit/<parent name>), so branch protection sees one stable check per application. Without the App, previews work the same but nothing is reported back to GitHub.
Managing Previews
The Previews tab of the parent application lists active previews with their PR number, branch, status, URL and last commit. Operators can delete a preview from there; this stops its container immediately, but the next push to an open PR creates it again.