教程2026-11-09 · 智涌AI

Copilot 代码审查 API 配置:用 GraphQL 批量设 effort 与 MCP

Copilot 代码审查 API 配置教程头图:终端里用 gh api graphql 批量修改仓库审查 effort 和 MCP 开关,并设置组织默认档位

仓库一多,Copilot 代码审查的设置就很难在网页里一个个点。GitHub 11 月 6 日(美国时间)放出了配置接口:企业开关、组织默认 effort、审查用的 runner、仓库是否允许调用 MCP 服务器,现在都能用 GraphQL 和 REST API 改。这篇按官方 changelog、配置文档和 GraphQL 参考,把三层设置怎么读、怎么改、怎么批量下发写成可以照抄的命令。

先分清三层:谁能改什么

目标读者是管着一个组织、几十上百个仓库的平台或安全负责人。前置条件:你的方案是 Copilot Pro、Pro+、Max、Business 或 Enterprise 之一;本机装好 GitHub CLI 并已 gh auth login。

层级能改的设置GraphQL mutation令牌
企业对所有组织开 / 关,或交给组织管理员决定updateEnterpriseCopilotCodeReviewPolicy不支持 GitHub App 和细粒度令牌
组织开关(企业放权时)、默认 effort、runner 配置updateOrganizationCopilotCodeReviewPolicy / …Settings / …RunnerConfiguration同上
仓库effort、是否用自定义指令、是否用 MCP 服务器、过滤低严重度评论updateRepositoryCopilotCodeReviewSettingsGitHub App、细粒度令牌都行:读要 Administration: read,写要 Administration: write;经典令牌需仓库管理员权限

配置文档写明,最高 effort 上限、计费、自动批准这几项仍然只能在网页里改。GraphQL 参考里还有一句容易忽略:仓库这组设置只负责「怎么审」,并不负责「开不开」。想让某个仓库自动请求 Copilot 审查,还是要在规则集(Rulesets)里勾上「Automatically request Copilot code review」。

上层管住的设置,下层改不动;组织层的接口会在返回的 conflict 字段里写明是谁管着。

第一步:读出一个仓库的当前设置

GitHub 公开的 GraphQL schema 里,Repository 对象上有 repositoryCopilotCodeReviewSettings 字段,这是我们 11 月 9 日查询 schema 确认过的。把 OWNER 和 REPO 换成你的:

gh api graphql -f owner=OWNER -f name=REPO -f query='
query($owner:String!, $name:String!) {
  repository(owner:$owner, name:$name) {
    id
    repositoryCopilotCodeReviewSettings {
      availableReviewEfforts
      reviewEffort { configured effective }
      customInstructionsEnabled
      mcpEnabled
      severityFilter
    }
  }
}'

几个字段的意思:availableReviewEfforts 是这个仓库眼下能选的档位;reviewEffort.configured 是仓库自己存的值,继承上层时为 null,effective 是请求者和 PR 都没指定时实际用的档位。返回里的 id(形如 R_ 开头)下一步要用。

第二步:改一个仓库

effort 有 AUTO、LITE、BALANCED、MAX 四档,仓库层多一个 INHERIT,表示清掉自己的值、回到组织或企业的默认。按配置文档的说法,Lite 是标准审查,Balanced 对复杂逻辑、安全敏感代码和跨服务改动分析得更深,Max 动用多个高推理模型;Balanced 和 Max 消耗的 AI 额度更多,GitHub Actions 分钟数也可能略多一点。changelog 补了一句:Balanced 现在用三个审查模型,再由另一个模型合并结论。

gh api graphql -f id=R_xxxxxxxx -f query='
mutation($id:ID!) {
  updateRepositoryCopilotCodeReviewSettings(input:{
    repositoryId:$id,
    reviewEffort:BALANCED,
    mcpEnabled:false,
    severityFilter:LOW
  }) {
    settings { reviewEffort { configured effective } mcpEnabled severityFilter }
  }
}'

参考文档写明,没传的设置保持原样,所以只想关 MCP 就只传 mcpEnabled。severityFilter 三个取值:NO_FILTER 全保留,LOW 去掉低严重度评论,LOW_AND_MEDIUM 连中等也去掉。

MCP 开关值得单独想一下。审查时能调用 MCP 服务器,意味着 Copilot 读 PR 的同时还能访问你接进来的外部工具。对放着第三方贡献代码的公开仓库,可以先关掉,等确认接了哪些服务器再开。GitHub 自家 MCP 服务器的只读配置,可以参考站内的 GitHub MCP Server 工具集与只读教程。

第三步:批量下发到整个组织

gh repo list 能直接输出仓库的节点 id,接一个循环即可。先用 --limit 拿两三个仓库试,确认返回没问题再放开:

ORG=your-org
gh repo list "$ORG" --limit 500 --no-archived --json id,name \
  --jq '.[] | "\(.id) \(.name)"' |
while read -r id name; do
  echo "== $name"
  gh api graphql -f id="$id" -f query='
  mutation($id:ID!) {
    updateRepositoryCopilotCodeReviewSettings(input:{repositoryId:$id, reviewEffort:INHERIT, mcpEnabled:false}) {
      settings { reviewEffort { effective } mcpEnabled }
    }
  }' --jq '.data.updateRepositoryCopilotCodeReviewSettings.settings'
done

这里给每个仓库传 INHERIT,是想让 effort 统一跟着组织默认走,以后只改组织一处。组织默认这样设(先用 organization(login:"ORG"){ id } 查出组织 id):

gh api graphql -f org=O_xxxxxxxx -f query='
mutation($org:ID!) {
  updateOrganizationCopilotCodeReviewSettings(input:{organizationId:$org, defaultReviewEffort:LITE}) {
    conflict
    settings { defaultReviewEffort { configured effective editable } availableReviewEfforts }
  }
}'

conflict 为 null 表示改成功;返回 SETTING_NOT_EDITABLE 说明这项被企业管着。组织开关那个 mutation 对应的冲突值是 POLICY_MANAGED_BY_ENTERPRISE。

runner 和企业开关

想让审查跑在自己的 runner 上,用 updateOrganizationCopilotCodeReviewRunnerConfiguration:runnerType 选 STANDARD(GitHub 托管)或 LABELED;选 LABELED 至少要给一个 runnerLabels 或 runnerGroupName,输入不合法时配置不变。allowRepositoryCustomization 控制仓库能否用自己的 runner。返回里的 configuredBy 如果是 CODING_AGENT,表示这套值继承自组织的 Copilot coding agent runner 配置。

企业层只有一个字段 policyState:ENABLED_FOR_ALL_ORGANIZATIONS、DISABLED_FOR_ALL_ORGANIZATIONS,或 CONFIGURED_BY_ORGANIZATION_ADMINS 交给组织决定。最后这个值独立企业(standalone)用不了。

顺手:给单个 PR 请求一次审查

设置之外,schema 里还有 requestCopilotCodeReview,输入是 PR 的节点 id 和可选的 reviewEffort。返回的 success 和 failureReason 会告诉你请求有没有成功。适合在 CI 里对改动大的 PR 单独要一次 MAX 档,平时仍走仓库默认:

gh api graphql -f pr=PR_xxxxxxxx -f query='
mutation($pr:ID!) {
  requestCopilotCodeReview(input:{pullRequestId:$pr, reviewEffort:MAX}) { success failureReason }
}'

PR 的节点 id 可以用 gh pr view 123 --json id 取。什么时候走 API、什么时候在网页点,大致这么分:只有一两个仓库、偶尔调一次,网页更直观;仓库多、要定期对齐、要留变更记录,就把上面的命令放进仓库管理脚本,和规则集一起进版本库。

常见坑

现象原因和处理
组织 / 企业接口报权限错误用了 GitHub App 或细粒度令牌,这两层不支持,换经典令牌
仓库设置改了,PR 上还是没有自动审查仓库设置不负责开启,去规则集勾自动请求
想用 API 调最高 effort 上限或自动批准不在 API 范围内,只能在网页设置页改
组织默认改不动看返回的 conflict,企业层管住了就找企业管理员
configured 是 null仓库在继承上层,或存的档位当前不可用,以 effective 为准

审计这一面,changelog 提到 API 返回里多了归属字段,能分出哪些评审和评论出自 Copilot、用了哪档 effort,以及它报告的依据来自哪些 Skill、MCP 服务器和自定义指令。快讯版见 Copilot 代码审查开放 API;AI 审查和人工审查怎么分工,可以看 Agent 代码审查:客观与主观怎么分工。

完成标准

最后

先挑一个仓库跑第一步的查询,看看它现在用哪档 effort、开没开 MCP,再决定要不要把整个组织统一下发。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。