《Cursor文档》-GitHub Actions

在 GitHub Actions 及其他 CI/CD 系统中使用 Cursor 命令行界面，自动化开发任务。

GitHub Actions 集成¶

基本设置：

- name: Install Cursor CLI
  run: |
    curl https://cursor.com/install -fsS | bash
    echo "$HOME/.cursor/bin" >> $GITHUB_PATH

- name: Run Cursor Agent
  env:
    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
  run: |
    agent -p "Your prompt here" --model gpt-5

对于 Windows 运行器，请使用 PowerShell：irm 'https://cursor.com/install?win32=true' | iex

Cookbook 示例¶

参阅我们的 Cookbook 示例，了解实用工作流：更新文档和修复 CI 问题。

其他 CI 系统¶

只要具备以下条件，即可在任何 CI/CD 系统中使用 Cursor 命令行界面：

Shell 脚本执行功能 (bash、zsh 等)
用于配置 API 密钥的环境变量
可访问 Cursor API 的互联网连接

自主权限级别¶

选择智能体的自主权限级别：

完全自主模式¶

赋予智能体对 Git 操作、API 调用及外部交互的完全控制权。设置更简单，但需要更高的信任度。

**示例：**在我们的更新文档 cookbook 中，第一个工作流让智能体能够：

分析 PR 更改
创建和管理 Git 分支
提交并推送更改
在 PR 中发表评论
处理所有错误情况

- name: Update docs (full autonomy)
  run: |
    agent -p "You have full access to git, GitHub CLI, and PR operations. 
    Handle the entire docs update workflow including commits, pushes, and PR comments."

受限自主性方案¶

对于生产环境的 CI 工作流，我们建议将此方案与基于权限的限制结合使用。这能兼顾两者优势：智能体可以
智能处理复杂分析和文件修改，同时关键操作仍保持确定性且可审计。

将关键步骤放在单独的工作流步骤中处理，以限制智能体操作，从而获得更好的控制力和可预测性。

示例： 同一 cookbook 中的第二个工作流将智能体限制为只能修改文件：

- name: Generate docs updates (restricted)
  run: |
    agent -p "IMPORTANT: Do NOT create branches, commit, push, or post PR comments. 
    Only modify files in the working directory. A later workflow step handles publishing."

- name: Publish docs branch (deterministic)
  run: |
    # CI 负责执行确定性的 Git 操作
    git checkout -B "docs/${{ github.head_ref }}"
    git add -A
    git commit -m "docs: update for PR"
    git push origin "docs/${{ github.head_ref }}"

- name: Post PR comment (deterministic)
  run: |
    # CI 负责执行确定性的 PR 评论操作
    gh pr comment ${{ github.event.pull_request.number }} --body "Docs updated"

基于权限的限制¶

使用权限配置在 CLI 层面实施限制：

{
  "permissions": {
    "allow": [
      "Read(**/*.md)",
      "Write(docs/**/*)",
      "Shell(grep)",
      "Shell(find)"
    ],
    "deny": ["Shell(git)", "Shell(gh)", "Write(.env*)", "Write(package.json)"]
  }
}

身份验证¶

生成 API 密钥¶

首先，前往 Cursor 仪表盘生成 API 密钥。

配置代码仓库机密信息¶

使用 GitHub CLI 将 Cursor API 密钥安全地存储在代码仓库中：

# 代码仓库机密信息
gh secret set CURSOR_API_KEY --repo OWNER/REPO --body "$CURSOR_API_KEY"

# 组织机密信息（所有仓库）
gh secret set CURSOR_API_KEY --org ORG --visibility all --body "$CURSOR_API_KEY"

或者，使用 GitHub 界面：前往你的代码仓库 → 设置 → 机密信息和变量 → Actions → 新建仓库机密信息

在工作流中使用¶

设置 CURSOR_API_KEY 环境变量：

env:
  CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}