chadtmiller.com/knotless

Switch repository

Loading…

Where it stands

The model already supports bring-your-own runners. Any account can run knotless-run, watch any public repository, and write dev.knotless.check records in its own account. The owner opts in with knotless runners <url> add <handle> and readers only show checks from named runners. Executors (docker, shell), per-runner secrets with ref scoping, --pulls, reruns, caches, cancellation and crash recovery all work, and knotless.dev itself runs this way.

What's missing is packaging and a path for someone who isn't running knotless-serve on their own host.

Gaps

1. Not distributed. deploy/release.sh only builds knotless, git-remote-knotless and knotless-mcp, so install.sh never installs knotless-run. The knotless:current image is built on the host by deploy.sh and not published. Today the only route is cloning and cargo install --path crates/knotless-run.
2. Only one deployment is documented: beside knotless-serve via deploy.sh and compose. Nothing for a standalone box, homelab, or laptop (docker run, systemd).
3. Docs are scattered across the README, deploy/README.md, docs/design.md, and the MCP server's instructions. There's no workflow reference: cache, image, .json workflow files, name rules (1 to 64 of [A-Za-z0-9_-]), default on, and the KNOTLESS_RUN_* variables aren't in the README.
4. Undocumented setup details: that knotless login works as well as an app password; that --pulls needs KNOTLESS_APPVIEW (e.g. https://knotless.dev); the binary's default Jetstream (jetstream2.us-east) differs from compose's (jetstream.us-east); --state/--work defaults; --jobs, --cache-max, --image aren't mentioned.
5. Private repositories can't be watched. Runner::start fails with "no public repository by that name" for spaces, even if the runner's account is a member.
6. Watched repos are fixed at startup. Adding one means a restart.
7. Isolation: docker socket only, no rootless/podman notes, and step containers have no CPU/memory limits beyond --step-timeout.

Plan

Make it happen (P1)

• Add knotless-run to the release tarballs (Linux musl only, or all four targets) and to install.sh.
• Publish an image, or add a slim runner target to the Dockerfile with just knotless-run, git and the docker CLI.
• Write docs/runners.md (outline below) and link it from the README Workflows section.
• Ship deploy/runner/ with a systemd unit and a standalone compose file.

Follow-ups (P2)

• --repos-file with reload on SIGHUP, or discover repos whose record names this runner's DID via the appview.
• Watch private repos when the runner is a member of the space.
• --cpus / --memory flags passed to step containers.
• knotless runners add warns when the named account has never written a check for the repo.

docs/runners.md outline

1. How runners work: owner names the runner, checks live in the runner's account, Jetstream is only a doorbell, the ref is read from the owner's PDS.
2. Make an account for the runner (separate handle recommended); app password or knotless login.
3. Install: release, cargo, or docker.
4. Run it: minimal command, then a flags table with defaults.
5. Name it: knotless runners <url> add <handle>, verify with knotless checks <url> --wait 300.
6. Secrets file format, including refs scoping and log masking.
7. Pulls: --pulls, KNOTLESS_APPVIEW, docker only, never secrets, separate caches.
8. Running as a service: systemd, compose, stop grace period vs --step-timeout.
9. Security: docker socket is root on the host; shell executor for trusted repos only; pull code is untrusted.
10. Workflow reference: every field in workflow.rs, plus KNOTLESS_RUN, KNOTLESS_RUN_REPO, _REF, _SHA, _PULL.
11. Troubleshooting: "names no runners", "not logged in", checks ended as "the runner stopped before this run finished", secrets file errors, duplicate workflow names.

Done when

• Someone with only install.sh and a Docker host can follow docs/runners.md to a green check on their own repo without cloning knotless.
• CI or a scenario track exercises the released knotless-run binary, not just the in-tree build.

Closing, as what this asked for has landed. install.sh brings knotless-run (The install script brings the runner, labeller and reviewer), and the published knotless-server image holds it and the docker client. The workflows guide's "Start a runner" covers running one from the install alone. Private repositories, --discover and the run limits are in too.

Not done, and not reopened here unless someone needs them:

• a slim image with only the runner
• a systemd unit or standalone compose file
• knotless runner add warning when the account has never filed a check
• a check of a real released binary: installing_a_release installs an archive the test builds

Running steps on Kubernetes is No way to run a workflow's steps as Kubernetes pods.