@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 any LLM provider supported by the Vercel AI SDK — OpenAI, Anthropic, Google Gemini, Amazon Bedrock, Mistral, Cohere, Groq, xAI, DeepSeek, or any OpenAI-compatible gateway.

Examples handbook: runnable snippets for every public export are in HANDBOOK.md.

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 LLM — any provider supported by the Vercel AI SDK (OpenAI, Anthropic, Google, Bedrock, Mistral, Cohere, Groq, xAI, DeepSeek) or an OpenAI-compatible gateway (company proxy, 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 chosen 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 LLM (OpenAI, Anthropic, Google, Bedrock, Mistral, Cohere, Groq, xAI, DeepSeek, or an OpenAI-compatible 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). Posting merge request notes (optional on some helpers) requires a token with the api scope so GitLab accepts POST to the notes API.
• An LLM provider credential (see LLM configuration). @ai-sdk/openai and @ai-sdk/openai-compatible ship as direct dependencies via @mcarvin/smart-diff. Every other provider (@ai-sdk/anthropic, @ai-sdk/google, @ai-sdk/amazon-bedrock, @ai-sdk/mistral, @ai-sdk/cohere, @ai-sdk/groq, @ai-sdk/xai, @ai-sdk/deepseek) is declared as an optional peer and only needs to be installed when you actually use that provider.
• @mcarvin/smart-diff and Git: Helpers that summarize a GitLab merge request (summarizeMergeRequestDiffWithSmartDiff, etc.) only use the GitLab REST API plus the LLM—no local Git install is required. Helpers that summarize a local clone (summarizeGitDiff, generateSummary with patches from disk, etc.) need the git CLI on your PATH. On Windows, install Git for Windows (or another distribution) and ensure git is available to the same environment as Node—often Git Bash or PowerShell after choosing “Git from the command line” during setup. CI images usually include git; add it explicitly if your runner image is minimal.

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).

Writing MR or issue comments, releases, or wiki: To use createMergeRequestNote, createIssueNote, upsertRelease, createWikiPage, updateWikiPage, upsertWikiPage, or related insight flags (postSummaryAsMergeRequestNote, postSummaryAsIssueNote, postSummaryAsReleaseDescription, postSummaryToWikiSlug, …), the token must include the api scope (full REST read/write). Read-only scopes are not sufficient for those writes.

Self-managed example:

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

LLM — bring your own (OpenAI, Anthropic, Google, Bedrock, …)

Both createLabflowLlm() and the @mcarvin/smart-diff integration share the same provider resolver: they look at the standard LLM_* / provider-specific env vars and build a Vercel AI SDK LanguageModel. You can pick a provider explicitly with LLM_PROVIDER or let auto-detection choose based on which credentials are set.

Selecting a provider

LLM_PROVIDER explicitly selects a provider. When unset, the resolver auto-detects in this order: LLM_BASE_URL/OPENAI_BASE_URL → openai-compatible, OPENAI_API_KEY/LLM_API_KEY → openai, then ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY (or GOOGLE_API_KEY), MISTRAL_API_KEY, COHERE_API_KEY, GROQ_API_KEY, XAI_API_KEY, DEEPSEEK_API_KEY, and finally OPENAI_DEFAULT_HEADERS/LLM_DEFAULT_HEADERS → openai.

LLM_* wins over OPENAI_* where both exist.

Common env vars

Example: native OpenAI

$env:OPENAI_API_KEY = "sk-..."
# Optional: $env:LLM_MODEL = "gpt-4o"

Example: Anthropic Claude

$env:ANTHROPIC_API_KEY = "sk-ant-..."
$env:LLM_MODEL = "claude-3-5-sonnet-latest"   # optional override

Example: company-managed OpenAI-compatible gateway

$env:OPENAI_BASE_URL = "https://llm-gateway.company.com/v1"
$env:OPENAI_DEFAULT_HEADERS = '{"x-company-rbac":"your-rbac-token-here","Authorization":"Bearer sk-your-api-key-here"}'
# LLM_PROVIDER is auto-detected as "openai-compatible" because LLM_BASE_URL/OPENAI_BASE_URL is set.

Example: Google Gemini

$env:GOOGLE_GENERATIVE_AI_API_KEY = "..."
$env:LLM_MODEL = "gemini-2.0-flash"

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',
  // postSummaryAsMergeRequestNote: true,  // optional: POST summary as an MR note (needs PAT with `api` scope)
});

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, {
  // postSummaryAsMergeRequestNote: true,  // optional: POST digest as an MR note (needs PAT with `api` scope)
});
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' });

Posting summaries to GitLab (MR notes, issue notes, releases, wiki)

Merge requests: Some helpers create a merge request note with the generated markdown:

• summarizeMergeRequestDiffWithSmartDiff — set postSummaryAsMergeRequestNote: true.
• Merge-request insight helpers use AiMergeRequestInsightOptions: aiMergeRequestDiscussionDigest, aiWhatChangedSinceLastReview, aiSuggestedMergeRequestReply, aiMergeRequestActionItems, and aiMergeRequestReviewerBriefingMeta.

Issues: Issue insight helpers accept postSummaryAsIssueNote: true on AiIssueInsightOptions: aiIssueThreadSummary, aiStaleIssueSummary, and aiIssueSuggestedNextStep.

Commits: aiCommitCommentsDigest accepts postSummaryAsCommitNote: true on AiCommitCommentsDigestOptions to post the markdown as a comment on that commit SHA (via createCommitNote — POST …/repository/commits/:sha/comments). Requires api scope.

Releases: aiDraftReleaseNotes accepts postSummaryAsReleaseDescription: true on AiDraftReleaseNotesOptions to set the GitLab release description for the given tag (via upsertRelease — PUT if the release exists, otherwise POST). If the Git tag does not exist yet, pass releaseRef (branch or SHA) so GitLab can create the tag when creating the release.

Wiki: These accept postSummaryToWikiSlug (plus optional wikiPageTitle / wikiFormat) and write with upsertWikiPage: aiListReleasesOverview (AiListReleasesOverviewOptions), aiWikiRunbookTldr, aiWikiOutdatedDocHints, and aiSuggestMergeWikiPages (shared AiWikiInsightOptions; runbook also has AiWikiRunbookTldrOptions including wikiVersion). Prefer a destination slug that should receive the generated markdown (often different from the source runbook slug so you do not replace a full page with a short TL;DR).

You can also call createMergeRequestNote, createIssueNote, createCommitNote, upsertRelease, createWikiPage, updateWikiPage, or upsertWikiPage yourself. Notes use POST …/merge_requests/…/notes, POST …/issues/…/notes, or POST …/repository/commits/…/comments (Commits API); releases use the Releases API; wiki uses the Wikis API. All require a token with the api scope; otherwise GitLab often returns 403.

If posting fails: The client throws GitlabHttpError (see GitlabHttpError in exports). For a missing or wrong scope you typically get status: 403 and a JSON body from GitLab such as "error":"insufficient_scope" and "error_description":"The request requires higher privileges than provided by the access token." Read-only scopes (e.g. read_api only) are enough to fetch project data and run the LLM, but not to write notes, releases, or wiki pages—use a token that includes api (full REST API access). Your GitLab version’s token UI may show other scope names; follow your admin’s guidance.

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, Pipeline, PipelineJob, …). GitlabClient also exposes requestText for non-JSON responses (for example job log traces).

LLM layer

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

Because GitLab returns a pre-rendered unified diff, only stripDiffPreamble and maxHunkLines from DiffShapingOptions affect the bridge output. contextLines and ignoreWhitespace are git-arg flags and apply only to the local summarizeGitDiff pipeline.

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, getChangedFiles, filterCommitsByMessageRegexes, buildDiffPathspecs, buildDiffShapingGitArgs, shapeUnifiedDiff, DEFAULT_NOISE_EXCLUDES, createGitClient, getRepoRoot, truncateUnifiedDiffForLlm, resolveLlmMaxDiffChars, DEFAULT_GIT_DIFF_SYSTEM_PROMPT, LLM_GATEWAY_REQUIRED_MESSAGE, resolveLanguageModel, detectLlmProvider, isLlmProviderConfigured, defaultModelForProvider, resolveLlmBaseUrl, parseLlmDefaultHeadersFromEnv, plus related types (LlmModelProvider, ResolveLanguageModelOptions, LlmProviderId, SummarizeFlags, GenerateSummaryInput, CommitInfo, DiffSummary, DiffFileSummary, DiffPathFilter, DiffShapingOptions, GitDiffRangeQuery, GitDiffAiSummaryOptions).

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

Migrating from 1.x → 2.x

v2 swaps the direct openai SDK dependency for the Vercel AI SDK via @mcarvin/smart-diff v2. If you only rely on env-var configuration, your setup keeps working — OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_DEFAULT_HEADERS, LLM_* equivalents, OPENAI_MAX_DIFF_CHARS, and OPENAI_MAX_TOKENS are all still honored.

Breaking changes:

• createLabflowLlm no longer takes apiKey / baseURL / defaultHeaders. Configure the provider with env vars (LLM_PROVIDER, OPENAI_API_KEY, ANTHROPIC_API_KEY, LLM_BASE_URL/OPENAI_BASE_URL, OPENAI_DEFAULT_HEADERS, …) the same way @mcarvin/smart-diff does. The option bag now accepts provider, defaultModel, maxUserChars, and languageModelProvider (factory returning a Vercel AI SDK LanguageModel).
• summarizeMergeRequestDiffWithSmartDiff / summarizeCompareDiffWithSmartDiff removed openAiClientProvider. Use llmModelProvider: () => Promise<LanguageModel> instead, or set LLM_PROVIDER and the relevant provider env var. They now also accept an explicit provider id.
• Removed re-exports from smart-diff: createOpenAiLikeClient, resolveOpenAiLikeClientInit, shouldUseLlmGateway, OpenAiLikeClient, OpenAiLikeClientInit. Use resolveLanguageModel, detectLlmProvider, isLlmProviderConfigured, and LLM_GATEWAY_REQUIRED_MESSAGE instead (all re-exported from @mcarvin/gitlab-llm-kit).
• openai npm package is no longer a dependency. Remove it from your own package.json if you only depended on it transitively via this toolkit.

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.