@bugmole/cli 0.4.0

package/src/registry-worker/github/checks.ts

@@ -0,0 +1,374 @@
+// GitHub PR checks: a pull request (or a successful deployment) starts the
+// project's plans, and each run reports back as a check run on the commit.
+//
+// The dashboard receives GitHub's webhooks (it holds the webhook secret) and
+// forwards the few fields that matter here. Check runs are created and
+// updated from the outbox, so GitHub being slow never slows a run down.
+import { createCheckRun, githubAppConfigured, GithubAppError, updateCheckRun, type CheckRunUpdate, type GithubAppEnv } from "../../integrations/github-app.js";
+import type { Env, Principal } from "../core.js";
+import { memberOfProject, newId, requestJson, response } from "../core.js";
+import { getEntitlements, workspaceOfProject } from "../billing/entitlements.js";
+import { flagOn } from "../flags.js";
+import { runChangedHooks, runService, type InternalRunFields } from "../hooks.js";
+import { auditProject } from "../org/audit.js";
+import { enqueue, PermanentDeliveryError, registerOutboxHandler } from "../notifications/outbox.js";
+import { detachedContext, matchPath, registerRoutes, type AuthedRouteContext } from "../routes/index.js";
+import { previewUrl } from "../repo-triggers.js";
+import { digging, molesFound, NO_BUGS } from "../../runtime/mole-voice.js";
+
+export const DASHBOARD_SERVICE_ID = "bugmole-dashboard-service";
+const TRIGGERS = new Set(["pull_request", "deployment"]);
+const REPO = /^[A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}$/;
+const SHA = /^[0-9a-f]{40}$/;
+
+export type GithubEvent =
+  | { type: "pull_request"; installationId: number; repo: string; sha: string; prNumber: number; branch?: string }
+  | { type: "deployment"; installationId: number; repo: string; sha: string; url: string; environment?: string; prNumber?: number }
+  | { type: "check_rerun"; installationId: number; repo: string; checkRunId: number };
+
+type Binding = {
+  id: string;
+  project_id: string;
+  installation_id: number;
+  repo_full_name: string;
+  plan_ids_json: string | null;
+  environment_id: string | null;
+  trigger: "pull_request" | "deployment";
+  base_url_template: string | null;
+  execution_mode: "self" | "cloud";
+  created_by: string;
+};
+
+function github(env: Env): GithubAppEnv {
+  return env as Env & GithubAppEnv;
+}
+
+function dashboard(env: Env): string {
+  return (env.DASHBOARD_URL || "https://app.bugmole.com").replace(/\/$/, "");
+}
+
+export { previewUrl };
+
+/** GitLab's merge request checks share this gate — one PR/MR checks feature regardless of provider. */
+export async function prChecksOn(env: Env, projectId: string): Promise<boolean> {
+  const workspaceId = await workspaceOfProject(env, projectId);
+  if (!workspaceId || !(await flagOn(env, workspaceId, "pr_checks"))) return false;
+  return (await getEntitlements(env, workspaceId)).features.prChecks;
+}
+
+/** The binding's installation must still be connected to its project and cover the repo. */
+async function installationCovers(env: Env, projectId: string, installationId: number, repo: string): Promise<boolean> {
+  const row = await env.DB.prepare(`
+    SELECT repository_selection AS selection, repositories_json AS repos FROM github_installations
+    WHERE project_id = ? AND installation_id = ? AND revoked_at IS NULL
+  `).bind(projectId, installationId).first<{ selection: string; repos: string }>();
+  if (!row) return false;
+  if (row.selection === "all") return true;
+  const [owner, name] = repo.toLowerCase().split("/");
+  const repos = JSON.parse(row.repos || "[]") as Array<{ owner: string; repo: string }>;
+  return repos.some((item) => item.owner.toLowerCase() === owner && item.repo.toLowerCase() === name);
+}
+
+async function publishedPlans(env: Env, projectId: string, only: string[] | null): Promise<string[]> {
+  const rows = await env.DB.prepare("SELECT plan_id AS planId FROM plan_drafts WHERE project_id = ? ORDER BY plan_id").bind(projectId).all<{ planId: string }>();
+  const all = rows.results.map((row) => row.planId);
+  return only ? all.filter((planId) => only.includes(planId)) : all;
+}
+
+async function startRun(env: Env, binding: Binding, planId: string, idempotencyKey: string, internal: InternalRunFields): Promise<string | null> {
+  if (!runService.create) throw new Error("Run creation isn't wired");
+  const principal: Principal = { aegisId: binding.created_by, projectIds: [], scopes: ["*"] };
+  const request = new Request("https://registry.internal/github", {
+    method: "POST",
+    body: JSON.stringify({ planId, idempotencyKey, executionMode: binding.execution_mode, ...(binding.environment_id ? { environmentId: binding.environment_id } : {}) }),
+  });
+  const created = await runService.create(request, env, principal, binding.project_id, detachedContext(), internal);
+  const body = await created.json().catch(() => ({})) as { run?: { id: string }; error?: string };
+  if (!created.ok || !body.run) {
+    console.warn(`[github] couldn't start ${planId} for ${binding.repo_full_name}: ${body.error ?? created.status}`);
+    return null;
+  }
+  // A new run (201) gets a check; a repeat delivery (200) already has one.
+  if (created.status === 201) await enqueue(env, "github.check.create", { runId: body.run.id }, { dedupeKey: `gh-check-create:${body.run.id}` });
+  return body.run.id;
+}
+
+export async function handleGithubEvent(env: Env, event: GithubEvent): Promise<{ started: string[] }> {
+  const started: string[] = [];
+  if (event.type === "check_rerun") {
+    const run = await env.DB.prepare(`
+      SELECT r.plan_id AS planId, r.project_id AS projectId, r.commit_sha AS sha, r.pr_number AS prNumber,
+             r.environment_base_url AS baseUrl, r.trigger_source AS trigger, r.repo_full_name AS repo
+      FROM runs r WHERE r.check_run_id = ? AND r.github_installation_id = ?
+    `).bind(event.checkRunId, event.installationId).first<{ planId: string; projectId: string; sha: string; prNumber: number | null; baseUrl: string | null; trigger: string; repo: string }>();
+    if (!run || run.repo.toLowerCase() !== event.repo.toLowerCase()) return { started };
+    const binding = await env.DB.prepare("SELECT * FROM project_repo_bindings WHERE project_id = ? AND lower(repo_full_name) = lower(?) AND trigger = ? AND enabled = 1")
+      .bind(run.projectId, run.repo, run.trigger).first<Binding>();
+    if (!binding || !(await prChecksOn(env, binding.project_id))) return { started };
+    const id = await startRun(env, binding, run.planId, `gh:rerun:${event.checkRunId}:${newId("r")}`, {
+      triggerSource: run.trigger, repoFullName: binding.repo_full_name, commitSha: run.sha,
+      prNumber: run.prNumber ?? undefined, githubInstallationId: event.installationId, environmentBaseUrl: run.baseUrl ?? undefined,
+    });
+    if (id) started.push(id);
+    return { started };
+  }
+
+  const bindings = await env.DB.prepare(`
+    SELECT * FROM project_repo_bindings WHERE lower(repo_full_name) = lower(?) AND installation_id = ? AND trigger = ? AND enabled = 1
+  `).bind(event.repo, event.installationId, event.type).all<Binding>();
+  for (const binding of bindings.results) {
+    if (!(await prChecksOn(env, binding.project_id))) continue;
+    if (!(await installationCovers(env, binding.project_id, binding.installation_id, binding.repo_full_name))) continue;
+    let baseUrl: string | undefined;
+    if (event.type === "deployment") {
+      baseUrl = binding.base_url_template ? previewUrl(binding.base_url_template, { sha: event.sha, number: event.prNumber }) ?? event.url : event.url;
+    } else if (binding.base_url_template) {
+      const url = previewUrl(binding.base_url_template, { number: event.prNumber, sha: event.sha, branch: event.branch });
+      if (!url) continue;
+      baseUrl = url;
+    }
+    const plans = await publishedPlans(env, binding.project_id, binding.plan_ids_json ? JSON.parse(binding.plan_ids_json) as string[] : null);
+    for (const planId of plans) {
+      const id = await startRun(env, binding, planId, `gh:${binding.id}:${event.sha}:${planId}`, {
+        triggerSource: binding.trigger,
+        repoFullName: binding.repo_full_name,
+        commitSha: event.sha,
+        prNumber: event.prNumber,
+        githubInstallationId: binding.installation_id,
+        environmentBaseUrl: baseUrl,
+      });
+      if (id) started.push(id);
+    }
+  }
+  return { started };
+}
+
+// --- Check runs ------------------------------------------------------------------------------
+
+type RunForCheck = {
+  id: string;
+  projectId: string;
+  planId: string;
+  status: string;
+  repo: string | null;
+  sha: string | null;
+  installationId: number | null;
+  checkRunId: number | null;
+  passed: number | null;
+  failed: number | null;
+  error: string | null;
+  baseUrl: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+};
+
+async function runForCheck(env: Env, runId: string): Promise<RunForCheck | null> {
+  return env.DB.prepare(`
+    SELECT id, project_id AS projectId, plan_id AS planId, status, repo_full_name AS repo, commit_sha AS sha,
+           github_installation_id AS installationId, check_run_id AS checkRunId, steps_passed AS passed,
+           steps_failed AS failed, error_message AS error, environment_base_url AS baseUrl,
+           started_at AS startedAt, completed_at AS completedAt
+    FROM runs WHERE id = ?
+  `).bind(runId).first<RunForCheck>();
+}
+
+function iso(value: string | null): string | undefined {
+  if (!value) return undefined;
+  return /[zZ]$/.test(value) ? value : `${value.replace(" ", "T")}Z`;
+}
+
+function completedTitle(title: string, conclusion: "success" | "cancelled" | "failure", failed: number): string {
+  if (conclusion === "cancelled") return `${title} was cancelled`;
+  // A failure with no failed step (the run couldn't start) found no bugs.
+  if (conclusion === "failure" && failed === 0) return `${title} failed`;
+  return conclusion === "success" ? `${title} passed: ${NO_BUGS.toLowerCase()}` : `${title}: ${molesFound(failed).replace(/^Our/, "our")}`;
+}
+
+export function checkUpdateFor(run: RunForCheck, detailsUrl: string): CheckRunUpdate {
+  const title = `Bugmole: ${run.planId}`;
+  if (run.status === "queued") return { status: "queued", details_url: detailsUrl, output: { title, summary: "Waiting for a runner." } };
+  if (run.status === "running") {
+    return { status: "in_progress", started_at: iso(run.startedAt), details_url: detailsUrl, output: { title, summary: digging(run.baseUrl) } };
+  }
+  const conclusion = run.status === "success" ? "success" : run.status === "cancelled" ? "cancelled" : "failure";
+  const summary = [
+    `${run.passed ?? 0} step${run.passed === 1 ? "" : "s"} passed, ${run.failed ?? 0} failed${run.baseUrl ? ` on ${run.baseUrl}` : ""}.`,
+    run.error ? `\n\n> ${run.error.slice(0, 500).replaceAll("\n", "\n> ")}` : "",
+    `\n\n[Open the run in Bugmole](${detailsUrl})`,
+  ].join("");
+  return {
+    status: "completed",
+    conclusion,
+    completed_at: iso(run.completedAt) ?? new Date().toISOString(),
+    details_url: detailsUrl,
+    output: { title: completedTitle(title, conclusion, run.failed ?? 0), summary },
+  };
+}
+
+function detailsUrl(env: Env, run: RunForCheck): string {
+  return `${dashboard(env)}/runs?${new URLSearchParams({ project: run.projectId, run: run.id })}`;
+}
+
+async function deliver(work: () => Promise<unknown>): Promise<void> {
+  try {
+    await work();
+  } catch (error) {
+    // A removed installation or repo (403/404/422) won't start working on a retry.
+    if (error instanceof GithubAppError && [401, 403, 404, 422].includes(error.status)) throw new PermanentDeliveryError(error.message);
+    throw error;
+  }
+}
+
+registerOutboxHandler("github.check.create", async (env, payload: { runId: string }) => {
+  const run = await runForCheck(env, payload.runId);
+  if (!run?.repo || !run.sha || !run.installationId || run.checkRunId) return;
+  if (!githubAppConfigured(github(env))) throw new PermanentDeliveryError("The GitHub App isn't configured on the registry");
+  const url = detailsUrl(env, run);
+  await deliver(async () => {
+    const created = await createCheckRun(github(env), run.installationId!, run.repo!, { name: `Bugmole: ${run.planId}`, head_sha: run.sha!, external_id: run.id, ...checkUpdateFor(run, url) });
+    await env.DB.prepare("UPDATE runs SET check_run_id = ? WHERE id = ?").bind(created.id, run.id).run();
+  });
+  // The run may have moved on while the check was being created.
+  if (run.status !== "queued") await enqueue(env, "github.check.update", { runId: run.id });
+});
+
+registerOutboxHandler("github.check.update", async (env, payload: { runId: string }) => {
+  const run = await runForCheck(env, payload.runId);
+  if (!run?.repo || !run.installationId) return;
+  // Created from the other handler, which queues this again once it has an id.
+  if (!run.checkRunId) return;
+  await deliver(() => updateCheckRun(github(env), run.installationId!, run.repo!, run.checkRunId!, checkUpdateFor(run, detailsUrl(env, run))));
+});
+
+runChangedHooks.push(async (env, event) => {
+  const run = await env.DB.prepare("SELECT repo_full_name AS repo FROM runs WHERE id = ?").bind(event.runId).first<{ repo: string | null }>();
+  if (!run?.repo) return;
+  // One update per state; the handler always sends the run's latest state.
+  await enqueue(env, "github.check.update", { runId: event.runId }, { dedupeKey: `gh-check:${event.runId}:${event.status}` });
+});
+
+// --- Routes ----------------------------------------------------------------------------------
+
+function isDashboardService(principal: Principal): boolean {
+  return principal.aegisId === DASHBOARD_SERVICE_ID && principal.scopes.includes("*") && !principal.apiKeyId && !principal.runner;
+}
+
+function validRepo(repo: string): boolean {
+  return REPO.test(repo) && !repo.split("/").some((part) => part === "." || part === "..");
+}
+
+export function parseGithubEvent(body: Record<string, unknown> | null): GithubEvent | null {
+  if (!body) return null;
+  const installationId = Number(body.installationId);
+  const repo = typeof body.repo === "string" ? body.repo : "";
+  if (!Number.isInteger(installationId) || installationId <= 0 || !validRepo(repo)) return null;
+  if (body.type === "check_rerun") {
+    const checkRunId = Number(body.checkRunId);
+    return Number.isInteger(checkRunId) && checkRunId > 0 ? { type: "check_rerun", installationId, repo, checkRunId } : null;
+  }
+  const sha = typeof body.sha === "string" ? body.sha.toLowerCase() : "";
+  if (!SHA.test(sha)) return null;
+  const prNumber = body.prNumber === undefined || body.prNumber === null ? undefined : Number(body.prNumber);
+  if (prNumber !== undefined && (!Number.isInteger(prNumber) || prNumber <= 0)) return null;
+  if (body.type === "pull_request") {
+    if (prNumber === undefined) return null;
+    return { type: "pull_request", installationId, repo, sha, prNumber, ...(typeof body.branch === "string" ? { branch: body.branch } : {}) };
+  }
+  if (body.type === "deployment") {
+    const url = typeof body.url === "string" ? body.url : "";
+    try {
+      const parsed = new URL(url);
+      if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
+    } catch {
+      return null;
+    }
+    return { type: "deployment", installationId, repo, sha, url, ...(prNumber ? { prNumber } : {}), ...(typeof body.environment === "string" ? { environment: body.environment } : {}) };
+  }
+  return null;
+}
+
+async function listBindings({ env, principal }: AuthedRouteContext, projectId: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId))) return response({ error: "Project scope is not allowed" }, 403);
+  const rows = await env.DB.prepare(`
+    SELECT id, installation_id AS installationId, repo_full_name AS repo, plan_ids_json AS planIds, environment_id AS environmentId,
+           trigger, base_url_template AS baseUrlTemplate, execution_mode AS executionMode, enabled, created_at AS createdAt
+    FROM project_repo_bindings WHERE project_id = ? ORDER BY created_at ASC
+  `).bind(projectId).all<Record<string, unknown> & { planIds: string | null; enabled: number }>();
+  return response({
+    available: await prChecksOn(env, projectId),
+    configured: githubAppConfigured(github(env)),
+    bindings: rows.results.map((row) => ({ ...row, planIds: row.planIds ? JSON.parse(row.planIds) : null, enabled: Boolean(row.enabled) })),
+  });
+}
+
+async function saveBinding({ env, principal, request }: AuthedRouteContext, projectId: string, bindingId?: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId, "project.manage"))) return response({ error: "Project scope is not allowed" }, 403);
+  if (request.method === "DELETE") {
+    const deleted = await env.DB.prepare("DELETE FROM project_repo_bindings WHERE id = ? AND project_id = ?").bind(bindingId, projectId).run();
+    if ((deleted.meta?.changes ?? 0) === 0) return response({ error: "Not found" }, 404);
+    await auditProject(env, principal, projectId, { action: "github.checks_removed", targetType: "repo_binding", targetId: bindingId }, request);
+    return response({ deleted: true });
+  }
+  if (!(await prChecksOn(env, projectId))) {
+    return response({ error: "Pull request checks are included in Team and Business.", code: "plan_feature", feature: "prChecks", upgradeUrl: "/billing" }, 402);
+  }
+  const body = await requestJson(request);
+  const repo = typeof body?.repo === "string" ? body.repo.trim() : "";
+  const installationId = Number(body?.installationId);
+  const trigger = body?.trigger ?? "pull_request";
+  const planIds = body?.planIds === null || body?.planIds === undefined ? null : body.planIds;
+  const template = typeof body?.baseUrlTemplate === "string" && body.baseUrlTemplate.trim() ? body.baseUrlTemplate.trim() : null;
+  const executionMode = body?.executionMode ?? "cloud";
+  const environmentId = typeof body?.environmentId === "string" && body.environmentId ? body.environmentId : null;
+  const enabled = body?.enabled === undefined ? true : body.enabled === true;
+  if (!validRepo(repo) || !Number.isInteger(installationId)) return response({ error: "repo (owner/name) and installationId are required" }, 422);
+  if (typeof trigger !== "string" || !TRIGGERS.has(trigger)) return response({ error: "trigger must be pull_request or deployment" }, 422);
+  if (executionMode !== "cloud" && executionMode !== "self") return response({ error: "executionMode must be cloud or self" }, 422);
+  if (planIds !== null && (!Array.isArray(planIds) || !planIds.every((id) => typeof id === "string"))) return response({ error: "planIds must be a list of plan ids, or null for all" }, 422);
+  if (template && !previewUrl(template, { number: 1, sha: "0".repeat(40), branch: "main" })) {
+    return response({ error: "The preview URL template must be an http(s) address; it can use {number}, {sha}, {short_sha} and {branch}" }, 422);
+  }
+  if (!(await installationCovers(env, projectId, installationId, repo))) {
+    return response({ error: "Connect that repository to this project through the GitHub App first" }, 422);
+  }
+  if (environmentId) {
+    const environment = await env.DB.prepare("SELECT id FROM project_environments WHERE project_id = ? AND id = ?").bind(projectId, environmentId).first();
+    if (!environment) return response({ error: "Environment not found in this project" }, 422);
+  }
+  const id = bindingId ?? newId("bind");
+  if (bindingId) {
+    const updated = await env.DB.prepare(`
+      UPDATE project_repo_bindings SET repo_full_name = ?, installation_id = ?, trigger = ?, plan_ids_json = ?, base_url_template = ?,
+        execution_mode = ?, environment_id = ?, enabled = ?
+      WHERE id = ? AND project_id = ?
+    `).bind(repo, installationId, trigger, planIds ? JSON.stringify(planIds) : null, template, executionMode, environmentId, enabled ? 1 : 0, bindingId, projectId).run();
+    if ((updated.meta?.changes ?? 0) === 0) return response({ error: "Not found" }, 404);
+  } else {
+    try {
+      await env.DB.prepare(`
+        INSERT INTO project_repo_bindings (id, project_id, installation_id, repo_full_name, plan_ids_json, environment_id, trigger, base_url_template, execution_mode, enabled, created_by)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).bind(id, projectId, installationId, repo, planIds ? JSON.stringify(planIds) : null, environmentId, trigger, template, executionMode, enabled ? 1 : 0, principal.aegisId).run();
+    } catch {
+      return response({ error: "This repository already runs checks for that trigger" }, 409);
+    }
+  }
+  await auditProject(env, principal, projectId, { action: bindingId ? "github.checks_updated" : "github.checks_added", targetType: "repo_binding", targetId: id, data: { repo, trigger } }, request);
+  return response({ binding: { id, repo, installationId, trigger, planIds, baseUrlTemplate: template, executionMode, environmentId, enabled } }, bindingId ? 200 : 201);
+}
+
+registerRoutes(async (context) => {
+  const { request, url, env, principal } = context;
+  if (url.pathname === "/api/github/events" && request.method === "POST") {
+    if (!isDashboardService(principal)) return response({ error: "Not allowed" }, 403);
+    const event = parseGithubEvent(await requestJson(request));
+    if (!event) return response({ error: "Unrecognized event" }, 422);
+    return response(await handleGithubEvent(env, event));
+  }
+  let params = matchPath(url.pathname, "/api/projects/:projectId/repo-bindings");
+  if (params && request.method === "GET") return listBindings(context, params.projectId);
+  if (params && request.method === "POST") return saveBinding(context, params.projectId);
+  params = matchPath(url.pathname, "/api/projects/:projectId/repo-bindings/:bindingId");
+  if (params && (request.method === "PATCH" || request.method === "DELETE")) return saveBinding(context, params.projectId, params.bindingId);
+  return null;
+});

package/src/registry-worker/gitlab/checks.test.ts

@@ -0,0 +1,141 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { Env } from "../core.js";
+import { call, createTestEnv, seedPlan, seedProject } from "../testing/harness.js";
+import { drainOutbox } from "../notifications/outbox.js";
+import { parseMergeRequestEvent } from "./checks.js";
+
+const SHA = "b".repeat(40);
+
+function fakeGitlab() {
+  const state = { statuses: [] as Array<{ path: string; body: any }>, projects: new Map<string, { id: number; path_with_namespace: string }>(), failWith: 0 };
+  state.projects.set("acme/shop", { id: 555, path_with_namespace: "acme/shop" });
+  const doFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = new URL(String(input));
+    const body = init?.body ? JSON.parse(String(init.body)) : null;
+    const projectMatch = url.pathname.match(/^\/api\/v4\/projects\/([^/]+)$/);
+    if (projectMatch) {
+      const project = state.projects.get(decodeURIComponent(projectMatch[1]));
+      return project ? Response.json(project) : new Response("not found", { status: 404 });
+    }
+    if (state.failWith) return new Response("nope", { status: state.failWith });
+    const statusMatch = url.pathname.match(/^\/api\/v4\/projects\/(\d+)\/statuses\/([0-9a-f]+)$/);
+    if (init?.method === "POST" && statusMatch) {
+      state.statuses.push({ path: url.pathname, body });
+      return Response.json({ id: state.statuses.length });
+    }
+    return new Response("not found", { status: 404 });
+  }) as unknown as typeof fetch;
+  return { state, doFetch };
+}
+
+async function setup(gl: ReturnType<typeof fakeGitlab>, plan = "team") {
+  const created = createTestEnv({ FEATURE_PR_CHECKS: "on", GITLAB_FETCH: gl.doFetch, DASHBOARD_URL: "https://dash.test", SECRETS_ENCRYPTION_KEY: "test-secrets-key-32-bytes-long!!" } as Partial<Env>);
+  const project = await seedProject(created.env);
+  created.db.db.prepare("INSERT INTO workspace_plans (workspace_id, plan) VALUES (?, ?)").run(project.workspaceId, plan);
+  await seedPlan(created.env, project.projectId, project.owner, "checkout");
+  return { ...created, ...project };
+}
+
+function mrPayload(action: string, extra: Record<string, unknown> = {}) {
+  return {
+    object_kind: "merge_request",
+    project: { id: 555, path_with_namespace: "acme/shop" },
+    object_attributes: { iid: 7, action, source_branch: "feature", last_commit: { id: SHA }, ...extra },
+  };
+}
+
+test("parseMergeRequestEvent only accepts a well-formed Merge Request Hook", () => {
+  assert.deepEqual(parseMergeRequestEvent(mrPayload("open")), { gitlabProjectId: 555, action: "open", hasCommit: false, iid: 7, sha: SHA, branch: "feature" });
+  assert.equal(parseMergeRequestEvent(mrPayload("update", { oldrev: "a".repeat(40) }))?.hasCommit, true);
+  assert.equal(parseMergeRequestEvent({ object_kind: "push" }), null);
+  assert.equal(parseMergeRequestEvent({ object_kind: "merge_request", project: { id: 555 }, object_attributes: { iid: 7, action: "open", last_commit: { id: "short" } } }), null);
+  assert.equal(parseMergeRequestEvent({ object_kind: "merge_request", project: { id: "not-a-number" }, object_attributes: { iid: 7, action: "open", last_commit: { id: SHA } } }), null);
+});
+
+test("connecting a project verifies the token, then a merge request runs the chosen plans and reports statuses", async () => {
+  const gl = fakeGitlab();
+  const { env, db, projectId, owner } = await setup(gl);
+  const bind = await call(env, "POST", `/api/projects/${projectId}/gitlab-bindings`, {
+    as: owner,
+    body: { projectPath: "acme/shop", accessToken: "glpat-token", planIds: ["checkout"], baseUrlTemplate: "https://pr-{number}.preview.acme.test", executionMode: "self" },
+  });
+  assert.equal(bind.status, 201, JSON.stringify(bind.json));
+  assert.ok(bind.json.webhookSecret, "the secret is returned once, at creation");
+  assert.match(bind.json.webhookUrl, /\/api\/gitlab\/webhook\?binding=/);
+  const bindingId = bind.json.binding.id;
+  const secret = bind.json.webhookSecret as string;
+
+  const webhook = (body: unknown, token = secret) => call(env, "POST", `/api/gitlab/webhook?binding=${bindingId}`, { headers: { "x-gitlab-token": token }, body });
+
+  assert.equal((await webhook(mrPayload("open"), "wrong-token")).status, 401);
+  assert.equal((await webhook({ ...mrPayload("open"), project: { id: 999, path_with_namespace: "other/repo" } })).json.started.length, 0, "a different project id is ignored");
+
+  const started = await webhook(mrPayload("open"));
+  assert.equal(started.json.started.length, 1, "only the chosen plan");
+  const again = await webhook(mrPayload("open"));
+  assert.deepEqual(again.json.started, started.json.started, "a redelivered webhook doesn't start a second run");
+  const runId = started.json.started[0];
+  const run = db.db.prepare("SELECT environment_base_url AS url, commit_sha AS sha, pr_number AS pr, execution_mode AS mode, gitlab_binding_id AS bindingId FROM runs WHERE id = ?").get(runId) as any;
+  assert.deepEqual({ ...run }, { url: "https://pr-7.preview.acme.test/", sha: SHA, pr: 7, mode: "self", bindingId });
+
+  await drainOutbox(env);
+  assert.equal(gl.state.statuses.length, 1);
+  assert.deepEqual(gl.state.statuses[0].body, { state: "pending", name: "Bugmole: checkout", description: "Waiting for a runner.", target_url: `https://dash.test/runs?project=shop&run=${runId}` });
+
+  await call(env, "POST", `/api/runs/${runId}/claim`, { as: owner, body: { workerId: "w1" } });
+  await drainOutbox(env);
+  assert.equal(gl.state.statuses.at(-1)!.body.state, "running");
+
+  await call(env, "POST", `/api/runs/${runId}`, { as: owner, body: { workerId: "w1", status: "error", stepsPassed: 2, stepsFailed: 1, errorMessage: "Payment never appeared" } });
+  await drainOutbox(env);
+  const finalStatus = gl.state.statuses.at(-1)!.body;
+  assert.equal(finalStatus.state, "failed");
+  assert.match(finalStatus.description, /2 step\(s\) passed, 1 failed on https:\/\/pr-7\.preview\.acme\.test\//);
+});
+
+test("merge request checks need a paid plan, a real token, and only project managers to set them up", async () => {
+  const gl = fakeGitlab();
+  const free = await setup(gl, "free");
+  const refused = await call(free.env, "POST", `/api/projects/${free.projectId}/gitlab-bindings`, { as: free.owner, body: { projectPath: "acme/shop", accessToken: "x" } });
+  assert.equal(refused.status, 402);
+
+  const { env, projectId, owner } = await setup(gl);
+  const add = (body: Record<string, unknown>, as = owner) => call(env, "POST", `/api/projects/${projectId}/gitlab-bindings`, { as, body });
+  assert.equal((await add({ projectPath: "acme/missing", accessToken: "glpat-token" })).status, 422, "GitLab doesn't know that project");
+  assert.equal((await add({ projectPath: "acme/shop", accessToken: "glpat-token", baseUrlTemplate: "ftp://{number}" })).status, 422);
+  assert.equal((await add({ projectPath: "acme/shop", accessToken: "glpat-token" }, "user_stranger")).status, 403);
+  const ok = await add({ projectPath: "acme/shop", accessToken: "glpat-token", executionMode: "self" });
+  assert.equal(ok.status, 201);
+  assert.equal((await add({ projectPath: "acme/shop", accessToken: "glpat-token" })).status, 409, "already connected for this trigger");
+
+  const list = await call(env, "GET", `/api/projects/${projectId}/gitlab-bindings`, { as: owner });
+  assert.equal(list.json.bindings.length, 1);
+  assert.equal(list.json.available, true);
+  assert.equal((await call(env, "DELETE", `/api/projects/${projectId}/gitlab-bindings/${ok.json.binding.id}`, { as: owner })).status, 200);
+});
+
+test("rotating the webhook secret invalidates the old one", async () => {
+  const gl = fakeGitlab();
+  const { env, projectId, owner } = await setup(gl);
+  const bind = await call(env, "POST", `/api/projects/${projectId}/gitlab-bindings`, { as: owner, body: { projectPath: "acme/shop", accessToken: "glpat-token", executionMode: "self" } });
+  const bindingId = bind.json.binding.id;
+  const oldSecret = bind.json.webhookSecret as string;
+  const rotated = await call(env, "POST", `/api/projects/${projectId}/gitlab-bindings/${bindingId}/rotate-webhook-secret`, { as: owner });
+  assert.equal(rotated.status, 200);
+  assert.notEqual(rotated.json.webhookSecret, oldSecret);
+  const webhook = (token: string) => call(env, "POST", `/api/gitlab/webhook?binding=${bindingId}`, { headers: { "x-gitlab-token": token }, body: mrPayload("open") });
+  assert.equal((await webhook(oldSecret)).status, 401);
+  assert.equal((await webhook(rotated.json.webhookSecret)).json.started.length, 1);
+});
+
+test("a status GitLab won't accept is dropped, not retried forever", async () => {
+  const gl = fakeGitlab();
+  const { env, db, projectId, owner } = await setup(gl);
+  const bind = await call(env, "POST", `/api/projects/${projectId}/gitlab-bindings`, { as: owner, body: { projectPath: "acme/shop", accessToken: "glpat-token", executionMode: "self" } });
+  gl.state.failWith = 404;
+  await call(env, "POST", `/api/gitlab/webhook?binding=${bind.json.binding.id}`, { headers: { "x-gitlab-token": bind.json.webhookSecret }, body: mrPayload("open") });
+  await drainOutbox(env);
+  const dead = db.db.prepare("SELECT COUNT(*) AS c FROM outbox WHERE kind = 'gitlab.status.update' AND status = 'dead'").get() as any;
+  assert.equal(dead.c, 1);
+});