gitlab-webhooks

GitLab Webhooks

When to Use This Skill

• Setting up GitLab webhook handlers
• Debugging webhook token verification failures
• Understanding GitLab event types and payloads
• Handling push, merge request, issue, or pipeline events

Essential Code (USE THIS)

GitLab Token Verification (JavaScript)

function verifyGitLabWebhook(tokenHeader, secret) {
  if (!tokenHeader || !secret) return false;

  // GitLab uses simple token comparison (not HMAC)
  // Use timing-safe comparison to prevent timing attacks
  try {
    return crypto.timingSafeEqual(
      Buffer.from(tokenHeader),
      Buffer.from(secret)
    );
  } catch {
    return false;
  }
}

Express Webhook Handler

const express = require('express');
const crypto = require('crypto');
const app = express();

// CRITICAL: Use express.json() - GitLab sends JSON payloads
app.post('/webhooks/gitlab',
  express.json(),
  (req, res) => {
    const token = req.headers['x-gitlab-token'];
    const event = req.headers['x-gitlab-event'];
    const eventUUID = req.headers['x-gitlab-event-uuid'];

    // Verify token
    if (!verifyGitLabWebhook(token, process.env.GITLAB_WEBHOOK_TOKEN)) {
      console.error('GitLab token verification failed');
      return res.status(401).send('Unauthorized');
    }

    console.log(`Received ${event} (UUID: ${eventUUID})`);

    // Handle by event type
    const objectKind = req.body.object_kind;
    switch (objectKind) {
      case 'push':
        console.log(`Push to ${req.body.ref}:`, req.body.commits?.length, 'commits');
        break;
      case 'merge_request':
        console.log(`MR !${req.body.object_attributes?.iid} ${req.body.object_attributes?.action}`);
        break;
      case 'issue':
        console.log(`Issue #${req.body.object_attributes?.iid} ${req.body.object_attributes?.action}`);
        break;
      case 'pipeline':
        console.log(`Pipeline ${req.body.object_attributes?.id} ${req.body.object_attributes?.status}`);
        break;
      default:
        console.log('Received event:', objectKind || event);
    }

    res.json({ received: true });
  }
);