feat(gitlab): add @droid fill mode (native parity, no webhook receiver)

Adds GitLab support for `@droid fill` via the three native pipeline-
firing surfaces that don't require a webhook receiver: MR description,
MR title, and labels. Plus an `automatic_fill` always-on mode.

How the trigger works:

  * `automatic_fill: "true"` -> droid-fill runs on every MR event
    and decides to fill based on description content.
  * `@droid fill` in MR title -> matched at rule level via
    $CI_MERGE_REQUEST_TITLE.
  * `droid:fill` label -> matched at rule level via
    $CI_MERGE_REQUEST_LABELS.
  * `@droid fill` in MR description -> not matchable at rule level
    (description isn't in env), so the job runs and exits early via
    state file if no match found in title/labels and the description
    fetched from the API doesn't contain the phrase.

After fill completes the prompt instructs the model to strip the
`@droid fill` token from the new description so the next
`merge_request_event` (fired by our own update) does not re-fire fill.

Discussion-comment triggers (`@droid fill` posted as a note on the
MR) still require a webhook receiver because GitLab does not fire CI
on note events. That subset is deliberately deferred.

Files:

  * `gitlab/templates/fill.yml` — new GitLab CI/CD Component with
    one `droid-fill` job, three trigger rules, MCP registration,
    `.droid-debug/` artifact staging.
  * `src/gitlab/validation/trigger.ts` — port of GitHub's
    `checkContainsTrigger` for the fill path with
    `checkContainsFillTrigger` + `stripFillTrigger`.
  * `src/gitlab/prompts/fill.ts` — fill prompt mirroring the GitHub
    `fill-prompt.ts` but writing back via
    `gitlab_mr___update_mr_description` instead of
    `github_pr___update_pr_description`.
  * `src/entrypoints/gitlab-fill-prepare.ts` — single-pass prepare
    that reads the MR description via API, checks the trigger, and
    writes the fill prompt + state file.
  * `src/gitlab/context.ts` — adds `automaticFill` input and
    `mr.labels` parsed from `CI_MERGE_REQUEST_LABELS`.

Tests: 24 new tests across `fill-trigger.test.ts` and
`fill-prompt.test.ts`. 469 pass, typecheck clean.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: factory-nizar

src/entrypoints/gitlab-fill-prepare.ts

@@ -0,0 +1,225 @@
+#!/usr/bin/env bun
+
+/**
+ * Prepare step for the GitLab `@droid fill` mode.
+ *
+ * Responsibilities:
+ *   1. Parse GitLab CI env into a normalized context.
+ *   2. Decide whether this pipeline should run fill, based on whether
+ *      `@droid fill` appears in the MR title, description, or labels
+ *      (or `automatic_fill` is enabled).
+ *   3. Fetch the MR via API (description is not exposed as an env var)
+ *      so we can match the trigger phrase against it.
+ *   4. Write the fill prompt + a state file consumed by the CI script.
+ *
+ * Unlike the review flow this is a single-pass job: the fill prompt
+ * itself calls `gitlab_mr___update_mr_description` to write back the
+ * new description.
+ */
+
+import * as fs from "fs/promises";
+import * as path from "path";
+import { parseGitlabContext, isMergeRequestContext } from "../gitlab/context";
+import { setupGitlabToken, MissingGitlabTokenError } from "../gitlab/token";
+import { GitlabClient } from "../gitlab/api/client";
+import { computeReviewArtifacts } from "../gitlab/data/review-artifacts";
+import { checkContainsFillTrigger } from "../gitlab/validation/trigger";
+import { generateGitlabFillPrompt } from "../gitlab/prompts/fill";
+import { setupDroidSettings } from "../../base-action/src/setup-droid-settings";
+
+export type FillPrepareState = {
+  shouldRunFill: boolean;
+  projectId: string;
+  projectPath: string;
+  mrIid: number | null;
+  pipelineUrl: string | null;
+  jobUrl: string | null;
+  promptPath: string | null;
+  fillModel: string | null;
+  descriptionPath: string | null;
+  diffPath: string | null;
+  triggerSource: string;
+  reason?: string;
+};
+
+function promptFilePath(): string {
+  return process.env.DROID_PROMPT_FILE || "/tmp/droid-prompts/droid-prompt.txt";
+}
+
+function promptsDir(): string {
+  return path.dirname(promptFilePath());
+}
+
+function stateFilePath(): string {
+  return (
+    process.env.DROID_STATE_FILE ||
+    path.join(process.env.CI_PROJECT_DIR || "/tmp", ".droid-state.json")
+  );
+}
+
+function resolvedEnvShimPath(): string {
+  return (
+    process.env.DROID_RESOLVED_ENV_FILE || "/tmp/droid-prompts/resolved-env.sh"
+  );
+}
+
+function shellEscape(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+async function writeResolvedEnvShim(
+  extras: Record<string, string | null>,
+): Promise<void> {
+  const filePath = resolvedEnvShimPath();
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const lines = [
+    "# Generated by gitlab-fill-prepare; source this to expose resolved env.",
+  ];
+  for (const [k, v] of Object.entries(extras)) {
+    lines.push(`export ${k}=${shellEscape(v ?? "")}`);
+  }
+  await fs.writeFile(filePath, lines.join("\n") + "\n");
+  console.log(`Wrote resolved env shim to ${filePath}`);
+}
+
+async function writeState(state: FillPrepareState): Promise<void> {
+  const filePath = stateFilePath();
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(state, null, 2));
+  console.log(`Wrote droid fill state to ${filePath}`);
+}
+
+async function run(): Promise<void> {
+  const context = parseGitlabContext();
+
+  const baseState: FillPrepareState = {
+    shouldRunFill: false,
+    projectId: context.project.id,
+    projectPath: context.project.pathWithNamespace,
+    mrIid: context.mr?.iid ?? null,
+    pipelineUrl: context.pipelineUrl,
+    jobUrl: context.jobUrl,
+    promptPath: null,
+    fillModel: context.inputs.fillModel || null,
+    descriptionPath: null,
+    diffPath: null,
+    triggerSource: "none",
+  };
+
+  if (!isMergeRequestContext(context)) {
+    console.log(
+      "Not a merge_request_event pipeline; skipping droid fill prepare.",
+    );
+    await writeState({ ...baseState, reason: "not-merge-request-event" });
+    return;
+  }
+
+  let token: string;
+  try {
+    token = setupGitlabToken();
+  } catch (err) {
+    if (err instanceof MissingGitlabTokenError) {
+      console.error(err.message);
+    }
+    throw err;
+  }
+
+  try {
+    await setupDroidSettings(context.inputs.settings || undefined);
+  } catch (err) {
+    console.warn(
+      "Failed to setup droid settings; continuing with defaults:",
+      err,
+    );
+  }
+
+  const client = new GitlabClient(token, context.apiUrl);
+  const mrIid = context.mr.iid;
+  const projectId = context.project.id;
+
+  // Description is not exposed as an env var; fetch via API.
+  const mr = await client.getMr(projectId, mrIid);
+  const description = mr.description ?? "";
+  const title = mr.title ?? context.mr.title ?? "";
+  const labels = context.mr.labels;
+
+  const trigger = checkContainsFillTrigger({
+    description,
+    title,
+    labels,
+    triggerPhrase: context.inputs.triggerPhrase,
+    automaticFill: context.inputs.automaticFill,
+  });
+
+  console.log(
+    `Fill trigger check: matched=${trigger.matched} source=${trigger.source} ` +
+      `triggerPhrase=${JSON.stringify(context.inputs.triggerPhrase)} ` +
+      `labels=${JSON.stringify(labels)}`,
+  );
+
+  if (!trigger.matched) {
+    console.log(
+      "No fill trigger found in description/title/labels and automatic_fill is off; skipping droid exec.",
+    );
+    await writeState({
+      ...baseState,
+      reason: "no-fill-trigger",
+      triggerSource: trigger.source,
+    });
+    return;
+  }
+
+  // Reuse the review-artifacts helper for diff + description; we ignore
+  // existing_comments.json for fill mode (the prompt does not need them).
+  console.log("Computing fill artifacts (diff, description)...");
+  const artifacts = await computeReviewArtifacts({
+    client,
+    projectId,
+    mrIid,
+    outDir: promptsDir(),
+  });
+  console.log(
+    `Artifacts written:\n  ${artifacts.diffPath}\n  ${artifacts.descriptionPath}`,
+  );
+
+  await writeResolvedEnvShim({
+    DROID_MR_IID: String(mrIid),
+    FILL_MODEL: context.inputs.fillModel || "",
+  });
+
+  const promptCtx = {
+    projectPath: context.project.pathWithNamespace,
+    mrIid,
+    mrTitle: title,
+    sourceBranch: artifacts.mr.source_branch ?? "",
+    targetBranch: artifacts.mr.target_branch ?? "",
+    triggerSource: trigger.source,
+    triggerPhrase: context.inputs.triggerPhrase,
+    descriptionPath: artifacts.descriptionPath,
+    diffPath: artifacts.diffPath,
+  };
+
+  const prompt = generateGitlabFillPrompt(promptCtx);
+  const promptPath = promptFilePath();
+  await fs.mkdir(path.dirname(promptPath), { recursive: true });
+  await fs.writeFile(promptPath, prompt);
+  console.log(`Wrote fill prompt (${prompt.length} bytes) to ${promptPath}`);
+
+  await writeState({
+    ...baseState,
+    shouldRunFill: true,
+    promptPath,
+    descriptionPath: artifacts.descriptionPath,
+    diffPath: artifacts.diffPath,
+    triggerSource: trigger.source,
+  });
+}
+
+if (import.meta.main) {
+  run().catch((error) => {
+    console.error("gitlab-fill-prepare failed:", error);
+    process.exit(1);
+  });
+}
+
+export { run };

src/gitlab/context.ts

@@ -18,6 +18,7 @@ export type ParsedGitlabContext = {
     targetBranchSha: string | null;
     diffBaseSha: string | null;
     title: string | null;
+    labels: string[];
   } | null;
   commit: {
     sha: string;
@@ -32,6 +33,7 @@ export type ParsedGitlabContext = {
   inputs: {
     automaticReview: boolean;
     automaticSecurityReview: boolean;
+    automaticFill: boolean;
     triggerPhrase: string;
     reviewDepth: string;
     reviewModel: string;
@@ -81,13 +83,19 @@ export function parseGitlabContext(): ParsedGitlabContext {
     process.env.CI_PROJECT_URL || `${serverUrl}/${projectPath}`;
 
   const mrIid = optional("CI_MERGE_REQUEST_IID");
+  const labelsRaw = optional("CI_MERGE_REQUEST_LABELS") ?? "";
+  const labels = labelsRaw
+    .split(",")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
   const mr = mrIid
     ? {
         iid: parseInt(mrIid, 10),
         sourceBranchSha: optional("CI_MERGE_REQUEST_SOURCE_BRANCH_SHA"),
         targetBranchSha: optional("CI_MERGE_REQUEST_TARGET_BRANCH_SHA"),
         diffBaseSha: optional("CI_MERGE_REQUEST_DIFF_BASE_SHA"),
         title: optional("CI_MERGE_REQUEST_TITLE"),
+        labels,
       }
     : null;
 
@@ -119,6 +127,7 @@ export function parseGitlabContext(): ParsedGitlabContext {
     inputs: {
       automaticReview: process.env.AUTOMATIC_REVIEW === "true",
       automaticSecurityReview: process.env.AUTOMATIC_SECURITY_REVIEW === "true",
+      automaticFill: process.env.AUTOMATIC_FILL === "true",
       triggerPhrase: process.env.TRIGGER_PHRASE ?? "@droid",
       reviewDepth: process.env.REVIEW_DEPTH ?? "deep",
       reviewModel: process.env.REVIEW_MODEL ?? "",

src/gitlab/prompts/fill.ts

@@ -0,0 +1,61 @@
+/**
+ * Prompt for the `@droid fill` mode on GitLab MRs. Mirrors the GitHub
+ * action's fill-prompt but writes back via the GitLab MCP server's
+ * `update_mr_description` tool instead of `update_pr_description`.
+ */
+
+export type GitlabFillPromptContext = {
+  projectPath: string;
+  mrIid: number;
+  mrTitle: string;
+  sourceBranch: string;
+  targetBranch: string;
+  triggerSource: "description" | "title" | "label" | "automatic_fill" | "none";
+  triggerPhrase: string;
+  descriptionPath: string;
+  diffPath: string;
+};
+
+export function generateGitlabFillPrompt(ctx: GitlabFillPromptContext): string {
+  return `You are updating the description of merge request !${ctx.mrIid} in ${ctx.projectPath}.
+
+## MR details
+* Title: ${ctx.mrTitle}
+* Source branch: ${ctx.sourceBranch}
+* Target branch: ${ctx.targetBranch}
+* Trigger: \`${ctx.triggerPhrase} fill\` detected via **${ctx.triggerSource}**
+
+## Inputs already on disk
+* Current description: \`${ctx.descriptionPath}\` (may contain \`${ctx.triggerPhrase} fill\` as placeholder text)
+* Full unified diff: \`${ctx.diffPath}\`
+
+## Procedure
+1. Read \`${ctx.descriptionPath}\` and \`${ctx.diffPath}\` to ground every claim in verified changes.
+2. Check the workspace for an MR description template:
+   * \`.gitlab/merge_request_templates/Default.md\`
+   * \`.gitlab/merge_request_templates/default.md\`
+   * Any other file under \`.gitlab/merge_request_templates/\` (use the first match)
+   If one exists, fill out its sections. Otherwise use:
+   \`\`\`
+   ## Summary
+   ## Changes
+   ## Implementation Details (optional when not applicable)
+   ## Testing
+   ## Breaking Changes (only when relevant)
+   \`\`\`
+3. Preserve any non-placeholder content already in the existing description (ticket links, custom sections, manual notes). If a detail is uncertain, keep it as-is.
+4. Do **not** infer or invent ticket references (Linear, Jira, GitLab issues, etc.) that are not already explicitly present in the existing description, MR comments, or branch name. Never extract ticket IDs from commit messages or other indirect sources. If no ticket is linked, leave the section empty or omit it.
+5. **Strip the trigger phrase.** Remove any literal occurrence of \`${ctx.triggerPhrase} fill\` from the new description so the next \`merge_request_event\` (fired by this update) does not re-trigger fill mode.
+6. Keep the tone concise and factual. Use clear Markdown headings and bullets. For sections you cannot verify, write \`[To be filled by author]\`.
+
+## Submission
+* Call \`gitlab_mr___update_mr_description\` with the final Markdown body and \`mr_iid: ${ctx.mrIid}\`. This is the only mutation tool available in this pass.
+* Do **not** post inline review comments, summary notes, or anything else. Fill mode is description-only.
+* Do **not** call \`update_mr_description\` more than once. Compose the final body in one go and submit it.
+
+## Hard constraints
+* Output must be Markdown — no surrounding code fence, no commentary.
+* Do not modify any files other than the MR description.
+* If the diff is empty or unreadable, abort with a clear error message and do **not** call \`update_mr_description\`.
+`;
+}