企业官网建设流程全解析

gh-stack Webhooks完全指南：pull_request的stacked新事件详解

【免费下载链接】gh-stackGitHub Stacked PRs项目地址: https://gitcode.com/GitHub_Trending/ghst/gh-stack

gh-stack 是 GitHub 堆叠式拉取请求（Stacked PRs）的官方配套 CLI 工具。本文面向新手详解 gh-stack 的 Webhooks 机制：pull_request事件负载如何扩展出stack对象、全新的stacked事件在何时触发，以及你如何用它打通 CI/CD 与通知工具。

先用30秒看懂 Stacked PRs 是什么

常规工作流里，一个大改动只能"PR1 合并完 → 再开 PR2"地串行推进。而 Stacked PRs 允许多个 PR 上下叠放成一摞：每个 PR 指向下方 PR 的分支形成链条，同时每个 PR 都按指向主干分支（如main）来评估——分支保护规则和 CI 检查一个都不少。

feat/frontend → PR #3（指向 feat/api） ← 顶层 feat/api → PR #2（指向 feat/auth） feat/auth → PR #1（指向 main） ← 底层 main（主干分支）

上图的stack map（堆叠导航图）会出现在每个堆叠 PR 页面顶部：点一下就能看到整摞 PR、各自状态，并一键跳转任意层。而这套"我在堆叠中的位置"信息，现在也能通过 Webhooks 以结构化数据拿到。

pull_request 负载扩展：stack 对象

当一个拉取请求属于某个堆叠时，GitHub 会在 Webhook 的pull_request事件负载中、pull_request对象内部附加一个stack属性。这让应用和集成工具不仅能看到 PR 的直接父分支，还能检查整个堆叠的终极目标分支。

• stack对象会出现在该 PR 属于堆叠时的所有PR 生命周期事件（opened、synchronize、closed等）中；
• 对独立 PR（不属于任何堆叠），该字段为null。

字段一览

💡 最容易踩的坑：pull_request.base.ref是 PR 的直接父分支（堆叠里它下面那一层），而pull_request.stack.base.ref是整个堆叠的终极目标。两者只有在堆叠最底层 PR 上才相同，其余 PR 都不同。

详解 stacked 新事件：何时触发、负载长什么样

一个自然的问题：PR 是先创建、后加入堆叠的，那怎么监听"它成为堆叠一员"的那一刻？答案就是pull_request事件的新stackedaction——当一个拉取请求被加入堆叠时，GitHub 会以action = stacked投递pull_request事件。

stacked 事件的三种触发场景

实践中 PR 加入堆叠主要有三条路径，都会触发stacked事件：

1️⃣创建第二个 PR 时勾选 Create stack——第一个 PR 照常创建，之后创建下一个 PR 并勾选堆叠选项，它即成为堆叠顶层；

2️⃣把已有 PR 加到现有堆叠顶部——在 stack map 中点击 "Add to stack"，为新 PR 自动设置好基础分支；

3️⃣把已存在的 PR 链自动转成堆叠——多个已打开 PR 的分支首尾相接时，页面会出现推荐横幅，点击预览确认后即成堆叠：

3 分钟读懂 stacked 负载

stacked事件负载有一个关键特点：除了pull_request内嵌的stack，它还会把刚加入的堆叠以顶层stack对象的形式直接带出来。两个对象字段相同、取值始终一致，读哪个都行。

{ "action": "stacked", "number": 42, "stack": { "id": 123456, "number": 50, "size": 5, "position": 2, "base": { "ref": "main", "sha": "def456..." } }, "pull_request": { "number": 42, "title": "Add API routes", "base": { "ref": "feat/auth-layer", "sha": "abc123..." }, "stack": { "id": 123456, "number": 50, "size": 5, "position": 2, "base": { "ref": "main" } } } }

⚙️ 注意：opened、synchronize等其他pull_requestaction 只在pull_request内部携带嵌套的stack；顶层stack对象是stacked事件独有的。

💡 实现建议：监听器先判payload.pull_request.stack != null确认"属于堆叠"，再对action == "stacked"做特殊处理——这是捕获"刚加入堆叠"这一时刻唯一可靠的信号，非常适合发通知或记录堆叠成员变化。

GitHub Actions：stack 自动识别，零配置

stack对象的收益不止于 Webhook 监听器。GitHub Actions 评估工作流触发条件时会自动采用堆叠的基础分支：如果你的工作流配置为"针对main的 pull_request 事件运行"，那么指向main的堆叠里每个 PR 都会触发它——无需改动任何工作流。

你也可以在 workflow 表达式中通过github.event.pull_request.stack读取堆叠元数据：

- name: Show stack info if: github.event.pull_request.stack != null run: | echo "堆叠目标分支: ${{ github.event.pull_request.stack.base.ref }}" echo "PR 位置: ${{ github.event.pull_request.stack.position }} / ${{ github.event.pull_request.stack.size }}"

省钱技巧：CI 按需运行

由于工作流对堆叠中每个 PR 都会跑，大堆叠会成倍放大 CI 用量。用stack字段就能精准控制：

• 最底层未合并 PR：条件stack.base.ref == base.ref成立（只有最底层直接指向堆叠基础分支）；
• 顶层 PR：position == size（包含完整变更集，适合跑端到端检查）。

- name: Run for the lowest unmerged PR in the stack if: github.event.pull_request.stack != null && github.event.pull_request.stack.base.ref == github.event.pull_request.base.ref run: echo "仅对堆叠中最低的未合并 PR 运行 CI"

随着底层 PR 陆续合并，"最底层未合并 PR"会自动下移——条件无需维护，逻辑始终正确。

边界提醒：PR 离开堆叠之后

堆叠成员关系不是永久的。既可以在界面上执行Unstack，也可以用 CLI 命令gh stack unstack解除堆叠。解除后 PR 回归独立状态，后续 Webhook 负载里的stack字段会重新变回null——所以监听器请务必先判存在、再读字段，避免空指针。

新手接入清单 ✅

1. 监听pull_request事件（X-GitHub-Event: pull_request）；
2. 判读pull_request.stack：非空 = 属于堆叠，null= 独立 PR；
3. 对action == "stacked"做专属分支处理，可顺带读取顶层stack对象；
4. 在 GitHub Actions 中直接用github.event.pull_request.stack.*做条件判断与 CI 优化；
5. 需要按需补查时，用 REST API 的GET /repos/{owner}/{repo}/pulls/{pull_number}获取同一个stack对象。

📚 延伸阅读（均为本仓库内的官方文档）：

• Webhooks 参考（stack对象与stacked事件完整字段）：docs/src/content/docs/reference/webhooks.md
• REST API 参考（按需读取stack对象与 Stacks API）：docs/src/content/docs/reference/rest-api.md
• GitHub 界面操作指南（创建堆叠、推荐横幅与解除堆叠的图解）：docs/src/content/docs/guides/ui.md
• FAQ（Stacked PRs 的分支保护规则与 CI 行为详解）：docs/src/content/docs/faq.md

【免费下载链接】gh-stackGitHub Stacked PRs项目地址: https://gitcode.com/GitHub_Trending/ghst/gh-stack