@cursor/july 0.1.111 → 0.1.113

package/dist/docs/guides/gitlab.md

@@ -1,35 +1,235 @@
 # GitLab agents
 
-Use `gitlabChannel()` for GitLab.com and self-managed GitLab. The channel
-verifies project hooks, normalizes their payloads, and gives each hook a
-project-bound `ctx.gitlab` API client.
+A GitLab agent wakes from a verified project event, reads the current
+project or merge-request state, and writes the result back to GitLab.
+`gitlabChannel()` supports the same hooks on GitLab.com and self-managed
+GitLab.
 
-## Define the channel
+## Review a merge request
 
-Author `agent/channels/gitlab.ts`:
+Opening, reopening, or pushing commits to a merge request starts a
+review. The hook reads the latest diff through the project-bound GitLab
+client, the model returns a verdict, and the completed answer appears
+as a note on the merge request.
 
 ```ts
-import { gitlabChannel } from "@cursor/july/channels/gitlab";
+// agent/channels/gitlab.ts
+import {
+  createGitLabApi,
+  defaultGitLabAuth,
+  gitlabChannel,
+  gitlabChannelStateForEvent,
+} from "@cursor/july/channels/gitlab";
+import {
+  postMergeRequestNote,
+  setPipelineTriageStatus,
+} from "../lib/gitlab.js";
 
-export default gitlabChannel({});
+export default gitlabChannel({
+  projects: ["acme/platform"],
+  onMergeRequest: async (ctx, mergeRequest) => {
+    if (mergeRequest.draft) {
+      return null;
+    }
+    const hasNewCommits =
+      mergeRequest.action === "update" && mergeRequest.oldrev !== undefined;
+    if (
+      mergeRequest.action !== "open" &&
+      mergeRequest.action !== "reopen" &&
+      !hasNewCommits
+    ) {
+      return null;
+    }
+
+    const api = createGitLabApi(
+      ctx.gitlab,
+      ctx.project.pathWithNamespace
+    );
+    const diffs = await api.listMergeRequestDiffs(mergeRequest.iid);
+    return {
+      // `auth` starts a model turn running as the event sender.
+      auth: defaultGitLabAuth(ctx),
+      message: `Review ${ctx.project.pathWithNamespace}!${mergeRequest.iid}.`,
+      context: [`<gitlab_diffs>${JSON.stringify(diffs)}</gitlab_diffs>`],
+    };
+  },
+  events: {
+    async "message.completed"(event, channel, ctx) {
+      if (ctx.session.purpose === "eval") {
+        return;
+      }
+      if (event.data.finishReason === "tool_call" || event.data.text === "") {
+        return;
+      }
+      const mergeRequestIid = channel.state.mergeRequestIid;
+      if (
+        (channel.state.eventType !== "merge_request" &&
+          channel.state.eventType !== "note") ||
+        mergeRequestIid === null
+      ) {
+        return;
+      }
+      await postMergeRequestNote(
+        channel.state.projectPath,
+        mergeRequestIid,
+        event.data.text
+      );
+    },
+  },
+});
+```
+
+`postMergeRequestNote` is a small wrapper around the GitLab REST API.
+Configure it with the same API token and base described under
+[Connect](#connect). It uses the project and MR IID stored from the
+verified event, so the model never chooses where its review is posted.
+
+## Answer a note
+
+Mentioning `@cursor-reviewer` in an MR note resumes that merge
+request's conversation, and the reply sink from the first example posts
+the answer back to the same MR. The author guard drops notes written by
+the agent itself, preventing each reply from starting another turn.
+
+```ts
+const AGENT_USERNAME = "cursor-reviewer";
+
+onNote: (ctx, note) => {
+  if (note.author?.username === AGENT_USERNAME) {
+    return null;
+  }
+  if (!note.body.includes(`@${AGENT_USERNAME}`)) {
+    return null;
+  }
+  return {
+    auth: defaultGitLabAuth(ctx),
+    message: note.body,
+  };
+},
+```
+
+`onNote` receives merge-request notes by default. Add this property to
+the same `gitlabChannel()` declaration as the review handler.
+
+## Triage a failed pipeline
+
+When a pipeline fails, GitLab immediately shows a running
+`cursor/pipeline-triage` status on the commit. The webhook is
+acknowledged while the model investigates, then the status changes to
+success or failure based on whether that triage turn completed.
+
+```ts
+onPipeline: (ctx, pipeline) => {
+  if (pipeline.status !== "failed" || pipeline.sha === undefined) {
+    return null;
+  }
+  const sha = pipeline.sha;
+
+  return {
+    // `task` runs this host sequence after the webhook is acknowledged.
+    task: async ({ send }) => {
+      await ctx.gitlab.setCommitStatus({
+        sha,
+        state: "running",
+        name: "cursor/pipeline-triage",
+        description: "Investigating failed pipeline",
+      });
+
+      await send(
+        `Triage failed GitLab pipeline ${pipeline.id}.`,
+        {
+          auth: defaultGitLabAuth(ctx),
+          title: `GitLab pipeline ${pipeline.id}`,
+          state: {
+            ...gitlabChannelStateForEvent({
+              project: ctx.project,
+              headSha: sha,
+              eventType: ctx.eventType,
+            }),
+          },
+        }
+      );
+    },
+  };
+},
+```
+
+Extend the `events` map so the turn's terminal event concludes the
+status through the same provider wrapper:
+
+```ts
+async "message.completed"(event, channel, ctx) {
+  if (
+    ctx.session.purpose !== "eval" &&
+    channel.state.eventType === "pipeline" &&
+    channel.state.headSha !== null &&
+    event.data.finishReason !== "tool_call"
+  ) {
+    await setPipelineTriageStatus(
+      channel.state.projectPath,
+      channel.state.headSha,
+      "success",
+      "Pipeline triage complete"
+    );
+    return;
+  }
+
+  // Continue with the merge-request reply branch from the first example.
+},
+async "turn.failed"(_event, channel, ctx) {
+  if (
+    ctx.session.purpose === "eval" ||
+    channel.state.eventType !== "pipeline" ||
+    channel.state.headSha === null
+  ) {
+    return;
+  }
+  await setPipelineTriageStatus(
+    channel.state.projectPath,
+    channel.state.headSha,
+    "failed",
+    "Pipeline triage failed"
+  );
+},
 ```
 
-Without `onMergeRequest`, new and reopened merge requests start turns.
-Updates start turns only when they include new commits. Notes, pushes, and
-pipelines are opt-in through `onNote`, `onPush`, and `onPipeline`.
-Use `onEvent` for other GitLab event types. Set `webhookEvents` when managed
-event delivery must subscribe to an event that only `onEvent` handles.
+The status reports whether triage completed; it does not change the
+failed pipeline's own result.
+
+## Events
+
+Use `onMergeRequest`, `onNote`, or `onPipeline` for the events shown
+above. Each hook returns one of three decisions:
+
+| Return | What happens |
+| --- | --- |
+| `{ auth }` | Start a model turn as the GitLab event sender |
+| `{ task }` | Acknowledge the webhook, then run host code that may also call `send` |
+| `null` | Skip the event |
+
+The [Channels reference](/docs/reference/channels.md) covers the remaining
+hook and session behavior.
+
+## Merge request affinity
+
+Every merge-request event and note for the same project path and MR IID
+resumes one agent session. An open, a new commit, and a later mention
+therefore share the same conversation.
+
+## Call GitLab through `ctx.gitlab`
 
-Filter note hooks by author before starting a turn. This prevents comments
-posted by the agent from triggering another turn.
+Each hook receives a GitLab client already bound to the project from
+the verified delivery. Use `ctx.gitlab.request()` for REST calls,
+`setCommitStatus()` for one status update, or `createCheck()` when you
+need a status handle that changes throughout longer work.
 
-`ctx.gitlab` can call the project REST API and create commit statuses. See the
-[Channels reference](/docs/reference/channels.md) for hook return values and
-session behavior.
+The project does not come from model output. Keep API calls on this
+bound client so the event decides where reads and writes go.
 
-## Connect GitLab
+## Connect
 
-On Cursor-managed hosting, use the signed-in Cursor account:
+On Cursor-managed hosting, use the signed-in Cursor account and list
+the GitLab.com projects that may wake the agent:
 
 ```ts
 export default gitlabChannel({
@@ -39,54 +239,53 @@ export default gitlabChannel({
 });
 ```
 
-For direct webhooks, set a project hook secret and API token:
+`cursorAccount` covers event delivery and API calls made through
+`ctx.gitlab` inside hooks. The `postMergeRequestNote` and
+`setPipelineTriageStatus` wrappers are separate REST clients, so
+configure their GitLab API credential too.
 
-```bash
-GITLAB_WEBHOOK_SECRET=...
-GITLAB_TOKEN=...
-```
-
-Add a project webhook for
-`https://<your-host>/<slug>/v1/channels/gitlab`. Use the same value for the
-GitLab secret token and `GITLAB_WEBHOOK_SECRET`. The channel checks
-`X-Gitlab-Token` before it parses the payload.
-
-Self-managed GitLab also needs its REST API base:
+For direct webhooks or self-managed GitLab, configure the project hook
+secret, API token, and allowed projects. Add the API base for a
+self-managed host:
 
 ```ts
 export default gitlabChannel({
-  apiBaseUrl: "https://gitlab.example.com/api/v4",
   projects: ["acme/platform"],
+  webhookSecret: () => process.env.GITLAB_WEBHOOK_SECRET,
+  token: () => process.env.GITLAB_TOKEN ?? "",
+  apiBaseUrl: "https://gitlab.example.com/api/v4",
 });
 ```
 
-You can set `GITLAB_API_BASE_URL` instead.
+Without `webhookSecret`, the direct production route stays
+loopback-only. Setting it admits deliveries that carry the matching
+project-hook secret; `token` authorizes the API reads and writes in the
+examples.
+
+Register the project webhook at
+`https://<your-host>/<slug>/v1/channels/gitlab` with the same secret.
+For GitLab.com, omit `apiBaseUrl`.
 
 ## Test locally
 
-Start the agent, then replay a merge request you can read:
+Replay lets you exercise the same channel hooks with a merge request
+you can read before registering a live project webhook.
 
 ```bash
 agent-sdk dev
 agent-sdk gitlab replay \
-  https://gitlab.example.com/acme/platform/-/merge_requests/42
-```
-
-`GITLAB_TOKEN` needs API read access. Replay reads the merge request,
-creates GitLab-shaped payloads, and sends them through the same channel route.
-Use `--events '*'` to replay the supported events declared by the channel.
-Use `--dry-run --out fixtures/gitlab` to save fixtures.
-
-```bash
-agent-sdk gitlab events --dir .
-agent-sdk gitlab forward --dir .
+  https://gitlab.example.com/acme/platform/-/merge_requests/42 \
+  --events '*'
 ```
 
-GitLab has no local webhook relay. `forward` prints the project-hook and HTTPS
-tunnel setup for live deliveries.
+Use `--dry-run --out fixtures/gitlab` to save the payloads instead of
+posting them. `GITLAB_TOKEN` needs read access to the merge request.
 
 ## Related
 
-- [Channels reference](/docs/reference/channels.md)
-- [Webhooks and custom channels](/docs/guides/webhooks.md)
-- [Evals](/docs/evals.md)
+- [Channels reference](/docs/reference/channels.md): channel hooks,
+  dispatch decisions, and session behavior
+- [Webhooks and custom channels](/docs/guides/webhooks.md): direct webhook auth
+  and reply delivery
+- [Evals](/docs/evals.md): turn saved GitLab payloads into regression
+  fixtures