Kiln 怎么把一个 Issue 自动变成一次发布
读 Kiln(kilnflow.dev)的源码:一个打了 kiln:ready 的 Issue,怎样经过 AI 开发、另一个 Agent 的独立审计、自建的合并队列、自动打 tag,最后由 Server 发布,中间没有人参与。
English version: How Kiln turns an issue into a release · 姊妹篇:kiln-orca 怎么让 Orca 里的 Agent 干 Kiln 的活
Kiln 是一套自托管的 CI:一台小 Server 把全部状态放在 Postgres 里,构建机和 AI 执行机都从自己那边连过来领活。接上可选的 AI 节点之后,一个打了 kiln:ready 标签的 GitHub Issue 会被 AI 设计、写代码、由另一个 Agent 审计,然后合并、打 tag、发布,中间不需要人点任何按钮。
这篇顺着这条路读它的代码。我读的是 commit e3bff51,只读源码,没有构建,也没有运行。下文的文件路径如无说明,都相对于 internal/server/。
一句话:GitHub 只管发事件和收结果;判断、调度、合并、打 tag、发布全在 Kiln 的 Server 里,靠「状态变更和外发消息同一个事务提交」把这些步骤串成一条不会丢步的链。
谁和谁说话
Server 里 CI 和 AI 是两个分开的领域:表、调度器、通信协议(runner.v1 和 airunner.v2)都不同。它们只在组装文件 server.go 里通过窄接口接线,或者经由共用的 outbox 表传事件。internal/archtest 会在一个领域直接 import 另一个领域、或查询别人的表时让测试失败,这条边界是机器检查的,不只是写在文档里。
一次真实的流转
Kiln 用 Kiln 构建自己。2026 年 11 月 22 日,也就是开源后的第二天,三个打了 kiln:ready 的 i18n Issue 走完了整条链。下面的时间是 UTC,取自 commit 和 tag 的元数据;审计结果来自 PR 页面。
| 时间 | 发生了什么 | 谁做的 |
|---|---|---|
| 09:44 | 为 Issue #2 推到 kiln/dev-6,开出 PR #9 | Claude Code 写代码;Server 开 PR |
| 09:44 之后 | 19 个检查运行。AI 审计不通过:1 个中等问题,一个测试测不出它声称覆盖的错误 | Codex,发为 PR review |
| 10:07 | 第 1 轮返修:重写测试,贴出处置说明 | Claude Code |
| 10:19 之前 | 第二次审计通过;加上 kiln:merge | Codex;Server |
| 10:19 | squash 合并为 11deef3,在它上面打 v1.0.3 | kiln-runner[bot] |
| 10:20 | 发布 Release v1.0.3(12 个 asset),关闭 Issue #2 | Server |
PR #10 也是一轮返修(11:41 合并,v1.0.4);PR #11 一次通过审计(12:32 合并,v1.0.5)。从第一个 commit 到公开发布,三个分别用了 36、45 和 13 分钟。
CI 这一段:从 webhook 到绿色的 Check Run
1. 接收:验签、存下、立刻回
GitHub 把事件 POST 到 /webhook。处理函数用常数时间比较校验 HMAC-SHA256 签名,按 delivery id 去重存进 events 表,然后返回 202,请求里不做别的事。
一个后台循环再逐条处理存下的事件:不在 KILN_ALLOWED_ACCOUNTS 里的账号的安装会被拒绝并卸载;来自 fork 的 PR 一律丢弃,没有开关;同一个 ref 已经有更新事件的旧事件直接跳过。
ingest/webhook.go:35 · ingest/event.go:159 · ingest/push.go:308
2. 规划:执行之前,job 图就全定了
Planner 按要构建的那个 commit 读 .kiln/workflows/*.yml。PR 构建的是 head commit,不是和目标分支的合并提交。语法沿用 GitHub Actions,但不支持 uses:;表达式只能引用规划时就知道的值,所以矩阵、if:、needs 在这一步全部展开。
run、job、并发组和第一批 Check Run 记录在同一个事务里写入。workflow 写错了也会建出 run,只是直接标为失败,commit 上会出现一个带错误信息的红色检查。
ci/planner/planner.go:234,342 · internal/workflow/
3. 已经构建过的不再构建
一个 job 的依赖全部完成时,engine 把会影响它的一切算成 action key:inputs 文件的摘要、env、steps、镜像 digest、runtime digest、上游输出的摘要。secret 只以名字计入。
action_cache 里有这个 key,job 就直接成功,不碰 Runner;有一个 key 相同、正在执行的 job,这个 job 就跟着它的结果走。所以 Kiln 自己的 workflow 把带版本号的构建单独放成一个 job:合并之后测试的 key 不变,不用重跑。
ci/engine/engine.go:205,372
4. 领取:选中、epoch+1、租约,一个事务
Runner 保持一个长轮询的 Acquire。调度器锁住这台 Runner 的行,用 FOR UPDATE SKIP LOCKED 按优先级和先后取最多 300 个候选 job,再按平台、pool、执行器、声明的 CPU 和内存(对照这台机器的剩余容量)以及仓库的并发上限筛选。
选中的 job 在同一个事务里变成 running、epoch 加一、插入 attempt、设好租约。Runner 之后的每次写入都要带上匹配的 epoch,所以一台丢了租约的 Runner 不可能覆盖新一次 attempt 的结果。
ci/scheduler/reserve.go:211,730 · ci/runnerapi/scheduler.go:140
5. 在 Runner 上执行
Runner 只检出 job 的 inputs 匹配到的文件,没有 .git;按 .kiln/runtimes.lock 的摘要安装并校验 Go、Node、pnpm;从内容寻址存储取上游 job 的输出;在主机上或容器里运行 steps。容器 job 默认 --network none。
拉源码用的 token 是 Server 为这一次 fetch 单独签发的、只覆盖这一个仓库,fetch 完就吊销。secret 经 RPC 下发,只放在 step 的环境变量里,日志中的原文、base64 和 URL 编码形式都会被遮掉。
每隔几秒的心跳续租约,也把取消请求带回来。输出上传到预签名的地址,最后 Complete 结束 attempt 并写缓存。
internal/runner/execute.go:61 · internal/runner/source.go:178 · ci/runnerapi/runnerapi.go:392
6. 经 outbox 回报
每次状态变更都在同一个事务里写一条 outbox 记录。记录里只有一个 id,所以连续几次变更会合成一次待投递。worker 把它变成 Check Run:先按 external id 查找再创建,指数退避,失败 20 次进死信。
一个 PR 的 run 最后一个 job 结束时,engine 发出 pr.verified。合并队列和 AI 开发都在等这一个事件。
outbox/worker.go:86 · ci/cicheck/checkrun.go:40 · server.go:390
从全部通过到发布
合并队列
Kiln 不用 GitHub 的 merge queue,也不需要分支保护。PR 有人加上 kiln:merge 就入队;默认分支上的 .kiln/merge.yml 写了 auto: true 时,required 里的每一项都通过后自动入队。这个配置只从默认分支读,PR 改不了自己的合并门槛。
每个仓库只有一个执行者,持有 Postgres 的 advisory lock。每一轮都重新从 GitHub 读 PR,从头判断:等、更新分支、合并,或者带着原因移出队列。合并请求带上它验证过的 head SHA,head 变了 GitHub 会拒绝。
mergequeue/process.go:46,894 · mergequeue/decide.go:208 · mergequeue/autoenqueue.go:85
自动打 tag 与发布
合并、队列条目的更新和一条 tag 记录在同一个事务里提交。tag worker 读出已有的 tag,算出下一个版本(默认升补丁号;release:minor、release:major、release:skip 标签改变规则),创建 ref,然后直接调用 CI 的 planner 为这个 tag 规划一次 push run。
写了 release: 的 job 没有 steps,不会到 Runner 上。Server 先把所有目标暂存好(npm 核对 integrity、镜像按 digest 推层、GitHub Release 建成草稿),过了最后一个可取消点后,按 npm、镜像 tag、HTTP 上传、GitHub Release 的顺序正式发布。重跑时,目标上已有相同内容就算成功。
autotag/autotag.go:315,684,932 · ci/publish/job.go:52 · ci/publish/targets.go:44
叠在上面的 AI 循环
AI 执行节点是一台装了 Orca 桌面版和连接器 kiln-orca 的机器,角色(审计或开发)在注册时由令牌决定。连接器领一个任务,在新的 Orca 工作区里启动编程 Agent,再把结果交回。Agent 和 Kiln 打交道只有一个入口:kiln-orca task 命令。
独立审计
PR 打开或推送时,和 CI run 一起规划一个审计请求。审计说明 .kiln/agent/review.md 从 PR 的 base 读,PR 改不了自己的审计标准。Agent 必须交回格式严格的 JSON 报告,只有「没有问题」才算通过;结果发为 PR review 和 ai-review 检查。
Server 记下每个开发工作项用过哪些 Agent,审计时拒绝派给其中任何一个:规划时检查一次,节点来领任务时再检查一次。Kiln 自己的配置是 Claude Code 开发、Codex 审计。
审计说明要求做变异验证:在临时副本里把改动的关键逻辑改坏,确认测试会失败。上面表格里两次审计不通过,都是这一类问题。
ai/review/plan.go:135,568 · ai/review/tasktype.go:104,178 · ai/review/publish.go:124
从 Issue 开发
- 任务池。打开的、带
kiln:ready的 Issue 经 Issues webhook 同步进dev_pool。 - 选题和领取。开发节点拿到候选,挑一批适合放进一个 PR 的领取;Server 在接受前从 GitHub 重新读一遍每个 Issue。
- 交付。Agent 在一次执行里先设计再实现,推到一次性的
kiln/attempt-<id>分支。判断一个 PR 做不完时,先交付只改 Markdown 的设计 PR,合并后 Server 自动开始实现。 - 推进。Server 核对交付,用自己签发的短期 token 把正式分支
kiln/dev-<工作项>快进过去,由自己开 PR。Agent 写的标题和正文会被处理,不能 @ 人,也不能顺手关掉别的 Issue。 - 暂停。改动了
.kiln/、.github/、AGENTS.md、CLAUDE.md、.claude/、.codex/,超过 300 个文件或 100 个 commit,或者声明要改项目 23 条已确认决定之一的交付,加kiln:hold等人确认。 - 返修。审计 finding、真实的 CI 失败、合并冲突,都把同一个工作项送回再做一轮,在同一个 PR 上,最多
max_fix_rounds轮(Kiln 自己配的是 10)。
ai/aidev/pool.go:49 · ai/aidev/claim.go:84 · ai/aidev/executor.go:224,627 · ai/aidev/fix.go:162 · ai/aidev/state.go:14
让它不出错的四条规则
| 规则 | 防的是什么 | 在哪 |
|---|---|---|
| 状态变更和外发消息同一个事务提交 | job 绿了却没有 Check Run;合并了却没记下 tag | outbox/,各领域共用 |
| job 和任务的每次写入都带 epoch | 丢了租约的 Runner 覆盖新一次 attempt 的结果 | ci/engine/engine.go:569、ai/lease.go:21 |
| 每个对象一个执行者,每次按最新状态判断 | 两个进程合并、打 tag 同一个东西;按过期的读结果行事 | mergequeue/process.go:43、autotag/autotag.go:315 |
| 没有幂等键的写操作先记意图,绝不盲目重试 | 响应丢失后重复评论、重复 review、重复关 Issue | mergequeue/closeissues.go:180、ai/review/publish.go:124 |
还有一条范围更窄的:构建机和 AI 机器上都不存 git 凭据。每次 clone、fetch、push 都向 Server 要一枚只覆盖一个仓库的 token,操作结束或 attempt 结束时由 Server 吊销(gitcred/)。
你要配置的东西
| 文件或标签 | 管什么 | 从哪读 |
|---|---|---|
.kiln/workflows/*.yml | job、矩阵、容器、services、发布目标 | 正在构建的 commit |
.kiln/runtimes.lock | Go、Node、pnpm、Bun 的版本和各平台摘要 | 正在构建的 commit |
.kiln/merge.yml | 合并方式、必需检查、自动入队、打 tag 规则、允许的目标分支 | 只从默认分支 |
.kiln/agent/config.yml | 谁审计、谁开发、平台、超时、返修轮数 | 审计:PR head;开发:默认分支 |
review.md / development.md | 给两个 Agent 的说明 | PR base / 默认分支 |
kiln:ready / kiln:skip | 把 Issue 放进 / 排除出 AI 任务池 | Issue |
kiln:merge / kiln:hold | 进入合并队列 / 不自动入队 | PR |
release:minor / major / skip | 合并后打 tag 时怎么升版本 | PR,合并时冻结 |
secret、变量和 environment 都存在 Kiln 里,用 Server 的主密钥加密,不放在 GitHub Settings。日志、产物和缓存只保留 12 小时,长期只留结果。
读完的几点看法
我把六个子系统各读了一遍,没有找到高危问题;值得改的地方集中在设计上默认可信的那些对象。例如:漏掉 webhook 后补对账时,push 不再带「是不是 Bot」的标记,第三方 Bot 推的 tag 可能照常发布;开发节点拿到的写权限 token 覆盖整个仓库;kiln:ready 批准的是 Issue 编号而不是正文,之后改了正文,Agent 照新内容做。这些都只在信任边界被拉宽时才要紧(第三方 Bot 有推送权限、Agent 被提示注入、依赖里混进恶意代码)。
更大的风险不在代码里:只有一位人类维护者,设计文档在私有的 Outline 里,CI 日志不对外公开。