Skip to content

docs: add problem statement to README #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
theaussiepom merged 7 commits into from
Dec 24, 2025
Merged

docs: add problem statement to README #7

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
62499d2
docs: explain why this project exists
theaussiepom Dec 24, 2025
94c6e54
docs: add problem/solution statement to README
theaussiepom Dec 24, 2025
058d5f6
docs: rewrite README motivation paragraph
theaussiepom Dec 24, 2025
a34eb29
docs: clarify sandboxed Pi infra testing motivation
theaussiepom Dec 24, 2025
901afef
docs: clarify Linux infra motivation and bind mounts
theaussiepom Dec 24, 2025
d94e326
docs: clarify host integration ro vs rw
theaussiepom Dec 24, 2025
b7e2c58
docs: tidy README intro formatting
theaussiepom Dec 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 4 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,12 @@
# runner

This repo is a small “appliance” (a handful of Bash scripts + systemd unit files) that runs a single
GitHub Actions self-hosted runner on a Linux machine.

If you’re new to self-hosted runners: it’s GitHub’s runner program, but running on your own machine
instead of GitHub’s hosted runners.

Linux notes:

- This works on general Linux (Raspberry Pi is supported, but it’s not a requirement).
- systemd is used to start/stop things reliably at boot.
This is useful when you want to test code against a Linux host but you don’t want every workflow run to permanently
mutate the machine. The core idea is to keep the runner operationally predictable (systemd-managed, reliable at boot),
while running container-style job steps inside an ephemeral `systemd-nspawn` guest so filesystem changes made during a
job are discarded when the guest is torn down. Writing to real devices (USB/ACM/TTY) is not reverted on teardown.

What it aims to do:

Expand Down