把 Cursor CLI 接进 GitHub Actions：workflow 字段与凭证怎么给

2026-08-18

想在 CI 里让 agent 干活，卡住人的往往不是提示词，而是两件很土的事：可执行文件装到哪儿了、密钥用什么方式递进去。第一次写这种 workflow，很容易在”install 步跑完了，下一步却说找不到命令”和”密钥明明配了却报未认证”之间来回折腾。Cursor 官方文档《GitHub Actions》页（cursor.com/docs/cli/github-actions）把这两件事写成了几行 YAML，这篇就沿着这几行讲清楚每个字段在改什么。

一、它解决的是哪一段

这一页的定位很窄：把 Cursor CLI 放进 GitHub Actions 以及其它 CI/CD 系统里跑自动化任务。文档给”其它 CI 系统”列的接入条件只有三条——能执行 shell 脚本（bash、zsh 等）、能用环境变量配置 API key、能连上 Cursor 的 API。换句话说，这套东西不依赖 GitHub 特有的能力，GitHub Actions 只是最省事的那个宿主。

需要先明确一点边界：CI 里跑的是 CLI 的 print mode，不是交互式会话。-p, --print 在参数文档（cursor.com/docs/cli/reference/parameters）里的说明是”打印响应到控制台（用于脚本或非交互场景）“，并且注明它可以访问全部工具，包括写文件与 shell。这句话是后面所有权限讨论的起点：默认不是只读。

二、前置条件

1. 一个 API key。 认证文档（cursor.com/docs/cli/reference/authentication）把认证分成两种：浏览器登录（文档标注为推荐）和 API key。文档明确写了 API key 这条路是给”自动化、脚本或 CI 环境”用的。key 从 Cursor Dashboard 的 API Keys 页生成（cursor.com/dashboard/api）。文档给浏览器流程另留了一个 NO_OPEN_BROWSER=1，作用是”只打印登录 URL、不打开浏览器”——但那仍然是一条要人去点的流程，CI 里该走的是 API key 这条，文档也是这么分的。

2. runner 上能跑安装脚本。 安装文档（cursor.com/docs/cli/installation）把平台分成两组：macOS、Linux 和 Windows（WSL）用 curl https://cursor.com/install -fsS | bash；Windows 原生用 PowerShell 的 irm 'https://cursor.com/install?win32=true' | iex。GitHub Actions 页对 Windows runner 的说明只有一句”use PowerShell”，给的就是后面这条命令。

3. 网络能出去。 前面那三条接入条件里明写了需要能访问 Cursor 的 API。自建 runner 在公司代理后面的情况，配置文档（cursor.com/docs/cli/reference/configuration）给了 HTTP_PROXY、HTTPS_PROXY、NODE_USE_ENV_PROXY=1 这几个环境变量，代理做 SSL 中间人检查时还要用 NODE_EXTRA_CA_CERTS 指到组织的 CA 证书；对不支持 HTTP/2 双向流的企业代理，配置项 network.useHttp1ForAgent 可以切到 HTTP/1.1 加 SSE。这些属于配置文档的内容，GitHub Actions 页本身没有提代理。

4. 一个装 secret 的地方。 下面第二步会用到。

三、按文档写这几步

安装步：注意第二行

文档给的基本写法是：

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

第二行才是关键。$GITHUB_PATH 是 GitHub Actions 用来把目录追加进后续步骤 PATH 的机制，不写这一行，安装是成功的，但下一个 step 里敲 agent 就找不到。文档在这里写的目录是 $HOME/.cursor/bin。

顺带一个容易踩的口径差：安装文档的”安装后设置”一节让你把 ~/.local/bin 加进 PATH（bash 写 ~/.bashrc，zsh 写 ~/.zshrc），而 GitHub Actions 页写进 $GITHUB_PATH 的是 $HOME/.cursor/bin。两页给的是两个目录，落盘文本里就是这么写的，我们没有依据判断哪个对哪种场景更准——CI 里就照 GitHub Actions 页那行抄，本机安装按安装页那行来。

Windows runner 侧，文档只给了安装命令这一句，至于要不要以及怎么往 $GITHUB_PATH 里追加目录、追加哪个目录，官方文档没有说明这一点。

凭证步：环境变量，不是命令行参数

secret 的建立方式，文档给的是 GitHub CLI：

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

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

两条的区别只在作用域：前者落到单个仓库，后者是组织级、--visibility all 表示对所有仓库可见。文档另给了一条不走命令行的路径：仓库的 Settings → Secrets and variables → Actions → New repository secret。

注入方式只有一个字段：

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

变量名固定是 CURSOR_API_KEY，这也是认证文档里那个 export CURSOR_API_KEY=<YOUR_API_KEY> 用的名字。参数文档里确实还有 --api-key <key> 这个全局选项，说明中括注”也可以用 CURSOR_API_KEY 环境变量”；认证文档把这两条路并列时，明确把环境变量那条标为 recommended，命令行 flag 只作为 Option 2。GitHub Actions 页给的也是 env 写法，CI 里照它抄就行。

合起来，运行步是：

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

--model 后面那个值是官方文档当时的示例值，可用模型随时在变，别当清单用；参数文档里另有两个查询入口：全局选项 --list-models，说明是”列出所有可用模型”；子命令 agent models，说明是”列出该账号可用的模型”。两句措辞不一样，落盘文本里没有进一步解释差别在哪，要用哪个以 --help 的实际输出为准。

自主度：两档写法的差别在”谁来做 git 操作”

文档把 CI 里的授权强度分成两档。完全自主那档，是把 git 操作、API 调用、对外交互都交给 agent，文档对它的描述是”设置更简单，需要更多信任”，示例提示词直接写明”You have full access to git, GitHub CLI, and PR operations”。

受限自主那档，把 agent 限制在只改工作目录里的文件，提交、推分支、发 PR 评论拆成独立的 workflow step 由 CI 自己做：

- 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: |
    # Deterministic git operations handled by CI
    git checkout -B "docs/${{ github.head_ref }}"
    git add -A
    git commit -m "docs: update for PR"
    git push origin "docs/${{ github.head_ref }}"

文档自述推荐生产 CI 用受限这一档并配合基于权限的限制，给出的理由是：agent 负责复杂分析与文件修改，关键操作保持确定性和可审计。注意上面这段限制是写在提示词里的，属于”请你别做”，不是机制上的拦截；文档紧接着给出的机制手段是下一节的权限配置。

权限：在 CLI 这一层落硬约束

GitHub Actions 页给的示例是这样一段 JSON：

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

读法对着权限文档（cursor.com/docs/cli/reference/permissions）看：权限令牌分五类，Shell(commandBase)、Read(pathOrGlob)、Write(pathOrGlob)、WebFetch(domainOrPattern)、Mcp(server:tool)。上面这段把 git 和 gh 放进 deny，正好和受限自主那档”git 由 CI 步骤做”配套。文档写明 deny 规则优先于 allow 规则，相对路径限定在当前工作区，绝对路径可以指到项目外。

这段 JSON 放哪个文件，GitHub Actions 页没写，得回配置文档看：全局配置在 ~/.cursor/cli-config.json（Windows 是 $env:USERPROFILE\.cursor\cli-config.json），项目级是 <project>/.cursor/cli.json。配置文档还有一句对 CI 很要紧的话——只有 permissions 可以在项目级配置，其余 CLI 设置必须全局设。所以想让权限约束跟着仓库走、被 checkout 出来就生效，要放的是项目里那个 .cursor/cli.json。

以上为按官方文档中的参数语义组合的示例，未经实测，以官方文档与 --help 的实际输出为准。

四、边界：这几处文档没有给你保证

print mode 默认不改文件，但也不是只读。 headless 文档（cursor.com/docs/cli/headless）写明 -p 要配合 --force（或别名 --yolo）才会直接落盘修改，不加 --force 时改动只是被提出、不会应用。--force 在参数文档里的语义是”强制允许命令，除非被显式 deny”——它和 deny 列表是配合关系，不是绕过关系。
--trust 只在 headless 模式下有效。 参数文档对它的说明是”信任工作区、不提示”，并括注 headless mode only。
一些命令文档自己标了 hidden。 agent acp（ACP server 模式）与 agent sandbox 在参数文档里都标注为 hidden，前者还写明”面向自定义 ACP 客户端与高级集成，默认帮助输出里不显示”。别把 hidden 命令当稳定接口写进流水线。
cookbook 那两个链接。 GitHub Actions 页的”Cookbook examples”给了 updating documentation 和 fixing CI issues 两个例子的链接，但落盘文本里这两个链接指向的都是 headless CLI 那一页。要看完整示例 workflow，以官网当前页面为准。
并发、重试、超时、失败重跑这些 CI 侧的工程问题，这一页没有涉及，官方文档没有说明这一点。
权限令牌是在 CLI 这一层做的约束，不等于 runner 的隔离。CI 里给的 token、拉到的源码、runner 上的凭证仍在同一台机器上；相关做法请结合自身环境评估。

五、怎么验证配对了

三步，按顺序卡：

命令找得到吗。 在 install 步之后单独加一步跑 agent --version，这是安装文档给的验证命令。它过不了，说明 $GITHUB_PATH 那行没生效，不用往下查密钥。
认上了吗。 跑 agent status（别名 whoami）。认证文档写明它会显示是否已认证、账号信息和当前 endpoint 配置；参数文档给了 --format <format>，可取 text 或 json，默认 text——CI 里想机器判读就用 json。注意这一步必须带上 CURSOR_API_KEY 那个 env 块，否则查的是”没配密钥时的状态”。
权限真的收住了吗。 headless 文档给了 --output-format 三个取值：text（--print 的默认）、json、stream-json，另有 --stream-partial-output 做增量流式输出（文档写明只在 --print 配 stream-json 时有效）。想确认 agent 没去碰 git，用 json 或 stream-json 把输出留档，比事后看仓库里有没有多出分支要直接。

顺序反过来查会很浪费时间：密钥问题和 PATH 问题的报错长得不一样，但在 CI 日志里都表现为”这一步红了”。先确认命令在，再确认认证过，最后才谈 agent 做了什么。

Cursor CLI 迭代频繁，上面这些命令、选项与配置字段随版本变动，请以官方文档最新内容与 agent --help 的实际输出为准。

本文依据 Cursor 官方文档（cursor.com/docs 与 cursor.com/help）于 2026-08-18 的公开内容整理。该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。该产品迭代频繁，文中涉及的设置项与命令随版本变动，请以官方文档最新内容为准。本文不涉及订阅价格、额度与模型清单，相关信息请以官方定价与模型说明页为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。