@anthaathi/chat-sdk-gitlab-adapter

GitLab adapter for Chat SDK. Respond to @mentions in merge request and issue note threads.

The GitLab adapter treats issue notes, merge request notes, and merge request discussions as messages.

Installation

pnpm add @anthaathi/chat-sdk-gitlab-adapter

Usage

The adapter auto-detects credentials from GITLAB_TOKEN, GITLAB_WEBHOOK_SECRET, GITLAB_API_URL, and GITLAB_BOT_USERNAME environment variables:

import { Chat } from "chat";
import { createGitLabAdapter } from "@anthaathi/chat-sdk-gitlab-adapter";

const bot = new Chat({
  userName: "my-bot",
  adapters: {
    gitlab: createGitLabAdapter(),
  },
});

bot.onNewMention(async (thread) => {
  await thread.post("Hello from GitLab!");
});

Authentication

Create a GitLab personal, project, or group access token with api access, then set:

GITLAB_TOKEN=glpat_xxxxxxxxxxxx
GITLAB_WEBHOOK_SECRET=your-webhook-secret

You can also pass configuration directly:

createGitLabAdapter({
  token: process.env.GITLAB_TOKEN!,
  webhookSecret: process.env.GITLAB_WEBHOOK_SECRET!,
  userName: "my-bot",
});

For self-managed GitLab:

createGitLabAdapter({
  apiUrl: "https://gitlab.example.com/api/v4",
  token: process.env.GITLAB_TOKEN!,
  webhookSecret: process.env.GITLAB_WEBHOOK_SECRET!,
});

Webhook Setup

For project or group webhooks:

1. Go to Settings then Webhooks.
2. Set URL to https://your-domain.com/api/webhooks/gitlab.
3. Set Secret token to match webhookSecret.
4. Enable Comments events.

GitLab sends the secret in the X-Gitlab-Token header. This adapter validates that token.

Thread Model

| Type | Context | Thread ID format | |------|---------|------------------| | Merge request note | MR overview notes | gitlab:{namespace}/{project}:mr:{iid} | | Merge request discussion | MR discussion thread | gitlab:{namespace}/{project}:mr:{iid}:discussion:{discussionId} | | Issue note | Issue notes | gitlab:{namespace}/{project}:issue:{iid} |

Namespaces can be nested. For example:

gitlab:acme/platform/app:mr:42

Reactions

Supports GitLab award emoji on issue and merge request notes:

| SDK emoji | GitLab award emoji | |-----------|--------------------| | thumbs_up | thumbsup | | thumbs_down | thumbsdown | | laugh | laugh | | confused | confused | | heart | heart | | hooray | hooray | | rocket | rocket | | eyes | eyes |

Configuration

| Option | Required | Description | |--------|----------|-------------| | token | Yes* | GitLab access token. Auto-detected from GITLAB_TOKEN | | webhookSecret | Yes* | GitLab webhook secret token. Auto-detected from GITLAB_WEBHOOK_SECRET | | apiUrl | No | GitLab API URL. Auto-detected from GITLAB_API_URL; defaults to https://gitlab.com/api/v4 | | userName | No | Bot username. Auto-detected from GITLAB_BOT_USERNAME; defaults to gitlab-bot | | botUserId | No | Bot's numeric GitLab user ID | | logger | No | Logger instance |

*Required via config or environment variable.