Keep Shipping documentation

How the Keep Shipping harness is put together: the site-file language, the command line, the ports and adapters, the diagnostics, and the decisions behind them.

Guides

• Agents: what the policy decides, and what it does not — A workflow file says what a coding agent may do alone, what waits for a named human, and what is refused outright. This page says exactly how that is decided, what a decide step sends and receives, an
• Architecture — Keep Shipping is a harness in the style of Factory Zero's Cratefield harness: a small Rust core, ports (traits), and adapters (the only vendor-aware code), composed at compile time.
• Step caching — Skip a step's work when the inputs provably have not changed (#43).
• Calibrating the decision models — A confidence is a claim about how often an answer is right. Nothing in the language, the engine or the CLI takes that claim on trust yet, and this is the document that says so out loud: no threshold i
• Running on any CI — keepshipping run works on a laptop and in a CI job, on any CI system that can run a binary (#130). Pass --ci and the run answers for the CI it is in, from the variables that CI exports:
• The keepshipping command line — keepshipping type-checks a site file and runs it. Two of the three subcommands are implemented end to end today; run is not.
• Clusters — Which cluster a run targets, and how it authenticates (#75).
• Running alongside an existing pipeline — Your repo already deploys. Keep Shipping is going to arrive next to it, one environment at a time, and the old pipeline keeps shipping until you say otherwise.
• Compatibility — The three contracts outside this repository depend on, and the number each is at. Each is bumped only for a breaking change.
• Per-step cloud credentials — A plan reads your cloud; an apply writes to it. Not the same permission, not the same step.
• Deploy verification — A deploy ships an image. The question this harness asks about that image is never "is it the right one" — the type system already pins that to a digest — but "is it signed by somebody we said it would
• Diagnostics: output formats, exit codes, colour — keepshipping check reports every problem it finds and never runs a step. Every finding carries a stable KSxxxx code — what each one means lives in ERRORS.md; this file pins how findings are printed.
• Early access — How Keep Shipping admits its first users: who goes in each batch, the one email they get, and what happens after they say yes.
• Editors — A site file is named ship.ks, or <something>.ship.ks. Every package here claims those two names and nothing else: .ks belongs to Red Hat/Fedora Kickstart (LANGUAGE.md, "File name and association"). Th
• Edit as code — The Keep Shipping console's forms write Terraform pull requests — never Cloudflare API calls. A signed-in person fills a plain-words form; the worker turns it into one additive HCL file in the infrast
• Error codes — Every diagnostic the ks parser and checker emit carries exactly one code, stable forever: tools and agents match on the code, not on the message. Codes are grouped by block — KS00xx syntax, KS01xx typ
• Getting started — From a fresh clone to a site file that checks, explains itself and gates CI. This walks the example service in examples/example-api/ from install to the policy a person would be held to — and stops wh
• GitHub Actions — Running a site file on GitHub Actions: a composite action that installs one pinned release and runs one command on it. GitHub Actions is the first native CI (ADR 0008); this covers the first of the fi
• GitHub approvals — How a run asks a team of people for permission on a pull request, and how the answer comes back. The adapter is ks-github (#96); it implements two ports from ks-core:
• GitLab CI — How a run identifies itself inside a GitLab pipeline, and how the pipeline hands the run off to a person. The adapter is GitlabCiRunContext (crates/cli/src/gitlab_ci_run_context.rs) (#131); it fills t
• Helm — ks-helm-cli implements the Cluster port by driving the helm CLI. There is no mature Helm implementation in Rust, so the adapter shells out — and it shells out to Helm, not to kubectl, because a chart
• Installing keepshipping — A release is four archives, a CycloneDX SBOM beside each of them, one signed checksum file and the signature on that. install.sh does the whole thing — download, verify, install — and it verifies befo
• Early-access interviews: the six questions that decide pricing, scope and the second CI — The waitlist collects an email and nothing else — no company size, no CI system, no IaC tool, no deploy target (ventures/keepshipping/README.md, "Answers fields … deferred"). That is why this file exi
• The Keep Shipping language — A site file is a line-oriented, indentation-scoped key: value entry tree. This document specifies what ks-lang parses; ks-core decides meaning. 0003 accepts this grammar, fixing the output and operato
• ship.lock — How a repository pins a block, what the lock records, and what check and run read (#81, decided by ADR 0011).
• Measuring the plan, without watching you — The plan is in the issues, starting with the master plan, #1. It has success metrics in it. This page says how each one gets measured, and — because the acceptance criterion is that no metric is publi
• Onboarding note: GETTING_STARTED.md — The record behind the acceptance criterion on #140 — "someone who hasn't seen the project completes it without help".
• Ports — A port is a trait a step asks for and never implements (ADR 0002): ks-core declares the traits in crates/core/src/ports/, an adapter crate outside this workspace is the only code that knows how to ans
• Data inventory: what the hosted service holds — Every field the hosted Keep Shipping service receives, why we hold it, how long we keep it, and how it is deleted. It covers three modules — the early-access waitlist, which is written and deployable
• Provenance: what a pushed image can say about itself — An image digest says what came out of the build. Provenance says what built it. The oci.image step attaches a statement to the digest it just signed (#114, ADR 0010): what is in it, where it ends up,
• Registries — Which OCI registries the Registry adapter (#60) has actually been run against, and what each one exercised.
• Reproducibility: what "the same digest" means — The site shows one sha256:… digest on the laptop and the same one on the CI runner. This page says exactly what that claim rests on today, and what is still to be built.
• Security model — What Keep Shipping defends, who it defends it from, which control covers which threat, and what is still open.
• Stale plans: apply stops and asks again — An approved infrastructure plan is applied exactly as approved, or the run stops and asks again. This page says exactly which kinds of change are caught, and — as important — which are not.
• Writing steps and adapters — A step is one StepKind implementation: a named, versioned unit of work with a declared input and output schema. An adapter is one port trait implementation: the only code in the workspace that knows h
• Built-in steps — Every step kind the harness ships, with its declared schema. Inputs are checked against the schema before the step runs; outputs, after.
• Telemetry — Keep Shipping ships no telemetry. There is no command that turns it on, no config key that enables it, and no outbound call that is not already in ADR 0005's exhaustive list of what leaves the runner.

Decisions

• ADR 0000: Record architecture decisions — Status: accepted, 2026-09-25
• ADR 0001: Typed values and secret references — Status: accepted, 2026-09-27
• ADR 0002: Ports and adapters — Status: accepted, 2026-10-06
• ADR 0003: Workflow syntax — Status: accepted, 2026-10-06
• ADR 0004: Secrets — Status: accepted, 2026-10-06
• ADR 0005: Local-first core with optional hosted services — Status: accepted, 2026-10-06
• ADR 0006: Licence and open-source model — Status: accepted, 2026-10-06
• ADR 0008: GitHub Actions first — Status: accepted, 2026-10-06
• ADR 0009: TypeScript escape-hatch runtime — Status: accepted, 2026-10-06
• ADR 0010: Image build backend — Status: proposed, 2026-10-06
• ADR 0011: Block distribution — Status: accepted, 2026-10-06
• ADR 0012: Policy authority — Status: proposed, 2026-10-07
• ADR 0013: Rust workspace — Status: accepted, 2026-10-06
• ADR 0014: Release and contract versioning — Status: accepted, 2026-10-07
• ADR 0015: Telemetry policy — Status: accepted, 2026-10-08
• ADR 0100: Step contract and composition checks — Status: accepted, 2026-09-26
• ADR 0200: Hosted venture on the Cratefield harness — Status: accepted, 2026-09-29
• ADR 0201: Hosted on Cloudflare — Status: proposed, 2026-10-08
• ADR 0202: Billing through Polar — Status: accepted, 2026-10-08
• Architecture decision records — Every architectural decision is an ADR in this directory: one file per decision, with Status, Context, Decision and Consequences sections. An ADR starts as a GitHub issue labelled adr; the accepted te

Research

• Competitive landscape — Internal research for #157, researched 2026-10-08. It records what each neighbouring tool is documented to do today, so any comparison we publish can be checked line by line against a source.