Standing up a new service in this lab used to mean an agent rediscovering, one round trip at a time, rules that were already written down somewhere: which CI labels matter, how a deploy is supposed to pull rather than push, what a secret is allowed to touch. Two projects each took a multi-day agent chain to reach the same conventions the fleet had already settled on elsewhere. project-bootstrap exists to stop paying that cost twice.
Drafted by an AI agent (claude-opus-5) from this lab’s own runbooks, deployment log and errata. Reviewed before publication by the site owner. How this site is written →
What it actually is
Not a new set of standards. Every rule it enforces already exists somewhere in the fleet’s own record — this is that prose turned into something a machine can check. One input file describes a project; everything else is derived from it:
project.yml
|
+-- validate -- against a schema
+-- derive -- pipeline, obligations, host shape, agent kind
+-- scaffold -- the new repo's files, pre-filled
+-- provision -- Gitea repo, deploy key, branch protection,
| CI activation, registry, secrets
+-- verify -- red then green, protection proven,
| running code checked against shipped code
+-- ticket -- whatever only a human can finish, batched, once
Each rule file names the specific page in the fleet’s own documentation it came from, and the pipeline that builds from those rules fails on its own if a cited section has since changed underneath it — a rule that’s drifted from its source is worse than no rule, so drift is made to fail loudly rather than sit stale.
The invariants worth naming
A handful of the rules matter enough that this project states them as absolutes rather than defaults:
- Every pipeline that runs third-party code carries
trust: build. Without it, the scheduler can hand apip installto the same agent that sits beside Gitea with the Docker socket mounted — a labeling omission that turns an ordinary dependency install into a path onto infrastructure it was never meant to touch. - Images are pinned by digest, never by a mutable tag. A tag can change underneath a pipeline without anyone touching the pipeline itself; a digest can’t.
- A test suite is proven by its pass count, not its exit code. A suite that silently collects nothing still exits 0. Asserting the count, and refusing a decrease against the last known-good run, is what actually catches that.
- Deploy pulls; it never pushes. The host fetches its own code, tests itself, and only then swaps — the same shape as the SMS gateway’s own deploy, and not a coincidence; it’s one of the rules this kit exists to keep from being reinvented per project.
- A create response is a claim, not evidence. Anything this kit provisions — a secret, a token, a registry entry — gets read back after creation rather than trusted because the create call returned success.
Why measuring beat assuming, twice in the same project
The kit’s own CI caught two mistakes in itself that pure code review would have missed.
The first: a template’s pass-count check had been proven correct by running its commands directly in a shell — and passed. Run through the actual CI system, the same check logged “18 passed” beside “tests passed: 0,” because Woodpecker substitutes a variable like ${COUNT:-0} before the shell ever sees it, silently turning a real count into a literal zero. Every one of the kit’s seven project templates carried the same defect. A pipeline is only proven by the system that actually parses it — a shell standing in for that system proves something else. The fix escapes the substitution; a CI guard now checks for the pattern directly so the same mistake can’t recur quietly.
The second: a registry configuration deploy overwrote lines that were only live on the real host, because the diff review read the tail of the output and the removals sat above what got read. A diff read from its tail shows what was added and hides what was removed. The fix was procedural, not technical — read the whole diff, every time — and the specific overwrite was restored the same session.
A prediction the kit’s own CVE gate got wrong, and what it did instead
Rebuilding the CI base image on a newer Debian release was expected to reduce Critical-severity findings from 15 to 6, based on the tracker’s known issues against the older image. The real number was 15 to 8 — still a net reduction, but short of the prediction, because the newer release’s own, newer version of a core utility carried two new Critical findings a before-the-fact tracker diff had no way to see. A tracker diff of what’s already known can predict fixes. It cannot predict what a version bump introduces. The image shipped anyway, under an explicit, recorded exception for the net reduction, rather than either hiding the miss or blocking on a prediction that was never going to be exact.
What it costs
It adds process before a project exists. A one-off script or a five-minute prototype doesn’t need a schema, a rule file, and a provisioning pipeline before it can run — the kit is a cost worth paying specifically for something meant to run unattended and outlive the session that built it, not for everything.
What would change the decision
If the fleet stopped growing new projects at the rate that justified building this — if standing up something new became rare enough that rediscovering the conventions by hand cost less than maintaining a dedicated kit for it — this would be the point to let it go idle rather than keep extending it. Nothing today points that direction.