Skip to main content

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

Last updated 4 min read

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.

# 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.

# 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.

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:

# 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:

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

Related articles