Aspire CI 实战：用 GitHub App 请求 Copilot 代码审查，实现组织级计费（Organization-funded Copilot Reviews 工作流解析）

Aspire CI 实战：用 GitHub App 请求 Copilot 代码审查，实现组织级计费（Organization-funded Copilot Reviews 工作流解析）

【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire

本篇技术指南以 docs/ci/organization-funded-copilot-reviews.md 为核心，结合其对应的 工作流实现，完整拆解 Aspire 仓库如何用一个独立 GitHub App 安装令牌（而非GITHUB_TOKEN或个人 PAT）向 PR 请求 Copilot Code Review（CCR），覆盖 App 前置条件、COPILOT_REVIEW_MODE/COPILOT_REVIEW_PR_NUMBER两个控制变量、触发与对账（reconciliation）行为、安全边界，以及灰度上线（rollout）六步法和计费归属的验证方法。读完你可以理解"让组织为 bot 请求的 Copilot 审查付费"这一目标的完整落地路径，并掌握在受控前提下评估、试点和回滚该类自动化审查的能力。

1. 设计目标：改变"请求方身份"，而不是选择计费账户

Organization-funded Copilot reviews工作流的核心意图是：请求 Copilot 代码审查（CCR）时使用aspire-repo-bot的 App 安装令牌，而不是 workflow 自带的GITHUB_TOKEN或贡献者的个人令牌。

需要强调的是文档反复声明的一个边界："组织出资"是目标，不是已验证的计费保证（organization funding is the goal, not a verified billing guarantee）。工作流只覆盖满足以下条件的 PR：

• 目标分支为main或release/**；
• 包括 draft 和来自 fork 的 PR；
• PR 作者当前对microsoft/aspire拥有 write、maintain 或 admin 权限。

没有 license 过滤，也没有配额可用性保证。文档明确指出，GitHub 的 CCR 文档将内置自动审查记到作者头上，而"bot 请求的审查直接计给组织"这一说法，在 Aspire 仓库此前的GITHUB_TOKEN实现中已被两次现象削弱：PR #18530 上出现"Actions-bot 请求审查后 CCR 以贡献者身份启动"，PR #17949 上出现配额上限拒绝。这两者都不是计费凭证（receipt），但足以说明不能仅凭请求方是 bot 就推断组织出资。因此整套设计把"验证计费归属"作为上线流程的独立一步（见第 6 节），而不是默认假设。

2. App 前置条件与令牌的作用域收窄

2.1 必需的安装权限与 Secrets

Aspire App 必须已安装在microsoft/aspire上，且具备Pull requests: write权限。工作流复用仓库既有的两个 Actions secrets：

• ASPIRE_BOT_APP_ID：通过actions/create-github-app-token的client-id输入传入，与 仓库中其他使用同一 App 的 workflow（如backport.yml、apply-test-attributes.yml、sync-main-to-release-14.0同步流）保持一致；
• ASPIRE_BOT_PRIVATE_KEY：仅传给 token action，绝不传给内联的对账脚本。

2.2 每次运行都铸造最小权限的临时令牌

从 工作流实现 可以看到，每次运行都会新铸造一个作用域被显式收窄的安装令牌：

- name: Create Aspire App token id: app-token uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 with: client-id: ${{ secrets.ASPIRE_BOT_APP_ID }} private-key: ${{ secrets.ASPIRE_BOT_PRIVATE_KEY }} owner: microsoft repositories: aspire permission-pull-requests: ${{ vars.COPILOT_REVIEW_MODE == 'enabled' && 'write' || 'read' }} skip-token-revoke: false

要点：

• 令牌明确限定在microsoft安装 +aspire单一仓库，避免继承 App 更宽的安装级权限；
• Pull requests 权限随模式动态收窄：模式恰好为enabled时请求 write，其他情况（含 dry-run）只请求 read——dry-run 从机制上不可能调用写端点；
• skip-token-revoke: false表示 action 在 job 清理阶段主动撤销令牌；同时 GitHub 安装令牌本身 1 小时后过期，形成双保险；
• 令牌创建或权限失败会让 job 直接停止，没有回退到GITHUB_TOKEN的兜底。

3. 控制变量：免 PR 的模式切换与试点范围

所有开关都通过仓库变量控制，入口为Settings > Secrets and variables > Actions > Variables。修改模式无需再提 PR，变量在 run 启动时读取。

变量	取值	效果
COPILOT_REVIEW_MODE	未设置或dry-run	只读元数据并汇报决策，绝不请求审查
COPILOT_REVIEW_MODE	enabled	用 Aspire App 请求审查
COPILOT_REVIEW_MODE	disabled	跳过整个 job（kill switch）
COPILOT_REVIEW_PR_NUMBER	未设置	考虑所有合格 PR，包括 rollout 前就已打开的
COPILOT_REVIEW_PR_NUMBER	正 PR 编号	将事件触发与定时扫描都限制到该 PR，用于试点

从 源码中的变量校验逻辑 可以看到几个实现细节：

• 未设置的COPILOT_REVIEW_MODE默认按dry-run处理；但如果变量已经是enabled，合入该变更后的下一次运行会立即切到 App 写路径——文档因此要求在合入前先显式设置 dry-run 和试点 PR，把 rollout 分阶段推进；
• 非法取值（既不是disabled/dry-run/enabled）直接抛错使 run 失败，而不是"宁可放开"；
• 试点 PR 编号用正则/^[1-9][0-9]*$/+Number.isSafeInteger严格校验，明确拒绝parseInt式的宽松截断——例如"12345-untrusted"绝不会被解析成 PR 12345。

还有一个容易误解的行为：变量是运行时读取的，disabled不能取消已在运行的 job，也不能撤销已请求的审查。处置事故时，需要另外手动取消活跃的 workflow run。

4. 触发路径与对账行为

4.1 三种触发方式

从 workflow 定义 看，工作流有三类触发：

1. pull_request_target（分支main、release/**，事件opened/synchronize）：PR 创建（含 draft）和新推送都会触发一次"仅元数据"运行；重新打开 PR 或把 draft 标记为 ready不会触发额外运行；
2. schedule：cron 表达式7,22,37,52 * * * *，即每 15 分钟一次定时扫描，用于对账所有开放 PR；
3. workflow_dispatch：仅允许在main分支上手动触发。

定时扫描是兜底机制：GitHub 可能延迟 schedule 运行、并发合并可能丢弃排队中的 run（见第 4.6 节），扫描会修复这些漏掉的 head。

4.2 作者写权限门：所有路径统一执行

所有处理路径（PR 事件、定时扫描、手动 dispatch、dry-run）都通过 GitHub 的 collaborator-permission API 检查PR 作者当前的有效仓库权限：

• read、triage、无权限的作者一律跳过，包括没有写权限的 bot 作者；
• maintainer 向别人的 PR 推提交、或 maintainer 手动 dispatch，都不能绕过这道门——代码里检查的是pull.user而不是触发者（github.actor）；
• 不拿组织成员身份或author_association当作写权限的代理；
• 自定义角色走 API 返回的有效基础权限（maintain 映射为 write，triage 映射为 read）。

源码中 authorCanWrite 的注释解释了背后的动机："a maintainer pushing to an external PR must not opt its author in"。此外，权限检查在取回审查历史和 PR 状态之后、发起请求之前会再执行一次（避免复用旧结果），查询失败或出现意外权限值会让 run 明显失败，而不是发起请求。文档也坦承：GitHub 不提供"权限检查 + 审查请求"的原子操作，权限变化与最终请求之间的竞态仍然可能，只是无法在 API 层消除。

4.3 Copilot 作者身份的例外处理

GitHub 的 coding-agent 作者身份（login: Copilot，type: Bot）在权限查询之前就被跳过：collaborator 端点对它会返回404: Copilot is not a user。实现上 isCopilot 与 authorCanWrite 的判断 要求同时满足 bot 类型和精确 login，其他作者仍走正常的权限 API；无关的 404 或其他查询失败不会被吞掉。被跳过的 PR 得到标准的 no-write-access 跳过决策，定时扫描继续处理后续 PR。

4.4 Dependabot 的特殊处理

由dependabot[bot]发起的pull_request_target运行会在创建 App 令牌之前就跳过整个 job，原因是 Dependabot 的 PR 事件可能缺失 Actions secrets（GitHub 官方对 Dependabot-on-Actions 有专门限制说明）。job 级 if 条件 同时承担了"仅microsoft/aspire运行"和"手动 dispatch 必须来自main"的校验。

注意两点配套约束：

• 定时扫描和 maintainer 手动 dispatch 使用自己的执行上下文和凭据，但仍然执行作者权限门——没有写权限的 Dependabot PR 在这些路径上同样被跳过；
• 不要把 App 私钥复制进 Dependabot secrets。

4.5 14 天活跃度过滤：只作用于定时扫描

定时扫描会跳过最近 14 天无活动的 PR，判定依据是 GitHub 的updated_at时间戳——不是PR 创建日期或最新提交日期。关键细节（对应 ineligibleReason 实现）：

• 截止是包含的：恰好 14 天前更新的 PR 即视为陈旧（updatedAt <= staleCutoff）；
• 跳过时 summary 记录Skipped: no PR activity in the last 14 days.，且发生在拉取审查历史之前；
• dry-run 和 enabled 模式、包括单 PR 试点，全部适用；
• 该过滤只跳过，不会关闭 PR 或撤销已有审查；
• 反映在updated_at中的任何活动（含自动更新）都会让老 PR 重新变得合格；
• updated_at缺失或非法会让 run 失败，而不是静默地把 PR 当活跃处理；
• push 触发和手动运行不应用该过滤，maintainer 始终可以手动对账老 PR。

4.6 并发、待定审查与竞态边界

• 单一并发组，不取消活跃 run：所有 run 共享group: organization-funded-copilot-reviews且cancel-in-progress: false（见 concurrency 定义），push 处理器和定时扫描不会同时为同一 PR 请求审查；GitHub 可能用较新的 run 替换排队中较旧的 run，被合并的事件由定时扫描兜底；
• 待定审查让路：若requested_reviewers中已有 Copilot，本轮记为Deferred: Copilot review is pending.，等它完成后下一次扫描再判断；
• 以 head SHA 为单位的去重：Copilot 对当前 head SHA 已有非 PENDING 审查（包括被 dismiss 的）即跳过；人类审查不计入；这是对"最新推送的 head"的审查，不是对多提交 push 中每个中间 commit 分别审查；
• 请求前重新取回 PR 状态：因为 GitHub 不提供把审查请求绑定到特定 head SHA 的事务或幂等键，并发推送或工作流之外的请求仍可能与 API 调用竞态；此时记为Deferred: PR changed during reconciliation.，由后续扫描安全修复。定时对账能修复漏掉的 head，但不能保证 exactly-once 计费；
• API 错误让 run 明显失败；请求审查的 POST 不自动重试（retries: 0），因为超时可能发生在 GitHub 已接受请求之后；卡死的 pending 请求需要 maintainer 介入，工作流绝不删除别人的审查请求来强制重试。

5. 安全边界：特权 workflow 的"零检查"设计

文档的安全边界一节与实现逐条对应，核心是把"能读到 PR 内容"与"能执行 PR 代码"彻底分开：

• 特权 workflow 不检出任何源码：不 checkout、不执行 PR 代码、不加载本地 actions、不安装包、不消费 artifacts 或 caches。所有策略逻辑以内联脚本形式写在 workflow 文件 里，正是为了免检出；
• 仅有的两个 action（actions/create-github-app-token与actions/github-script）全部使用完整 SHA 固定版本；
• workflow 自身的GITHUB_TOKEN没有任何授予的权限（permissions: {}）；App 安装令牌限制为本仓库 + Pull requests read/write（按模式收窄）+ GitHub 强制的元数据读取；
• 私钥与令牌分离：App 私钥只交给 token action，对账脚本拿到的是已收窄的临时令牌。文档提醒：私钥可以铸造出拥有 App 全部安装级权限的令牌，因此保护 secret 与可信 workflow/运行时仍然至关重要；全程不使用 PAT；job 使用临时 GitHub 托管 runner，超时 10 分钟；
• 身份固定：仓库、审查者（copilot-pull-request-reviewer[bot]）都硬编码；PR 可控的值只作为 API 数据，永不内插进脚本或用作 API URL；日志与 summary 只包含校验过的 PR 编号、SHA 和固定决策消息；
• pull_request_target执行的是基线分支的 workflow 版本，因此必须保护main与允许的 release 分支、对 workflow 变更要求可信评审；
• 该 job 只请求审查：不 approve、不 merge、不推修复、不执行 suggestions。CCR 自身的 runner/setup 与 secret 配置是另一条安全边界，试点前需要单独评估。

6. 计费归属验证与六步 rollout

6.1 为什么"bot 请求"不等于"组织付费"

GitHub 文档将内置自动审查记到作者名下，并明确 bot 请求的审查直接计给组织。但如第 1 节所述，Aspire 仓库的历史现象（#18530、#17949）削弱了这一假设：GITHUB_TOKEN本身也是安装令牌，换用独立 App 改变的是请求方身份，而不是文档化保证的"计费账户选择器"。把自动化限制在写权限作者范围内，可以避免自动把其他贡献者拉进可能消耗个人额度的审查；但它既不修复归属问题，也不保证合格作者有预算。在 Microsoft 的策略下，实际执行、配额强制与计费必须在扩大 rollout 前单独确认。

6.2 上线步骤（原文六步，完整继承）

1. 合入前：设置COPILOT_REVIEW_MODE=dry-run，并把COPILOT_REVIEW_PR_NUMBER设为一个约定的、团队拥有的试点 PR；如有必要取消已有的 enabled workflow run——改变变量不能停止它们。合入后检查 workflow 的决策记录和 App 令牌创建是否成功；
2. 排查既有规则：找出适用的仓库/组织级自动 CCR 规则（含 "Review new pushes"），在开启写路径前禁用它们，否则它们仍可能创建作者归属的或重复的审查；
3. 评估 CCR 下游 runner 权限，确认组织出资/预算策略；取得试点参与者的同意（可能消耗其个人额度），不要在不知情的人身上做实验；
4. 设置COPILOT_REVIEW_MODE=enabled。确认aspire-repo-bot[bot]发出了审查请求；再推一个提交，确认触发重新审查（包括在一次审查进行中推送的场景）；记录 PR/head、时间戳、请求方 actor、执行归属和任何配额错误，用于计费关联分析；
5. 由计费管理员确认：这些 bot 请求的审查确实归属组织、且未消耗任何贡献者的个人额度。API 调用成功或审查帖子本身不是计费归属的证明；
6. 清空试点变量，覆盖所有写权限作者的开放 PR。保持人工 approve 要求不变，监控开销与失败的 workflow run。

6.3 失败路径与回滚

• 若 App 无法发起 CCR、或归属仍不清晰：保持写路径关闭，把试点证据升级给 GitHub 支持，问清楚配额检查的是哪个 principal、账单记到哪个账户、Actions 令牌与独立 App 安装令牌是否被区别处理。不要用个人令牌替代，不要静默提权，也不要仅凭请求 bot 或显示的 "on behalf of" 身份推断计费；
• 个人自动审查设置与手动请求不受该工作流控制，保留各自的计费归属；CCR agentic 能力消耗的 Actions 用量与审查本身的 AI credits 也是两笔账；
• 回滚方式就是COPILOT_REVIEW_MODE=disabled；不要自动恢复作者归属类的 ruleset。

7. 小结

Organization-funded Copilot reviews工作流（docs/ci/organization-funded-copilot-reviews.md + workflow 实现）提供了一个可参考的"高敏感自动化审查"工程范本：

• 身份设计：独立 App + 每次运行铸造最小作用域临时令牌 + 写权限按模式动态收窄，GITHUB_TOKEN零权限，无 PAT；
• 准入设计：所有触发路径统一执行基于 collaborator-permission API 的作者写权限门，pull_request_target的"维护者代推"场景也无法绕过；
• 对账设计：15 分钟定时扫描 + 14 天活跃度过滤 + 单并发组 + pending 让路 + 请求前二次取回，用最终一致的方式补偿 GitHub 缺少事务/幂等键的现实；
• 上线设计：dry-run 默认、单 PR 试点、kill switch、六步 rollout，并把"计费归属验证"作为独立且不可跳过的关卡。

如果你在自己的仓库中评估类似能力，可以直接对照上述变量表、权限门实现与安全清单逐项检查，而不是假设"换一把 bot 令牌"就能解决计费与权限问题。

【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire