Skip to content

WorkWingman CI runner - plain-language version

What is this, really?

WorkWingman's automated tests and checks (GitHub Actions "CI") need a computer to actually run on. GitHub will happily provide one for free ("GitHub-hosted runners"), but this project instead uses our own house computers as those worker machines - four PCs around the house, each contributing a slot in a shared pool.

Think of it like a car wash with four bays. Each bay (PC) keeps one car-sized space open and ready. When a job (a car) shows up, it pulls into whichever bay is free. If one bay is closed for the day, cars just use the other three - no one has to coordinate that by hand.

Why not just use GitHub's free runners?

Speed, cost, and control - the house PCs are already on and idle most of the time, and some of WorkWingman's checks need Windows-specific things (like Windows' built-in credential encryption) that are simpler to test on a real Windows machine than to fake in a cloud container.

How does a PC "join" safely?

This is the part that gets the most engineering attention, because "let a PC run code from GitHub" is exactly the kind of thing that needs a lock on the front door.

  1. GitHub issues each PC its own private key, like a house key that only opens that PC's door - if one is lost, you change that lock without re-keying the whole house.
  2. That key never sits around in plain text. It's stored in a password vault, then encrypted onto the PC using a feature built into Windows itself (so even someone with a copy of the file, but not this specific Windows user account, cannot read it).
  3. When a PC wants a fresh worker, a small always-running helper program (the "watchdog") uses that key to ask GitHub for a very short-lived, one-time pass - good for about an hour, and only good for registering a single worker. That pass, not the house key, is the only thing that ever actually touches the worker itself.
  4. The worker does exactly one job, then it deletes itself. Next time one is needed, the watchdog repeats the whole dance with a fresh pass.

So even in the worst case - someone gets hold of a single worker's one-time pass - the damage is capped at "run one job," not "control the house."

One project or the whole family? (org mode)

Originally the pool served exactly one project (WorkWingman). It can now optionally serve every project in the family at once ("org mode"): flip one setting on each PC and the same four bays wash any of the house projects' cars, not just one project's. The safety story doesn't change - same keys, same short-lived one-time passes - the pass is just valid for the whole family's garage instead of a single driveway. The pool also learned some manners for the busier road: if GitHub is having a bad moment it waits progressively longer between retries instead of pestering it, it tidies away worker entries that died and never signed out, and each PC has a hard limit on how many workers it will ever run at once so your PC stays usable. Turning this on has a short to-do list for a human: docs/ORG-MIGRATION.md.

What happens if a PC is off, or the internet hiccups?

Nothing dramatic. GitHub keeps a to-do list of pending jobs and simply waits for a free worker; if a PC is off, its bay is just closed and the other three keep going. When the PC comes back on, its watchdog restarts automatically and rejoins the pool within moments.

What can I trust this NOT to do?

  • It cannot run someone else's code on your PC uninvited - only trusted house members can trigger these jobs (see docs/technical/SECURITY.md for the detailed version).
  • It never asks you to type in or paste a secret into a script - the actual secret material only ever lives in the password vault and inside Windows' own encrypted storage.
  • Nothing about how it works is a black box - every step above is implemented in plain PowerShell/Bash you (or any house member) can read end to end; see docs/technical/ARCHITECTURE.md for the exact diagrams.

Where to go next

  • Setting one of these up on a new PC: docs/SETUP.md.
  • Something seems broken: docs/DR-OPS.md.
  • You suspect a key leaked: docs/REVOCATION-RUNBOOK.md.
  • The technical deep dive: docs/technical/ARCHITECTURE.md and docs/technical/SECURITY.md.