--- title: "Connect GitLab to Coolhand" answer: "Connect GitLab to Coolhand with your instance URL, group path and a personal access token with the api scope. Then add a webhook for merge request, comment, push and pipeline events so Coolhand can follow its merge requests. This guide covers each step, what Coolhand does afterwards, and fixes for common errors." category: "Integrations" tags: ["integrations","gitlab","self-hosted"] published: 2026-10-23T14:50:05Z updated: 2026-10-23T14:50:05Z canonical_url: https://coolhandlabs.com/help/connect-gitlab index_url: https://coolhandlabs.com/help.md --- # Connect GitLab to Coolhand Connect GitLab to Coolhand with your instance URL, group path and a personal access token with the api scope. Then add a webhook for merge request, comment, push and pipeline events so Coolhand can follow its merge requests. This guide covers each step, what Coolhand does afterwards, and fixes for common errors. --- ## Before you start You need: - A GitLab instance running version 17.3 or later, and the GitLab group that holds the projects you want Coolhand to work on. Coolhand connects to one group and includes its subgroups. - An instance URL that starts with `https://` and that Coolhand can reach from the internet. Coolhand cannot connect to an instance that is only reachable on a private network. - Someone with the **Maintainer** role on each project (or the group) to add the webhook in Step 3. --- ## Step 1: Create a personal access token Merge requests that Coolhand opens are authored by the token's owner. Create the token from a dedicated service account rather than a personal one, and make sure that account can push branches and open merge requests in the projects you want to include. 1. Sign in to GitLab as that account. 2. Select your avatar, then **Edit profile**, then **Access tokens**. 3. Select **Add new token**. 4. Name it `Coolhand`, set an expiry date that fits your security policy, and check the **api** scope. 5. Select **Create personal access token**. 6. Copy the token now. GitLab only shows it once. An expired token is the most common cause of a failed connection, so note the expiry date somewhere your team will see it. --- ## Step 2: Connect in Coolhand 1. In Coolhand, open [Settings](https://coolhandlabs.com/settings#gitlab) and find the **GitLab Integration** card. 2. Enter: - **GitLab Instance URL**: the base URL only, for example `https://gitlab.example.com`. - **GitLab Group**: the group path from a project URL. For `https://gitlab.example.com/my-group/my-project` this is `my-group`. It is case-sensitive. - **Personal Access Token**: the token from Step 1. 3. Select **Test Connection** to check the details, then **Connect GitLab**. When the connection succeeds, Coolhand shows a **webhook URL** and a **secret token**. Copy both for the next step. --- ## Step 3: Add the webhook The webhook tells Coolhand what happens to its merge requests. Coolhand only hears about projects that send it events, so add the webhook to each project you want it to follow. If your GitLab plan includes group webhooks, you can add it once on the group instead. 1. In GitLab, open the project and go to **Settings**, then **Webhooks**, then **Add new webhook**. 2. Set: - **URL**: the webhook URL from Coolhand. - **Secret token**: the secret token from Coolhand. This is a separate value from the URL. 3. Under **Trigger**, check: - Push events - Merge request events - Comments - Pipeline events - Job events - Issues events - Project or group access token events 4. Leave **Enable SSL verification** on. 5. Select **Add webhook**, then use the **Test** menu to send a test event and confirm Coolhand responds with `200`. Coolhand acts on merge request, comment, push and pipeline events today. Job, issue and access token events are received but not yet acted on. Subscribing to them now means you will not need to change the webhook later. If you prefer less traffic, check only the first four. --- ## What Coolhand does with the connection - Reads the projects in your group, including subgroups, when you connect. - Clones projects so the coding agent can work on them. - Opens, updates and closes merge requests on your instance. - Follows each merge request it opened: opens, updates, merges and closes, comments on the merge request, new pushes to its branch, and pipeline results (passed, failed or canceled). To pick up projects that were created after you connected, reconnect from Settings. --- ## Troubleshooting **"Invalid token"**: the token has expired, was copied incorrectly, or does not have the `api` scope. Create a new token and reconnect. **"Group not found"**: the group path must match exactly, including case, and the token's owner must be a member of the group. **"Could not connect to GitLab with the supplied details"**: the instance URL is wrong, uses `http://`, or cannot be reached from Coolhand. Use the instance's canonical URL, with no path, query string or credentials. Coolhand does not follow redirects, so a vanity hostname that redirects elsewhere will fail; enter the address it redirects to. **The webhook test fails or shows an error**: check the **Recent events** list on the webhook in GitLab and read the response. If GitLab cannot reach Coolhand, ask your GitLab administrator to check outbound webhook rules under **Admin area**, then **Settings**, then **Network**, then **Outbound requests**. **Events are not arriving**: confirm the webhook URL and secret token match what Coolhand shows on the Settings page, and that the webhook is on the project in question. **Projects are missing from Coolhand**: the token's owner may not have access to them. Add the account to the project or group, then reconnect from Settings. --- Related: - [Connect GitHub Enterprise Server to Coolhand](https://coolhandlabs.com/help/connect-github-enterprise-server.md) - [Connect GitHub to Coolhand](https://coolhandlabs.com/help/connect-github.md) - [How to Set Up and Test the GitLab Integration via CLI and Docker](https://coolhandlabs.com/help/gitlab-cli-docker-setup.md) - [Ollama best practices](https://coolhandlabs.com/help/ollama-best-practices.md) [← All help articles](https://coolhandlabs.com/help.md) · [Integrations](https://coolhandlabs.com/help/category/integrations.md)