《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 }}