镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/onboarding-guide.md ↗
接入指南:把一个代码仓交给 launchpad
这份文档面向使用 bot 的仓库维护者:从"我有一个代码仓"到"bot 在这个仓库开始工作"。主线是两步:在 GitHub 上安装 App,然后在控制台的接入向导里让助手读懂仓库、回答几个问题、确认方案。后面还有看板、CI 怎么改,以及需要你亲手做的几步。
访问入口
| 入口 | 地址 | 用途 |
|---|---|---|
| 管理面(控制台) | https://agent-ci-infra-bot-admin.llmbots.co/ | 接入仓库、管理项目、用户与仓库授权 |
| 公共 Dashboard | <公网入口地址>/dashboard/ | 看所有已登记仓库的 PR、Issue、贡献者和版本等社区指标 |
| 单仓看板 | <公网入口地址>/boards/<owner>/<repo>/ |
单个仓库的 Issue、PR、CI 运行历史、定时运行结果的趋势图和发版,<owner>/<repo> 用小写;任何仓库开启后就有内容,不需要按约定配置 CI |
| GitHub App 安装页 | https://github.com/apps/agent-ci-infra-bot/installations/select_target | 把 bot 安装到你的账号/组织 |
管理面怎么登录
- 打开 https://agent-ci-infra-bot-admin.llmbots.co/ ;
- 如果出现 Cloudflare Access 的验证页,先填你的邮箱,收邮件验证码完成验证(这一步是网关鉴权,不是 bot 账号);
- 进入控制台登录页后,用管理员分配的用户名 + 密码登录;
- 首次部署时首页会显示「创建第一名管理员」,由部署者初始化,之后这里只提供登录。
登录后,系统超级管理员从顶部「全局设置」进入部署用的「接入向导」,在第三步配置 GitHub 账号登录(它配置的是整个部署,和下面第 2 节接入单个仓库的向导不是一回事)。完整向导仅系统超级管理员可用;普通使用者通常是项目管理员,只看到分配给自己的仓库,超级管理员能看到全部。
GitHub 登录使用独立 OAuth App:在 OAuth Apps 中登记 Bot 入口和登录 Callback URL,复制这个 OAuth App 的 Client ID 和 Client secret,再回本页保存启用。仓库连接使用另一份 GitHub App,组织 Members 只读权限也在仓库 App 上配置。更换仓库 App 不会切换登录配置;已有登录 Secret 留空保留。升级前复用仓库 App 登录的配置会显示迁移说明。详细配置见GitHub 用户登录。
忘记密码或需要账号,找超级管理员在「用户管理」里重置或新建;控制台的写操作需要登录会话,长时间无操作后会要求重新登录。
0. 开始之前
| 你的仓库需要 | 说明 |
|---|---|
| 你是仓库的管理员 | GitHub 上的仓库 Admin 或组织 owner 才能打开接入向导;超级管理员也可以 |
| 已安装 GitHub App | 向导读仓库、建标签用 App 的安装令牌;改 CI 的 bot PR 要用 App 的 Workflows 权限 |
| 至少有一个提交 | 空仓库没有可读的事实,先推送代码 |
| 不限语言 | Node、Python、Go、Rust、Java 等都可以;不要求 package.json 或 npm 锁文件 |
| 是公开或私有仓库 | 公开仓安装后默认提供看板;私有仓由超管在仓库列表开启看板后公开 |
项目不需要事先启动:向导的分析只读,确认方案时才启动(见 2.4)。
1. 安装 GitHub App
1.1 安装
打开安装页,选择你的账号或组织,勾选这个仓库:
https://github.com/apps/agent-ci-infra-bot/installations/select_target
这一步只能你本人做:GitHub 要求仓库所有者确认授权,别人代替不了。
装好后 GitHub 会跳回控制台。身份页的「选择仓库安装 App」也通往这里。
1.2 同步到管理面
控制台仓库列表右上角点 同步安装列表(或让超管点)。新仓库出现在项目列表的「待接入的仓库」里,身份页也会列出它。
2. 接入向导
接入向导是新仓库接入的唯一入口:助手先读懂仓库,讲清楚 bot 能在这里做什么,问几个关键问题,再按你确认的方案把项目配置好。你不需要知道各项设置在哪一页。
2.1 打开向导
- 新仓库:在项目列表「待接入的仓库」或身份页里,点仓库旁的 开始接入;
- 已经启动的项目:在项目的「基本设置」点 重新运行接入向导,助手对照现在的设置,只列出建议改变的项,你不确认就不改。
页面顶部写着现在到了哪一步(分析仓库 → 回答问题 → 确认方案 → 启动与应用 → 完成)和下一步该做什么。左边是和助手的对话,右边是仓库画像、问题、方案三段;手机上它们排成「对话 / 画像 / 问题 / 方案」四个标签。会话属于仓库:刷新、换一台设备,或者另一位管理员打开,看到的都是同一个状态。
2.2 分析
点 开始分析。助手只读:读 README、目录、语言与构建文件、.github/workflows/、标签和最近的 Issue/PR、Actions 运行,不写 GitHub,也不启动项目。回复流式显示,较长的工作会先发一条阶段消息;随时可以点 停止。几分钟内它给出仓库画像(做什么的、技术栈、协作方式、CI、标签)和读过的来源。
分析用部署的共享模型;所属组织受信任并设了默认模型时用组织的。用量记在这个仓库上。分析没完成(模型出错、被停止)时,页面给出 重试分析、重新开始 和返回项目列表。
2.3 回答问题
助手的问题以选项卡片出现在「问题」里,每题标出推荐答案和理由,也可以补一句自己的想法再 提交回答;直接在对话里打字回答也一样。助手据此给出方案。
2.4 确认方案
「方案」逐项写明会改什么、在哪里生效,每项都能取消勾选,整份方案确认一次:
| 项 | 在哪里生效 |
|---|---|
| 启动项目 | 还没启动的仓库才有,不能去掉 |
| 能力上限 | 项目设置:只读问答/可评论和打标签/可开发并开 PR |
| 监听与触发 | Manager 接收哪些 Issue、PR 和 Actions 事件 |
| 测试命令 | 项目设置;确认时不运行,首个任务或 CI 任务运行时验证 |
| 检视语言 | 项目设置 |
| 本仓库约定 | 作为独立段落追加到 Manager 和各角色的提示词:标签怎么用、检视重点、哪些问题算简单问题 |
| GitHub 标签 | 直接在 GitHub 上新建,已有的同名标签保持原样 |
| Manager 定时检查 | 计划与通知;以项目的服务身份运行 |
| CI 建议 | 建一个开发任务,bot 开 PR 改 CI,由人检视合并(见 3.2) |
按钮随你的情况变化:
- 确认并启动:仓库所属组织已受信任(#848),或者你是超级管理员。项目马上启动,其余各项接着应用;受信任组织用组织的默认模型和能力上限启动,再调到方案的能力上限。
- 确认并申请启动:组织还没受信任。控制面向超级管理员提交启动申请,页面显示「已申请(等待超管)」,你可以 撤回申请。超级管理员在控制台「待处理」页顶部的启动申请里看到仓库画像和方案要点(绑定了飞书私聊的还会收到一条私聊,直接回复「同意」或「拒绝」加原因就能处理,也带控制台的处理链接),同意时可以改模型和能力上限,也可以顺带信任这个组织,之后这个组织的仓库由管理员自己启动;拒绝必须写原因。结果在接入页上显示,绑定了飞书私聊的申请人也会收到。同意后其余各项以申请人的身份、按申请人自己的权限应用。
- 确认并应用:已经启动的项目,只应用你勾选的差异。
2.5 完成页
方案应用完,页面变成完成页:
- 每一项的回执:已生效、已是方案值、未应用(确认时去掉了),或者没生效和原因。没生效的项带 重试;定时检查缺少结果发送的去处时,先选飞书私聊或群再重试。启动申请被拒绝或撤回时,重试会再申请一次。
- bot 现在会做什么(按能力上限和监听设置),在 GitHub 上怎么用(在 Issue 或 PR 评论里 @ 它;能力上限含开发时,加开发标签、维护者在评论里提出,或者 Manager 提示词里的规则允许,它就会开发),在飞书私聊和群里怎么用,以后在哪里改(基本设置、监听与触发、角色、计划与通知)。
2.6 超级管理员直接启动
超级管理员也可以不走向导,在自己的仓库列表里点未启动仓库的 启动:选模型、能力上限,组织还没受信任时可以勾选「信任 …」。超级管理员在「全局设置 → 项目管理 → 受信任的组织」信任一个组织后,该组织仓库的管理员确认方案时直接启动,模型和能力上限用组织的默认值,资源用全局默认值,机器配置仍只由超级管理员修改。撤销信任只影响以后的启动,已启动的项目照常运行。信任、撤销和每次启动都写入审计。
启动之后 bot 才会收这个仓库的 Issue / PR 事件。
3. 看板与发版本
仓库列表中直接用 看板 开关控制单仓看板与公共 Dashboard 汇总,无需走接入向导,也无需启动检视或开发项目:
- 公开仓默认开启,私有仓默认关闭。
- 开启私有仓后,其看板数据无需登录即可访问,请确认允许公开。
- 关闭后立即停止对外展示,包括已经生成的快照;设置在刷新、同步安装和重启后保留。
- 以前已明确启用的私有仓会保留开启状态。已保存的开或关在仓库可见性变化后也保持不变;未保存选择的仓库按新可见性使用默认值。
发版本:在项目页「发版本」确认版本后,bot 打版本标签,标签触发仓库的 release.yml;运行成功后,bot 按已核实的提交和 PR 写发行说明,创建 Release 草稿,由人点击「正式发布」。
使用时,仓库需要有发布用的 CI(.github/ci-gates.json 和运行它的 ci.yml)和版本标签触发的 .github/workflows/release.yml,再到项目页「发版本」检查版本和目标提交。相对上一枚可达的合法版本标签没有新提交时,页面说明跳过,不能确认;没有上一枚标签则按首次发布处理。填写的版本必须按 SemVer 高于上一枚可达版本标签,否则页面给出可填写的更高版本,不能确认。有新提交时,人确认后创建标签,仓库 Release Actions 成功后生成草稿,再由人点击「正式发布」。定时发版本和自动计算版本号不在当前框架范围内。
公开页面与原看板使用同一套字段、统计方法和版式,和控制台一起由业务端口 8791 托管,但无需控制台登录。控制台里的「任务看板」页是另一页面,仍需登录。
3.1 私有仓库的看板开关
私有仓默认不出现在公共页面。超管在仓库列表开启「看板」后,bot 在本地保存公开授权,并使用源仓只读安装令牌采集,后续由已验证 webhook 更新。不需要外部 dashboard 仓、登记 PR 或 PRIVATE_SOURCE_TOKEN。关闭开关会立即隐藏该仓的单仓页面和 Dashboard 数据;未开启的路径返回 404。
首次采集尚未完成时,页面或数据接口会提示等待;后台失败时保留上一次有效快照并退避重试。请先在安装向导验证公网入口地址,接入结果才会生成这个入口上的稳定链接。
3.2 CI 改动走 bot PR
bot 不按固定模板给仓库配 CI。CI 改动和其他代码改动一样,以 bot PR 交付,由人检视、合并:
- 提出改动:接入向导的「CI 建议」一项确认后,会直接建这样一个任务;也可以由项目管理员在控制台「新建任务」里写明想要的 CI,例如 PR 上跑哪些检查、哪些放进定时运行;交付类型选「可检视的代码 PR」,勾选「允许修改 .github/workflows/(CI 改动)」。只有项目管理员能看到并勾选这一项。
- bot 按仓库实际情况改:任务和其他开发任务一样在项目电脑里工作。agent 读仓库已有的脚本、Makefile、构建文件和 workflow,改 workflow,跑项目的测试命令和独立 QA,再推送自己的 bot 分支、开 PR。推送时才向 GitHub App 申请 Workflows 写权限,前提是安装已授予。
- 人合并后才生效:默认分支上的 workflow 只在人合并这个 PR 后才变化,必需检查照常运行。
没有这样确认过的任务不能改 .github/workflows/:Issue 开发和普通开发任务推送改到 workflow 的分支时,GitHub 拒绝发布;Manager 和其他角色的 github_write 也拒绝写这个目录。agent 会在任务里说明需要一个确认过的 CI 任务。
App 的 Workflows 权限仍然申请,只用于上面这类确认过的 CI 任务。安装没有授予时,确认过的 CI 任务也推不了改到 workflow 的分支,仓库列表的权限提示会写明「经确认的 CI 改动」受影响。
已经用 .github/ci-gates.json 和 scripts/gate/gate.mjs 配过门禁的仓库,这些文件归仓库自己维护,照常运行;已经开出的门禁 PR 也照常可以合并。「发版本」的预检仍读取它们。
4. 需要你亲手确认的事项
自动化到"PR 开出来"为止,CI 内容和开发授权仍留给人把关:
- 检视并合并改 CI 的 PR:PR 上的 Actions 跑过后再合入;是否在 Release workflow 里发布包或镜像由本仓库开发者决定;
- 确认私有仓快照是否可以公开:需要公开时,由超管在仓库列表开启看板;公开仓不需要这一步;
- 决定哪些 Issue 交给 bot 开发:能力上限含开发时,Manager 只在有依据时开发一个 Issue:有人加了开发标签(标签名在「基本设置 · 标签」查看和修改)、triage 以上权限的维护者在评论里提出,或者 Manager 提示词里的规则允许(接入向导确认的「简单问题」约定就是这样的规则);外人的评论不算;
- 打开分支保护和必需检查:bot 的 Manager 默认有 Contents 写权限,可以经
github_write合并 PR、写分支(包括默认分支),控制面不限制目标分支,也不替它跑合并前的校验,见角色池。所以请给默认分支打开分支保护(或规则集),把仓库的 CI 检查设为必需检查,启用 merge queue 时要求经队列合入;这样 bot 和人的合并都要先过这些检查。不希望 Manager 合并时,在「角色 → Manager」把 Contents 改成只读。
5. 接入之后会发生什么
你 push / 开 PR
└─ 仓库自己的 CI 运行
└─ 已验证 webhook → bot 后台采集 → 本地快照
└─ <公网入口地址>/boards/<owner>/<repo>/
- 检视:你开 PR 后 bot 会自动检视并评论;也可以在 Issue/PR 里 @ 它再检视一次;
- 开发:能力上限含开发时,Issue 有了开发依据(开发标签、维护者的评论或提示词里的规则),bot 会开分支改代码并回 PR;
- 看板:已验证 webhook 触发后台采集,单仓快照和 Dashboard 汇总一起更新,不再部署 Pages。
6. 常见问题
列表里"门禁未知"? 检查器会实时读你的仓库确认。出现未知通常是 App 没装到该仓库、或安装权限还没被批准。装/批之后点一次同步即可。
"单仓看板"报缺少权限? 看板采集仅使用源仓只读权限:Contents、Issues、Pull requests、Actions、Checks、Metadata。安装需要允许读取对应数据(没有 Checks 时定时运行的结果只从产物读取);不需要 Pages、Administration 或 Workflows 写权限。
单仓看板 CI 页的「定时运行」图怎样才有数据?
有定时触发(schedule)的 workflow 在默认分支上的运行(定时和手动触发都算)会被逐次读取,看板依次找:该运行检查套件里检查运行输出中的 Markdown 表格(例如测试报告类 action 写的检查结果),运行产物里的 JUnit XML 或简单 JSON({"metrics": [{"name": "tests", "value": 120, "unit": "count"}]}),都没有时只画运行和各 job 的耗时。表格的列、JUnit 的总数和 JSON 的名称都成为可选指标;每次运行最多读 3 个不超过 10 MiB 的产物。Actions 的 step summary($GITHUB_STEP_SUMMARY)GitHub 不经 API 提供,看板读不到。
私有仓库能接吗? 能。安装 App 不代表同意公开私有仓;超管在仓库列表开启看板后,快照才会公开,由 webhook 更新。无需配置额外 secret。
想撤销某个项目的接入? 控制台项目行的 删除 只清理本系统记录(仓库、策略、运行记录),不会卸载 App,也不会删除 GitHub 上的仓库。GitHub 侧请自行处理。
改 CI 的任务发布失败了怎么排查?
任务页写明原因和错误码。GitHub 拒绝推送改到 .github/workflows/ 的分支,通常是任务没有确认为 CI 改动,或 App 安装没有授予 Workflows 写权限。看板的问题(如 public_address_not_verified、collection_failed)显示在仓库列表的看板开关旁。