---
title: "How to Set Up and Test the GitLab Integration via CLI and Docker"
answer: "You can automate the Coolhand GitLab integration using the GitLab REST API with `curl` to create access tokens and webhooks. For end-to-end testing, you can run a self-contained GitLab instance locally using Docker, allowing you to configure and validate the webhook connection without affecting your production environment."
category: "Integrations"
tags: []
published: 2026-10-24T05:45:54Z
updated: 2026-10-06T15:00:59Z
canonical_url: https://coolhandlabs.com/help/gitlab-cli-docker-setup
index_url: https://coolhandlabs.com/help.md
---

# How to Set Up and Test the GitLab Integration via CLI and Docker

You can automate the Coolhand GitLab integration using the GitLab REST API with `curl` to create access tokens and webhooks. For end-to-end testing, you can run a self-contained GitLab instance locally using Docker, allowing you to configure and validate the webhook connection without affecting your production environment.


## Prerequisites

Before you start, ensure you have:

*   Access to a GitLab instance (17.3+), either self-hosted or on GitLab.com.
*   A GitLab user with the **Maintainer** role or higher on the target group.
*   `curl` and `docker` installed on your local machine.

---

## Automating GitLab Setup with the API

You can script the entire GitLab configuration process using its REST API. This is useful for automating setup or managing multiple connections.

### 1. Create a Personal Access Token (PAT)

First, create a PAT with `api` scope to authenticate subsequent requests.

```bash
# Replace with your GitLab instance URL and a valid user ID
GITLAB_URL="https://gitlab.example.com"
USER_ID="1"

# You will need an existing PAT with `api` scope to create a new one via the API
# or use another authentication method as described in GitLab's documentation.
ADMIN_PAT="your_existing_admin_pat"

PAT_RESPONSE=$(curl --request POST \
  --header "PRIVATE-TOKEN: $ADMIN_PAT" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "coolhand-integration",
    "scopes": ["api"],
    "expires_at": "2027-01-01"
  }' \
  "$GITLAB_URL/api/v4/users/$USER_ID/personal_access_tokens")

GITLAB_PAT=$(echo "$PAT_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")
echo "Your new GitLab PAT is: $GITLAB_PAT"
```

**Note:** Keep this token secure, as it provides API access to your GitLab account.

### 2. Create a Project Webhook

After connecting GitLab in the Coolhand UI (**Settings > GitLab Integration**), Coolhand will provide a **Webhook URL** and a **Secret Token**. Use these to create a webhook in your GitLab project.

```bash
# Replace with your project ID, PAT, and Coolhand webhook details
PROJECT_ID="123"
GITLAB_PAT="your_new_gitlab_pat"
WEBHOOK_URL="https://app.coolhand.com/webhooks/gitlab"
WEBHOOK_TOKEN="your_coolhand_secret_token"

curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_PAT" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "'$WEBHOOK_URL'",
    "token": "'$WEBHOOK_TOKEN'",
    "push_events": true,
    "merge_requests_events": true,
    "pipeline_events": true,
    "note_events": true,
    "enable_ssl_verification": true
  }' \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/hooks"
```

This command registers the webhook, which will notify Coolhand of events in your project. Note that creating group-level webhooks requires a GitLab Premium license.

---

## Testing the Integration Locally with Docker

You can run a complete GitLab instance on your local machine to test the integration from end to end.

### 1. Run GitLab in Docker

This command starts a GitLab CE container. It may take 5-20 minutes to become fully available, especially on Apple Silicon devices.

```bash
docker run --detach \
  --hostname gitlab.local \
  --name coolhand-gitlab-test \
  --publish 8929:8929 \
  --env GITLAB_OMNIBUS_CONFIG="external_url 'http://host.docker.internal:8929'; gitlab_rails['initial_root_password'] = 'Coolhand123!';" \
  --shm-size 256m \
  gitlab/gitlab-ce:17.3.1-ce.0
```

Once started, you can access it at `http://localhost:8929` with username `root` and password `Coolhand123!`.

### 2. Connect Coolhand to Your Local GitLab

Because your local GitLab instance is not on the public internet, you will need a tool like `ngrok` to expose your local Coolhand development server's webhook endpoint to the GitLab container.

1.  In your Coolhand settings, connect to the local GitLab instance using:
    *   **Instance URL**: `http://host.docker.internal:8929` (This special DNS name resolves to your host machine from within the Docker container).
    *   **Personal Access Token**: Create one in your local GitLab instance.
2.  Copy the **Webhook URL** and **Secret Token** from Coolhand.

### 3. Create and Test the Webhook

Use the `curl` command from the previous section to create the project webhook, but with two changes:

*   Set the `url` to your `ngrok` forwarding address.
*   Set `enable_ssl_verification` to `false` if you are not using HTTPS.

To test that GitLab can successfully send an event, you can trigger one via the API:

```bash
# Creates a new file, which triggers a push event
curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_PAT" \
  --header "Content-Type: application/json" \
  --data '{
    "branch": "main",
    "content": "Testing the webhook",
    "commit_message": "Test commit"
  }' \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/repository/files/test.txt"
```

Check your Coolhand server logs to confirm the webhook was received.

### Cleanup

To stop and remove the GitLab container:

```bash
docker stop coolhand-gitlab-test && docker rm coolhand-gitlab-test
```


---

Related:
- [Connect GitLab to Coolhand](https://coolhandlabs.com/help/connect-gitlab.md)
- [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)
- [What is the Coolhand GitHub App and what does it do?](https://coolhandlabs.com/help/what-is-the-coolhand-github-app.md)

[← All help articles](https://coolhandlabs.com/help.md) · [Integrations](https://coolhandlabs.com/help/category/integrations.md)