# GitHub App 适配器(`@wishforge/github`) 通过 GitHub 官方 REST API(固定版本 `2026-03-10`)实现 GitHub App 安装令牌、PR 创建、对账与合并。租户、项目与运行级的授权、持久化的操作记录与按确切版本的合并审批在 `apps/api/src/domain/github.ts` 中。它不读取 `gh` 登录缓存、`GH_TOKEN`、浏览器会话或开发者的 Git 凭据。 ## 运维配置 API 进程挂载只读的 `WF_GITHUB_APP_CONFIG_FILE`(安装 ID 与仓库 ID 不接受来自租户的请求): ```json { "appId": "12345", "privateKeyFile": "/run/secrets/wishforge-github-app.pem", "apiBaseUrl": "https://api.github.com", "webOrigin": "https://github.com", "tenantInstallations": [{ "tenantId": "tenant-id", "installationId": 9001, "repositories": [{ "owner": "example-org", "name": "web-project", "repositoryId": 101, "allowedBaseBranches": ["main"], "allowAutomaticMerge": false }] }] } ``` 也可以用 `privateKeyVaultPath`(如 `secret/data/wishforge/github-app`)代替 `privateKeyFile`,此时需要 HTTPS 的 `VAULT_ADDR` 与只给 API 使用的 `VAULT_TOKEN`,PEM 位于 KV v2 的 `data.data.privateKey`。App 私钥与 Vault 令牌都不会发给 worker。没有配置时报告 `GITHUB_UNCONFIGURED`,对应的运行进入 `github_unconfigured` 等待,不会退回直接推送。 运维在目标仓库安装 App,并在线下把它映射到正确的租户。仓库规则中不要给 App 任何绕过权限。不支持 fork 的 PR 与任意基础分支:两个分支都必须属于映射的仓库,head 必须是本运行的 `wishforge/<运行>/` 分支。 ## 令牌 API 签发最长 10 分钟的 RS256 App JWT,用恰好一个 `repository_ids` 并显式声明 `contents` 与 `pull_requests` 权限换取安装令牌:executor 只读,verifier 可写;返回的有效期、权限与仓库范围都会核对,范围过大的令牌被拒绝。令牌只发给当前持有执行租约的身份,I/O 之后再次核对租约。安装令牌按 GitHub 的约定一小时后过期,并不随 worker 租约提前失效。Git over HTTPS 使用用户名 `x-access-token` 的 Basic 认证,令牌不出现在克隆地址或命令行参数中。参见 [App JWT](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app)、[安装令牌](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app)。 ## 操作 | 方法 | 说明 | |---|---| | `status(actor, projectId)` | 仓库能力 | | `credential(actor, project, run)` | 最小权限的安装令牌 | | `createPullRequest(actor, runId, input)` | 以 `operationId`、标题与正文、`headBranch`、`baseBranch`、`expectedHeadSha`、`expectedBaseSha` 创建 PR;head 必须等于运行已验证的 commit | | `readPullRequest` / `reconcilePullRequest` | 读取已记录操作的远端状态 | | `authorizeMerge(actor, id, {expectedHeadSha, expectedBaseSha})` | 交互式的 owner/admin/deployer 按确切版本授权合并 | | `merge(actor, id)` | 需要上述授权或运维配置的自动合并 | - 创建操作在发出远程请求前写入数据库;对账按 head/base 与稳定的操作标记匹配(包括已关闭的 PR);没有该标记的已打开 PR 视为冲突。响应丢失时结果记为未知,之后的调用先读状态,不会盲目重建或重复合并。 - 合并前重新读取两个分支并检查可合并性,使用异步合并 API(确切的 head `sha`、`merge_action: default`、`bypass_rules: false`),配置的合并队列仍然生效;排队中的结果保持 pending。合并后重新读取 PR 得到实际的合并 commit。它与已验证的 commit 不同时,旧的验证与审批失效,运行回到 verify 等待重新验证(`github_review`)。参见 [PR 与合并 API](https://docs.github.com/en/rest/pulls/pulls?apiVersion=2026-03-10)。 ## worker 协议 verifier 使用 `/internal/runs/:id/github/{state,create,advance}`,每个请求都带当前租约 token。创建时绑定候选检查点的源与基线 commit 以及分支 `wishforge/<运行>/<候选 commit>`;操作 ID 在访问 GitHub 前持久化,恢复时对账已有操作而不是新建。`apps/worker/src/github-delivery.ts` 在每次推送评审分支或尝试合并前都要求持有项目集成租约;`GitWorkspace.pushReviewBranch` 只创建新的不可变分支(引用不存在时才写入),已存在时只接受内容一致的情况,从不强制更新目标分支。合并确认后,worker 在新工作区恢复实际的合并 commit,重新运行验收配置与清单检查,然后才提交集成证据或构建。 这是由应用保证的写入路径,不是按分支限定的 GitHub 令牌:安装令牌在一小时内对整个仓库有效,本地检查与外部写入之间存在租约过期的时间窗,已经发出的操作无法被数据库 fence 撤回。分支保护、App 无绕过权限、verifier 隔离、凭据撤销与结果对账仍然必需。 ## 测试 ```bash npx vitest run tests/github.test.ts apps/worker/test/github-delivery.test.ts ``` 测试使用伪造的 HTTP 传输与临时 RSA 密钥,覆盖令牌范围、JWT 签名、租约归属、PR 操作身份、结果未知、审批与 commit 检查、排队合并与合并 commit 变化后的失效;不访问 GitHub、不创建真实 PR。真实的 App 安装、仓库规则与合并队列、合并后构建需要在运维提供安装映射后验收。