BuddingPlanted Tended 10 min read

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 里,靠「状态变更和外发消息同一个事务提交」把这些步骤串成一条不会丢步的链。

谁和谁说话

GitHub装在自己账号上的 App
webhook
kiln-serverPostgres 是唯一状态 · 只有它回写 GitHub
派活给主动来领的机器;发布产物
kiln-runner × NCI:主机 / Docker / BuildKit
kiln-orca × NAI:Orca + Codex / Claude Code
发布目标Release · npm · 镜像 · HTTP
构建机和 AI 机器都是主动连出去,所以可以放在家里或内网;GitHub App 私钥和发布凭据只在 Server 上,回写 GitHub 的也只有 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 #9Claude Code 写代码;Server 开 PR
09:44 之后19 个检查运行。AI 审计不通过:1 个中等问题,一个测试测不出它声称覆盖的错误Codex,发为 PR review
10:07第 1 轮返修:重写测试,贴出处置说明Claude Code
10:19 之前第二次审计通过;加上 kiln:mergeCodex;Server
10:19squash 合并为 11deef3,在它上面打 v1.0.3kiln-runner[bot]
10:20发布 Release v1.0.3(12 个 asset),关闭 Issue #2Server

PR #10 也是一轮返修(11:41 合并,v1.0.4);PR #11 一次通过审计(12:32 合并,v1.0.5)。从第一个 commit 到公开发布,三个分别用了 36、45 和 13 分钟。

CI 这一段:从 webhook 到绿色的 Check Run

接收验签 · 存事件 · 回 202
后台逐条处理
规划整个 job 图一次定好
依赖完成
算 action key所有输入的指纹
没命中缓存
领取同一事务:epoch+1 · 租约
心跳续约
Runner 执行只看得到 inputs 的文件
Complete
outbox写 Check Run
✓ 命中缓存:job 直接成功,不占 Runner
action key 是这条链上省时间的地方:输入没变的 job 不再执行。

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

从全部通过到发布

CI + AI 审计在 PR head 上
pr.verified:必需项全过
合并队列每个仓库一个执行者
合并,同一事务记下 tag
自动打 tag下一个 vX.Y.Z
直接规划这个 tag 的 run
发布 job在 Server 上执行
↺ 落后于目标分支:队列先更新分支,新 head 重新验证
唯一的回路是更新分支:落后的 PR 被队列更新后,必须在新 head 上再验证一遍才合并。

合并队列

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 开发

developing从任务池领取
Agent 交付
deliveringServer 核对
Server 推分支、开 PR
pr_open等 CI · 审计 · 合并
合并队列合入
merged
↺ 审计有问题 / CI 失败 / 冲突:fixing,同一个 PR 返修返修轮数用完:blocked,等人
工作项在 dev_work_items 里的状态(省略了终态 stopped 和 no_change)。同一个仓库一次只跑一个未结束的工作项;停在 pr_open 等待时不占节点容量。
  • 任务池。打开的、带 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;合并了却没记下 tagoutbox/,各领域共用
job 和任务的每次写入都带 epoch丢了租约的 Runner 覆盖新一次 attempt 的结果ci/engine/engine.go:569、ai/lease.go:21
每个对象一个执行者,每次按最新状态判断两个进程合并、打 tag 同一个东西;按过期的读结果行事mergequeue/process.go:43、autotag/autotag.go:315
没有幂等键的写操作先记意图,绝不盲目重试响应丢失后重复评论、重复 review、重复关 Issuemergequeue/closeissues.go:180、ai/review/publish.go:124

还有一条范围更窄的:构建机和 AI 机器上都不存 git 凭据。每次 clone、fetch、push 都向 Server 要一枚只覆盖一个仓库的 token,操作结束或 attempt 结束时由 Server 吊销(gitcred/)。

你要配置的东西

文件或标签管什么从哪读
.kiln/workflows/*.ymljob、矩阵、容器、services、发布目标正在构建的 commit
.kiln/runtimes.lockGo、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 日志不对外公开。