Building CI Pipelines with the Cursor SDK for Automated Code Review

The Cursor SDK (@cursor/sdk) enables cloud-based agents to perform automated code review in CI environments by configuring cloud runtimes, handling authentication via environment variables, and returning semantic exit codes that distinguish between transient failures and permanent errors.

Building CI pipelines with the Cursor SDK for automated code review allows teams to integrate AI-powered analysis directly into their deployment workflows. In the cursor/plugins repository, the SDK provides cloud-native agents that execute without local state, making them ideal for ephemeral CI runners. By leveraging the patterns documented in the SDK reference files, you can implement robust review automation that streams logs, posts PR comments, and handles failures gracefully.

Architecture of a Cursor SDK CI Pipeline

A production-ready pipeline requires three coordinated layers: runtime selection, authentication, and standardized error handling.

Cloud Runtime Selection

The SDK automatically selects a cloud runtime when cloud options are supplied, allowing agents to access the repository without requiring a local checkout. This eliminates the need to persist workspace state between CI steps.

According to [cursor-sdk/skills/cursor-sdk/references/runtime-choice.md](cursor-sdk/skills/cursor-sdk/references/runtime-choice.md), cloud runtimes spin up fresh environments for each execution, ensuring reproducible results across different CI providers. This architecture is particularly valuable for GitHub Actions, GitLab CI, and other ephemeral environments where runners are destroyed after each job.

Authentication and MCP Configuration

Pass the Cursor API key via the CURSOR_API_KEY environment variable. For integrations requiring GitHub access (such as posting PR comments), also supply GITHUB_TOKEN.

The SDK's MCP (Model Context Protocol) helper forwards GitHub credentials to the agent, enabling secure repository interaction without hardcoding tokens. See the authentication implementation details in [cursor-sdk/skills/cursor-sdk/references/auth.md](cursor-sdk/skills/cursor-sdk/references/auth.md) and the MCP configuration reference in [cursor-sdk/skills/cursor-sdk/references/mcp.md](cursor-sdk/skills/cursor-sdk/references/mcp.md).

Error Handling and Exit Codes

The SDK distinguishes between startup failures (CursorAgentError) and runtime errors (result.status === "error"). The pattern file [cursor-sdk/skills/cursor-sdk/references/patterns.md](cursor-sdk/skills/cursor-sdk/references/patterns.md) defines a canonical exit code convention:

• 0: Success
• 1: Permanent startup failure (configuration error)
• 2: Runtime error (analysis completed but found issues)
• 75: Transient retryable failure (network timeout, rate limit)

This semantic exit code system enables CI platforms to automatically retry transient failures while halting permanently on configuration errors.

Implementing Automated Code Review in CI

GitHub Actions Integration

The complete GitHub Action workflow resides in [cursor-sdk/skills/cursor-sdk/references/patterns.md](cursor-sdk/skills/cursor-sdk/references/patterns.md) (lines 9-88). The configuration creates a cloud Agent with skipReviewerRequest: true to prevent spamming human reviewers during automated runs.

# .github/workflows/cursor-review.yml

name: Cursor Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Install Node & deps
        uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci

      - name: Run Cursor review
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          npx ts-node ./ci/review-pr.ts

The review-pr.ts script streams progress via run.stream() and awaits completion with await run.wait(), returning the appropriate exit code based on the agent's final status.

One-Shot Analysis Scripts

For ad-hoc analysis steps without full agent initialization, use the minimal one-shot pattern documented in [cursor-sdk/skills/cursor-sdk/references/patterns.md](cursor-sdk/skills/cursor-sdk/references/patterns.md) (lines 66-90):

#!/usr/bin/env node
// file: ci/analyze.ts
import { Agent } from "@cursor/sdk";

const prompt = process.argv.slice(2).join(" ").trim();
if (!prompt) {
  console.error("Usage: analyze.ts <question>");
  process.exit(1);
}

const result = await Agent.prompt(prompt, {
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() }, // runs locally in CI container
});

console.log(result.result ?? "(no output)");
process.exit(result.status === "finished" ? 0 : 2);

This approach is ideal for quick vulnerability scans or style checks that do not require persistent agent state.

Advanced CI Patterns

Parallel Fan-Out for Monorepos

The Fan-Out pattern in [cursor-sdk/skills/cursor-sdk/references/patterns.md](cursor-sdk/skills/cursor-sdk/references/patterns.md) demonstrates how to launch agents against multiple repositories simultaneously. This pattern is essential for monorepo architectures where you need to run independent review jobs across service boundaries in parallel, reducing overall pipeline duration.

Automated Remediation with fix-ci

When CI runs fail, the fix-ci skill provides a guided workflow for locating the failing job, fetching logs, and applying patches. Defined in [cursor-team-kit/skills/fix-ci/SKILL.md](cursor-team-kit/skills/fix-ci/SKILL.md), this skill can be invoked as a CI step:

- name: Assist with CI fix
  uses: cursor-team-kit/fix-ci@v1
  with:
    ci_status: ${{ steps.review.outcome }}

Long-Running Pipelines with Loop-on-CI

For extended validation suites, the Loop-on-CI pattern documented in [cursor-team-kit/skills/loop-on-ci/SKILL.md](cursor-team-kit/skills/loop-on-ci/SKILL.md) enables agents to poll CI status until all checks pass:

import { Agent } from "@cursor/sdk";

async function waitForGreen() {
  while (true) {
    const status = await getCiStatus();          // custom helper
    if (status === "green") break;
    console.log("CI still failing – retrying in 30s");
    await new Promise(r => setTimeout(r, 30_000));
  }
}
await waitForGreen();

This pattern prevents premature pipeline completion when downstream services require additional validation time.

Summary

• Cloud runtime selection eliminates local state dependencies by spinning up fresh agent environments for each CI execution, as configured in [runtime-choice.md](cursor-sdk/skills/cursor-sdk/references/runtime-choice.md).
• Semantic exit codes (0, 1, 2, 75) distinguish between success, permanent configuration errors, runtime analysis failures, and transient retryable conditions.
• MCP integration securely forwards GitHub tokens to agents via environment variables, enabling PR comment posting without credential exposure.
• Streaming and cancellation support via run.stream() and run.wait() provides real-time log visibility and timeout control.
• Parallel execution patterns support monorepo architectures by fanning out review jobs across multiple repositories simultaneously.

Frequently Asked Questions

How do I authenticate the Cursor SDK in GitHub Actions?

Export CURSOR_API_KEY and optionally GITHUB_TOKEN as environment variables in your workflow step. The SDK automatically detects these variables and initializes the MCP helper to forward GitHub credentials to the agent, as detailed in [cursor-sdk/skills/cursor-sdk/references/auth.md](cursor-sdk/skills/cursor-sdk/references/auth.md).

What exit codes does the Cursor SDK return in CI pipelines?

The SDK returns 0 for successful completion, 1 for permanent startup failures (such as invalid API keys), 2 for runtime errors where the analysis completed but detected issues, and 75 for transient failures that warrant automatic retry. These conventions are standardized in [cursor-sdk/skills/cursor-sdk/references/patterns.md](cursor-sdk/skills/cursor-sdk/references/patterns.md).

Can I run Cursor agents locally instead of in the cloud?

Yes. Supply the local: { cwd: process.cwd() } option to Agent.prompt() to execute analysis within the CI container's filesystem. However, cloud runtimes are recommended for automated code review to ensure consistent environments and eliminate local state conflicts.

How do I prevent review requests from spamming reviewers in CI?

Set skipReviewerRequest: true when creating the Agent instance in your CI script. This configuration, shown in the GitHub Action example within [patterns.md](cursor-sdk/skills/cursor-sdk/references/patterns.md), suppresses reviewer notifications while still allowing the agent to post comments and status checks to pull requests.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}