Chain file keys
read_only
How read_only makes Kraft verify that a step, node or recovery plan leaves the checkout as it found it, and what happens when it doesn't.
read_only goes on a step, an exec node or an on_failure plan, never on a
task. A task that sets it is refused at load. On a plan, it makes every step of
the plan read_only, the one a tasks plan becomes included.
- What is checked. Before a read_only step's first task launches, Kraft
records each repository of the checkout (the root and every workspace member):
HEAD,git status --porcelain=v1 -z(ignored files stay out), and a hash ofgit diff HEAD. It reads them again after the last task exits. A read_only node does the same around all of its steps. - What counts as a change. Any difference, including an untracked file or a commit.
- What happens. The item stops and waits for you, with a
read_only_violatedevent and a stop reason naming the changed files. It isn't a task failure, so no recovery, fix loop or attempt is spent on it. - Exclusions. A read_only step's check doesn't cover a recovery or a fix
loop. It runs again when a recovery retries the step's tasks. An
on_failureplan, or a step in it, may be read_only, and is then checked around its own tasks. Afix_loop, anon_conflictand anon_merge_rejectedrepair write by design, and refuseread_only. - What the agent is told. An agent task in a read_only step, or in one of a read_only node's own steps, gets the read-only contract (change, write and commit nothing, run no tests) instead of the one that says to run tests and commit. A task in a handler of a read_only node doesn't, as the node's check doesn't cover it.
- Sandboxed items. In a sandboxed item, if the worktree gains a repository Kraft didn't create, Kraft runs no host git there and reports that repository as the change.
- Default. Off. The shipped chains set it on
verification.reviewandreview_feedback. Setting it on both a node and its steps is allowed and redundant.
Waiting for a pipeline by ID
How a ci.pipeline task waits for one CI pipeline named by its ID, what each pipeline state makes the task do, and what it never does.
Step outputs
How a task leaves files and variables for a later task, how the reader names the writer, and when Kraft checks and deletes them.