Skip to main content

Connect GitLab to Coolhand

Last updated 5 min read

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 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 articles