镜像自 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 安装到你的账号/组织

管理面怎么登录

  1. 打开 https://agent-ci-infra-bot-admin.llmbots.co/ ;
  2. 如果出现 Cloudflare Access 的验证页,先填你的邮箱,收邮件验证码完成验证(这一步是网关鉴权,不是 bot 账号);
  3. 进入控制台登录页后,用管理员分配的用户名 + 密码登录;
  4. 首次部署时首页会显示「创建第一名管理员」,由部署者初始化,之后这里只提供登录。

登录后,系统超级管理员从顶部「全局设置」进入部署用的「接入向导」,在第三步配置 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)

按钮随你的情况变化:

2.5 完成页

方案应用完,页面变成完成页:

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 交付,由人检视、合并:

  1. 提出改动:接入向导的「CI 建议」一项确认后,会直接建这样一个任务;也可以由项目管理员在控制台「新建任务」里写明想要的 CI,例如 PR 上跑哪些检查、哪些放进定时运行;交付类型选「可检视的代码 PR」,勾选「允许修改 .github/workflows/(CI 改动)」。只有项目管理员能看到并勾选这一项。
  2. bot 按仓库实际情况改:任务和其他开发任务一样在项目电脑里工作。agent 读仓库已有的脚本、Makefile、构建文件和 workflow,改 workflow,跑项目的测试命令和独立 QA,再推送自己的 bot 分支、开 PR。推送时才向 GitHub App 申请 Workflows 写权限,前提是安装已授予。
  3. 人合并后才生效:默认分支上的 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 内容和开发授权仍留给人把关:

  1. 检视并合并改 CI 的 PR:PR 上的 Actions 跑过后再合入;是否在 Release workflow 里发布包或镜像由本仓库开发者决定;
  2. 确认私有仓快照是否可以公开:需要公开时,由超管在仓库列表开启看板;公开仓不需要这一步;
  3. 决定哪些 Issue 交给 bot 开发:能力上限含开发时,Manager 只在有依据时开发一个 Issue:有人加了开发标签(标签名在「基本设置 · 标签」查看和修改)、triage 以上权限的维护者在评论里提出,或者 Manager 提示词里的规则允许(接入向导确认的「简单问题」约定就是这样的规则);外人的评论不算;
  4. 打开分支保护和必需检查:bot 的 Manager 默认有 Contents 写权限,可以经 github_write 合并 PR、写分支(包括默认分支),控制面不限制目标分支,也不替它跑合并前的校验,见角色池。所以请给默认分支打开分支保护(或规则集),把仓库的 CI 检查设为必需检查,启用 merge queue 时要求经队列合入;这样 bot 和人的合并都要先过这些检查。不希望 Manager 合并时,在「角色 → Manager」把 Contents 改成只读。

5. 接入之后会发生什么

你 push / 开 PR
  └─ 仓库自己的 CI 运行
       └─ 已验证 webhook → bot 后台采集 → 本地快照
            └─ <公网入口地址>/boards/<owner>/<repo>/

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)显示在仓库列表的看板开关旁。