在 GitHub Actions 與其他 CI/CD 系統中使用 Cursor CLI,自動化各種開發任務。
基本設定:
- name: 安裝 Cursor CLI
run: |
curl https://cursor.com/install -fsS | bash
echo "$HOME/.cursor/bin" >> $GITHUB_PATH
- name: 執行 Cursor Agent
env:
CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
run: |
cursor-agent -p "在這裡輸入你的指令" --model gpt-5
看看我們的 cookbook 範例,了解實用的工作流程:更新文件 和 修正 CI 問題。
只要符合以下條件,就能在任何 CI/CD 系統中使用 Cursor CLI:
- 可執行 Shell 腳本(bash、zsh 等)
- 透過 環境變數 設定 API key
- 具備 網際網路連線 可連到 Cursor 的 API
選擇 agent 的自主性等級:
讓 agent 對 git 操作、API 呼叫與外部互動擁有完整控制。設定更簡單,但需要更高信任。
範例: 在我們的 Update Documentation 實作範本中,第一個工作流程讓 agent 可以:
- 分析 PR 變更
- 建立與管理 git 分支
- 建立提交並推送變更
- 在 Pull Request 中發佈留言
- 處理所有錯誤情況
- name: 更新文件(完全自主)
run: |
cursor-agent -p "你對 git、GitHub CLI 與 PR 操作擁有完整存取權限。
全程處理整個文件更新流程,包括 commit、push 與 PR 評論。"
我們建議在生產環境的 CI 工作流程中,搭配基於權限的限制使用這種方法。這能同時滿足兩種需求:代理能智慧處理複雜的分析與檔案變更,而關鍵操作仍維持可預測且可稽核。
將關鍵步驟拆分到獨立的工作流程步驟,並限制代理的操作。帶來更好的可控性與可預測性。
範例: 同一份範例手冊中的第二個工作流程,將代理限制為只能進行檔案變更:
- name: 產生文件更新(受限)
run: |
cursor-agent -p "重要:不要建立分支、提交、推送,或發佈 PR 留言。
只修改工作目錄中的檔案。後續的工作流程步驟會處理發布。"
- name: 發佈文件分支(具決定性)
run: |
# 由 CI 處理的具決定性的 git 作業
git checkout -B "docs/${{ github.head_ref }}"
git add -A
git commit -m "docs: 更新此 PR"
git push origin "docs/${{ github.head_ref }}"
- name: 發佈 PR 留言(具決定性)
run: |
# 由 CI 處理的具決定性的 PR 留言
gh pr comment ${{ github.event.pull_request.number }} --body "文件已更新"
使用權限設定在 CLI 層級強制套用限制:
{
"permissions": {
"allow": [
"Read(**/*.md)",
"Write(docs/**/*)",
"Shell(grep)",
"Shell(find)"
],
"deny": [
"Shell(git)",
"Shell(gh)",
"Write(.env*)",
"Write(package.json)"
]
}
}
先在 Cursor 控制台產生一組 API 金鑰。
把你的 Cursor API 金鑰安全地存放在儲存庫中:
- 前往你的 GitHub 儲存庫
- 點選 Settings → Secrets and variables → Actions
- 點選 New repository secret
- 將名稱設為
CURSOR_API_KEY
- 貼上你的 API 金鑰作為值
- 點選 Add secret
設定你的 CURSOR_API_KEY 環境變數:
env:
CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}