github-pr-diff-tree 进阶用法:如何精细化控制 PR 树状 Diff 触发事件类型
github-pr-diff-tree 进阶用法:如何精细化控制 PR 树状 Diff 触发事件类型
github-pr-diff-tree 是一个 GitHub Action,它能自动在 Pull Request 上发布一条“树状 diff”评论,把 PR 中所有改动文件按目录结构可视化,让 Reviewer 一眼看清改动的全貌。这篇文章聚焦进阶用法:如何精细化控制触发事件类型(pull_request: types),并配合分支过滤、路径过滤,让 Action 恰好在正确的时机运行——不多跑一次,也不漏掉一次。
一、配置前先理解:Action 凭什么“决定”运行?
要精细化控制触发,先要看懂它的运行机制。Action 的入口逻辑在 src/main.ts 中:
const {repo, payload} = github.context
const number = payload.pull_request?.number
if (number == null) {
core.info('nothing to do')
return
}
两个关键结论:
- 它只服务于 Pull Request 事件。 只有当 workflow 被
pull_request事件触发、payload 里带有pull_request对象时,Action 才会继续执行;如果你在push或schedule上挂载它,它会打印nothing to do后静默退出。所以“控制事件类型”的目的,是节省 runner 分钟数、避免无意义运行,而不是修复报错。 - 重复触发不会产生重复评论。 这是精细化配置可以放心放手用的底气,下一节详述。
另外,Action 唯一的必填输入是 token,定义在 action.yml 中:
inputs:
token:
required: true
description: 'GITHUB_TOKEN as provided by secrets'
二、pull_request 触发事件类型速查表
pull_request 事件支持多种 types,官方常见取值与适用性如下:
| 事件类型 | 触发时机 | 是否推荐启用 |
|---|---|---|
opened |
PR 首次创建 | ✅ 推荐,首条评论入口 |
synchronize |
PR 分支推送新 commit | ✅ 推荐,评论保持实时刷新 |
reopened |
PR 被关闭后重新打开 | ✅ 推荐,恢复评论 |
ready_for_review |
退出 Draft 状态转正 | 🔶 可选,视团队流程 |
edited |
修改 PR 标题/描述 | ❌ 不影响 diff,纯浪费 |
labeled / unlabeled |
标签增删 | ❌ 与代码变更无关 |
closed |
PR 被关闭(合并与否均触发) | ❌ 收尾时无需再刷评论 |
convert_to_draft |
重新变为 Draft | ❌ 通常不需要 |
locked / unlocked |
锁定/解锁 PR | ❌ 与 diff 无关 |
review_requested |
请求 Reviewer 审核 | 🔶 可选,用于提醒审核人看树 |
💡 黄金组合:[opened, synchronize, reopened]。这三者覆盖了“新建 → 迭代 → 重开”的完整生命周期;其余类型要么不改变 diff 内容(跑了也是白跑),要么属于收尾事件(再刷一次评论意义不大)。
三、推荐配置:最小且稳定的触发组合
以下配置覆盖了最常用的场景,事件类型、分支、路径三层过滤齐活:
# .github/workflows/pr-diff-tree.yml
name: 'PR Diff Tree'
on:
pull_request:
types: [opened, synchronize, reopened]
branches:
- main
- 'release/**'
paths:
- 'src/**'
permissions:
issues: write
jobs:
dump:
runs-on: ubuntu-latest
steps:
- uses: wadackel/github-pr-diff-tree@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
逐层解读:
types:控制“哪类 PR 动作”会触发,是精细化的核心;branches:只对目标分支为main或release/前缀的 PR 生效,实验分支的 PR 不会消耗分钟数;paths:只有当 diff 涉及src/**下文件时才触发,纯文档 PR 直接跳过;permissions: issues: write:评论本质是通过 issues 接口写入的,显式声明最小权限是安全最佳实践。
四、为什么高频触发也不会刷屏?(评论 upsert 机制)
synchronize 会在 PR 分支每推一次 commit 就触发一次,看似高频,但评论只会有一条。原理在 src/main.ts:
Action 每次运行都会先列出 PR 的评论,查找由 github-actions<a href="https://link.gitcode.com/i/155e8caf393e1fbf80e83cf257edbcca" target="_blank">bot] 发出、且正文以标记注释 <!-- wadackel/github-pr-diff-tree --> 开头的那一条(标记定义见 [src/main.ts):
- 找到了 → 调用
updateComment原地更新内容; - 没找到 → 才调用
createComment新建一条。
也就是说:无论触发多少次,PR 里始终只维护一条永远反映最新 diff 的树状评论。这就是你可以放心把 synchronize 留在 types 里的根本原因。
而评论中展示的树,来自两个模块的配合:src/parse.ts 解析原始 diff,识别出新增(A)、删除(D)、修改(M +行数, -行数)、重命名(R)及二进制文件;src/print.ts 再按目录层级拼出带 ├──、└── 的树形文本,并在文件前打上 +/- 标记,对应你截图中看到的颜色高亮列表。
五、进阶技巧清单
- 对外部贡献者(fork PR)开放:fork 仓库发起的 PR 默认只读 token,需要在 workflow 中显式声明
permissions: issues: write,否则评论会静默失败。 - 想“仅在转正时评论”:如果你的团队习惯长时间停留在 Draft 阶段,可以把
types收窄为[opened, ready_for_review, synchronize, reopened],让评论在转正前后各刷一次。 - 与 CI 解耦:建议把 diff-tree 放在独立的 workflow 文件(如
pr-diff-tree.yml)中,而不是塞进 CI 流程里,这样调整触发类型时不影响构建链路,基础用法参考 README.md 的 Basic 示例。 - 排查“评论没出现”:按顺序检查——
types是否包含当前事件、是否被branches/paths过滤、token 是否有issues: write权限、Action 版本是否固定(如@v1)。
六、常见问题
Q:为什么用 push 事件挂载它没有任何反应?
A:设计上它只认 pull_request payload(src/main.ts),其他事件会打印 nothing to do 直接退出。把它挂到 push 上没有任何意义,请改用 pull_request。
Q:PR 连续推了 5 次 commit,会出现 5 条评论吗? A:不会。upsert 机制保证只有 1 条评论,后一次运行会原地更新前一次的树(见 src/main.ts)。
Q:只想让树出现在发往 main 的 PR 上,其他分支都不要,怎么配?
A:在 pull_request 下加 branches: [main] 即可,这是比 types 更粗的一层过滤,二者可叠加使用。
📌 小结:github-pr-diff-tree 本身零配置即可工作,真正的进阶在于 workflow 的触发层——用 types: [opened, synchronize, reopened] 锁定核心生命周期事件,用 branches、paths 做二次过滤,再依赖内置的评论 upsert 机制实现“高频触发、单条评论”。掌握这三点,你的 PR 审核体验将显著提效。
