feat(integrations): add GitLab as alternative SCM provider

Add GitLab as a second SCM integration alongside GitHub, following the
existing IntegrationModule/SCMIntegration architecture. This enables
CASCADE to process GitLab merge request webhooks and run agents against
GitLab repositories.

Key additions:
- Core GitLab module (client via @gitbeaker/rest, dual-persona model,
  SCMIntegration implementation)
- Router layer (webhook route, signature verification, adapter, queue types)
- 9 trigger handlers (MR opened, pipeline success/failure, approval,
  reviewer added, comment mention, merged, conflict detected, ready to merge)
- 11 GitLab gadgets for agent MR operations
- SCM-provider-aware context pipeline, CLI commands, tool manifests,
  and agent system prompts
- Frontend SCM tab with GitHub/GitLab provider selector
- CLI webhook commands with --gitlab-only support
- GitLab webhook CRUD via API
- Worker entry GitLab job dispatch with CASCADE_SCM_PROVIDER env var
- PR/MR URL extraction supports both /pull/NNN and /merge_requests/NNN
- Post-execution work-item linking works for GitLab MRs
- Database migration for gitlab SCM provider CHECK constraint
- glab CLI installed in worker Docker image
- 100 unit tests across 7 test files

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Author: suda

Dockerfile.worker

@@ -69,6 +69,12 @@ RUN ARCH=$(dpkg --print-architecture) && \
     rm /tmp/ast-grep.zip && \
     chmod +x /usr/local/bin/sg
 
+# Install glab (GitLab CLI)
+RUN ARCH=$(dpkg --print-architecture) && \
+    curl -L "https://gitlab.com/gitlab-org/cli/-/releases/v1.52.0/downloads/glab_1.52.0_linux_${ARCH}.deb" -o /tmp/glab.deb && \
+    dpkg -i /tmp/glab.deb && \
+    rm /tmp/glab.deb
+
 # Install agent CLIs used by headless engines in worker jobs.
 # All three are explicitly pinned so worker image rebuilds are reproducible —
 # upstream CLI changes can introduce subtle behavioural drift in headless mode.

package-lock.json

@@ -55,6 +55,7 @@
 	"license": "MIT",
 	"dependencies": {
 		"@anthropic-ai/claude-agent-sdk": "^0.2.119",
+		"@gitbeaker/rest": "^43.8.0",
 		"@hono/node-server": "^1.19.13",
 		"@hono/trpc-server": "^0.4.2",
 		"@llmist/cli": "^16.0.3",

package.json

@@ -5,6 +5,7 @@
  * These are the building blocks composed by the YAML contextPipeline arrays.
  */
 
+import { getIntegrationProvider } from '../../db/repositories/credentialsRepository.js';
 import { formatCheckStatus } from '../../gadgets/github/core/getPRChecks.js';
 import { ListDirectory } from '../../gadgets/ListDirectory.js';
 import {
@@ -20,7 +21,8 @@ import {
 	initTodoSession,
 	saveTodos,
 } from '../../gadgets/todo/storage.js';
-import { githubClient } from '../../github/client.js';
+import { githubClient, type PRDiffFile } from '../../github/client.js';
+import { gitlabClient } from '../../gitlab/client.js';
 import { getJiraConfig, getLinearConfig, getTrelloConfig } from '../../pm/config.js';
 import type {
 	Attachment,
@@ -153,6 +155,24 @@ export async function fetchPRContextStep(params: FetchContextParams): Promise<Co
 	if (!repoFullName || !prNumber) {
 		throw new Error('fetchPRContextStep requires repoFullName and prNumber in input');
 	}
+
+	// Check if the project uses GitLab
+	const scmProvider = params.project?.id
+		? await getIntegrationProvider(params.project.id, 'scm')
+		: null;
+
+	if (scmProvider === 'gitlab') {
+		return fetchGitLabMRContextStep(params, repoFullName, prNumber);
+	}
+
+	return fetchGitHubPRContextStep(params, repoFullName, prNumber);
+}
+
+async function fetchGitHubPRContextStep(
+	params: FetchContextParams,
+	repoFullName: string,
+	prNumber: number,
+): Promise<ContextInjection[]> {
 	const injections: ContextInjection[] = [];
 	const { owner, repo } = parseRepoFullName(repoFullName);
 
@@ -237,13 +257,114 @@ export async function fetchPRContextStep(params: FetchContextParams): Promise<Co
 	return injections;
 }
 
+async function fetchGitLabMRContextStep(
+	params: FetchContextParams,
+	projectPath: string,
+	mrIid: number,
+): Promise<ContextInjection[]> {
+	const injections: ContextInjection[] = [];
+
+	params.logWriter('INFO', 'Fetching MR details and diff from GitLab', {
+		projectPath,
+		mrIid,
+	});
+
+	const mrDetails = await gitlabClient.getMR(projectPath, mrIid);
+	const mrDiff = await gitlabClient.getMRDiff(projectPath, mrIid);
+
+	// Format MR details
+	const detailsFormatted = [
+		`MR #${mrDetails.iid}: ${mrDetails.title}`,
+		`State: ${mrDetails.state}`,
+		`Author: ${mrDetails.author.username}`,
+		`Source: ${mrDetails.sourceBranch} → Target: ${mrDetails.targetBranch}`,
+		`URL: ${mrDetails.webUrl}`,
+		mrDetails.description ? `\nDescription:\n${mrDetails.description}` : '',
+	]
+		.filter(Boolean)
+		.join('\n');
+
+	injections.push({
+		toolName: 'GetMRDetails',
+		params: { comment: 'Pre-fetching MR details for review context', projectPath, mrIid },
+		result: detailsFormatted,
+		description: 'Pre-fetched MR details',
+	});
+
+	// Compact per-file diffs sourced from the checked-out local MR workspace,
+	// mirroring the GitHub PR context path. Files that don't fit the budget or
+	// can't be diffed are surfaced in a separate SKIPPED FILES injection so the
+	// agent can fetch them on demand.
+	const prDiffCompat: PRDiffFile[] = mrDiff.map((f) => ({
+		filename: f.newPath,
+		previousFilename: f.renamedFile ? f.oldPath : undefined,
+		status: f.newFile
+			? 'added'
+			: f.deletedFile
+				? 'removed'
+				: f.renamedFile
+					? 'renamed'
+					: 'modified',
+		additions: 0,
+		deletions: 0,
+		changes: 0,
+		patch: f.diff,
+	}));
+	const localDiffSource = await sourceLocalPRDiffs({
+		files: prDiffCompat,
+		repoDir: params.repoDir,
+		baseBranch: mrDetails.targetBranch,
+		logWriter: params.logWriter,
+	});
+	const diffContext = extractPRDiffs(localDiffSource.files);
+	const skipReasons = countSkipsByReason(diffContext.skipped);
+	params.logWriter('INFO', 'MR context prepared', {
+		included: diffContext.included.length,
+		skipped: diffContext.skipped.length,
+		skipReasons,
+		totalDiffTokens: diffContext.totalDiffTokens,
+		perFileTokenCap: diffContext.perFileTokenCap,
+	});
+
+	injections.push({
+		toolName: 'GetMRDiff',
+		params: { comment: 'Pre-fetching compact per-file diffs for review', projectPath, mrIid },
+		result: formatPRDiffContext(diffContext),
+		description: 'Pre-fetched MR diff context',
+	});
+
+	if (diffContext.skipped.length > 0) {
+		injections.push({
+			toolName: 'SkippedFiles',
+			params: {
+				comment: 'MR files omitted from the compact context — fetch on demand if relevant',
+				prNumber: mrIid,
+			},
+			result: formatSkippedFilesInjection(diffContext.skipped, mrIid),
+			description: 'Skipped files',
+		});
+	}
+
+	return injections;
+}
+
 export async function fetchPRConversationStep(
 	params: FetchContextParams,
 ): Promise<ContextInjection[]> {
 	const { repoFullName, prNumber } = params.input;
 	if (!repoFullName || !prNumber) {
 		throw new Error('fetchPRConversationStep requires repoFullName and prNumber in input');
 	}
+
+	// Check if the project uses GitLab
+	const scmProvider = params.project?.id
+		? await getIntegrationProvider(params.project.id, 'scm')
+		: null;
+
+	if (scmProvider === 'gitlab') {
+		return fetchGitLabMRConversationStep(params, repoFullName, prNumber);
+	}
+
 	const injections: ContextInjection[] = [];
 	const { owner, repo } = parseRepoFullName(repoFullName);
 
@@ -294,6 +415,43 @@ export async function fetchPRConversationStep(
 	return injections;
 }
 
+async function fetchGitLabMRConversationStep(
+	params: FetchContextParams,
+	projectPath: string,
+	mrIid: number,
+): Promise<ContextInjection[]> {
+	const injections: ContextInjection[] = [];
+
+	params.logWriter('INFO', 'Fetching MR conversation context from GitLab', {
+		projectPath,
+		mrIid,
+	});
+
+	const notes = await gitlabClient.getMRNotes(projectPath, mrIid);
+
+	// Filter to non-system notes (user comments only)
+	const userNotes = notes.filter((n) => !n.system);
+
+	const formatted = userNotes
+		.map(
+			(n) => `[${n.createdAt}] @${n.author.username}${n.resolved ? ' (resolved)' : ''}:\n${n.body}`,
+		)
+		.join('\n\n---\n\n');
+
+	injections.push({
+		toolName: 'GetMRNotes',
+		params: {
+			comment: 'Pre-fetching MR notes for conversation context',
+			projectPath,
+			mrIid,
+		},
+		result: formatted || '(No comments on this MR)',
+		description: 'Pre-fetched MR notes',
+	});
+
+	return injections;
+}
+
 export async function prepopulateTodosStep(
 	params: FetchContextParams,
 ): Promise<ContextInjection[]> {

src/agents/definitions/contextSteps.ts

@@ -30,7 +30,7 @@ triggers:
     label: PR Conflict Detected
     description: Trigger when a PR has merge conflicts with the base branch
     defaultEnabled: false
-    providers: [github]
+    providers: [github, gitlab]
     contextPipeline: [prContext, directoryListing, contextFiles, workItem]
 
 strategies: {}

src/agents/definitions/resolve-conflicts.yaml

@@ -31,7 +31,7 @@ triggers:
     label: Check Suite Failure
     description: Trigger when CI checks fail
     defaultEnabled: false
-    providers: [github]
+    providers: [github, gitlab]
     contextPipeline: [prContext, directoryListing, contextFiles, workItem]
 
 strategies: {}

src/agents/definitions/respond-to-ci.yaml

@@ -29,7 +29,7 @@ triggers:
     label: PR Comment @mention
     description: Trigger when the implementer bot is @mentioned in a PR comment
     defaultEnabled: false
-    providers: [github]
+    providers: [github, gitlab]
     contextPipeline: [prContext, prConversation, directoryListing, contextFiles]
 
 strategies:

src/agents/definitions/respond-to-pr-comment.yaml

@@ -30,7 +30,7 @@ triggers:
     label: PR Review Submitted
     description: Trigger when a review with changes requested or comments is submitted
     defaultEnabled: false
-    providers: [github]
+    providers: [github, gitlab]
     contextPipeline: [prContext, prConversation, directoryListing, contextFiles]
 
 strategies:
@@ -48,7 +48,7 @@ prompts:
     <%= it.commentBody %>
     ---
 
-    Carefully read each review comment and make the requested changes. Commit and push your changes when done. Use the ReplyToReviewComment tool to respond to individual review comments as you address them. Focus on surgical, targeted fixes unless the reviewer clearly asks for broader changes.
+    Carefully read each review comment and make the requested changes. Commit and push your changes when done. Use the comment reply tool (ReplyToReviewComment or PostMRNote, whichever is available) to respond to individual review comments as you address them. Focus on surgical, targeted fixes unless the reviewer clearly asks for broader changes.
 
 hooks:
   trailing: