GitLab Webhook Bridge

Standalone GitLab webhook bridge library. It verifies GitLab webhook requests, normalizes supported GitLab events, fans out built-in normalized events, and delivers them to configured targets.

Install

npm install @xmz-ai/gitlab-webhook-bridge

Basic Usage

import {
  GitLabWebhookBridge,
  gitlabPipelineTarget,
} from '@xmz-ai/gitlab-webhook-bridge';

const bridge = new GitLabWebhookBridge({
  gitlab: {
    baseUrl: 'https://git.example.com',
    token: process.env.GITLAB_TOKEN!,
    webhookSecret: process.env.GITLAB_WEBHOOK_SECRET,
  },
  targets: [
    gitlabPipelineTarget(),
  ],
});

const result = await bridge.handle({
  headers: req.headers,
  body: req.body,
});

API

• bridge.normalize(input) verifies and parses a GitLab webhook without delivering targets.
• bridge.trigger({ deliveryId, events }) delivers pre-normalized events.
• bridge.handle(input) runs the full verify -> normalize -> fanout -> target delivery flow.
• gitlabPipelineTarget() delivers normalized events by creating or reusing a GitLab project pipeline trigger token and then triggering a pipeline. If no variable mapper is configured, it sends defaultVariables().
• gitlabPipelineTarget({ createTriggerIfMissing: false }) reuses cached or existing GitLab project pipeline trigger tokens and fails when none is available.
• gitlabPipelineTarget({ variablePrefix: 'AGENTRIX_' }) renames the default mapper output without replacing the mapper. The default prefix is GITLAB_BRIDGE_*.
• gitlabPipelineTarget({ forwardTriggerPipelines: true }) also forwards GitLab pipeline webhooks whose source is trigger. By default these are ignored by pipeline delivery to avoid recursive trigger loops.
• deliveryTarget(name, handler, { onError }) adapts a delivery-level handler into a BridgeDeliveryTarget, with optional ignored-error behavior for best-effort sinks such as inbox fan-out.
• defaultVariables({ prefix }) maps normalized events to prefixed pipeline variables. By default it emits GITLAB_BRIDGE_*.
• memoryStore() provides in-memory delivery dedupe and trigger-token caching for development and tests. Host applications can pass their own store or gitlabClient to integrate existing persistence and GitLab access layers.

Supported webhook classes:

• GitLab branch creation/deletion pushes -> create / delete
• GitLab issues -> issues.*
• GitLab merge requests -> pull_request.* / pull_request_review.*
• GitLab non-system notes -> issue_comment.* / pull_request_review_comment.*
• GitLab pipelines -> workflow_run.*

By default, system notes and unsupported provider-specific events are ignored. Pipeline webhooks from source=trigger are normalized as workflow_run.* events, but gitlabPipelineTarget() ignores them unless forwardTriggerPipelines is enabled.

Tests

npm test
npm run typecheck
npm run build

The live GitLab E2E test is skipped unless explicitly enabled:

RUN_GITLAB_E2E=1 npm run test:e2e

The E2E test reads GITLAB_BASE_URL, GITLAB_TOKEN, GITLAB_TEST_PROJECT, and optional GITLAB_TEST_REF from the environment. If they are not set, it can fall back to /Users/alex/git/github/nil4u/issue-flow/.env on this machine.

Publishing

The package is published as @xmz-ai/gitlab-webhook-bridge to the public npm registry.

Local release checks:

npm run verify
npm run publish:dry-run