Pipelines and gates

A pipeline is an optional file that lists a work item's stages in order; a gate is a pause in that path where a person decides before the work goes on.

#When to use a pipeline

Without a pipeline, the foreman builds a path for each work item (see How Kiln works). Add a pipeline when your team wants the same stages every time, a gate in a specific place, or loop limits you choose.

A work item uses a pipeline when factory.yaml sets defaultPipeline: <name>, or when the work item is created with a pipeline name.

#A pipeline file

# pipelines/feature.yaml
stages:
  - { id: triage,  agent: triage }
  - { id: spec,    agent: spec, skip_if: "triage.size in ['xs','s']", gate: spec-approval }
  - { id: build,   agent: implement, fan_out: per_user_story }
  - { id: verify,  agent: verify, requires: [ci_green, criteria_videos], on_fail: build, max_loops: 3 }
  - { id: preview, action: preview.deploy, gate: preview-acceptance }
  - { id: review,  agent: review }
  - { id: handoff, action: handoff }   # people merge through branch protection

#Stage keys

#What each stage does

A stage's behavior comes from its agent's agentType or its action:

#requires

When a stage fails, Kiln goes back to on_fail. After max_loops failures, or when the stage has no on_fail, Kiln opens a <stage>-stuck question and parks the item as blocked. The exception is a review stage with advisory: true: it posts its findings on the pull request and continues to hand-off instead of parking. Answering the question resets the loop counters and retries the stage that stopped; rejecting it cancels the item.

#Expressions in skip_if

skip_if reads these fields:

#Gates

A gate pauses a work item until someone decides. Gate files live in gates/<name>.yaml.

# gates/spec-approval.yaml
kind: approval
approvers: [requester, role:po]
evidence: [spec, open_questions]
nudge: 24h
expire: 72h -> park

#Built-in gates

You can use these names without a file. A file with the same name replaces the built-in one.

The foreman's default path uses spec-approval and preview-acceptance. Hand-off always opens a merge gate.

#Deciding a gate

A gate can be approved or rejected from the inbox, a reply in the source thread, the API or the Kiln MCP. All of them use the same code path and record who decided and through which surface. A reply in a Slack thread or on an issue or pull request decides a gate only when its author is one of the gate's assignees, or the gate has none. See Who may decide from a reply. Only question gates take free-text answers.

When a gate expires with park, it closes as expired and the item moves to blocked. A message on a blocked item with nothing left open (for example, a follow-up after its question expired) resumes it at the stage that stopped. The task page also shows why it stopped, with a Retry button that restarts it there without a message.

Runs live in the API process, so a restart (for example a deploy) cuts off whatever was running. On startup Kiln stops those runs as blocked, closes the command questions they were waiting on, and moves their tasks to blocked with the reason "Kiln restarted while this task was working". Retry, or a message, continues the task; a follow-up continues the run.

A person who cancels, interrupts or pauses a stage's run stops the task too: it moves to blocked with the reason " was stopped (cancelled) in ", and Kiln does not count it as the agent failing, start the agent again or open a question gate. Retry, or a message, continues it. Cancelling the task itself stops its runs and cancels it without opening a gate. A cancel also works while a run waits to retry after a platform error: the run ends as cancelled without another attempt.

A follow-up on a finished run starts one continuation. Further follow-ups on that run, while the continuation is starting or going, steer it instead of starting more runs on the same branch; a follow-up sent while a run waits to retry reaches its next attempt.

#Related pages

• How Kiln works
• Typed decisions
• Policies and budgets
• Approving specs and previews
• Inbox