GitLab Webhooks

Set up GitLab webhooks to trigger Sluice pipelines.

GitLab Webhooks

This guide walks you through setting up GitLab webhooks to automatically trigger your Sluice pipelines.

Prerequisites

• A Sluice pipeline configured and ready
• Maintainer or Owner access to your GitLab project
• Your pipeline’s webhook URL and secret

Step 1: Get Webhook Details

1. Navigate to your pipeline in Sluice
2. Go to Settings > Webhooks
3. Copy the Webhook URL
4. Copy the Webhook Secret

Step 2: Configure GitLab

1. Go to your GitLab project
2. Navigate to Settings > Webhooks
3. Fill in the webhook form

Step 3: Select Triggers

Choose which events trigger the webhook:

Branch Filter

Optionally filter pushes by branch:

• Leave empty for all branches
• Enter main for only main branch
• Use regex like ^(main|develop)$ for multiple branches

Step 4: SSL Verification

For production, keep Enable SSL verification checked.

For testing with self-signed certificates:

1. Uncheck Enable SSL verification
2. Re-enable it before production use

Step 5: Save and Test

1. Click Add webhook
2. Find your webhook in the list
3. Click Test and select Push events
4. Verify the test succeeds

Verify Setup

After a test or real push:

1. Click on your webhook
2. View Recent events
3. Check for successful deliveries (200 status)

If delivery failed:

• Click on the event for details
• Check the Response section for errors
• Verify URL and secret are correct

Event Payloads

Push Event

{
  "object_kind": "push",
  "ref": "refs/heads/main",
  "before": "abc123...",
  "after": "def456...",
  "project": {
    "path_with_namespace": "group/project",
    "git_http_url": "https://gitlab.com/group/project.git"
  },
  "commits": [...],
  "user_name": "Username",
  "user_email": "[email protected]"
}

Merge Request Event

{
	"object_kind": "merge_request",
	"object_attributes": {
		"iid": 42,
		"title": "Add feature",
		"source_branch": "feature-branch",
		"target_branch": "main",
		"state": "opened",
		"action": "open"
	}
}

Merge Request States

When using merge request triggers, Sluice receives events for:

Configure your pipeline to handle these appropriately.

Group-Level Webhooks

For webhooks across multiple projects:

1. Go to your GitLab group
2. Navigate to Settings > Webhooks
3. Configure as above

GitLab Self-Managed

For GitLab self-managed instances:

1. Ensure outbound HTTPS is allowed to Sluice endpoints
2. Use your instance URL for repository cloning
3. Configure any corporate proxy settings

Allow Local Network Requests

If Sluice runs on your internal network:

1. Go to Admin Area > Settings > Network
2. Expand Outbound requests
3. Check Allow requests to the local network from webhooks

Troubleshooting

Webhook not triggering

1. Verify the webhook is not disabled
2. Check Recent events for delivery attempts
3. Ensure branch filter matches your branch

SSL certificate error

1. Temporarily disable SSL verification
2. If it works, your Sluice endpoint may have cert issues
3. Resolve cert issues and re-enable verification

Timeout errors

GitLab webhooks timeout after 10 seconds. If Sluice responds slowly:

• Check Sluice service health
• Consider network latency issues
• Contact support if persistent

Secret token mismatch

1. Regenerate the secret in Sluice
2. Update the secret in GitLab
3. Use Test to verify

Next Steps

• Webhook Overview - General webhook concepts
• Pipeline Configuration - Configure your pipeline