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

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 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). Posting merge request notes (optional on some helpers) requires a token with the api scope so GitLab accepts POST to the notes API.
• @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"

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',
  // 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)

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.