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。

接下來去哪