GitHub Preview Deploy

Preview deployments allow Coolify to automatically deploy new versions of your application whenever someone opens a pull request (PR) on your GitHub repository.

These preview deployments are automatically deleted once the associated pull request is merged or closed, ensuring a clean environment.

Features

• Scoped Deployments: Control who can trigger PR preview deployments.
• Scoped Secrets: Keep production and preview environment variables separate.
• Automated Comments: Post deployment status updates directly on pull requests.

Preview Deployments Options

• Preview URL Template: Each preview deployment gets its own unique URL based on this template.
  • Use {{random}} to generate a random subdomain each time a PR is deployed.
  • Use {{pr_id}} to use the pull request ID as the subdomain.

• Load Pull Requests: Allows you to manually fetch all open pull requests on your repository. This is useful if you already had open PRs before setting up preview deployments.

Scoped Deployments

If anyone can trigger a new preview deployment by creating a pull request, they could run arbitrary code directly on your environment, potentially gaining access to your environment or secrets.

Coolify allows you to configure who can trigger new preview deployments to prevent this:

• Preview Deployments: Enables the Preview Deployments feature, and only repository members, collaborators, and contributors can trigger PR deployments.
• Allow Public PR Deployments: Anyone can trigger PR deployments.

Scoped Secrets

Coolify separates environment variables for production and preview deployments, keeping your secrets safe.

• Production Environment Variables: These variables are used only in your main deployment. They remain fully isolated and are never exposed to preview deployments triggered from pull requests.
• Preview Deployment Environment Variables: A separate set of variables used only for PR-based preview deployments. These variables can safely contain non-sensitive or limited-scope values, ensuring contributors' pull requests cannot access production secrets.

Automated Comments

Coolify posts comments on pull requests with the deployment status and automatically updates them if the status changes.

Setup Methods

There are two methods to set up preview deployments on Coolify:

• Using GitHub App
• Using Webhooks

Setup Using GitHub App

We have a dedicated guide for setting up the GitHub App, so please follow it first: /applications/ci-cd/github/setup-app.

As part of the setup, ensure Preview Deployments is configured correctly. The steps differ depending on whether you use Automated or Manual setup, as shown below.

---

If you have already set up the GitHub App without enabling the "Preview Deployments" feature, follow these steps:

1. In your Coolify dashboard, click on Sources from the sidebar, then select your GitHub App.
2. Click the Update button in the "Permissions" section (this will redirect you to GitHub).

3. Under the "Permissions" section, click on "Repository permissions".
4. Set access to Read and write for Pull Requests.
5. Scroll down to the "Subscribe to events" section.
6. Enable the Pull requests option.

---

Setup Using Webhooks

1. Enter a GitHub webhook secret (this must be a random string; you can use tools like Random String Generator).
2. Save the webhook URL somewhere safe—we'll need it later.

3. Go to your repository settings page.
4. Click on Webhooks from the sidebar.
5. Click the Add webhook button.

6. Enter the previously copied webhook URL from Coolify in the "Payload URL" field.
7. Enter the webhook secret from Coolify in the "Secret" field.
8. Enable "Enable SSL verification".
9. Select "Let me select individual events".
10. Select "Pull Requests".
11. Enable "Active".
12. Click the Add webhook button.

After clicking "Add webhook", you'll see a page like the one shown below:

That's it! Coolify will automatically deploy preview deployments when a new pull request is created.