GITHUB_TOKEN建的PR永远不触发CI，statusCheckRollup为空、auto-merge永久卡死，这个死锁怎么解？

一、导语：一个被反复复现的死锁现场

先说结论：用 GITHUB_TOKEN 创建的 PR 不触发 CI，是 GitHub 的刻意设计，不是故障。GitHub 官方文档明确说明，由 GITHUB_TOKEN 执行的操作所产生的事件（除 workflow_dispatch 与 repository_dispatch 外）不会创建新的工作流运行，目的是防止工作流递归触发自身。这条规则本身合理，但当它与"分支保护要求必需状态检查"叠加时，就形成了一个闭合环路：PR 需要检查才能合并，检查需要事件才能触发，事件被令牌身份抑制——于是 PR 永远等不到检查，auto-merge 永远等不到满足条件。

这个问题的迷惑性在于，三个现象看起来毫不相干。开发者先看到 CI 没跑，以为是工作流配置问题；去查 statusCheckRollup，发现是空数组，以为是 GraphQL 查询写错；开了 auto-merge，发现状态一直是 BLOCKED，又以为是权限不足。实际上它们共享同一个根因。本文的主线就是这条因果链：令牌身份 → 事件抑制 → 检查缺失 → 必需检查不满足 → 合并状态机阻塞。只要抓住这条链，任何一环的解法都能被定位和评估。

需要提前说明的是，本文讨论的场景限定在 GitHub 平台，涉及 GitHub Actions、Branch Protection / Rulesets、Merge Queue 三个子系统。文中引用的行为描述以 GitHub 官方文档为准，社区复现案例来自公开 issue 与讨论帖，模拟数据会单独标注。本文评述：很多团队把这个问题当成"配置玄学"，反复试错却不得要领，根本原因是缺少对事件模型的形式化理解——一旦把"谁触发、触发什么、被谁看见"三件事分开看，死锁的结构就一目了然。

二、背景与问题定义：三个现象，一条因果链

2.1 现象一：PR 创建成功，但 CI 工作流不触发

典型复现路径是：一个定时任务或发布工作流用 actions/github-script 或 gh pr create 创建 PR，PR 页面正常出现，但预期的 pull_request 事件工作流没有任何运行记录。检查 Actions 页面，只有创建 PR 的那个工作流本身在跑，目标工作流从未被调度。

这里需要区分两种"不触发"。第一种是事件根本没产生——GITHUB_TOKEN 的操作被平台过滤；第二种是事件产生了但工作流文件的条件不匹配，比如 on.pull_request.branches 过滤、路径过滤、或者工作流文件不在默认分支上。二者表现相似，排查手段完全不同。本文评述：实践中大量误判来自把第二种当成第一种，建议先用 workflow_dispatch 手动触发一次目标工作流，确认工作流本身可用，再判断是否为事件抑制。

2.2 现象二：statusCheckRollup 为空数组

statusCheckRollup 是 GitHub GraphQL API 中 PullRequest 对象的一个字段，聚合该 PR 关联的提交上的状态检查（status contexts）与检查运行（check runs）。当它返回 [] 时，意味着该 PR 的 head commit 上没有任何检查记录。这与"检查失败"有本质区别：失败是 FAILURE 状态，空数组是"从未存在"。

空数组的直接后果是：如果分支保护规则要求"必需状态检查"，而 PR 上没有任何检查，那么必需检查永远处于 pending 状态。GitHub 的合并判定逻辑不会把"检查不存在"视为"检查通过"，而是视为"条件未满足"。这一点常被误解，有人以为没检查就等于没约束，实际上恰恰相反——要求了必需检查但检查缺失，比不要求检查更严格地阻塞合并。

2.3 现象三：auto-merge 永久 BLOCKED

GitHub 的 auto-merge 是一个"条件满足即自动合并"的委托机制。开启后，PR 的 mergeStateStatus 会反映当前阻塞原因。当必需检查缺失时，状态停留在 BLOCKED，且不会自行恢复，因为没有任何事件会改变检查集合——除非有人手动推送新提交或手动触发工作流。

三个现象串起来就是完整因果链。下表把每一环的"触发条件—平台行为—可观测现象"对齐，便于排查时逐环定位。

表 1：死锁因果链的四环对齐（依据 GitHub Docs 与 GraphQL API 字段语义整理）

三、原理拆解：事件模型、权限边界与合并状态机

3.1 防递归触发机制：为什么 GITHUB_TOKEN 被特殊对待

GitHub Actions 的 GITHUB_TOKEN 是一个安装级访问令牌（installation access token），由 GitHub App 机制签发，生命周期限于单次工作流运行，运行结束即失效。它的权限由工作流的 permissions 字段声明，默认继承仓库设置。官方文档在"Triggering a workflow"一节中明确：当使用 GITHUB_TOKEN 执行操作时，由该操作产生的事件不会创建新的工作流运行，例外是 workflow_dispatch 和 repository_dispatch。

这条规则的动机是防止无限递归：如果 A 工作流用 token 推送提交触发 B，B 又用 token 触发 A，系统会陷入自激循环。设计上选择"一刀切抑制"而非"深度限制"，是工程上的保守取舍。本文评述：这个取舍在安全上是正确的，但它把成本转移给了合法场景——发布机器人、依赖升级、自动格式化这类"机器创建 PR"的正当需求，恰好落在被抑制的区间里。理解这一点，才能明白为什么社区解法都围绕"换一个身份"展开。

关键边界：抑制的是"由 token 操作产生的事件"，不是"token 本身不能创建 PR"。PR 能建、能推提交、能改标签，只是这些动作不会唤醒其他工作流。区分这两点，是排查的第一道分水岭。

3.2 权限边界：permissions 字段与最小权限原则

工作流的 permissions 声明决定了 token 能做什么。常见配置如下，注意 pull-requests: write 与 contents: write 是创建 PR 与推送分支的最小集合。

permissions:
  contents: write        # 推送分支
  pull-requests: write   # 创建/更新 PR
  checks: read           # 读取检查状态（可选）
  statuses: read         # 读取提交状态（可选）

需要强调的是，permissions 只影响 token 的能力范围，不改变事件抑制规则。即使把权限开到最大，GITHUB_TOKEN 创建的 PR 依然不会触发 pull_request 工作流。本文评述：这是最常见的认知误区之一——很多排查帖建议"把 permissions 改成 write"，方向就错了。权限解决的是"能不能做"，事件抑制解决的是"做了之后有没有人知道"，两者正交。

3.3 合并状态机：mergeStateStatus 的取值语义

GitHub 的 PR 合并判定可以抽象为一个状态机，核心状态由 mergeable、mergeStateStatus、statusCheckRollup 三者共同决定。下表列出 mergeStateStatus 的主要取值及其语义（依据 GitHub GraphQL API 文档的枚举定义整理）。

表 2：mergeStateStatus 主要取值语义（依据 GitHub GraphQL API 枚举文档整理）

从状态机角度看，死锁的本质是：系统处于一个没有出边的状态。BLOCKED 状态等待"必需检查通过"事件，但该事件永远不会到来，因为产生检查需要的工作流被抑制。这不是普通的"等待中"，而是"等待一个不可能发生的事件"。本文评述：用状态机的语言描述，比用"卡住了"这种模糊说法更有诊断价值——它直接指向"缺少哪个转移条件"，从而指导我们人为注入该条件。

3.4 三条主线的耦合关系

把事件模型、权限边界、合并状态机放在一起看，会发现它们通过"检查集合"这个共享变量耦合。事件模型决定检查集合是否被填充，权限边界决定谁能填充，合并状态机消费检查集合做判定。任何试图单点修复的方案，都必须回答一个问题：你如何让检查集合从空变为非空？ 下面五种解法，本质上是五种不同的填充策略。

四、五种解法与操作路径

4.1 解法一：改用 PAT 或 GitHub App Token（最直接）

既然抑制规则针对 GITHUB_TOKEN 这个特定身份，换一个身份即可绕开。两种选择：个人访问令牌（PAT，fine-grained 或 classic）与 GitHub App 安装令牌。PAT 配置简单但绑定个人，人员离职即失效；App Token 更工程化，可长期运行、权限可精细控制。

操作路径（App Token 方案）：

1. 创建一个 GitHub App，授予 Contents: Read and write、Pull requests: Read and write 权限。
2. 将 App 安装到目标仓库，记录 App ID 与 Installation ID。
3. 在私钥存入仓库 Secrets 后，工作流中用 actions/create-github-app-token 换取短期 token。
4. 用该 token 执行 gh pr create 或 API 调用。

- uses: actions/create-github-app-token@v1
  id: app-token
  with:
    app-id: ${{ secrets.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}

- run: gh pr create --title "chore: bump deps" --body "auto"
  env:
    GH_TOKEN: ${{ steps.app-token.outputs.token }}

本文评述：这是社区最常用的解法，但它把"身份管理"问题引入了流水线。PAT 的过期、App 私钥的轮换、token 泄露的风险，都需要额外的治理成本。对于高频、多仓库的自动化，App Token 是更可持续的选择；对于低频、单仓库，PAT 足够。关键是要意识到，这不是"配置技巧"，而是"引入了一个新的信任主体"。

4.2 解法二：workflow_run 链式触发（不换身份）

如果不想引入新身份，可以利用 workflow_run 事件。该事件在另一个工作流运行完成时触发，且不受 GITHUB_TOKEN 抑制规则影响——因为它监听的是"工作流运行"这个对象，而非 PR 操作。思路是：创建 PR 的工作流结束后，由监听 workflow_run 的工作流接手，主动对 PR 的 head commit 触发检查。

on:
  workflow_run:
    workflows: ["create-pr"]
    types: [completed]

jobs:
  trigger-checks:
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - run: |
          gh workflow run ci.yml \
            --ref "${{ github.event.workflow_run.head_branch }}"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

注意 gh workflow run 触发的是 workflow_dispatch，而 workflow_dispatch 正是抑制规则的例外之一，因此这里用 GITHUB_TOKEN 也能成功。本文评述：这个方案的巧妙之处在于"用例外打例外"——不换身份，而是走一条不受抑制的触发通道。代价是链路变长，调试复杂度上升，且需要目标工作流支持 workflow_dispatch 并正确解析 ref。

4.3 解法三：pull_request_target 的适用边界

pull_request_target 事件在目标分支的上下文中运行，且对来自 fork 的 PR 也会触发，常用于需要写权限的场景。它确实能绕开部分抑制，但安全风险极高：如果工作流 checkout 了 PR 的代码并执行，等于把仓库写权限交给了不可信代码。GitHub 安全文档对此有明确警告。

本文评述：pull_request_target 不应被当作"触发 CI"的通用解法。它适合的场景是"只读 PR 元数据、不执行 PR 代码"的评论、标签、审批类工作流。用它来跑测试，必须严格隔离：不 checkout PR head、不执行 PR 中的脚本、只读取可信的元数据。把这条边界讲清楚，比推荐这个事件本身更重要。

4.4 解法四：显式合并，绕开 auto-merge 的等待

如果业务上不需要"等检查通过再合并"，而只是想让 PR 自动落地，可以直接用 gh pr merge 显式合并，跳过 auto-merge 的条件等待。前提是分支保护允许管理员合并，或该 PR 不强制要求必需检查。

gh pr merge "$PR_NUMBER" \
  --squash \
  --admin \
  --delete-branch

本文评述：--admin 是双刃剑。它让自动化能突破保护规则，但也意味着保护规则对这条路径形同虚设。更稳妥的做法是把"自动合并"降级为"自动创建 + 人工审批"，用流程而非权限来保证质量。显式合并适合低风险、可回滚的变更（如文档、依赖补丁），不适合核心代码。

4.5 解法五：合并队列（Merge Queue）适配

GitHub 的 Merge Queue 在合并前会创建一个临时分支并运行检查，其事件模型与普通 PR 不同。对于启用了 Merge Queue 的仓库，GITHUB_TOKEN 创建的 PR 进入队列后，队列自身的检查运行由平台调度，不受 PR 创建事件的抑制影响。但前提是 PR 能进入队列——而进入队列同样要求必需检查满足，所以这个方案只在"必需检查由队列自身提供"的配置下有效。

本文评述：Merge Queue 不是死锁的通用解药，它改变的是"检查在哪里跑"，而不是"检查是否被触发"。把它纳入解法清单，是因为它代表了一种架构思路：把检查的执行点从 PR 事件迁移到合并流程内部，从而绕开事件抑制。这个思路值得在大型仓库中认真评估。

4.6 五种解法的对比

表 3：五种解法的权衡对比（依据各方案的事件模型与权限模型整理）

五、关键数据、案例与对比局限

5.1 社区复现与官方立场

这个问题在 GitHub 社区讨论区（github.com/orgs/community/discussions）有大量复现帖，核心诉求集中在"能否为受信任的 token 开放例外"。GitHub 官方在多个讨论中的回应一致：抑制规则是防递归设计的一部分，暂无计划为 GITHUB_TOKEN 开放白名单，推荐使用 GitHub App Token。本文评述：官方的立场是清晰的——把"机器身份"与"工作流身份"分开，是平台鼓励的架构方向。与其等待规则松动，不如主动适配。

需要说明的是，本文未对社区帖做定量统计，因为讨论区的检索结果受时间、关键词、删除状态影响，难以构成可复现的样本。这里只做定性归纳，不给出"X% 的用户遇到此问题"这类无法验证的数字。

5.2 一个模拟的排查流程与耗时对比

为说明排查路径的效率差异，这里构造一个模拟场景（模拟数据，非真实测量）：假设一个团队遇到该问题，分别采用"盲目试错"与"按因果链定位"两种路径，记录定位到根因所需的步骤数。

表 4：两种排查路径的步骤数对比（模拟数据，用于说明方法论差异，非真实测量）

本文评述：这个模拟的价值不在数字本身，而在揭示"有主线"与"无主线"的差别。因果链定位之所以快，是因为它每一步都在缩小假设空间，而不是随机尝试。工程排查的效率，很大程度上取决于是否有一个可证伪的因果模型。

5.3 局限与边界条件

本文讨论的解法都有边界。PAT 会随人员变动失效；App Token 需要额外的密钥轮换流程；workflow_run 链式触发依赖目标工作流支持 dispatch；pull_request_target 有代码执行风险；显式合并绕过保护；Merge Queue 需要仓库升级到支持该功能的计划。没有一种解法是"零成本"的。

还有一个容易被忽略的边界：fork PR 与同仓库 PR 的事件行为不同。来自 fork 的 PR 在 pull_request 事件下默认拿不到 secrets，这会进一步影响检查的可用性。本文的讨论主要针对同仓库分支创建的 PR，fork 场景需要额外考虑 secrets 隔离与 pull_request_target 的安全边界。

六、结论与展望

回到最初的问题：这个死锁怎么解？答案取决于你愿意付出哪种成本。要最省事，用 App Token 换身份；要最少依赖，用 workflow_run 走例外通道；要最安全，接受"机器 PR 需人工审批"的流程降级。三条路都成立，关键是先理解死锁的结构，再选一条与团队治理能力匹配的路。

从更长的视角看，这个问题的本质是"自动化身份"与"安全边界"的张力。平台用抑制规则保护自己，团队用各种变通保护流水线，双方都在做局部最优。本文评述：未来的方向大概率是平台提供更细粒度的"受信任机器人"机制——既允许机器触发工作流，又能审计其行为。在那一刻到来之前，工程团队能做的是把"机器身份"当成一等公民来治理：独立的 App、独立的权限、独立的审计日志，而不是把它塞进某个人的 PAT 里。

最后给一条可执行的建议：在仓库里建一个 .github/automation.md，记录所有自动化 PR 的创建者身份、所用 token 类型、对应的检查触发方式。这份文档在排查时比任何搜索都管用，因为它把"谁在什么时候用什么身份做了什么"固化了下来。

七、主要参考文献

1. GitHub Docs. "Triggering a workflow." GitHub Actions Documentation, 2024. https://docs.github.com/en/actions/using-workflows/triggering-a-workflow
2. GitHub Docs. "Automatic token authentication." GitHub Actions Documentation, 2024. https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication
3. GitHub Docs. "About protected branches." GitHub Documentation, 2024. https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
4. GitHub Docs. "Managing a merge queue." GitHub Documentation, 2024. https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue
5. GitHub Docs. "Events that trigger workflows: workflow_run." GitHub Actions Documentation, 2024. https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run
6. GitHub Docs. "Events that trigger workflows: pull_request_target." GitHub Actions Documentation, 2024. https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target
7. GitHub Docs. "GraphQL API: PullRequest object." GitHub REST/GraphQL API Documentation, 2024. https://docs.github.com/en/graphql/reference/objects#pullrequest
8. GitHub Docs. "Security hardening for GitHub Actions." GitHub Actions Documentation, 2024. https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions
9. GitHub Community Discussions. "Workflow not triggered by pull request created with GITHUB_TOKEN." github.com/orgs/community/discussions, 2023–2024.

说明：本文引用的平台行为描述以 GitHub 官方文档为准；社区讨论仅作定性参考，未做定量统计。文中表 4 为模拟数据，已单独标注。涉及数据集的部分，本文未使用外部数据集，故无预处理细节需说明。