Use role-bound GitHub App identities for SDK development, reviews and delivery reconciliation #2365

Written-by: Codex

目标分支与负责人

• 实现/PR 目标分支：delivery/ai-centric-development-service。
• Assignee：@zy95-12。
• 关联：Support GitHub App installation credentials for project automation alongside gh-cli #2311（已有 GitHub App installation provider）、Automatically enter the host merge flow after Reviewer approval of the current candidate #2331（审核通过后的受控合入）、修复 Task-role 执行绑定含易变 cwd 导致跨 Attempt 无法 resume 的死锁 #2346（Task-role Session 恢复）。
• 本 Issue 记录本次 side conversation 确认的新设计，不中断或替换主会话正在开发的 Issue，不授权改动现场任务、资源配置、凭据或部署。

Owner 确认的方向

项目级 Chief、Dev、Reviewer、Tester 等 Bot 的 GitHub 操作应使用明确配置的 GitHub App installation 身份，避免把自动化行为归属到某个个人账号。SDK 可以直接通过 git、gh 或 GitHub API 完成角色获准的操作；不要求每个动作都由宿主代执行。

FlyBot 保留身份签发、当前授权校验、结果核验、Task/Attempt 绑定及审计职责。GitHub App 提供外部身份，SDK 执行代码与工具；App 不替代 FlyBot 的角色、Session、claim 或用户授权。

个人代理明确代表用户的行为仍遵守独立个人授权，不在本条中自动改成项目 App。

当前代码与缺口

只读核对交付分支：

• project-github-app.js 已实现安装验证、限定仓库/权限的短期 installation token、缓存/并发刷新及身份元数据，当前主要用于可信宿主 GitHub 调用。
• project-github.js 明确将凭据留在宿主；SDK 角色提示禁止直接 publish PR，共享分支 refs 也受限制。
• project-delivery.js 目前由宿主封候选并在测试/Review 通过后发布。不能仅把 Token 填进环境就宣称 SDK 直接提交/发布、候选关联和恢复已可用。
• 使用 App 推送不会自动改变 Git commit 的 author/committer；必须分别处理提交作者、推送主体、PR/Review/检查/合入主体。
• 一个 App 的不同 token、不同 installation 或不同 SDK Session 不构成多个 GitHub 审核身份。

本次决定对 #2311/#2331 中“Token 不进入通用 SDK 环境”的旧边界作明确且有限的扩展：允许授权角色通过专用 GitHub 凭据入口使用短期 installation token。私钥、Token 仍不得进入模型提示、记忆、公开状态/API、普通测试环境或日志。不得静默放宽其它权限。

实现范围

1. 角色与 App 连接绑定

• 支持可信配置将项目角色/能力绑定到已授权的 App connection；记录 App、installation、仓库、角色、权限及配置 revision。
• 至少支持 Dev 与 Reviewer 使用不同 App 身份：Dev 创建/更新 PR，Reviewer 提交真实审核。Tester 可发布对应检查；Chief/合入执行者按现有明确授权配置。
• 不要求每个项目、每个临时 Bot 注册一个 App。一个角色 App 可服务多个获准仓库/项目，操作时仍核验当前 installation、仓库及权限。
• 若 Dev/Reviewer 配成同一个 App，必须明确显示身份复用，不能把它冒充独立 GitHub approval，也不能绕过“作者不能批准自己的 PR”等实际规则。
• SDK 不能自行选用其它角色/App、扩大权限或切回 Owner/个人 gh/ambient token。现有 gh-cli 兼容配置可保留，但启用 App 模式后不作隐式降级。
• App 注册、安装与私钥接入仍由明确获准的人类/操作员负责，不由模型自行完成。

2. 执行资源侧短期凭据

• 私钥与长期配置仅保存在 FlyBot 的私有凭据边界。执行资源无需个人 PAT、无需复制 App 私钥、无需全局 gh auth login。
• 复用已有 provider，按当前 Project/Task/Attempt/claim/generation/角色及资源绑定签发或获取限定仓库、最小权限的短期 Token。
• 为本地和 Docker 资源的 git HTTPS、gh/API 提供角色专用认证入口；可用凭据助手/包装器或隔离的短期 GH_TOKEN，方案应支持 SDK 直接操作，不能把每个开发动作重新变成宿主专用业务接口。
• 认证入口不将 Token 拼入持久 remote URL、命令参数、shell history、SDK stdin 记录或工具输出。对 SDK 自身及其工具输出、异常、调试/trace 日志落实脱敏，不承诺 SDK 持有凭据后模型主动外传在技术上绝对不可能。
• 续期与并发刷新复用已有 provider；长任务不因约一小时有效期而中断，刷新不改变操作身份或幂等键。
• 同一资源并发运行不同角色/项目时，凭据、临时认证配置和 Git 身份必须隔离，不能通过共享全局 git/gh 配置互相覆盖；普通宿主测试/验证子进程不得继承角色写凭据。
• 结束、取消、撤权、资源失联及宿主重启后清理或隔离临时凭据；无法立即远程清理时如实保留到期/风险状态，停止续签，不能伪报即时撤销成功。
• 明确说明 installation token 的仓库/权限约束不等于分支级约束；受控分支策略与仓库保护仍须独立执行。

3. GitHub 行为归属与实际操作

• Dev 在获准工作树中可 git commit、推送获准开发分支、创建/更新 Draft PR，不能仅因宿主代管凭据而被提示“无法提 PR、只能人工”。
• author/committer 使用经核验的对应 App Bot 名称和 noreply 邮箱，不能残留个人全局 Git 配置；涉及真实人类作者的已有提交不自动重写或冒名。
• PR、评论、Review、检查、合入等外部行为使用对应 App installation 身份；不用代表个人的 App user token 冒充项目自动化身份。
• Reviewer 独立核验完整候选 SHA，按允许的 App 身份提交实际 Review；Tester 检查与角色结论、GitHub approval、CI、合入结果分别记录。
• 与 Automatically enter the host merge flow after Reviewer approval of the current candidate #2331 协同：审核通过后按配置的真实门禁推进合入，不增加逐 PR 人工批准；也不因本条而授予任意角色绕过保护、跨分支合入、发布或部署的权限。
• 同步角色公约、原生/SDK 提示与任务验收措辞。正常新交付由 Dev 创建/更新 Draft PR，再由测试与审核推进；验收中的“一个 PR”表示同一交付跨返工 Attempt 复用正式 PR，不能每次重新开一个。

4. 候选与 PR 回写、恢复和幂等

• SDK 自行提交/创建 PR 后，宿主从真实 Git/GitHub 结果核验当前仓库、受控 head/base、完整 head SHA、当前角色身份、允许修改范围及 Task/Attempt/claim/generation，再正式记录候选和 PR 关联。
• 调整现有宿主封候选链路以接纳并核验 SDK 的真实提交，不能在 PR 创建后无提示地产生另一个 SHA，导致 PR head 与测试/Review 候选脱节。
• SDK 报告只是待核验线索，不是可信回执；不能仅凭模型给出的 PR URL 或 approve 字符串填充 candidateSha/publicationBinding 或伪造验证。
• 若 SDK/运维已创建 PR 而宿主回写失败，沿原持久 Effect/操作回执机制对账并恢复关联；需要显式认领时通过受权且可审计的流程核验，不能直接编辑 Attempt JSON。
• 已有正式候选发生变化时保留历史/使用符合当前契约的 successor Attempt；不得覆盖原有不可变测试和 Review 证据。head/base/权限/连接变化后重新校验，旧批准不迁移到新代码。
• 同一交付多次回调、Token 刷新、重启、响应丢失、未知 push/PR/review/merge 结果，先查询实际远端状态，避免重复创建 PR/重复发布审核或重复合入。
• 发现多个候选 PR 时明确对账和正式对象选择，不能再新建一个，也不能假称历史上只有一个或自动关闭他人的 PR。
• GitHub 实际结果与 FlyBot 发起人、执行角色、SDK Session、Task/Attempt、claim/generation 和候选 SHA 一起审计；人类发起人仍可记录，不能因此被标成实际 GitHub 作者。

5. 文档与测试

• 更新长期记忆、GitHub/资源/Harness/交付架构、角色提示、README 部署使用说明和必要的接口/OpenAPI；公开接口仅暴露连接状态、身份及操作事实，不返回凭据。
• 明确资源最低依赖（git、所选 gh/API 适配器、到 GitHub/签发端的连通性）、私钥存放位置、角色绑定配置、续期与故障排查。保持部署步骤简洁，优先复用现有资源/连接管理，不重构 control-plane/UI。

验收

• 本地与 Docker 上，实际 SDK Dev 使用 Dev App 提交、推分支、创建 Draft PR；Reviewer 使用不同 App 对同一 SHA 提交实际审核，Tester 检查可关联；不归属 Owner/个人账号。
• Git commit author/committer、实际 push、PR/Review/check/merge 身份分别核验；不会因仅换 Token 而错误宣称提交作者已迁移。
• 同资源多项目/多角色并发，凭据、Git 身份和认证配置不串用；无个人/ambient 凭据 fallback，测试进程不继承写凭据。
• Token 过期/并发刷新/重启/取消/撤权/安装挂起或移除/仓库及权限变化有明确行为，不重复外部写入或复活旧 claim。
• 同 App 的 Dev/Reviewer 不被视作独立审批主体；分支保护、CI、hold、required review 和 merge queue 仍按真实规则处理。
• “SDK 创建 PR → 宿主核验 → 正式 candidate/PR/Attempt 关联 → 测试与 Review → Automatically enter the host merge flow after Reviewer approval of the current candidate #2331 合入链路”可跑通；原生角色遵守相同身份与证据契约。
• PR 已创建但回写前失败/重启可通过对账恢复；旧 SHA、错误仓库/base、伪造 URL、重复 PR、未知写结果及外部认领路径有回归用例。
• 日志、模型上下文、工具输出、状态文件、公开 API、remote URL 和长期配置不泄漏私钥/Token；审计保留真实角色与外部主体。
• 在另行明确授权的测试仓库/App 安装完成真实 GitHub 读写验证，分别报告确定性 fixture、真实 SDK 与真实 GitHub 操作证据，不用 mock 身份代替实际 App 作者验证。

范围边界

本次只授权落 Issue；不在 side conversation 修改主会话代码或执行现场迁移。Issue 不授权注册/安装真实 App、修改现场凭据、给现有资源配置 Token、改变仓库保护、合入任意现场 PR、发布或部署。实际接入使用明确获准的连接和测试资源。

官方参考：

• Installation 认证、归属、仓库/权限范围和有效期
• Review API 对 installation token 的支持
• 作者不能批准自己的 PR