Coolify has two different webhook systems. A deploy webhook is called by a CI job and requires the application’s webhook URL plus an API token with the Deploy permission. A repository webhook is called by GitHub or GitLab when code is pushed and uses a Git-provider webhook secret. Choosing the wrong path is the most common reason an otherwise valid setup does nothing.
Antihost offers VPS plans with one-click Coolify, NVMe storage and a 14-day free trial.
This guide covers both configurations, including the exact Coolify screens, secret handling, GitHub App behavior, GitLab’s manual setup, verification, and the failure cases that commonly stop automatic deployments. Menu names can vary between Coolify releases; the linked documentation is the authority for your installed version.
As an Amazon Associate I earn from qualifying purchases.
Choose the webhook that matches your deployment flow
Start by deciding which system should initiate the deployment. If a build, test, approval, or release workflow should decide when Coolify deploys, use the CI-to-Coolify deploy webhook. If every push to a repository branch should notify Coolify directly, use a repository webhook.
| Characteristic | Deploy webhook (CI to Coolify) | Repository webhook (Git host to Coolify) |
|---|---|---|
| Caller | GitHub Actions, GitLab CI, Forgejo Actions, or another CI runner | GitHub or GitLab |
| Authentication | API token sent as an Authorization: Bearer header |
Shared webhook secret configured in Coolify and the repository |
| Trigger | Whatever event starts your CI workflow | Push events; GitLab can also send merge-request events for previews |
| Coolify configuration | API access, token, and the application’s Deploy webhook URL | Provider-specific source configuration, webhook URL, secret, and Auto Deploy where required |
| Manual setup | Always required for the token and CI request | Not required for a GitHub App source; required for manual GitHub and GitLab webhooks |
Do not combine the credentials: an API token does not replace a GitLab or GitHub webhook secret, and a repository secret does not authorize a CI deploy-webhook request.
#1 Best Overall
Set up a Coolify deploy webhook for CI
The deploy-webhook URL identifies one Coolify application. The API token authorizes the request. Both values are required.
1. Enable API access on self-hosted Coolify
On a self-hosted installation, the API is disabled by default. Sign in as an administrator and open Settings → Advanced → API Settings. Turn on API Access and save the setting. Coolify Cloud already has API access enabled. If this switch is off, a correctly formed request and a correctly copied token still cannot trigger a deployment. The official integration guidance is at Coolify’s CI/CD documentation.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
2. Create a token with the Deploy permission
- Open Keys & Tokens → API Tokens.
- Select Add (or the equivalent create action), enter a description that identifies the pipeline, and set an expiry appropriate for your rotation policy.
- Select the Deploy permission. A token without this permission cannot invoke the deploy webhook.
- Create the token and copy it immediately. Store it in your secret manager; do not put it in a workflow file, commit, issue, or build log.
Use a separate token for each pipeline or environment when practical. That makes revocation and auditing less disruptive than sharing one long-lived credential everywhere.
3. Copy the application’s Deploy webhook URL
Open the target application in Coolify and select Webhooks. Copy the Deploy webhook URL for that application. A URL copied from another application will authenticate successfully only if the token is valid, but it will start a deployment for the application represented by that other URL.
Rank #2
4. Save the URL and token as CI secrets
The Coolify documentation uses the names COOLIFY_WEBHOOK for the URL and COOLIFY_TOKEN for the token. Add both as encrypted repository, project, or environment secrets in your CI system. Keeping them out of YAML prevents accidental disclosure through source control and makes rotation possible without editing the workflow.
5. Call the webhook from the workflow
The following GitHub Actions example shows the documented request pattern. The same two environment variables can be used in GitLab CI, Forgejo Actions, or another runner that can execute curl.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →name: Deploy to Coolify
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Trigger Coolify deployment
env:
COOLIFY_WEBHOOK: ${{ secrets.COOLIFY_WEBHOOK }}
COOLIFY_TOKEN: ${{ secrets.COOLIFY_TOKEN }}
run: |
curl --fail --silent --show-error
--header "Authorization: Bearer ${COOLIFY_TOKEN}"
"${COOLIFY_WEBHOOK}"The command deliberately reads both values from the runner’s secret store. Do not echo either variable for debugging. If your Coolify release documents an explicit HTTP method or additional header, follow that release’s example; the essential authorization format is the Bearer token shown above.
6. Verify the first deployment
- Push a change that matches the workflow trigger, or run the workflow manually if your CI platform supports that option.
- Confirm that the CI step runs and does not print an HTTP failure. With
--fail, a non-success response makes the step fail instead of appearing successful. - Open the application’s deployment activity in Coolify and confirm that a new deployment was created for the expected commit.
- If the workflow runs on several branches, verify that each branch is intentionally allowed to deploy. Use separate workflows or environment-specific secrets when production and staging must be isolated.
Rotate or revoke the CI credential
Create a replacement token with the Deploy permission, update the CI secret, run a controlled deployment, and then revoke the old token. Replacing the secret first avoids an outage while the old credential is being retired. If a token may have appeared in logs or source control, revoke it immediately rather than waiting for its expiry.
Configure GitHub push webhooks
GitHub setup depends on the source type selected in Coolify. A native GitHub App source and a public-URL or deploy-key source do not behave the same way.
GitHub App source: no manual webhook
When the application uses Coolify’s native GitHub App source, the app configures the required webhook automatically. A push to the selected branch then triggers a redeploy, so adding a second webhook in the GitHub repository is unnecessary and can create duplicate notifications. The provider-specific instructions are in Coolify’s GitHub Actions documentation.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsIf pushes do not deploy with a GitHub App source, first confirm that the application is actually connected through the App rather than through a deploy key or public URL, and then check the branch and source settings in the application. Do not assume that a manual webhook is required simply because the repository has no visible webhook entry.
Public URL or deploy-key source: add a manual webhook
- In the Coolify application, open Configuration → Webhooks.
- Enter a long, random value in GitHub Webhook Secret and save the configuration.
- Copy the GitHub URL shown under Manual Git Webhooks.
- In GitHub, open the repository and go to Settings → Webhooks → Add webhook.
- Paste the Coolify URL into the payload URL, enter the exact same secret, and enable push events. Save the GitHub webhook.
The secret must match character for character. Generate it with a password manager or a cryptographically secure generator, and keep it private. The URL alone is not the authentication mechanism for this manual path.
Test the GitHub path
Use GitHub’s webhook delivery view to send a test delivery, then push a small change to the branch tracked by the Coolify application. A successful delivery only proves that GitHub reached the URL; confirm separately that Coolify accepted the secret and created a deployment. If the delivery is accepted but no deployment appears, inspect the application’s source, branch, and Auto Deploy settings rather than creating another webhook.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallConfigure GitLab push webhooks
For a manual GitLab repository webhook, Coolify and GitLab must share the same secret, and Auto Deploy must be enabled in the application.
Manual GitLab webhook procedure
- Open the application in Coolify and select Configuration → Webhooks.
- Copy the displayed GitLab webhook URL.
- Enter a strong value in GitLab Webhook Secret and save it. Keep a secure record of the value; Coolify rejects requests when the token is missing or does not match.
- In GitLab, open the project and go to Settings → Webhooks.
- Paste the Coolify URL, enter the identical secret token, and enable Push events. Save the webhook.
- If the application uses preview deployments, also enable Merge request events so the relevant GitLab event reaches Coolify.
- Back in Coolify, open Configuration → Advanced and enable Auto Deploy.
These steps are documented in Coolify’s GitLab integration guide and its manual webhook guide. A push event can be delivered successfully by GitLab while Auto Deploy remains disabled; in that case the network request works but no automatic deployment is scheduled.
GitLab source authentication and access tokens
A third-party setup guide describes a GitLab personal access token created under Settings → Access Tokens with the api and read_repository scopes for a GitLab source. The guide is older and its screens were not verified against every current Coolify release, so treat this as a version-dependent source-connection requirement, not as a substitute for the webhook secret. Check the current Coolify and GitLab screens before granting scopes. The secondary reference is AZDigi’s integration guide.
GitLab App warning: “managed automatically” may be misleading
A reported Coolify issue describes GitLab App sources whose Webhooks page says webhooks are “managed automatically” even though Coolify does not create a webhook in the GitLab project. In that situation, no project-level webhook exists until you add it yourself. Check each GitLab project and add the manual webhook when necessary. The issue’s current status was not confirmed, so verify the behavior in your Coolify version before relying on the label: Coolify issue #11602.
Understand secrets, events, and deployment boundaries
API token versus webhook secret
CI deploy webhooks use an API token in an HTTP authorization header. Repository webhooks use a shared secret that the provider sends with the event. They are independent credentials with different rotation paths. If you paste a repository secret into COOLIFY_TOKEN, Coolify will reject the request; if you paste an API token into GitLab’s secret-token field, the repository webhook will not be authenticated as intended.
Push deployment versus controlled release
A repository webhook is appropriate when every qualifying push should deploy without an intermediate pipeline decision. A CI deploy webhook is better when tests, image builds, migrations, approvals, or a release tag must complete before deployment. You can use both for different applications or environments, but avoid attaching both mechanisms to the same production application unless duplicate deployments are intentional.
Branch and preview planning
Keep the provider event aligned with the application’s source and branch configuration. Use push events for a persistent staging branch, and add GitLab merge-request events only when the application is configured for preview behavior. For production, a CI workflow can gate the deploy-webhook call on tests or an approval step instead of exposing production to every push.
Troubleshoot a webhook that does not deploy
| Symptom | Likely cause | What to check |
|---|---|---|
| CI request returns an authorization error | API access is disabled on self-hosted Coolify, the token is expired, or it lacks Deploy permission | Enable Settings → Advanced → API Settings → API Access; create a fresh token with Deploy permission; replace the CI secret. |
| CI job succeeds but the wrong application deploys | The webhook URL belongs to another application | Copy the URL again from that application’s Webhooks page and update COOLIFY_WEBHOOK. |
| CI job runs but the secret variable is empty | The secret was created at the wrong repository, project, or environment scope | Check the secret names exactly: COOLIFY_WEBHOOK and COOLIFY_TOKEN. Confirm the workflow is allowed to read environment-protected secrets. |
| GitHub delivery is successful but no deployment appears | The source is a GitHub App, a manual webhook points at the wrong URL, or the event targets an unconfigured branch | Identify the source type in Coolify, remove an unnecessary duplicate manual hook for an App source, and verify the manual URL and branch configuration. |
| GitLab reports a rejected or unauthorized webhook | The secret is missing or differs between GitLab and Coolify | Copy the value again into both GitLab Webhook Secret and GitLab’s secret-token field, save both sides, and resend the delivery. |
| GitLab delivery succeeds but nothing deploys | Auto Deploy is off, or the event type does not match the application’s workflow | Enable Configuration → Advanced → Auto Deploy; enable push events, and add merge-request events when previews require them. |
| GitLab App page says hooks are automatic, but the project has none | The behavior described in issue #11602 may affect the installed version | Inspect the project’s Settings → Webhooks page and add the Coolify URL and secret manually if no hook exists. |
| Deployments happen twice | Both a CI deploy webhook and a repository webhook are calling the same application | Choose one trigger for that environment or separate the applications and branches deliberately. |
Security and maintenance checklist
- Use HTTPS URLs and never place tokens or secrets in public issue comments, screenshots, workflow output, or committed files.
- Grant CI tokens only the Deploy permission and give them an expiry date.
- Use long, random, independently generated secrets for GitHub and GitLab manual hooks; do not reuse a password or another project’s token.
- Keep production and non-production credentials separate so a staging workflow cannot deploy production accidentally.
- After changing a webhook secret, save the Coolify value and the provider value, then send a test delivery before relying on the hook.
- When a credential is exposed, revoke or replace it immediately and review recent deployment activity.
- Document which mechanism owns each application. This prevents a future maintainer from adding a second hook to “fix” a problem caused by a disabled Auto Deploy setting or a missing API permission.
Which Coolify webhook should you use?
Use the CI deploy webhook when deployment is the final action of a controlled pipeline. Enable API access on self-hosted Coolify, create an API token with Deploy permission, store the token and application URL as CI secrets, and send the Bearer-authorized request. Use a repository webhook when GitHub or GitLab should deploy directly on push: GitHub App sources normally manage their own hook, while manual GitHub and GitLab setups require a matching secret; GitLab also requires Auto Deploy to be enabled. Confirm which source type and Coolify version you are using before following the screen-by-screen path, especially for GitLab App projects.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
