GitHub Copilot 代码审查证据链的工作流调整

团队把 GitHub Copilot 代码审查接入 Pull Request 后，最容易留下的空白不是“有没有评论”，而是“这条评论是在什么输入和环境下产生的”。审查指引来自哪个分支、是否安装了项目依赖、使用了 Lite 还是 Balanced、这是首次审查还是推送后的复查，都会影响读者对结果的判断。

官方资料地址：https://docs.github.com/en/copilot/tutorials/use-copilot-code-review-across-the-pull-request-lifecycle

这次工作流调整可以收敛成一条证据链：记录审查请求、头部分支里的指引、专用运行环境、审查深度和复查状态。它能让团队知道“Copilot 看到了什么、按什么规则看、结果是否已经被后续提交重新确认”，但不能把单次 AI 评论直接等同于人工批准或合并门禁。

先把一次审查拆成五段证据

GitHub 在 2026 年连续补齐了 Copilot code review 的配置和结果信息：自定义指引改为从 Pull Request 的头部分支读取，并扩展到 REVIEW.md、GEMINI.md 和 CLAUDE.md；仓库可以通过 copilot-code-review.yml 单独准备审查环境；审查摘要会区分开放问题、上次审查后已解决的问题和后续发现的问题；请求接口也支持设置审查深度。

因此，排查“为什么这次结果不一样”时，不要只复制评论内容。最小记录至少包含下面五段：

用头部分支指引做最小定制

如果团队想先调整审查规则，最小改动是把规则跟着功能分支一起提交。Copilot code review 读取的是头部分支，而不是目标分支；这意味着你可以在一个 Pull Request 里试验指引，再根据评论调整，而不必先把规则合并到主分支。

仓库级要求适合放在 .github/copilot-instructions.md，路径级规则适合放在 .github/instructions/ 下的 *.instructions.md，AGENTS.md 则补充架构边界和有意保留的模式。一个短小的路径级文件可以这样写：

---
applyTo: "**/*.{go,ts}"
---

# 服务代码审查重点


- 先检查错误是否在边界处被处理。
- 发现权限或敏感数据路径变化时，说明影响范围。
- 如果一个模式是有意保留的，请结合仓库上下文再提出建议。
- 给出建议时指出文件路径和可复现的判断依据。

这里的重点不是把规则写得更长，而是让每条规则都能对应一个审查判断。官方文档也提醒，指引文件过长会让部分内容被忽略；模糊的“提高质量”“不要漏问题”不如短而具体的检查项。

官方资料地址：https://docs.github.com/en/copilot/tutorials/customize-code-review

为审查单独准备运行环境

当审查需要读取依赖、运行项目工具或使用特定 runner 时，可以在 .github/workflows/copilot-code-review.yml 中给 Copilot code review 单独配置环境。若没有这个文件，平台会回退使用已有的 copilot-setup-steps.yml；新文件的价值在于把代码审查与 Copilot cloud agent 的准备动作拆开。

name: Copilot code review environment

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        # 中文注释：准备仓库内容，让后续工具安装与审查使用同一份代码上下文。
      - name: Install review tools
        run: |
          # 中文注释：只安装审查真正需要的工具，避免把无关环境带入证据链。
          npm ci
          npm run lint

这段配置表达的是“审查需要什么环境”，不是“审查已经得出了什么结论”。如果组织使用自托管 runner，官方当前支持的是 ARC 管理的 runner，并且需要自行设置网络安全控制；审查默认有防火墙，仓库和组织可以独立配置网络访问。环境记录应和审查结果分开保存，避免把一次安装失败误读成代码缺陷。

官方资料地址：https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment

按场景选择触发方式与审查深度

小团队可以先手动请求，确认指引和结果摘要符合预期后，再考虑规则集自动触发。草稿阶段请求适合尽早发现明显的正确性、安全和可维护性问题；准备让人审之前，可以再做一次人工触发的复查。频繁更新的 Pull Request 则适合开启新推送复查，但要接受评论可能重复出现这一边界。

GitHub 的配置入口把自动审查、草稿审查和新推送审查分开。审查深度方面，Lite 是标准审查，Balanced 会对复杂逻辑、安全敏感代码和跨服务变更进行更深分析；2026 年 9 月 28 日起，默认审查深度改为 Balanced，明确选择 Lite 的设置会保留。

# 中文注释：创建 Pull Request 时先请求一次 Copilot 审查，不改变分支或合并状态。
gh pr create --reviewer @copilot

# 中文注释：已有 Pull Request 需要复查时，指定编号并再次加入 Copilot 审查者。
gh pr edit 123 --add-reviewer @copilot

如果把审查接入脚本或内部工具，2026 年 10 月 2 日的更新已经支持通过 REST 和 GraphQL API 请求审查，并在请求中选择审查深度。API 让“什么时候触发”更容易纳入现有流水线，但仍要把请求参数、提交 SHA 和返回的审查记录保存下来，才算形成证据链。

官方资料地址：https://github.blog/changelog/2026-10-02-copilot-code-review-api-support-and-new-default-effort-level/

把结果状态写回复查记录

新版本的 Pull Request 概览会保留审查变化：开放问题表示仍未处理；“上次审查后已解决”表示 Copilot 根据后续提交确认了先前问题；“后续发现”表示不是新提交引入、但在后续审查中才发现的现有变更问题。每条评论还有简短标题，方便从摘要跳到对应代码。

因此，合并前的最小复查记录可以只写四列：提交 SHA、审查深度、仍开放的问题、触发复查的改动范围。跨服务改动、安全敏感行为变化，或一次性接受大量建议后，都应重新请求审查。不要只看评论数量减少了没有，要看开放问题是否真的转入已解决，以及是否出现后续发现。

一份可以落地的采用清单

1. 先在草稿 Pull Request 中提交一份短的仓库级或路径级指引，确认规则确实跟随头部分支生效。
2. 把依赖安装、runner 和网络要求写入专用的 copilot-code-review.yml，没有独立需求时再复用 copilot-setup-steps.yml。
3. 为自动审查明确选择开放时机：创建、草稿、新推送，或只在人工请求时触发。
4. 复杂逻辑、安全敏感和跨服务改动优先使用 Balanced，并记录这次请求的审查深度。
5. 修复后不要只关闭评论；在摘要中确认问题进入已解决，必要时保留复查的提交 SHA。
6. 把 Copilot 结果当作证据输入，最终合并决定仍由团队的测试、人工审查和分支规则共同完成。

常见问题

为什么我改了主分支的指引，这次审查却没按新规则执行？

Copilot code review 读取 Pull Request 的头部分支指引。把规则改在目标分支后，当前 Pull Request 不一定会把它当作本次审查输入；更稳妥的做法是把试验规则提交到头部分支，并用后续复查观察结果。

没有 copilot-code-review.yml 会不会不能审查？

不会。没有专用文件时，平台会使用已有的 copilot-setup-steps.yml；专用文件主要用于把代码审查环境与 Copilot cloud agent 的环境分开。

Balanced 结果是不是可以直接作为合并批准？

不是。Balanced 代表更深的分析投入，不代表它理解了全部业务约束，也不替代人工审查、测试和分支保护规则。它应该成为复查记录中的一个输入字段。

为什么复查后还会看到之前的评论？

官方文档说明，重新审查可能再次出现相同评论，即使评论已经被解决或点过反对。判断时应结合新的提交、摘要中的状态和具体代码位置，而不是只按评论条数去重。

把请求、指引、环境、深度和结果这五段记录齐，GitHub Copilot 代码审查才从“自动留言”变成了可以复盘的工程流程。真正值得调整的不是评论文案，而是每个证据段在团队决策中的位置。