Copilot 代码审查 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 服务器、过滤低严重度评论 | updateRepositoryCopilotCodeReviewSettings | GitHub 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 代码审查:客观与主观怎么分工。
完成标准
- 第一步的查询能返回
repositoryCopilotCodeReviewSettings,你说得清每个仓库的 effective effort。 - 批量脚本跑完,抽查几个仓库,
mcpEnabled和 effort 与预期一致。 - 组织默认 effort 的 mutation 返回
conflict: null。 - 需要自动审查的仓库,规则集里已经勾上自动请求。
最后
先挑一个仓库跑第一步的查询,看看它现在用哪档 effort、开没开 MCP,再决定要不要把整个组织统一下发。