Runnerly

The problem

Standing up a self-hosted GitHub Actions runner by hand means a tarball, a registration token, config.sh, a systemd unit — and noticing three weeks later that it went offline. The runner itself is fine; everything around it is the work.

How I built it

• Wraps GitHub's official runner instead of reimplementing it — zero lines of the runner itself rewritten.
• One command end to end: runnerly setup checks the machine, signs in, registers, and prints the unit that survives reboots. Every step it takes is also its own command, so nothing is a black box.
• doctor names the command that fixes each failure and exits non-zero, so it gates a provisioning script.
• The agent restarts a failed runner on a 5s to 80s backoff, then stops rather than hiding a runner that cannot start. systemd restarts the agent — two layers, each covering the other's failure.
• The Docker executor records what existed when a job started and removes only what appeared, rather than pruning containers belonging to something else on the machine.
• Safe by default: refuses to register against a public repository unless told to, verifies downloads against GitHub's published checksum, rejects archive entries that would escape the install directory, and never runs sudo for you.
• An optional control plane — server and dashboard from the same binary — answers what exists and whether it is healthy once more than one machine is running runners.

Where it landed

Three dependencies, 434 tests against real Postgres and Docker in CI, and 15 pages of documentation — including an honest list of what it does not do. MIT, free to run.