How Kiln turns an issue into a release
Reading the source of Kiln (kilnflow.dev): how an issue labelled kiln:ready goes through AI development, an independent review by a second agent, Kiln's own merge queue and auto-tagging, and is published by the server with no human step.
中文版:Kiln 怎么把一个 Issue 自动变成一次发布 · Companion post: How kiln-orca runs Kiln's work through agents in Orca
Kiln is a self-hosted CI. One small server keeps all state in Postgres; build machines and AI machines connect out to it to pick up work. With the optional AI nodes attached, a GitHub issue labelled kiln:ready is designed and coded by an AI, reviewed by a different agent, then merged, tagged and released, with no human clicking anything in between.
This post follows that path through the code. I read commit e3bff51, source only: nothing was built or run. File paths are relative to internal/server/ unless stated otherwise.
In one sentence: GitHub only sends events and receives results; deciding, scheduling, merging, tagging and publishing all happen in Kiln's server, chained together by one habit: every state change commits in the same transaction as the message it causes.
Who talks to whom
Inside the server, CI and AI are separate domains with different tables, schedulers and wire protocols (runner.v1 and airunner.v2). They meet only in the assembly file server.go, through narrow interfaces, or through events in a shared outbox table. internal/archtest fails the tests if one domain imports another or queries its tables, so the boundary is checked by a machine, not just described in a doc.
One real pass through the loop
Kiln builds itself with Kiln. On 22 November 2026, the day after it was open-sourced, three i18n issues labelled kiln:ready went through the whole chain. Times are UTC, from commit and tag metadata; review outcomes are from the PR pages.
| Time | What happened | Who |
|---|---|---|
| 09:44 | Pushed to kiln/dev-6 for issue #2; PR #9 opened | Claude Code writes; server opens the PR |
| after 09:44 | 19 checks run. AI review fails: one medium finding, a test that could not catch the bug it claimed to cover | Codex, as a PR review |
| 10:07 | Repair round 1: test rewritten, disposition comment posted | Claude Code |
| before 10:19 | Second review passes; kiln:merge added | Codex; server |
| 10:19 | Squash-merged as 11deef3; tag v1.0.3 created on it | kiln-runner[bot] |
| 10:20 | Release v1.0.3 published (12 assets); issue #2 closed | server |
PR #10 also took one repair round (merged 11:41, v1.0.4); PR #11 passed review first time (merged 12:32, v1.0.5). From first commit to public release: 36, 45 and 13 minutes.
The CI part: from webhook to a green Check Run
1. Intake: verify, store, answer
GitHub posts the event to /webhook. The handler checks the HMAC-SHA256 signature with a constant-time comparison, stores the event in events keyed by delivery id, and returns 202. Nothing else happens in the request.
A background loop then processes stored events one by one. Installations from accounts outside KILN_ALLOWED_ACCOUNTS are rejected and uninstalled; pull requests from forks are always dropped, with no switch to allow them; an event already superseded by a newer one for the same ref is skipped.
ingest/webhook.go:35 · ingest/event.go:159 · ingest/push.go:308
2. Plan: the job graph is fixed before anything runs
The planner reads .kiln/workflows/*.yml at the commit being built. For a PR that is the head commit, not a merge with the target branch. The syntax follows GitHub Actions minus uses:; expressions can only reference values known at planning time, so matrices, if: and needs are fully expanded here.
The run, its jobs, concurrency-group membership and the first Check Run records are written in one transaction. A broken workflow still produces a run, marked failed immediately, so the commit shows a red check carrying the error.
ci/planner/planner.go:234,342 · internal/workflow/
3. Don't build what was already built
When a job's dependencies finish, the engine hashes everything that can affect it into an action key: the digest of its input files, env, steps, image digest, runtime digests, upstream output digests. Secrets count by name only.
If action_cache has the key, the job succeeds without touching a runner; if an identical job is already running, this one follows its result. That is why Kiln's own workflow keeps the version-stamped build in a separate job: after merge, the tests keep the same key and are not rerun.
ci/engine/engine.go:205,372
4. Acquire: claim, epoch+1 and lease in one transaction
Runners hold a long-poll Acquire open. The scheduler locks the runner's row, takes up to 300 candidate jobs with FOR UPDATE SKIP LOCKED in priority-then-age order, and filters by platform, pool, executor, declared CPU and memory (against that machine's free capacity) and per-repo concurrency limits.
The chosen job becomes running, its epoch increments, an attempt row is inserted and a lease is set, in that same transaction. Every later write from the runner must carry the matching epoch, so a runner that lost its lease can never overwrite a newer attempt.
ci/scheduler/reserve.go:211,730 · ci/runnerapi/scheduler.go:140
5. Execute on the runner
The runner checks out only the files the job's inputs match, with no .git; installs Go, Node and pnpm verified against digests in .kiln/runtimes.lock; pulls upstream outputs from the content-addressed store; and runs steps on the host or in a container. Container jobs default to --network none.
Source is fetched with a token the server issues for that one fetch, scoped to that one repository, and revokes afterwards. Secrets arrive over RPC, live only in step environment variables, and are masked in logs in raw, base64 and URL-encoded form.
Heartbeats every few seconds renew the lease and carry cancellation back. Outputs go to presigned upload URLs, and Complete ends the attempt and writes the cache entry.
internal/runner/execute.go:61 · internal/runner/source.go:178 · ci/runnerapi/runnerapi.go:392
6. Report through the outbox
Each state change writes an outbox row in the same transaction. The row holds only an id, so several changes collapse into one pending delivery. A worker turns rows into Check Runs, looking up by external id before creating, with exponential backoff and a dead-letter state after 20 tries.
When the last job of a PR's run finishes, the engine emits pr.verified. The merge queue and AI development both wait on that one event.
outbox/worker.go:86 · ci/cicheck/checkrun.go:40 · server.go:390
From green checks to a release
Merge queue
Kiln uses neither GitHub's merge queue nor branch protection. A PR enters the queue when someone adds kiln:merge, or automatically once every entry under required has passed, if .kiln/merge.yml on the default branch sets auto: true. That config is read only from the default branch, so a PR cannot lower its own bar.
Each repository has one executor, holding a Postgres advisory lock. Every pass re-reads the PR from GitHub and decides from scratch: wait, update the branch, merge, or remove it with a reason. The merge request carries the head SHA it verified, and GitHub refuses if the head has moved.
mergequeue/process.go:46,894 · mergequeue/decide.go:208 · mergequeue/autoenqueue.go:85
Auto-tag and publish
The merge, the queue-entry update and a tag record commit together. The tag worker reads existing tags, picks the next version (patch by default; release:minor, release:major and release:skip labels change that), creates the ref, then calls the CI planner directly to plan a push run for the tag.
A job with a release: block has no steps and never reaches a runner. The server stages every target first (npm integrity check, image layers pushed by digest, a draft GitHub Release), passes a last cancel point, then commits in the order npm, image tags, HTTP uploads, GitHub Release. On a rerun, identical content already on a target counts as success.
autotag/autotag.go:315,684,932 · ci/publish/job.go:52 · ci/publish/targets.go:44
The AI loop on top
An AI node is a machine with the Orca desktop app and the kiln-orca connector. Its role, review or development, is fixed by its enrolment token. The connector takes a task, starts a coding agent in a fresh Orca worktree, and hands the result back. The agent's only way to talk to Kiln is the kiln-orca task command; the companion post covers that side.
Independent review
Opening or pushing to a PR plans a review request alongside the CI runs. The review brief, .kiln/agent/review.md, is read from the PR's base, so a PR cannot rewrite its own review standard. The agent must return a strict JSON report; only "no issues" passes. The result is posted as a PR review and as the ai-review check.
The server records which agents worked on each development item and refuses to give the review to any of them: checked once when planning and again when a node tries to take the task. Kiln's own config has Claude Code developing and Codex reviewing.
The review brief requires mutation checks: break the changed logic in a scratch copy and confirm a test fails. Both failed reviews in the table above were of that kind.
ai/review/plan.go:135,568 · ai/review/tasktype.go:104,178 · ai/review/publish.go:124
Development from an issue
- Pool. Open issues carrying
kiln:readyare mirrored intodev_poolfrom Issues webhooks. - Select and claim. A development node is offered the candidates, picks a batch that fits one PR, and claims it; the server re-reads each issue from GitHub before accepting.
- Deliver. The agent designs and implements in one run and pushes to a throwaway
kiln/attempt-<id>branch. If it judges one PR is not enough, it first delivers a Markdown-only design PR; the server starts implementation automatically once that merges. - Promote. The server checks the delivery, fast-forwards the formal branch
kiln/dev-<item>with a short-lived token of its own, and opens the PR itself. Agent-written titles and bodies are defused so they cannot mention people or close unrelated issues. - Hold. Deliveries that touch
.kiln/,.github/,AGENTS.md,CLAUDE.md,.claude/or.codex/, exceed 300 files or 100 commits, or declare a change to one of the project's 23 confirmed decisions getkiln:holdand wait for a person. - Repair. Review findings, real CI failures and merge conflicts each send the same item back for another round on the same PR, up to
max_fix_rounds(10 in Kiln's own config).
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
Four rules that keep it consistent
| Rule | What it prevents | Where |
|---|---|---|
| A state change and its outbound message commit together | A green job with no Check Run; a merge with no tag record | outbox/, shared by all domains |
| Every job and task write carries the epoch | A runner that lost its lease overwriting a newer attempt | ci/engine/engine.go:569, ai/lease.go:21 |
| One executor per object, deciding from fresh state | Two processes merging or tagging the same thing; acting on stale reads | mergequeue/process.go:43, autotag/autotag.go:315 |
| Writes without an idempotency key record intent first and are never blindly retried | Duplicate comments, reviews or issue closures after a lost response | mergequeue/closeissues.go:180, ai/review/publish.go:124 |
A fifth, narrower rule: no build or AI machine stores a git credential. Each clone, fetch or push asks the server for a token scoped to one repository, and the server revokes it when the operation or the attempt ends (gitcred/).
What you configure
| File or label | Controls | Read from |
|---|---|---|
.kiln/workflows/*.yml | Jobs, matrices, containers, services, release targets | The commit being built |
.kiln/runtimes.lock | Go, Node, pnpm, Bun versions and per-platform digests | The commit being built |
.kiln/merge.yml | Merge method, required checks, auto-enqueue, tag rule, allowed target branches | Default branch only |
.kiln/agent/config.yml | Who reviews, who develops, platforms, timeouts, repair rounds | Review: PR head; development: default branch |
review.md / development.md | The briefs given to the two agents | PR base / default branch |
kiln:ready / kiln:skip | Put an issue into / keep it out of the AI task pool | Issue |
kiln:merge / kiln:hold | Enter the merge queue / block auto-enqueue | PR |
release:minor / major / skip | Version bump for the tag created after merge | PR, frozen at merge |
Secrets, variables and environments are stored in Kiln, encrypted with the server's master key, not in GitHub settings. Logs, artifacts and caches are kept for 12 hours; only results are kept long-term.
What I took away
I read six subsystems in depth and found no high-severity defects; what is worth fixing clusters around the things the design assumes are friendly. For example: when a missed webhook is recovered by reconciliation, the push loses its "was this a bot" flag, so a third-party bot's tag can still publish; the write token a development node can get covers the whole repository; and kiln:ready approves an issue number, not its text, so an edited issue body is what the agent builds. Each of these only matters once the trust boundary widens: a third-party bot with push access, a prompt-injected agent, a malicious dependency.
The bigger risks are not in the code: there is a single human maintainer, the design docs live in a private Outline, and CI logs are not public.