Deploy a preview for each pull request
Turn on pull request previews for a project so every same-repository pull request gets its own environment, deployed from its branch and deleted when the pull request closes or goes idle.
A preview is a short-lived environment that NebulaCtrl clones from a base environment for one pull request. You review the change running on its own deployment before you merge.
Before you begin
- Connect a Git provider and deploy at least one service from the repository the pull requests target. See Deploy from Git and Git providers and registries. GitHub, Forgejo and GitLab connections deliver pull request events.
- Have a base environment: a non-production environment of the project that is bound to a cluster. A preview never clones a production environment or another preview. If the project has no such environment, the settings show "Create a non-production environment first."
- Hold the
adminrole or higher to change preview settings or to close a preview by hand. Theviewerrole can read the settings. - If your GitHub connection predates previews, approve the new pull request permission. Settings > Integrations shows a warning titled "Approve the new pull request permission on GitHub to enable previews" with a Review on GitHub button. Until you approve it, no preview is created for that connection. Pushes still deploy.
Turn on previews
Open the project, open the environment menu in the top bar, and select Environment settings…. The panel has a section named Pull request previews.
Turn on Previews. Two rows appear: Base environment and Expire idle previews after.
Under Base environment, choose the environment to clone. Only non-production environments are listed.
Under Expire idle previews after, choose 1 day, 3 days or 7 days. The default is 3 days.
Select Save. A toast reads "PR previews on": "The next same-repository pull request gets its own environment."
You can also open the environment menu in the top bar, select + New environment, choose PR previews, pick the base environment and lifetime, and select Enable PR previews.
If the base is production, the API answers 422 with baseEnvironmentId set to the offending field and a message that asks for a non-production environment. Turning previews on without a base returns 422 with "is required to enable previews; pick the environment previews are cloned from".
Changing the settings never touches previews that already exist. They keep the lifetime they were created with.
What a pull request creates
Open a pull request from a branch of the same repository. NebulaCtrl creates an environment named pr-NUMBER, where NUMBER is the pull request number. It appears under Pull request previews in the environment menu as "PR #NUMBER · BRANCH · expires in 3 days".
NebulaCtrl starts a build of every service in the project that tracks the repository, from the pull request's head commit. A service with an image push trigger waits for the externally built tag instead.
Push more commits to the branch. Each push builds and deploys, and restarts the idle clock.
The preview has auto-deploy on and tracks the pull request's head branch. The Environment settings… panel of a preview shows the pull request, its branch and when it Expires.
What the preview copies from the base environment:
| Copied | Not copied |
|---|---|
| The cluster binding | Domains |
| Environment variables and service variables, secrets included | Releases |
| External resources | |
| Per-environment settings: process, volume and service overrides |
A service that tracks a different repository gets no build in the preview. See Variables for how variables resolve.
NebulaCtrl posts a commit status named nebulactrl/pr-NUMBER on the head commit for builds and deployments. Its link opens the service's Deployments tab in the preview.
A preview is not a protected environment, so its deployments need no approval and a deploy freeze does not apply.
Close a preview
A preview is deleted when:
- The pull request is closed or merged. NebulaCtrl deletes the preview as soon as the provider reports it.
- The preview sits idle past its lifetime. The lifetime counts from the last push to the pull request, or from creation before the first push. NebulaCtrl checks every 5 minutes.
To delete one earlier:
Closing a preview deletes its namespace and everything the preview owns. The pull request is untouched. A later push to the open pull request creates a new preview from the base environment.
Open the environment menu in the top bar. Under Pull request previews, select the ✕ next to the preview.
In the dialog titled "Close pr-NUMBER?", select Close preview. A toast reads "Closed pr-NUMBER".
The same operation over the API is deleteEnvironment (DELETE /api/v1/environments/ENVIRONMENT_ID).
Limits
- Only pull requests from the same repository get a preview. A pull request from a fork never does, because it would build and run code the organization has not reviewed with the base environment's variables.
- One preview per pull request and project. If several projects track the repository, each creates its own.
- A pull request opened before you turned previews on gets its preview at its next push, or when it is reopened.
- The idle lifetime is one of 1, 3 or 7 days.
- If the base environment is bound to no cluster, the preview is created but nothing is built.
If a pull request creates no preview, check Settings > Integrations. A connection whose last webhook delivery was declined shows Last delivery failed. A fork, previews switched off for the project and a repository no service tracks all decline the delivery.
Verify
- Open a same-repository pull request.
- Open the environment menu.
pr-NUMBERis listed under Pull request previews. - On the pull request, the commit shows a
nebulactrl/pr-NUMBERstatus. It turns green when the deployment is healthy.
Next steps
Roll back or promote a release
Roll a service back to a release that ran before, redeploy its active release, or promote a release's image to another environment, from the console or the API.
Approve changes and set deploy freezes
Decide pending approvals for protected environments, set the organization's change policy, skip approval for one service, schedule weekly deploy freezes and cap concurrent deployments in a project.