GitLab

Coolify can deploy GitLab repositories through a public HTTPS URL, an SSH deploy key, or a GitLab App.

Method	Best for	Repository access
Public repository	Public source that needs no authentication	HTTPS URL
Deploy key	One private repository or a GitLab instance where an OAuth application is unavailable	SSH URL and repository deploy key
GitLab App	Private repositories on GitLab.com or a self-managed GitLab instance	OAuth application with repository browsing

Set up a GitLab App

GitLab App requires Coolify v4.3.0

GitLab App integration is available in Coolify v4.3.0 or above

A GitLab App lets Coolify list repositories and branches, clone private source over HTTPS, and receive push and merge-request events.

Add the source in Coolify

Open Sources and select New source > GitLab App.

Enter Name and optionally comma-separated values in Group name to limit the repositories Coolify lists. For a self-managed instance, expand Self-hosted GitLab and enter GitLab URL and API URL. GitLab.com is the default.

On a self-hosted Coolify instance, enable System wide only when every team should be able to select this source. Otherwise, keep the source scoped to the active team.

Select Continue. Coolify displays the redirect URI required by the OAuth application.

Create the OAuth application in GitLab

In GitLab, open User Settings > Applications. A group or instance administrator can create the application at group or instance level when ownership should not belong to one user.

Create an application with:

the exact redirect URI shown by Coolify
api, read_user, and read_repository scopes

Save the application, then copy its Application ID and Secret.

Connect Coolify to GitLab

Return to the GitLab source in Coolify. Enter the Application ID and Secret, confirm the GitLab and API URLs, then save the credentials.

Select Connect to GitLab and authorize the OAuth application. Use Test Connection after GitLab redirects back to Coolify.

Configure repository webhooks

Copy the webhook URL and secret token from the connected source.

In each GitLab project that should deploy automatically, open Settings > Webhooks, add the URL and matching secret token, then enable:

Push events for branch deployments
Merge request events for preview deployments

Coolify rejects GitLab webhook requests when the secret token is missing or does not match.

On a self-managed GitLab instance, an administrator can add one system hook instead of one webhook for each project. Read Use a GitLab system hook.

Deploy a repository

Open a Coolify project, select + New, then select Private Repository (with GitLab App).

Choose the server and connected GitLab App, load the repositories, select a repository and branch, then configure and deploy the application.

Verify that the deployment log clones the selected repository and checks out the requested commit.

Use a GitLab system hook

On GitLab Self-Managed and GitLab Dedicated, an administrator can add a system hook. A system hook sends events for all projects on the GitLab instance. Use it as an alternative to one webhook for each project.

In Coolify, open the connected GitLab source and copy the Webhook URL and the Webhook secret token. The URL ends with /webhooks/source/gitlab/events.
In GitLab, select Admin > System hooks, then select Add new webhook.
Enter the Coolify URL in URL and the same token in Secret token.
In Trigger, enable:
- Push events for branch deployments
- Merge request events for preview deployments
Select Add system hook.

Coolify uses only push and merge request events. It ignores other system hook events, such as project, user, tag push, and repository update events.

The secret token identifies the GitLab source. Coolify deploys only applications that use this source and that track the GitLab project in the event. Events for other projects do not start a deployment. If the token is missing or does not match a GitLab source, Coolify rejects the request.

Pushes with many branches

By default, GitLab does not send system hook events for a push that changes more than 3 branches or tags. GitLab administrators can change this limit with the push_event_hooks_limit setting.

Use a deploy key

Use a deploy key when Coolify only needs one private repository or cannot connect to the GitLab instance through OAuth.

Add a private key under Keys & Tokens > Private Keys.
Add its public key under the GitLab repository's Settings > Repository > Deploy keys.
Copy the repository SSH URL, such as git@gitlab.com:example/application.git.
In Coolify, create Private Repository (with deploy key) and select the stored key.

Read Deploy keys for the complete setup and security guidance.

Configure a manual GitLab webhook

For an application created from a public URL or deploy key:

Open Webhooks in the Coolify application.
Copy the GitLab webhook URL and enter Webhook secret in the GitLab section, then select Save changes.
In GitLab, open Settings > Webhooks and enter the same URL and secret.
Enable push events and, when using preview deployments, merge-request events.
Open Advanced > Deployment and choose Deploy on push (webhooks) in Auto deploy in Coolify.

Test the webhook from GitLab, then push to the configured branch and inspect Deployment Logs in Coolify.

Use GitLab Container Registry

Repository credentials do not authenticate Docker to GitLab Container Registry.

For a private registry, create a GitLab deploy token with read_registry and authenticate Docker on every server that pulls the image:

echo "$GITLAB_REGISTRY_TOKEN" | \
  docker login registry.gitlab.com \
  --username "$GITLAB_REGISTRY_USER" \
  --password-stdin

Use the complete image reference, including its tag, in a Docker Image or Docker Compose application. Read Docker registries for server authentication and build-server requirements.

Detect build configuration

The GitLab App creation form includes Smart Scan. Review detected Dockerfiles or Compose files, internal ports, and environment-template imports before continuing. Set Base directory and scan again when deploying a subdirectory.

On this page