@mcarvin/gitlab-llm-kit

TypeScript library for AI-assisted workflows on top of the GitLab REST API. It fetches merge requests, issues, diffs, wikis, releases, and other resources using ordinary personal or project access tokens, then generates summaries and review aids through an OpenAI-compatible Chat Completions API—including the same LLM stack used by @mcarvin/smart-diff for git diff summarization (local repos) and for GitLab merge request patches when you use the bundled helpers.

Why this exists (and not GitLab Duo)

GitLab Duo is GitLab’s hosted AI product; it requires the appropriate GitLab subscription and Duo licensing.

This package does not use Duo and does not call GitLab’s AI APIs. It only uses:

• The standard GitLab REST API (/api/v4/…) that ships with GitLab CE/EE and self-managed instances.
• Your own OpenAI-compatible endpoint—often already provided by your company (private gateway, Azure OpenAI-compatible proxy, etc.).

So teams on self-managed GitLab without Duo can still get MR/issue summaries, reviewer briefings, and diff narratives as long as they can reach GitLab’s API with a token and can reach their company’s LLM. You pay for whatever your org already pays for models and hosting, not for Duo.

Requirements

• Node.js 20+
• Network access to your GitLab (https://your.gitlab.example.com/api/v4 or GitLab.com)
• Network access to your OpenAI-compatible service (OPENAI_BASE_URL / company gateway)
• A GitLab token with scopes appropriate to what you call (e.g. read_api, read_repository for MR diffs—follow your admin’s least-privilege guidance)

Installation

npm install @mcarvin/gitlab-llm-kit

Configuration

GitLab (no Duo)

Create a Personal, Project, or Group access token in GitLab with the scopes you need. The library sends it as PRIVATE-TOKEN by default (or Authorization: Bearer if you use oauth: true for OAuth tokens).

Self-managed example:

$env:GITLAB_TOKEN = "glpat-xxxxxxxx"
$env:GITLAB_BASE_URL = "https://gitlab.internal.example.com/api/v4"

OpenAI / company LLM gateway

Insight functions use createLabflowLlm(), which reads the official OpenAI client env vars. The @mcarvin/smart-diff integration (summarizeMergeRequestDiffWithSmartDiff, summarizeGitDiff, etc.) understands the same LLM_* variables as that package, so you can align with a corporate gateway.

Example aligned with a company gateway:

$env:OPENAI_BASE_URL = "https://llm-gateway.company.com/v1"
$env:OPENAI_API_KEY = "your-key-or-token-accepted-by-gateway"
# If your gateway requires extra headers, also set LLM_DEFAULT_HEADERS as in @mcarvin/smart-diff README.

Quick start

Review a merge request (diff summary via smart-diff + GitLab MR changes):

import { GitlabClient, summarizeMergeRequestDiffWithSmartDiff } from '@mcarvin/gitlab-llm-kit';

const client = new GitlabClient({
  token: process.env.GITLAB_TOKEN,
  baseUrl: process.env.GITLAB_BASE_URL ?? 'https://gitlab.com/api/v4',
});

const markdown = await summarizeMergeRequestDiffWithSmartDiff({
  client,
  projectId: 'namespace/project', // or numeric project id
  mergeRequestIid: 42,            // IID from the MR URL
  teamName: 'Platform',
});

console.log(markdown);

Discussion-focused summary (threads + title/description):

import { GitlabClient, createLabflowLlm, aiMergeRequestDiscussionDigest } from '@mcarvin/gitlab-llm-kit';

const client = new GitlabClient({ token: process.env.GITLAB_TOKEN, baseUrl: '...' });
const llm = createLabflowLlm();

const digest = await aiMergeRequestDiscussionDigest(client, llm, 'namespace/project', 42);
console.log(digest);

Local repo (no GitLab)—re-exported from @mcarvin/smart-diff:

import { summarizeGitDiff } from '@mcarvin/gitlab-llm-kit';

await summarizeGitDiff({ from: 'origin/main', to: 'HEAD', cwd: '/path/to/repo' });

What’s included

GitLab REST helpers (GitlabClient)

Low-level request / requestAllPages plus typed wrappers, for example:

Utilities: encodeProjectId, encodeGroupId, encodeQuery, GitlabHttpError, shared types (MergeRequest, Issue, …).

LLM layer

Smart diff bridge (GitLab → @mcarvin/smart-diff)

Insight functions (ai… + helpers)

These take GitlabClient, a LabflowLlm from createLabflowLlm(), and resource ids (project IID for MRs/issues where applicable).

Re-exports from @mcarvin/smart-diff

For local git and advanced pipelines: summarizeGitDiff, generateSummary, getDiff, getDiffSummary, getCommits, createGitClient, getRepoRoot, truncateUnifiedDiffForLlm, resolveLlmMaxDiffChars, DEFAULT_GIT_DIFF_SYSTEM_PROMPT, createOpenAiLikeClient, resolveOpenAiLikeClientInit, shouldUseLlmGateway, plus related types.

The authoritative list of exports is src/index.ts.

Security notes

• Treat tokens and model endpoints like production secrets.
• Do not paste real credentials into issues or logs.
• Review large file / wiki content before sending to an LLM; the library includes prompt guardrails, but you remain responsible for data classification and retention policies at your company.

License

MIT — see LICENSE.md.