The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Coolify supports two different webhook patterns. A deploy webhook is called by a CI workflow 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 changes; it uses a shared webhook secret and can redeploy on pushes. Choosing the correct pattern first prevents most setup errors.
Antihost offers VPS plans with one-click Coolify, NVMe storage and a 14-day free trial.
The steps below cover Coolify Cloud and self-hosted installations, GitHub App sources, manual GitHub webhooks, and GitLab projects. Menu labels can vary between Coolify releases because no single version is established by the available documentation.
As an Amazon Associate I earn from qualifying purchases.
Choose the webhook that matches your deployment flow
Use a CI deploy webhook when a pipeline should decide when deployment occurs—for example, after tests, a build, or an approval. Use a repository webhook when every qualifying push should notify Coolify directly.
| Characteristic | CI deploy webhook | Repository webhook |
|---|---|---|
| Who starts the request? | GitHub Actions, GitLab CI, Forgejo Actions, or another workflow | GitHub or GitLab after a repository event |
| Coolify endpoint | The application’s Deploy webhook URL | A GitHub or GitLab URL shown under the application’s webhook configuration |
| Authentication | API token sent as Authorization: Bearer …; token must include Deploy |
Shared secret configured in Coolify and in the git host |
| Typical trigger | A workflow decides when to call Coolify | Push events; merge-request events can be added for GitLab preview deployments |
| Automatic management | You maintain the CI workflow and its secrets | GitHub App sources configure webhooks automatically; manual setups do not |
Coolify’s documentation describes the CI pattern in its GitHub Actions guide and the repository pattern in its manual webhook guide.
#1 Best Overall
Map each credential to its job
Three values are often confused because they can appear in the same application settings area:
- Deploy webhook URL: identifies the Coolify application that should be redeployed. It is used by a CI request and is different for each application.
- Coolify API token: authorizes a CI request. It is sent in an
Authorization: Bearerheader and must have the Deploy permission. - GitHub or GitLab webhook secret: authenticates an incoming repository event. It must match character-for-character in Coolify and the git host.
A GitLab source can also require a repository access credential. That credential allows Coolify to read repository data; it does not replace the webhook secret or the CI API token.
Recommended Free Tools
Prepare Coolify and protect your credentials
Self-hosted: enable API access
On a self-hosted installation, the API is disabled by default. Sign in as an administrator and open Settings → Advanced → API Settings. Tick API Access and save. Without this setting, an otherwise valid API token cannot authorize a CI deployment. Coolify Cloud already has API access enabled. The API and token workflow is documented in the other CI-provider documentation.
Keep URLs, tokens, and secrets out of source control
- Store the deploy URL and API token in your CI provider’s encrypted repository or project secrets.
- Do not paste a bearer token or webhook secret into a committed workflow file, issue, build log, or chat message.
- Give a token an expiry date and rotate it when staff, repositories, or runners change.
- Use a long, randomly generated value for a manual webhook secret rather than a memorable phrase.
- Use separate credentials for separate applications or pipelines when you need to revoke one deployment path without affecting others.
- When replacing a secret, update both sides of a manual webhook configuration and then send a controlled test event.
Set up a CI deploy webhook
This route is appropriate when a pipeline—not the git host’s webhook service—should call Coolify. The request identifies the application through its webhook URL and proves authorization with an API token.
1. Create an API token with Deploy permission
- In Coolify, open Keys & Tokens → API Tokens.
- Choose Add (or the equivalent create action), enter a description that identifies the repository or pipeline, and set an expiry.
- Select the Deploy permission. A token without this permission cannot trigger the webhook.
- Create the token and copy it immediately. Treat it like a password; the value may not be shown again.
The permission and token flow are specified in Coolify’s GitHub Actions documentation.
2. Copy the application’s Deploy webhook URL
- Open the target application in Coolify.
- Go to Webhooks.
- Copy the Deploy webhook URL. This URL is application-specific, so use the URL belonging to the application you intend to redeploy.
Do not substitute a repository webhook URL for the Deploy URL. The CI endpoint expects the API-token authorization flow, while a manual GitHub or GitLab endpoint expects a shared secret from the git host.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →3. Add both values to CI secrets
Coolify’s examples use the names COOLIFY_WEBHOOK for the URL and COOLIFY_TOKEN for the token. You can use different names, but keeping the names consistent with your workflow makes troubleshooting easier.
At minimum, the secret store must provide the URL and token to the job that performs the deployment. Keep them at the repository or project level appropriate for the application, and make sure the job context is allowed to read protected secrets.
4. Call the URL from the workflow
A minimal GitHub Actions job looks like this:
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 --show-error --location
"$COOLIFY_WEBHOOK"
--header "Authorization: Bearer $COOLIFY_TOKEN"The same request pattern can be used from GitLab CI, Forgejo Actions, or another system that can run curl; the Coolify documentation presents it as a general CI technique rather than a GitHub-only feature. Keep the URL and token in that system’s secret store and expose them to the command only at runtime.
The workflow can run after whatever checks your team requires. The webhook call itself starts the Coolify deployment; it does not replace your test, build, approval, or release stages. Put the call in the job that represents the point at which deployment is authorized.
Free tools Windows power users keep installed
One-click scans. No signup required.
5. Trigger and verify a deployment
- Push a change to the branch monitored by your workflow, or run the workflow manually if your CI provider supports manual dispatch.
- Confirm that the workflow step completes without exposing the token in its log.
- In Coolify, open the application’s deployment view and verify that a new deployment was queued and then reached its normal build and health states.
- If the workflow reports an HTTP failure, inspect the response status while keeping the
Authorizationvalue masked. A successful CI step only proves that the request was accepted; check the Coolify deployment record for the application result. - Record which application and branch were tested so a later credential rotation can be validated against the same target.
Common CI webhook mistakes
- API access is off: enable it under Settings → Advanced → API Settings on self-hosted Coolify.
- Wrong permission: recreate or edit the token so it includes Deploy; repository-read or unrelated permissions are insufficient.
- Wrong application URL: copy the Deploy URL from the specific application rather than from another service or environment.
- Secret is empty: verify that the workflow context is allowed to read repository secrets. Some CI systems withhold secrets from untrusted pull-request jobs.
- Token was copied incorrectly: create a replacement token and update the secret instead of adding whitespace or printing the old value.
- Expired token: inspect the token expiry in Coolify and replace it before rerunning the pipeline.
- Confusing success states: an accepted HTTP request is not the same as a completed deployment; always inspect the application’s deployment history.
Configure GitHub push deployments
GitHub App source: no manual webhook
When the application uses Coolify’s native GitHub App source, the app configures the webhook automatically. Select the branch for the application and let GitHub send push events through the app; you do not need to create a repository webhook yourself. This behavior is described in the Coolify GitHub documentation.
If pushes do not redeploy, first verify that the application is connected to the intended GitHub App installation and repository, then check the selected branch and the application’s deployment history. Creating a second manual webhook can produce duplicate events and is unnecessary for this source type.
Public-URL or deploy-key source: create a manual webhook
- Open the application in Coolify and select 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 the GitHub repository, open Settings → Webhooks and add a webhook using that URL.
- Enter exactly the same secret value that you saved in Coolify. Configure the repository event so GitHub sends push notifications, then save.
The URL and secret form a pair: the URL tells Coolify which application should receive the event, while the secret lets Coolify validate that GitHub generated it. If either value is copied from a different application, the push will not deploy the intended service.
Use this manual path when the application is connected through a public URL or deploy-key source rather than the native GitHub App. If you later switch source types, review the old repository webhook so the application does not receive both an automatically managed event and a manually configured event.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsConfigure GitLab push and merge-request webhooks
Manual GitLab repository webhook
- In Coolify, open the application and go to Configuration → Webhooks.
- Copy the displayed GitLab webhook URL.
- Set a GitLab Webhook Secret and save it.
- In GitLab, open the project and choose Settings → Webhooks.
- Paste the Coolify URL and enter the identical secret token.
- Enable Push events. If the application uses preview deployments, also enable Merge request events.
- In Coolify, open Configuration → Advanced and enable Auto Deploy.
Coolify rejects GitLab webhook requests when the secret token is missing or does not match. The event settings, secret requirement, and Auto Deploy control are covered in the GitLab integration documentation.
GitLab webhooks are configured at the project level. If several projects deploy to Coolify applications, repeat the URL-and-secret setup for each project and verify that each URL belongs to the intended application.
GitLab source authentication: distinguish it from the webhook secret
A GitLab source may also need credentials to read a private repository. A secondary guide says to create a GitLab personal access token under Settings → Access Tokens with the api and read_repository scopes. That guide is older and its screen names have not been verified against every current Coolify release, so treat it as a source-specific credential requirement rather than a replacement for the webhook secret. The guide is available at AZDigi’s Coolify CI/CD article.
These credentials serve different jobs:
- The GitLab access token, when required by the selected source integration, lets Coolify access repository data.
- The GitLab Webhook Secret authenticates incoming event notifications from GitLab.
- A CI API token with Deploy permission is a separate credential used only by the CI deploy-webhook pattern.
GitLab App projects that do not receive an automatic webhook
A reported GitHub issue describes GitLab App sources whose Coolify Webhooks page says webhooks are “managed automatically” even though no webhook is created in the GitLab project. Webhooks exist per GitLab project, and the issue says the workaround is to add the webhook manually in each affected project. The issue’s current status can change, so check your Coolify release and project settings before assuming the app created anything: coollabsio/coolify issue #11602.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
After adding the project webhook, confirm that the same GitLab Webhook Secret is saved in Coolify and GitLab, then enable the required event types. A label claiming automatic management is not proof that a project-level webhook exists.
Understand branches, pushes, and previews
A webhook notifies Coolify of an event; the application configuration still determines what code is deployed. Confirm that the application points to the expected repository and branch. A push to another branch may be received successfully but produce no deployment for the application’s configured branch.
For GitLab preview environments, enable merge-request events in addition to push events. Push events cover branch updates; merge-request events provide the event type needed for preview workflows. Keep Auto Deploy enabled in Configuration → Advanced when you want accepted events to start deployments automatically.
Rank #4
Branch selection is therefore a separate check from authentication. A matching secret can prove that GitLab or GitHub sent the event, while the repository and branch settings decide whether the event applies to this application.
How the two authentication models differ
| Question | CI deploy webhook | Manual repository webhook |
|---|---|---|
| Where is the credential stored? | In the CI provider’s encrypted secret store | In Coolify and the repository or project webhook form |
| What proves authorization? | An API token with the Deploy permission | A matching shared webhook secret |
| What causes a request? | A workflow step you control | A push or, for GitLab previews, a merge-request event |
| What must be maintained? | Workflow logic, secret names, token expiry, and the application URL | Repository URL, secret, event checkboxes, Auto Deploy, and branch configuration |
| Who manages the hook? | Your CI configuration | Coolify manages it for GitHub App sources; you manage it for manual integrations |
This distinction helps when diagnosing a failure. An unauthorized CI request points toward API access, token permission, expiry, or the URL. A rejected GitLab event points toward the project webhook and shared secret. An accepted event with no deployment usually points toward Auto Deploy, branch selection, or the application’s repository mapping.
Troubleshoot a webhook that does not deploy
| Symptom | Likely cause | What to check |
|---|---|---|
| CI call is unauthorized | API access is disabled or the token lacks Deploy permission | On self-hosted Coolify, enable API Access; inspect the token’s permissions and expiry. |
| CI call targets the wrong app | URL was copied from another application | Reopen the intended application’s Webhooks page and replace COOLIFY_WEBHOOK. |
| GitHub push does nothing | Manual secret mismatch, wrong repository URL, or branch mismatch | Compare the Coolify secret and GitHub secret character-for-character, confirm the webhook belongs to the correct repository, and check the configured branch. |
| GitLab reports rejection | Missing or incorrect GitLab Webhook Secret | Set the same secret in Coolify’s Configuration → Webhooks and GitLab’s project webhook form. |
| GitLab App says managed automatically, but no event arrives | The project webhook was never created | Inspect the project’s Settings → Webhooks page and add the Coolify URL and secret manually if needed. |
| Webhook is accepted but no deployment starts | Auto Deploy is disabled or the event does not match the application | Enable Configuration → Advanced → Auto Deploy, verify the branch, and enable merge-request events when previews require them. |
| Deployments happen twice | Both a GitHub App webhook and a manual webhook are active | Use the automatically managed App path or the manual path, not both, and remove the duplicate repository webhook. |
| Pushes from one branch deploy but another does not | The application tracks only its configured branch | Review the application’s repository and branch configuration; receiving an event does not make every branch deploy. |
| Only pull-request jobs fail to call Coolify | The CI provider withholds secrets from untrusted jobs | Run the deploy step in a trusted branch or release workflow that is permitted to read the encrypted secrets. |
| Deployment history is unchanged after a green CI step | The request was accepted by the shell but did not reach the intended application | Check the URL secret, masked response status, and Coolify’s deployment record rather than relying only on the CI job status. |
Operational checklist before relying on automatic deployments
- Decide whether CI or the git host is the intended initiator.
- For CI, confirm self-hosted API Access, a non-expired token with Deploy permission, the correct application URL, and masked CI secrets.
- For GitHub App sources, do not add a manual webhook unless the source type requires it.
- For manual GitHub and GitLab sources, save a long random secret in Coolify and copy the identical value into the repository or project webhook settings.
- For GitLab, enable push events and add merge-request events only when preview deployments need them.
- Enable Auto Deploy for the GitLab manual-webhook flow and verify the application’s branch.
- Send a controlled test push, observe the incoming webhook result in the git host, and then confirm the deployment record in Coolify.
- Rotate tokens and secrets after accidental disclosure, personnel changes, or migration between repositories.
- Document which source type is active so a future administrator does not add a duplicate manual webhook to an App-managed application.
Which setup should you use?
Choose the CI deploy webhook when deployment must follow tests, image builds, approvals, or a release job. It gives the pipeline explicit control and centralizes authorization in an API token. Choose a repository webhook when a qualifying push should deploy without a separate CI call. GitHub App sources are the lowest-maintenance option because Coolify manages their webhook configuration; manual GitHub and GitLab integrations require you to maintain the URL, secret, event selection, and—on GitLab—Auto Deploy setting.
If your team needs both validation and automatic deployment, keep the responsibilities distinct: let CI run tests and call the Deploy URL after success, or let the repository webhook handle a push-only path. Avoid enabling both for the same event unless duplicate deployments are intentional and controlled.
Frequently Asked Questions
Do I need an API token for a GitHub App webhook?
No. A native Coolify GitHub App source configures its repository webhook automatically. The API token is required for the separate CI deploy-webhook pattern.
Why does my self-hosted token fail even though it has Deploy permission?
Self-hosted Coolify disables API access by default. Enable Settings → Advanced → API Settings → API Access, then retry with a non-expired token.
Can I use a repository webhook URL in GitHub Actions?
Use the application’s Deploy webhook URL for CI. Repository webhook URLs are designed for GitHub or GitLab events and use a shared secret rather than the CI bearer-token flow.
Why is GitLab rejecting my webhook?
Coolify rejects GitLab requests when the webhook secret is missing or does not match. Copy the GitLab Webhook Secret from Coolify exactly into the GitLab project webhook settings.
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 minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Do GitLab preview deployments need merge-request events?
Yes. Keep push events enabled and also enable merge-request events when the application uses preview deployments.
What does Auto Deploy control?
For the manual GitLab webhook flow, Configuration → Advanced → Auto Deploy must be enabled for accepted events to start deployments automatically.
Why does a GitHub App page say automatic management but I still see no deployment?
Verify the App installation, repository, selected branch, and deployment history. If the source is actually a manual or deploy-key setup, configure the manual URL and secret instead.
What if a GitLab App says webhooks are managed automatically but none exists?
Inspect the GitLab project’s Settings → Webhooks page. Some reported GitLab App setups do not create the project webhook; add the Coolify URL and matching secret manually if it is absent.
Can one webhook secret be reused for several applications?
The setup requires a matching secret for each manual webhook, but separate long random secrets make it easier to isolate and rotate one application without changing the others.
How do I know a deployment really completed?
A successful webhook or CI command only shows that the request was accepted. Open the Coolify application’s deployment view and verify that the deployment reached its normal build and health states.
The Bottom Line
For a pipeline-controlled release, enable API Access on self-hosted Coolify, create an API token with Deploy, store it with the application’s Deploy webhook URL, and call that URL from CI. For push-driven releases, use the native GitHub App without a manual hook, or configure a manual GitHub/GitLab URL with the same secret saved on both sides. On GitLab, enable Auto Deploy, select the correct events, and check each project manually when an App claims to manage webhooks but no project webhook exists.
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.
