eust-w b38db08eeb docs: align documentation with the code and write it in Chinese
Operations, development and architecture docs, the reference pages and the
component READMEs were rewritten against the code: every documented variable
exists, and the settings operators need (runtime image, Git service, listen
addresses, Runner targets, single-tenant gateway and provisioner bindings) are
documented.

Gaps the docs used to present as working are now stated as such: IDE
workspaces do not clone the project yet (FR-H2), and in Kubernetes mode
dependency installs and image builds have no network path until an egress
proxy and builder access exist. The Kubernetes README describes what the
provisioner creates, what the Runner needs in a target namespace, and the
cluster acceptance that is still outstanding.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 18:01:39 +08:00

5.5 KiB
Raw Permalink Blame History

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 不接受来自租户的请求):

{
  "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/<运行>/<commit> 分支。

令牌

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、安装令牌。

操作

方法 说明
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。

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 隔离、凭据撤销与结果对账仍然必需。

测试

npx vitest run tests/github.test.ts apps/worker/test/github-delivery.test.ts

测试使用伪造的 HTTP 传输与临时 RSA 密钥,覆盖令牌范围、JWT 签名、租约归属、PR 操作身份、结果未知、审批与 commit 检查、排队合并与合并 commit 变化后的失效;不访问 GitHub、不创建真实 PR。真实的 App 安装、仓库规则与合并队列、合并后构建需要在运维提供安装映射后验收。