GitHub Actions

在 GitHub Actions 中使用 Cursor CLI，本质上是把 agent -p 放进 CI。核心不是能不能跑，而是权限、secrets、git 操作和 PR 评论由谁控制。

1. 基础安装方式

官方 GitHub Actions 示例包含两步：安装 CLI，把 binary 目录写入 GITHUB_PATH，然后用 CURSOR_API_KEY 运行 agent -p。

- 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 "Review the current pull request for risky changes" --model gpt-5.2

Windows runner 使用 PowerShell 安装入口：

irm 'https://cursor.com/install?win32=true' | iex

如果组织有供应链要求，不要直接在生产 CI 里 pipe 远程脚本。先做脚本审查或放进受管 runner image。

2. Secrets 配置

先在 Cursor dashboard 生成 API key，再放进 GitHub secrets。

# Repository secret
gh secret set CURSOR_API_KEY --repo OWNER/REPO --body "$CURSOR_API_KEY"

# Organization secret
gh secret set CURSOR_API_KEY --org ORG --visibility all --body "$CURSOR_API_KEY"

workflow 中只通过环境变量注入：

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

不要把 API key 写入 workflow 文件、日志、PR 评论或 Agent prompt。CI 日志通常会长期保留，泄露成本比本地终端高。

3. Full autonomy

Full autonomy 是让 Agent 自己处理 git、GitHub CLI、分支、commit、push、PR comment 和错误恢复。

典型 prompt 会明确给 Agent git、GitHub CLI 和 PR 操作权限，让它自己完成 docs update、branch、commit、push 和 comment。

它配置简单，但需要很高信任。适合低风险仓库、实验 workflow 或人工触发任务，不适合作为默认生产 CI 模式。

风险点：

• Agent 可能创建分支、commit、push。
• Agent 可能调用 gh 与外部 API。
• Agent 可能把日志或上下文写进 PR comment。
• 失败恢复由 Agent 自己决定，可审计性弱。

4. Restricted autonomy

官方更推荐 production CI 使用 permission-based restrictions。思路是：让 Agent 做复杂分析和文件修改，但关键发布动作由 deterministic workflow step 执行。

Agent step 只负责生成文件改动，并在 prompt 中明确禁止 branch、commit、push 和 PR comment。后续 publish step 再用固定 shell 命令执行 git checkout、git add、git commit、git push 和 PR comment。

这种模式更适合商业项目：Agent 做不确定性高的理解和修改，CI 做可预测的 git 和发布动作。

5. Permissions 配置

官方示例使用 permissions 限制读写和 shell。

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

生产 CI 的默认策略建议：

6. 推荐 workflow 结构

flowchart TD
  Trigger["pull_request / workflow_dispatch"] --> Checkout["actions/checkout"]
  Checkout --> Install["Install Cursor CLI"]
  Install --> Agent["agent -p with restricted prompt"]
  Agent --> Diff["git diff / artifact"]
  Diff --> Tests["lint / tests"]
  Tests --> Publish["deterministic publish step"]
  Publish --> Review["PR comment / artifact"]

不要让 Agent 同时负责“理解问题、修改文件、决定发布、push 分支、评论 PR”。这些职责拆开，CI 才可审计。

7. 其他 CI 系统

官方说明其他 CI/CD 只需要满足三类条件：

• 能执行 shell script。
• 能通过 environment variables 配置 API key。
• 有互联网连接访问 Cursor API。

迁移到 GitLab CI、CircleCI、Buildkite 或自托管 runner 时，核心检查项不变：安装、PATH、secret、网络、权限、日志和退出码。

本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. 为什么 CURSOR_API_KEY 必须走 GitHub secrets？
2. full autonomy 和 restricted autonomy 最大的责任边界差异是什么？
3. 为什么生产 CI 里通常要 deny Shell(git) 和 Shell(gh)？

通过标准：你能写出一个 restricted autonomy workflow，并把安装、API key、permissions、diff、测试和发布步骤分开。

官方来源

• Cursor GitHub Actions —— 官方 GitHub Actions 安装、CI 使用、autonomy levels、permission restrictions 和 authentication。
• Cursor Headless CLI —— 官方 headless / print mode 背景。
• Cursor CLI Permissions —— 官方 permissions 配置。
• Cursor CLI Authentication —— 官方 API key authentication。

接下来去哪