镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/external-executors.md ↗
外部执行端:临时授权、事件转发与轮询
外部执行端可继续使用自己的检视工具。Bot 负责验证 GitHub 投递、过滤转发,并在执行端完成工作后兑换 Bot 身份的临时 GitHub 凭据。两项功能均默认关闭,没有预置客户端、仓库或订阅。
一次完整接入
- 超级管理员登记 GitHub App 和目标仓库,并在 App 安装中授予 Contents read、Issues write、Pull requests write。外部凭据兑换只支持 GitHub App;不会把机器人账号的长期 Token 当作临时凭据分发。
- 在目标项目设置的「外部执行」类别选择「新增客户端」,自动绑定当前项目,不提供仓库选择。个人电脑选择公钥签名认证;GitHub Actions 选择 OIDC。项目管理员只能配置分配给自己的仓库。
- 个人电脑在本机生成 RSA 密钥,只向 Bot 登记 SPKI PEM 公钥;私钥不离开个人电脑。管理页显示公钥指纹,支持更换公钥或停用客户端。兑换地址作为签名证明的固定 audience:超级管理员可在全局「外部执行端」页保存实际 HTTPS 地址,未保存时使用接入向导已验证的公开地址(
<已验证 origin>/external/token,按公开路由推导;反代单独路由/external/时请保存显式地址),所以项目管理员不必等这一项也能完成接入。 - 在当前项目的「外部执行」中新增转发订阅,指定接收 URL、事件和动作。例如事件
pull_request,动作opened,ready_for_review,synchronize,勾选排除草稿。保存后显示一次签名密钥,在接收端保存并校验签名。客户端私钥与转发签名密钥分开管理。 - 外部接收端收到消息后,按转发 ID 去重,再运行原来的检视工具。检视完成后调用公开的临时凭据接口,再用取得的令牌请求 GitHub 评论/Review API。也可先兑换临时令牌,再用同一个令牌调用
GET /external/events拉取事件。完成后调用撤销接口。
若只想使用外部检视,可保留仓库 enabled,但把能力上限设为 read(等同于关闭内置 review_enabled);转发订阅有自己的启用开关,不依赖内置模型或检视开关。两边同时启用时都会处理事件,Bot 不会自动关闭其中一边。
管理页中的接入说明
全局「外部执行端」只管理兑换地址、展示一套完整接入说明,列出已配置外部客户端的项目链接,以及可在这里删除的各个客户端。超级管理员可以设置兑换地址,项目管理员只读。展开说明后,默认先给出可复制的 4 步短路径(生成密钥、登记公钥、在本机完成兑换、使用 token),协议细节折叠在「高级/协议说明」中;选择个人电脑客户端后也可点击「复制给我的 AI agent」,取得含客户端 ID、绑定仓库 ID、兑换/轮询地址的纯文本指令。短路径里的兑换步骤是一条可复制脚本,会写出 proof-header.txt 和 token-request.json 并发送请求,不必打开高级说明。地址未配置时不会编造 URL。客户端行和公钥登记表单不重复完整步骤,新增客户端对话框只保留简短的 OpenSSL 帮助。GitHub Actions OIDC 客户端不套用个人电脑公钥流程。
项目的「外部执行」页默认展开同一套接入说明,点击说明标题可在原页收起或再次展开,并提供「复制给我的 AI agent」按钮,无需跳转全局页。客户端选择只包含当前项目的个人电脑客户端,复制的指令使用所选客户端 ID、当前项目仓库 ID 和最新全局兑换地址。即使直接打开项目链接,也能读取完整说明并复制;没有个人电脑客户端时提示在本项目新增。
客户端、公钥、Webhook 订阅、转发状态和令牌记录在所属项目的「外部执行」类别管理。项目管理员只能查看和修改分配给自己的项目;超级管理员在某个项目中也只能操作该项目的资源。客户端可以在项目的「外部执行」或全局「外部执行端」删除:超级管理员可删任何项目的客户端,项目管理员只能删分配给自己的项目。删除客户端同时删除它的临时授权记录、转发订阅(转发记录引用订阅,随订阅一起删除)、事件轮询进度和尚未发出的转发,项目本身不受影响;已兑换的 GitHub 令牌按原到期时间失效。创建客户端自动绑定当前仓库,订阅不能引用其他仓库的客户端,令牌权限始终固定。
项目客户端行的「查看详情」打开可刷新、分享的同项目地址,分开展示认证身份、公钥或 OIDC 信任字段、客户端配置版本、接入能力和活动记录。授权与转发分别从当前项目最近最多 100 条记录中筛选,不能据此声称完整历史或执行端在线。认证启用只允许按身份规则兑换令牌;当前接入不提供 Agent/模型版本、运行心跳或隔离核验结果。停用前会说明阻止新兑换、取消待发送转发,以及已签发令牌仍需由执行端主动撤销或等待到期的影响。
手机使用全屏编辑器,保存操作与滚动字段分开。一次性转发签名密钥关闭、切换地址或退出后清空;取消编辑后迟到的保存响应不会再次弹出旧凭据,权限失效会清除当前记录和输入。
个人电脑认证与兑换
统一公网入口提供 POST /external/token,它和管理 API 在同一个业务端口,但只按客户端证明认证,不需要登录会话。HTTPS 反向代理把整个域名转发到业务端口即可。超级管理员在「外部执行端 → 设置兑换地址」填写实际完整 HTTPS 地址,以 /external/token 结尾;未保存时使用接入向导已验证的公开地址加 /external/token,保存的值优先。两者都不从传入 Host 头推导信任地址。项目管理员可读取该地址,不能修改。
在个人电脑生成新的密钥文件,私钥留在本机,公钥粘贴到管理页:
umask 077
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out bot-client.pem
openssl pkey -in bot-client.pem -pubout -out bot-client.pub.pem
支持 RSA 2048–4096 位、SPKI PEM 公钥(BEGIN PUBLIC KEY),不接受私钥或 SSH 格式。Bot 保存公钥与指纹,不生成、接收或分发客户端私钥。每个客户端仍绑定一个仓库。
取得页面中的客户端 ID 后,用任意语言或 HTTP 工具按下述接口规则兑换,不要求 Node.js 或下载项目脚本。完整的接口说明与 OpenSSL+curl 示例包含本机签名、POST 兑换、调用 GitHub 和撤销;URL 必须与管理页登记的兑换地址完全一致。scripts/external-token.mjs 仅作为可选实现保留。
使用 RS256 签名 JWT,header 为 alg: RS256、typ: JWT,payload:
{
"iss": "<客户端ID>",
"sub": "<客户端ID>",
"aud": "<管理页配置的完整HTTPS兑换地址>",
"iat": 1700000000,
"exp": 1700000120,
"jti": "<至少16位的随机唯一ID>"
}
时间戳需使用发送时的当前 Unix 秒,exp - iat 不得超过 120 秒,允许五秒时钟偏差。jti 使用 16–128 位字母、数字、下划线或短横线,推荐随机 24 字节编码。请求头是 Authorization: Bearer <签名JWT>、Content-Type: application/json;正文为 { "client_id": "<客户端ID>", "request_id": "<与jti完全相同>" }。这是 JSON 凭据 broker,采用私钥签名认证,不是完整 OpenID Provider 或标准 OAuth 表单端点。
服务端用登记公钥验签,精确校验客户端、audience、时间与一次性标识,拒绝其他算法和外部密钥 URL。签发前在事务中持久占用 request_id 和身份摘要;同一个签名换 request_id 也无法重放,重启后同样有效。更换公钥或停用客户端会在后续请求及签发中途的版本复核中生效。
成功响应包含 grant_id、token、token_type: Bearer、expires_at、repository_id 和权限。token 是 GitHub App 对指定单仓库的安装令牌,权限固定为 contents: read、issues: write、pull_requests: write,不含 Contents write。客户端不能扩大权限或更换仓库,签发时复核仓库、所有者和 App 安装关系。
响应使用 Cache-Control: no-store,不进入 Webhook 归档。数据库保存公钥、请求/身份摘要、令牌摘要和签发状态,不保存客户端私钥、原始签名 JWT 或 GitHub Token。每客户端每小时最多 20 次兑换,失败签发也占用配额;上游结果未知时该请求仍被消耗,不能反复签发。
GitHub 安装令牌通常有效一小时,以实际 expires_at 为准。它仍是 Bearer 凭据,不能限定到单条 PR 或只调用某个 API。内置检视保持 COMMENT,外部可信工具需遵守仓库策略。更换客户端公钥或停用只阻止新的签发;已经领取的 GitHub Token 需主动撤销或等待到期。Bot 不分发 App 私钥、入口签名密钥、模型 Key 或长期账号 Token。
撤销使用 POST /external/revoke,正文 { "grant_id": "<签发ID>", "token": "<已领取令牌>" }。不需要管理会话,但必须匹配该签发记录的令牌摘要;重复撤销幂等。
已有客户端迁移
升级自动将旧 client_secret 客户端改为「待登记公钥」,清除旧凭据摘要。客户端 ID、仓库、启停意图、订阅和历史保留;旧凭据立即不能兑换。原项目管理员在该客户端点击「登记公钥」,提交个人电脑生成的公钥即可恢复使用,无需重建客户端或订阅。不会在 Bot 服务器代生成个人私钥,也不保留旧凭据认证回退。
GitHub Actions OIDC
客户端选择 GitHub Actions OIDC 时使用 GitHub 签发的身份,不登记个人电脑公钥。管理员需要配置精确的 audience、subject、工作流仓库名、不可变仓库 ID、组织 ID、workflow_ref 和分支 ref。只信任 GitHub 的固定 issuer https://token.actions.githubusercontent.com 及其 JWKS,验证 RS256、签名、nbf/iat/exp、最大十分钟身份年龄和 jti。
兑换接口和请求正文相同,Authorization 改为 GitHub 签发的 OIDC JWT。必须满足所有已登记身份条件;若包含 job_workflow_ref,也必须匹配登记的工作流。仅接受 schedule、workflow_dispatch、repository_dispatch 事件和明确登记的分支,拒绝 PR 身份。相同 JWT 身份只能兑换一次,记录持久化,重启后也不能重放。这是凭据 broker,不是完整的 OpenID Provider,也没有把任意传入的 JWT 当作受信任身份。
转发协议
接收端须可从 Bot 控制面访问。默认只接受 HTTPS,并拒绝解析到私网、回环或本地地址的目标。若接收端位于部门内网,由部署管理员在 Docker 环境变量 BOT_FORWARD_PRIVATE_HOSTS 中显式批准准确主机名,逗号分隔,不支持通配符。例如可登记自己的内网接收主机;不要批准管理服务或元数据地址。只有这些主机允许 HTTP 和私网连接。
DNS 检查在每次投递前执行,连接固定使用已验证的地址;不跟随重定向。网络及响应超时有界。接收端不需要开放项目容器端口,Bot 也不会改变现有项目容器的网络隔离。
请求为 JSON,包含:
{
"version": 1,
"id": "<稳定的转发ID>",
"subscription_id": "<订阅ID>",
"client_id": "<授权客户端ID>",
"repository_id": "<仓库ID>",
"event": "pull_request",
"delivery_id": "<GitHub delivery ID>",
"received_at": "<首次归档时间>",
"payload": { "action": "opened", "pull_request": {} }
}
X-Bot-Delivery 与正文 id 相同;X-Bot-Event 给出事件类型;X-Bot-Signature-256 为 sha256= 加 HMAC-SHA256 的十六进制摘要,计算输入是收到的原始请求字节,密钥为订阅签名密钥。应先验签再解析和执行,校验头部 ID 与正文 ID 一致,并持久保存已处理的转发 ID。原 GitHub Authorization、Cookie 和签名头不会转发;正文不包含客户端私钥或临时令牌。
归档与转发入队在同一 SQLite 事务中完成,验签失败、范围外仓库、不匹配事件和草稿不会入队。重复 delivery 不重复入队。后台在提交后投递,2xx 视为已接收;网络故障、408、429 和 5xx 指数退避重试,最多五次,其他状态失败。返回 2xx 前,接收端应已可靠接收任务,而不必等待长时间检视完成。不要让耗时检视阻塞有五秒超时的 Webhook 响应。
转发采用至少一次投递。响应丢失或 Bot 重启时可能再次发送同一个 ID,接收端负责幂等;不能把内存去重当作生产保证。订阅变更、停用或客户端公钥更换会取消尚未发送的旧任务;已经发出的网络请求无法撤回。失败投递可在管理页面重试,仍使用同一个转发 ID。
事件轮询
公开 Webhook 监听提供与兑换地址同源的 GET /external/events。先按既有流程兑换,然后以 Authorization: Bearer <token> 使用同一个 GitHub App 安装令牌拉取。无需第二套登录或第二种令牌,不消耗每小时 20 次兑换额度;服务端校验已保存的 external_grants.token_hash、签发状态及到期时间,拒绝未知、撤销、过期令牌和已停用的客户端/项目。
轮询只返回绑定仓库最近 24 小时已验签归档的 issues、pull_request,包含事件名、GitHub delivery ID、action、仓库 ID、Issue/PR 编号和原始事件载荷。轮询与 Webhook 订阅过滤独立,同一次 GitHub delivery 去重,每批最多 100 条,无新事件时返回 {"events":[]}。管理页投递档案不受 24 小时窗口影响。
每个客户端独立持久保存进度,续换令牌和重启不重置。HTTP 200 响应写出完成后进度前进,此客户端下次不再收到这批旧事件;另一个客户端仍可取得自己未读的事件。发出前失败不前进;客户端丢失成功响应时服务端不补发。没有回放或显式 ACK;需要至少一次交付时仍可使用现有 Webhook 推送。完整请求和响应见接口说明。
管理 API
这些接口使用既有登录会话和 CSRF 校验。项目配置路径中的 :repository 固定为当前项目,列表、单条读取、更新和重试都校验项目归属;跨项目资源会被拒绝。读取沿用当前项目可见范围;新增、启停、换公钥、删除、订阅编辑与密钥轮换、转发重试还需要目标项目的 config.write,仅有任务读写权限不能修改外部执行配置。全局兼容端点同样按资源实际绑定的项目校验,其他项目的配置权限不能替代本项目权限。
仅有查看权限时,项目页保留客户端详情、授权与转发记录,并说明应联系项目配置管理员;不显示配置或重试操作。全局页保留详情入口,项目管理员在项目页管理客户端,超级管理员也可从全局列表删除。
| 路径 | 方法 | 内容 |
|---|---|---|
/api/external/settings |
GET / PUT | 读取固定 token_audience;只有超级管理员可保存完整 HTTPS 兑换地址 |
/api/repositories/:repository/external/clients |
GET / POST | 客户端列表/创建;字段 name、auth_type;repository_id 从路径确定,正文若提供必须一致;private_key_jwt 必须提供 public_key,OIDC 提供 trust |
/api/repositories/:repository/external/clients/:id |
GET / PATCH / DELETE | 读取元数据、公钥与指纹;enabled 启停、public_key 登记或更换公钥;DELETE 需 confirm:true,连同授权记录、订阅、轮询进度和转发一起删除(全局 /api/external/clients/:id 同样可删,按分配范围限制) |
/api/repositories/:repository/external/subscriptions |
GET / POST | 列表/创建,字段 client_id、name、url、filters;签名密钥只在创建时返回 |
/api/repositories/:repository/external/subscriptions/:id |
GET / PATCH | 更新 name、url、filters、enabled 或 rotate_secret;读取不含密钥 |
/api/repositories/:repository/external/deliveries |
GET | 最近 100 条转发状态、尝试次数与错误码 |
/api/repositories/:repository/external/deliveries/:id/retry |
POST | 重试失败投递 |
/api/repositories/:repository/external/grants |
GET | 最近 100 条签发记录,无原始凭据和身份 JWT |
全局 /api/external/ 兼容列表可用 repository_id 筛选,项目路径不允许以查询参数切换仓库。订阅签名密钥只在创建/轮换时显示一次。公钥可读,客户端私钥永不上传或回显。凭据兑换失败不降级为长期 PAT,不调用模型或读取其他项目材料。