.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Coolify GitHub integration is the part where the Git push to deploy magic actually happens. Get this right and your workflow is push, watch the build, get a green check on the PR. Get this wrong and you're stuck with manual deploys, broken webhooks or worse, no PR previews because you picked the wrong authentication method on day one.
This guide covers connecting GitHub to Coolify the right way, with the GitHub App. Includes the full permissions list, webhook configuration, the GitHub App vs Personal Access Token decision and the troubleshooting steps for when things break. Written against Coolify v4.0.0.
If Coolify isn't running yet, the LumaDock Coolify VPS ships with v4 pre-installed. The getting started guide covers initial setup.
The Coolify GitHub options at a glance
Coolify v4 supports three ways to authenticate with GitHub:
- GitHub App (recommended), full feature set including PR previews, automatic webhooks, commit status posting, granular permissions per-repo
- Personal Access Token (PAT), simpler setup, fewer features, no PR previews, no commit status
- Public Repository, no authentication, just clone over HTTPS. Works for public repos only, no auto-deploy from push
For 95% of users, the GitHub App is the right answer. The setup takes 5 minutes once and unlocks every feature Coolify has for GitHub. PATs are a fallback for very specific cases (you can't create GitHub Apps in your org due to policy or you're connecting to a self-hosted GitHub Enterprise that doesn't support Apps the way you'd expect).
Step 1, set up the Coolify GitHub App
From the Coolify dashboard, click Sources in the left sidebar. Click + Add to create a new source. From the dropdown, pick GitHub App.
Coolify shows you a form with a Create new GitHub App button that opens GitHub in a new tab with the app pre-configured. The pre-fill includes the webhook URL, the homepage URL and the redirect URL for OAuth. You only need to:
- Pick if you're installing on your personal account or on an organization
- Name the app (something descriptive like
coolify-prodorcoolify-yourcompany) - Click Create GitHub App
GitHub creates the app, sends you back to Coolify automatically. Coolify reads the App ID, Installation ID, Client ID, Client Secret and Webhook Secret from the response and stores them as the Source. From here on, every project on this Coolify instance can use this Source.
Coolify GitHub App permissions explained
Coolify pre-fills the GitHub App permissions when you create it. Worth understanding what each permission does:
Repository permissions
- Contents: Read, lets Coolify clone the repo and pull new commits. Mandatory for any deploy from Git
- Metadata: Read, mandatory for any GitHub App. Used for basic repo info
- Pull Requests: Read and Write, lets Coolify read PR events (open, close, sync) and post comments with preview deployment URLs. Required for PR previews
- Checks: Read and Write, lets Coolify post commit statuses (build success/failure) on the PR. Shows up as the green check or red X next to commits
- Deployments: Read and Write, lets Coolify create and update deployments in GitHub's deployment UI (visible on the repo's "Environments" page)
- Issues: Read, needed because GitHub treats PR comments as issue comments at the API level
Subscribed events
Coolify subscribes the App to these GitHub events:
- Push, fires when commits are pushed to any branch the App has access to. Coolify uses this to trigger auto-deploys on the configured deploy branch
- Pull request, fires on PR open, close, sync and merge. Coolify uses this to manage preview deployments lifecycle
The App doesn't need any other event subscriptions for the standard deploy + preview workflow. If you want to add custom integrations later, you can subscribe to additional events on the App's settings page on github.com.
Step 2, install the Coolify GitHub App on your repos
Creating the App on GitHub registers it with GitHub but doesn't connect it to any repos yet. You also need to install it.
From the GitHub App's settings page (you can get there from github.com/settings/apps/your-app-name or via the install link Coolify provides), click Install App. Pick the account or organization to install on, then choose either:
- All repositories, the App can access any repo in the account/org now and any new ones created later
- Only select repositories, you pick specific repos to grant access to
"Only select repositories" is the safer default. Add new repos to the App as you need them. "All repositories" is convenient for personal accounts where you trust the App with everything you own.
Once installed, your repos appear in Coolify's list when you create a new application. Click Add a new resource → Private Repository (with GitHub App), pick the Source you set up and Coolify shows you the repo list to choose from.
Step 3, deploy from a GitHub repo
With the Source connected and the App installed on a repo, the deploy flow is:
- Inside any Coolify project, click Add a new resource → Private Repository (with GitHub App)
- Select the GitHub App Source you created
- Pick the repo from the list
- Pick the branch (usually
mainormaster) - Coolify scans the repo and detects the framework (Node.js, Python, PHP, Ruby, Go, etc.)
- Configure the build pack if needed (Coolify usually auto-picks Nixpacks)
- Set environment variables and a custom domain
- Click Deploy
From now on, every push to the configured branch triggers an auto-deploy. Coolify clones the latest commit, builds, deploys and posts a commit status back to GitHub.
Auto-deploy on push, how it actually works
The mechanics behind auto-deploy:
- You push a commit to the configured branch
- GitHub fires a push event webhook to Coolify's webhook URL (something like
https://your-coolify.com/webhooks/source/github/events/manual) - Coolify verifies the webhook signature using the secret from your GitHub App
- Coolify checks if the push is to the configured deploy branch
- If yes, Coolify queues a new deployment
- Deployment runs, Coolify posts a "pending" check status to the commit, then "success" or "failure" when done
The whole flow is automatic and asynchronous. You push, you do something else, the deploy finishes, you get a notification (if you configured one) when it's done. The Coolify monitoring guide covers setting up notifications for deploy success and failure.
PR previews, the killer feature you only get with the GitHub App
This is the feature that makes the GitHub App vs PAT decision easy. PR previews require GitHub App authentication because they need the App's webhook events for pull_request and the App's permission to comment on PRs with the preview URL.
To enable PR previews on an application:
- Open the application in Coolify
- Find the Preview Deployments section in settings
- Toggle it on
- Set a domain pattern (typically
pr-{pr_number}.preview.yourdomain.com) - Set up wildcard DNS to support the pattern (the Coolify GitHub PR previews guide covers wildcard DNS in detail)
- Save
Every PR opened against the deploy branch now triggers a preview deployment with a unique URL. Coolify posts the URL as a PR comment automatically (using the Pull Requests Write permission). When the PR is merged or closed, the preview environment tears down (using the Deployments Write permission).
None of this works with a PAT. PR previews are GitHub App only.
GitHub App vs Personal Access Token
The full feature comparison:
| Feature | GitHub App | PAT |
|---|---|---|
| Auto-deploy on push | Yes | Yes (manual webhook) |
| Private repo support | Yes | Yes |
| PR preview deployments | Yes | No |
| Commit status posting | Yes | No |
| PR comments with preview URL | Yes | No |
| GitHub deployments UI integration | Yes | No |
| Per-repo install granularity | Yes | No (token has access to everything you do) |
| Token expiration concerns | No (Apps don't expire) | Yes (PATs expire by default in 2026) |
Use a PAT only if you can't create a GitHub App for some specific reason. Otherwise, the App is meaningfully better.
Connecting Coolify to GitHub Enterprise or self-hosted GitHub
If you're on GitHub Enterprise Server (the self-hosted version), Coolify supports it but the setup is slightly different. When creating the Source, Coolify lets you specify a custom GitHub URL. Use your Enterprise instance's URL there.
The GitHub App still works on Enterprise Server, the App lives on your self-hosted GitHub instance instead of github.com. Permissions are the same, the OAuth flow is the same, the webhook URL points at your Enterprise instance.
One thing to verify: your Coolify host needs to be able to reach your GitHub Enterprise instance over HTTPS. If GitHub Enterprise is on a private network and Coolify is on a public VPS, you'll need either VPN connectivity or to expose GitHub Enterprise publicly.
Multiple Coolify GitHub Apps
You can have multiple GitHub Apps connected as Sources in Coolify. Common reasons:
- One App for production deploys, one App for staging deploys, with different repo access
- One App per organization if you have repos across multiple orgs
- One App for one client's repos, one for another's, to keep them isolated
Each application in Coolify can pick which Source to use when it's created. The Source determines which repos the app can deploy from. Multiple Sources don't conflict, they're just different lists of repos with different App credentials.
Common Coolify GitHub problems and how to fix them
Webhook deliveries failing
Most common cause. Open your GitHub App's settings page on github.com, click Advanced, look at Recent Deliveries. Failed deliveries show the response code and body from Coolify's webhook endpoint.
If the failures are 4xx errors (usually 401 or 403), the webhook secret doesn't match between Coolify and GitHub. Regenerate the secret in Coolify, paste it into your GitHub App's webhook secret field on GitHub. If they're 5xx errors, Coolify's webhook handler is erroring, check Coolify's logs for the actual error. If they're timing out, your Coolify host might not be reachable from GitHub's IPs (firewall or DNS issue).
App can't see my private repo
Either the App isn't installed on the account or org that owns the repo or it's installed but with "Only select repositories" and that repo isn't in the list. Go to github.com/settings/installations, find your App, click Configure, add the repo. The repo appears in Coolify's list within seconds (the App refreshes its repo cache).
"App not found" or 404 errors during deploy
The App was deleted on GitHub or the App ID stored in Coolify doesn't match. Go to your Source in Coolify, regenerate the App credentials. If the App still exists on GitHub, you can re-fetch its credentials, otherwise create a new App and migrate.
Deploys triggering on every commit instead of just main
Your application's deploy branch is set to a wildcard or wrong branch. Open the application in Coolify, go to General, check the Branch field. It should be the specific branch you want deploys for, usually main or master. Don't use wildcards unless you specifically want every-branch deploys.
PR previews not triggering on new PRs
Either preview deployments aren't enabled on the application or the App doesn't have Pull Requests Write permission or the wildcard DNS isn't set up correctly. The PR previews guide walks through the diagnostic steps.
"Resource not accessible by integration" error
The App is missing a required permission. The most common cause is the App was created before Coolify added a new required permission and your installation hasn't been re-prompted to accept it. Go to your App's installation page on GitHub, accept the new permissions, retry the operation in Coolify.
Coolify says "Source not connected" even though the GitHub App exists
The webhook secret got out of sync between Coolify and GitHub or Coolify lost its credential storage during an upgrade. Recreate the Source: delete the broken one in Coolify, create a new GitHub App through the standard flow. Update your applications to point at the new Source. Old deploys keep working until you trigger a new one, but the new Source is now the active path.
Next steps
With GitHub connected, the natural next steps are setting up PR preview deployments (the PR previews guide covers wildcard DNS, environment scoping and resource limits), gating deploys with CI tests via GitHub Actions (the GitHub Actions CI/CD guide covers the test-then-deploy pattern) and configuring deploy notifications (the Coolify monitoring guide covers Slack, Discord and Email notifications).
If you're deploying a specific framework, the stack-specific guides cover the framework details: Next.js, Laravel, Django, SvelteKit.
