feat(integrations): add GitLab as alternative SCM provider (mongrel-intelligence#1087)

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)
- 8 trigger handlers (MR opened, pipeline success/failure, approval,
  comment mention, merged, conflict detected, ready to merge)
- 10 GitLab gadgets for agent MR operations
- Frontend SCM tab with GitHub/GitLab provider selector
- CLI webhook commands with --gitlab-only support
- Worker entry GitLab job dispatch

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: suda

package-lock.json

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

package.json

@@ -9,7 +9,7 @@ import { CAPABILITIES } from '../capabilities/registry.js';
 export const IntegrationCategorySchema = z.enum(['pm', 'scm', 'alerting']);
 
 // Known providers for validation
-export const KnownProviderSchema = z.enum(['trello', 'jira', 'github', 'sentry']);
+export const KnownProviderSchema = z.enum(['trello', 'jira', 'github', 'gitlab', 'sentry']);
 
 // Trigger event format validation: {category}:{event-name}
 // Categories: pm, scm (integration-bound), alerting (monitoring), internal (orchestration chaining)

src/agents/definitions/schema.ts

@@ -168,63 +168,63 @@ export const TRIGGER_REGISTRY: Record<TriggerCategory, KnownTriggerEvent[]> = {
 			label: 'CI Passed',
 			description: 'CI check suite passed',
 			contextPipeline: ['prContext'],
-			providers: ['github'],
+			providers: ['github', 'gitlab'],
 		},
 		{
 			event: 'scm:check-suite-failure',
 			label: 'CI Failed',
 			description: 'CI check suite failed',
 			contextPipeline: ['prContext'],
-			providers: ['github'],
+			providers: ['github', 'gitlab'],
 		},
 		{
 			event: 'scm:pr-review-submitted',
 			label: 'PR Review Submitted',
 			description: 'Review submitted on PR',
 			contextPipeline: ['prContext', 'prConversation'],
-			providers: ['github'],
+			providers: ['github', 'gitlab'],
 		},
 		{
 			event: 'scm:review-requested',
 			label: 'Review Requested',
 			description: 'Review requested on PR',
 			contextPipeline: ['prContext'],
-			providers: ['github'],
+			providers: ['github', 'gitlab'],
 		},
 		{
 			event: 'scm:pr-opened',
 			label: 'PR Opened',
 			description: 'PR opened',
 			contextPipeline: ['prContext'],
-			providers: ['github'],
+			providers: ['github', 'gitlab'],
 		},
 		{
 			event: 'scm:pr-comment-mention',
 			label: 'PR Comment Mention',
 			description: 'Bot @mentioned in PR comment',
 			contextPipeline: ['prContext', 'prConversation'],
-			providers: ['github'],
+			providers: ['github', 'gitlab'],
 		},
 		{
 			event: 'scm:pr-merged',
 			label: 'PR Merged',
 			description: 'PR merged to base branch',
 			contextPipeline: ['prContext'],
-			providers: ['github'],
+			providers: ['github', 'gitlab'],
 		},
 		{
 			event: 'scm:pr-ready-to-merge',
 			label: 'PR Ready to Merge',
 			description: 'PR approved and CI passed',
 			contextPipeline: ['prContext'],
-			providers: ['github'],
+			providers: ['github', 'gitlab'],
 		},
 		{
 			event: 'scm:pr-conflict-detected',
 			label: 'PR Conflict Detected',
 			description: 'PR has merge conflicts with the base branch',
 			contextPipeline: ['prContext'],
-			providers: ['github'],
+			providers: ['github', 'gitlab'],
 		},
 	],
 	internal: [

src/api/routers/_shared/triggerTypes.ts

@@ -15,12 +15,13 @@ import {
 import { trelloCreateWebhook, trelloDeleteWebhook, trelloListWebhooks } from './webhooks/trello.js';
 import type {
 	GitHubWebhook,
+	GitLabWebhookInfo,
 	JiraWebhookInfo,
 	SentryWebhookInfo,
 	TrelloWebhook,
 } from './webhooks/types.js';
 
-export type { GitHubWebhook, JiraWebhookInfo, SentryWebhookInfo, TrelloWebhook };
+export type { GitHubWebhook, GitLabWebhookInfo, JiraWebhookInfo, SentryWebhookInfo, TrelloWebhook };
 
 export const webhooksRouter = router({
 	list: adminProcedure
@@ -52,9 +53,16 @@ export const webhooksRouter = router({
 				};
 			}
 
+			// GitLab — informational only (webhooks must be configured in GitLab UI)
+			let gitlab: GitLabWebhookInfo[] | null = null;
+			if (pctx.scmProvider === 'gitlab') {
+				gitlab = [];
+			}
+
 			return {
 				trello: trelloResult.status === 'fulfilled' ? trelloResult.value : [],
 				github: githubResult.status === 'fulfilled' ? githubResult.value : [],
+				gitlab,
 				jira: jiraResult.status === 'fulfilled' ? jiraResult.value : [],
 				sentry,
 				errors: {
@@ -72,6 +80,7 @@ export const webhooksRouter = router({
 				callbackBaseUrl: z.string().url(),
 				trelloOnly: z.boolean().optional(),
 				githubOnly: z.boolean().optional(),
+				gitlabOnly: z.boolean().optional(),
 				jiraOnly: z.boolean().optional(),
 				oneTimeTokens: oneTimeTokensSchema,
 			}),
@@ -83,6 +92,7 @@ export const webhooksRouter = router({
 			const results: {
 				trello?: TrelloWebhook | string;
 				github?: GitHubWebhook | string;
+				gitlab?: { url: string; webhookSecretSet: boolean } | string;
 				jira?: JiraWebhookInfo | string;
 				sentry?: SentryWebhookInfo;
 				labelsEnsured?: string[];
@@ -134,8 +144,22 @@ export const webhooksRouter = router({
 				results.labelsEnsured = await jiraEnsureLabels(pctx);
 			}
 
+			// GitLab — display-only (webhooks must be configured in GitLab UI)
+			if (
+				!input.trelloOnly &&
+				!input.githubOnly &&
+				!input.jiraOnly &&
+				pctx.scmProvider === 'gitlab' &&
+				pctx.gitlabToken
+			) {
+				results.gitlab = {
+					url: `${baseUrl}/gitlab/webhook`,
+					webhookSecretSet: !!pctx.gitlabWebhookSecret,
+				};
+			}
+
 			// GitHub webhook
-			if (!input.trelloOnly && !input.jiraOnly && pctx.githubToken) {
+			if (!input.trelloOnly && !input.gitlabOnly && !input.jiraOnly && pctx.githubToken) {
 				const githubCallbackUrl = `${baseUrl}/github/webhook`;
 				const existing = await githubListWebhooks(pctx);
 				const duplicate = existing.find(
@@ -168,6 +192,7 @@ export const webhooksRouter = router({
 				callbackBaseUrl: z.string().url(),
 				trelloOnly: z.boolean().optional(),
 				githubOnly: z.boolean().optional(),
+				gitlabOnly: z.boolean().optional(),
 				jiraOnly: z.boolean().optional(),
 				oneTimeTokens: oneTimeTokensSchema,
 			}),
@@ -176,9 +201,10 @@ export const webhooksRouter = router({
 			const pctx = await resolveProjectContext(input.projectId, ctx.effectiveOrgId);
 			applyOneTimeTokens(pctx, input.oneTimeTokens);
 			const baseUrl = input.callbackBaseUrl.replace(/\/$/, '');
-			const deleted: { trello: string[]; github: number[]; jira: number[] } = {
+			const deleted: { trello: string[]; github: number[]; gitlab: number[]; jira: number[] } = {
 				trello: [],
 				github: [],
+				gitlab: [],
 				jira: [],
 			};
 

src/api/routers/webhooks.ts

@@ -38,18 +38,27 @@ export async function resolveProjectContext(
 	const alertingIntegration = await getIntegrationByProjectAndCategory(projectId, 'alerting');
 	const sentryConfigured = alertingIntegration?.provider === 'sentry' && !!creds.SENTRY_API_TOKEN;
 
+	// Determine SCM provider from integration config
+	const scmIntegration = await getIntegrationByProjectAndCategory(projectId, 'scm');
+	const scmProvider = (scmIntegration?.provider === 'gitlab' ? 'gitlab' : 'github') as
+		| 'github'
+		| 'gitlab';
+
 	return {
 		projectId,
 		orgId: project.orgId,
 		repo: project.repo,
 		pmType: project.pm?.type ?? 'trello',
+		scmProvider,
 		boardId: trelloConfig?.boardId,
 		jiraBaseUrl: jiraConfig?.baseUrl,
 		jiraProjectKey: jiraConfig?.projectKey,
 		jiraLabels,
 		trelloApiKey: creds.TRELLO_API_KEY ?? '',
 		trelloToken: creds.TRELLO_TOKEN ?? '',
 		githubToken: creds.GITHUB_TOKEN_IMPLEMENTER ?? '',
+		gitlabToken: creds.GITLAB_TOKEN_IMPLEMENTER ?? '',
+		gitlabWebhookSecret: creds.GITLAB_WEBHOOK_SECRET ?? undefined,
 		jiraEmail: creds.JIRA_EMAIL ?? '',
 		jiraApiToken: creds.JIRA_API_TOKEN ?? '',
 		webhookSecret: creds.GITHUB_WEBHOOK_SECRET ?? undefined,

src/api/routers/webhooks/context.ts

@@ -26,6 +26,12 @@ export interface JiraWebhookInfo {
 	enabled: boolean;
 }
 
+export interface GitLabWebhookInfo {
+	id: number;
+	url: string;
+	enableSslVerification: boolean;
+}
+
 export interface SentryWebhookInfo {
 	url: string;
 	webhookSecretSet: boolean;
@@ -37,13 +43,16 @@ export interface ProjectContext {
 	orgId: string;
 	repo?: string;
 	pmType: 'trello' | 'jira';
+	scmProvider: 'github' | 'gitlab';
 	boardId?: string;
 	jiraBaseUrl?: string;
 	jiraProjectKey?: string;
 	jiraLabels?: string[];
 	trelloApiKey: string;
 	trelloToken: string;
 	githubToken: string;
+	gitlabToken: string;
+	gitlabWebhookSecret?: string;
 	jiraEmail?: string;
 	jiraApiToken?: string;
 	webhookSecret?: string;

src/api/routers/webhooks/types.ts

@@ -15,6 +15,7 @@ export default class WebhooksCreate extends DashboardCommand {
 		}),
 		'trello-only': Flags.boolean({ description: 'Only create Trello webhook', default: false }),
 		'github-only': Flags.boolean({ description: 'Only create GitHub webhook', default: false }),
+		'gitlab-only': Flags.boolean({ description: 'Only create GitLab webhook', default: false }),
 		'github-token': Flags.string({
 			description: 'One-time GitHub PAT with admin:repo_hook scope',
 		}),
@@ -44,6 +45,7 @@ export default class WebhooksCreate extends DashboardCommand {
 					callbackBaseUrl,
 					trelloOnly: flags['trello-only'],
 					githubOnly: flags['github-only'],
+					gitlabOnly: flags['gitlab-only'],
 					oneTimeTokens: Object.keys(oneTimeTokens).length > 0 ? oneTimeTokens : undefined,
 				}),
 			);
@@ -71,6 +73,23 @@ export default class WebhooksCreate extends DashboardCommand {
 				}
 			}
 
+			if (result.gitlab) {
+				if (typeof result.gitlab === 'string') {
+					this.log(`GitLab: ${result.gitlab}`);
+				} else {
+					this.log('');
+					this.log('GitLab (manual setup required):');
+					this.log(`  Webhook URL: ${result.gitlab.url}`);
+					this.log('  Steps:');
+					this.log('    1. Go to your GitLab project > Settings > Webhooks');
+					this.log('    2. Set the URL to the webhook URL above');
+					this.log('    3. Enable triggers: Push events, Merge request events, Pipeline events');
+					if (result.gitlab.webhookSecretSet) {
+						this.log('    4. Set the Secret Token to your configured GITLAB_WEBHOOK_SECRET');
+					}
+				}
+			}
+
 			if (result.jira) {
 				if (typeof result.jira === 'string') {
 					this.log(`JIRA: ${result.jira}`);