A self-hosted GitHub Actions runner fleet, built to stop a private-repo account from running out of the free 2,000-minutes/month Actions quota — without raising a spending limit or upgrading a plan.
Status: Phase 1 (repository-scoped MVP) in progress. Design is done; the
runner image, registration entrypoint, and declarative repo config are
scaffolded — see development/ for the full plan and
04_ROADMAP.md for what's left.
| Path | Covers |
|---|---|
start.sh / start.ps1 |
One-command launcher for Linux containers from Bash / PowerShell |
stop.sh / stop.ps1 |
Gracefully shuts down Linux runner containers from Bash / PowerShell |
start-macos.sh / stop-macos.sh |
Installs/removes native macOS launchd runner agents |
start-windows.ps1 / stop-windows.ps1 |
Registers/removes native Windows Scheduled Task runner agents |
.gitattributes |
Preserves LF line endings for Linux container sources on Windows checkouts |
docker/runner/Dockerfile |
Runner image: pinned actions/runner + docker CLI (DooD) |
scripts/register-runner.sh |
Container entrypoint — mints a registration token, runs one ephemeral job, exits |
scripts/render-compose.py |
Renders config/repos.yaml into compose.generated.yaml |
scripts/render-macos-launchd.py |
Renders optional macos: entries into local launchd agent plists |
scripts/macos-runner-loop.sh |
Native macOS one-job runner supervisor, download verifier, and cleanup loop |
scripts/render-windows-scheduled-task.py |
Renders optional windows: entries into local Scheduled Task XML |
scripts/windows-runner-loop.ps1 |
Native Windows one-job runner supervisor, download verifier, and cleanup loop |
dashboard.sh / dashboard.ps1 |
Starts the local status dashboard for this host's runner fleet |
scripts/prune-ci-evidence.sh |
Deletes local CI evidence older than N days (installed as a daily cron job by install.sh) |
scripts/prune-docker-volumes.sh |
Deletes unused anonymous Docker volumes older than N days (default 7; installed as a daily cron job by install.sh) |
scripts/relocate-storage.sh |
One-off: moves Docker, containerd and the buildx cache from the root filesystem to a larger disk (default /data) |
scripts/dashboard.py |
Dashboard web server — reads local Docker/launchd/Scheduled Task state, no GitHub API calls |
config/repos.yaml.example |
Template for the declarative repo list — copy to config/repos.yaml (gitignored) and fill in real values |
The Linux runner container matches GitHub's official ubuntu-latest environment.
The optional macOS and Windows routes use native processes because a Linux
container cannot execute macOS or Windows-native workflows:
| Specification | Details |
|---|---|
| Linux runner OS | Ubuntu 24.04 LTS (noble), 64-bit x86 (x64) — matches GitHub-hosted ubuntu-latest |
| macOS runner OS | Native macOS 11+ on the host's architecture (ARM64 on Apple silicon, x64 on Intel) |
| Windows runner OS | Native Windows 10/11 or Windows Server on the host's architecture (x64 or ARM64) |
| Runner Runtime | Official GitHub Actions Runner runtime (pinned version in Dockerfile, macos-runner-loop.sh, and windows-runner-loop.ps1) |
| Linux pre-installed tooling | docker-ce-cli, git, curl, jq, ca-certificates, gnupg |
| Docker Support | DooD (Docker-outside-of-Docker) via host /var/run/docker.sock bind mount |
| Build Caching | Reuses host Docker layer cache across jobs (resulting in faster container builds) |
| Local artifact and image storage | /srv/ci-evidence (artifacts) and a loopback registry at localhost:5000 (images) on the host — see Local artifacts and images |
| macOS lifecycle | User-level launchd agents each provision a verified, native, ephemeral runner for one job, then erase its runner/work directory |
| Windows lifecycle | User-level Scheduled Tasks each provision a verified, native, ephemeral runner for one job, then erase its runner/work directory |
To allow runner containers to dynamically mint short-lived registration and removal tokens via the GitHub API, a Fine-grained Personal Access Token (PAT) is required.
Go to GitHub Settings → Developer Settings → Personal access tokens → Fine-grained tokens:
| Scope / Setting | Recommended Value | Description / Purpose |
|---|---|---|
| Resource owner | Target personal account or org | The owner of the target repositories |
| Repository access | Only select repositories | Select the exact private repositories listed in config/repos.yaml |
| Repository permissions → Administration | Read and write | Mandatory. Required to invoke GitHub Actions runner registration (/actions/runners/registration-token) and removal (/actions/runners/remove-token) endpoints. |
- Infrastructure vs. Workflow: The
Actionspermission only controls running, inspecting, and canceling workflows. In GitHub's security model, registering or removing compute nodes (Runners) in a repository is an infrastructure management action (Repository Settings), restricted exclusively to repository administrators. - Security Boundary: A self-hosted runner executes code directly on your local infrastructure (with Docker socket access). To prevent unauthorized computing nodes from being attached to a repo, GitHub strictly restricts runner registration to
Administration: write.
Important
Troubleshooting HTTP 404:
If your PAT does not have Administration: write permissions, or if the target repo is not selected in the token's repository access list, GitHub's API will return HTTP 404 Not Found (instead of 403 Forbidden) to prevent repository discovery. Ensure both settings are configured properly.
On a fresh Ubuntu or Debian host, install.sh does the whole setup. There is no
start.py; the Linux entry points are install.sh, start.sh and stop.sh.
git clone https://github.com/ephoton0210/github_self-hosted_runner.git
cd github_self-hosted_runner
./install.sh # install, configure and verify
./install.sh --start # the same, then start the runners
./install.sh --dry-run # only print what would be doneIt installs Docker Engine with the Compose and Buildx plugins from Docker's
official apt repository (and python3-yaml), enables the Docker service at boot,
adds you to the docker group, creates /opt/buildx-cache, /srv/ci-evidence and /srv/registry (plus a daily prune job for old evidence), creates .env
(it asks for the GH_PAT, input hidden, file mode 600) and config/repos.yaml
from their examples, then checks the result. It needs sudo and is safe to run
again: every step checks the current state first.
- Fill in
config/repos.yaml(target repositories, labels, replicas) before starting; the script refuses to start the runners while it still has the example placeholders. - Log out and back in (or run
newgrp docker) after the first run so thatdockerworks withoutsudo. - For unattended use, pass the token in the environment:
GH_PAT=github_pat_... ./install.sh --yes. - The script also reads the kernel clock and warns when the host clock runs fast or slow (kernel tick other than 10000). The runner containers share the host clock, and a clock that steps backwards fails tests that order rows by timestamp.
The steps below (and the macOS and Windows sections) describe what the script automates and how to do it by hand.
Native macOS runners are for workflows that genuinely need macOS (for example, Xcode, code signing, or an Apple-platform build). They are not Docker containers: jobs run as the currently logged-in macOS user. Use a dedicated macOS account and only route trusted private-repository workflows to it.
- macOS 11 or later, on either Apple silicon or Intel.
start-macos.shselects the matching official runner archive automatically. - A logged-in GUI user session. The launcher creates user-level
launchdagents; do not run it withsudo. - Python 3 with PyYAML (
python3 -m pip install -r requirements.txt), plus the built-incurl,jq,tar,shasum, andlaunchctlcommands. - Xcode and any platform-specific toolchains required by the target workflows.
Docker Desktop is optional and only needed by macOS jobs that invoke
docker.
The macOS supervisor disables automatic runner updates so its downloaded archive remains reproducible and SHA-256 verified. Update the pinned version and checksum together during the monthly runner update in 03_SECURITY.md.
For runs-on: [self-hosted, linux, ...] jobs, the runners remain Linux
containers even when the host is Windows. Install
Docker Desktop and make sure it
is running in Linux containers mode (the default). Docker Desktop provides the
Linux Docker engine and forwards its Docker socket into the runner containers, so
workflows should continue to request the linux labels configured below.
Keep the committed .gitattributes file: it prevents Git for Windows from
converting the Linux container entrypoint to CRLF line endings.
Install Python 3, then install the renderer dependency from PowerShell:
py -3 -m pip install -r requirements.txtImportant
Docker socket access gives every job host-level control of Docker Desktop's Linux VM. Only use this fleet for trusted workflows from private repositories; the same security restrictions in 03_SECURITY.md apply on Windows.
These are still Linux containers, not native Windows runners. To keep them easy to
tell apart in docker compose ps and in the GitHub runners list, render-compose.py
runs on the host at start time and defaults the runner name to a -windows-docker
suffix (e.g. runner-repo-a-windows-docker-1) whenever the host is Windows, versus
plain runner-repo-a-1 on a Linux host — set runner_name_prefix in
config/repos.yaml to override it. See config/repos.yaml.example.
Native Windows runners are for workflows that genuinely need Windows itself — for example MSBuild against the full .NET Framework, a Windows-only SDK, or a Windows service integration test — not just "any host running Docker Desktop." They are not Docker containers: jobs run as the currently logged-in Windows user, the same way the native macOS route runs jobs as a logged-in macOS user. Use a dedicated Windows account and only route trusted private-repository workflows to it.
- Windows 10/11 or Windows Server, on either x64 or ARM64.
start-windows.ps1selects the matching official runner archive automatically. - PowerShell 7+ (
pwsh.exe) — the generated Scheduled Task runswindows-runner-loop.ps1underpwsh, not the in-box Windows PowerShell 5.1. - A logged-in user session for the account the Scheduled Task's logon trigger runs as. The launcher registers user-level Scheduled Tasks; run it from an elevated prompt only if your environment requires elevation to register tasks, not as a way to run jobs as an administrator.
- Python 3 with PyYAML (
py -3 -m pip install -r requirements.txt), plus the built-inExpand-Archive,Get-FileHash, and Task Scheduler (schtasks/ScheduledTasksmodule) commands. - Visual Studio Build Tools and any platform-specific toolchains required by the
target workflows. Docker Desktop is optional and only needed by Windows jobs
that invoke
docker.
The Windows supervisor disables automatic runner updates so its downloaded archive remains reproducible and SHA-256 verified. Update the pinned version and checksum together during the monthly runner update in 03_SECURITY.md.
Copy .env.example to .env and fill in your Fine-grained PAT:
cp .env.example .envOn Windows PowerShell:
Copy-Item .env.example .envGH_PAT=github_pat_xxxxxxxxxxxxxxxxxxxxCopy config/repos.yaml.example to config/repos.yaml:
cp config/repos.yaml.example config/repos.yamlOn Windows PowerShell:
Copy-Item config/repos.yaml.example config/repos.yamlDefine your target repositories, labels, and concurrency replicas:
repos:
- owner: <account>
repo: repo-a
labels: [self-hosted, linux, x64, docker]
# Optional: avoids name clashes with a separate fleet serving this repo.
runner_name_prefix: runner-repo-a-host-a
replicas: 2
# Optional native macOS runners for this same repo. GitHub adds the standard
# self-hosted, macOS, and ARM64/x64 labels automatically.
macos:
labels: [native-macos]
runner_name_prefix: runner-repo-a-macos-host-a
replicas: 1
# Optional native Windows runners for this same repo. GitHub adds the
# standard self-hosted, Windows, and X64/ARM64 labels automatically.
windows:
labels: [native-windows]
runner_name_prefix: runner-repo-a-windows-host-a
replicas: 1./start.shOn Windows PowerShell:
.\start.ps1On macOS, start only the optional macos: runner entries:
./start-macos.shOn Windows PowerShell, start only the optional windows: runner entries:
.\start-windows.ps1Check live logs to confirm runners are connected and Listening for Jobs:
docker compose -f compose.generated.yaml logs -fFor native macOS runners:
tail -f .runner-macos/logs/*.logFor native Windows runners:
Get-ScheduledTask -TaskPath '\GitHubSelfHostedRunner\'To scale runners without interrupting running jobs, edit replicas in config/repos.yaml:
- Scale up: rerun
./start.sh.docker compose up -donly creates the missing containers. (If the runner image changed,--buildrecreates existing ones too; usedocker compose -f compose.generated.yaml up -d --no-build --no-recreatewhile jobs are running.) - Scale down: run
./scale-down.sh(add--dry-runto preview). It removes only idle runners that are no longer in the config and skips busy ones; rerun it after those jobs finish.
To stop all runners:
./stop.shOn Windows PowerShell:
.\stop.ps1On macOS:
./stop-macos.shFor native Windows runners, on Windows PowerShell:
.\stop-windows.ps1In the target repository (e.g. your-repo/.github/workflows/*.yml), switch jobs to target self-hosted runners:
runs-on: [self-hosted, linux, x64]
# or simply:
runs-on: self-hostedFor a native macOS entry with the example custom native-macos label:
runs-on: [self-hosted, macOS, native-macos]For a native Windows entry with the example custom native-windows label:
runs-on: [self-hosted, Windows, native-windows]Add ARM64 or x64 only when the workflow must target that exact architecture.
Warning
Do not use "Re-run" on old failed workflow runs:
GitHub Actions' "Re-run jobs" button executes the exact workflow configuration from the time that commit was created. If the historical commit used runs-on: ubuntu-latest, re-running it will still request GitHub-hosted compute and fail immediately when your account quota is 0.
To test your self-hosted runners, you must commit and push the updated workflow file (or open a new PR / dispatch a manual workflow) to create a new workflow run.
You can verify that your runners are properly registered and working at three levels:
Check the live runner logs:
docker compose -f compose.generated.yaml logs -fA successful runner startup displays:
√ Connected to GitHub
√ Runner successfully added
√ Settings Saved.
Current runner version: '2.336.0'
YYYY-MM-DD HH:MM:SSZ: Listening for Jobs
When you see Listening for Jobs, the runner is authenticated and standing by for CI jobs.
The macOS and Windows supervisors instead write ... is ready for one job to
their local log before the native runner starts listening.
Navigate to your target repository settings in a browser:
https://github.com/<owner>/<repo>/settings/actions/runners
- Status Badge: You should see your runner instances (e.g.
runner-<repo>-1,runner-<repo>-2) listed with a greenIdlebadge. - Labels: Verify that the labels (e.g.
self-hosted,linux,x64,docker) match yourconfig/repos.yaml.
When a workflow job with runs-on: [self-hosted, ...] is triggered:
- GitHub UI: The runner status changes from
IdletoActive. - Container Logs: You will see
Running job: <job-name>followed by step execution logs. - Lifecycle: Upon job completion, the container exits (
--ephemeral), and Docker Compose automatically spins up a fresh container instance with a new registration token to wait for the next job.
GitHub's included Actions storage (2 GB on the Team plan, 500 MB on Free) is
pooled between workflow artifacts and GitHub Packages (GHCR images), and it is
billed as GB-hours accumulated over the month: deleting files stops further
accrual but never refunds what was already accrued. Self-hosted runners do not
change that — actions/upload-artifact still uploads to GitHub. (Actions caches
are separate: 10 GB per repository, not part of the 2 GB.) To keep both off
GitHub, the Linux fleet provides two local stores, started by ./start.sh with
the runners:
| Need | GitHub-hosted way | Local way | Where it lives |
|---|---|---|---|
| Keep job output (test evidence, build files) | actions/upload-artifact |
copy to $CI_EVIDENCE_DIR |
/srv/ci-evidence/<run_id>/... on the host |
| Pass files between jobs | actions/download-artifact |
read the same directory | same host, so all such jobs must use this fleet |
| Publish an image | push to ghcr.io/<owner>/<name> |
push to $LOCAL_REGISTRY/<name> |
registry:2 container, 127.0.0.1:5000, data in /srv/registry |
| Docker layer cache | cache-to: type=gha |
type=local,dest=/opt/buildx-cache/<name> |
/opt/buildx-cache |
.dockerbuild build record |
uploaded automatically | set DOCKER_BUILD_RECORD_UPLOAD: false |
not created |
CI_EVIDENCE_DIR and LOCAL_REGISTRY are set in every runner container, so a
step can use them as plain shell variables. Workflow example:
env:
DOCKER_BUILD_RECORD_UPLOAD: false
steps:
- name: Retain backend test evidence
if: always()
run: |
d="$CI_EVIDENCE_DIR/${{ github.run_id }}/backend-pytest"
mkdir -p "$d" && cp -r test-results/. "$d"/
- name: Build and push to the local registry
run: |
docker build -t "$LOCAL_REGISTRY/omnisolve-backend:${{ github.sha }}" .
docker push "$LOCAL_REGISTRY/omnisolve-backend:${{ github.sha }}"Notes:
- Docker treats
localhostregistries as plain-HTTP-safe, so no TLS or daemon setting is needed, and the port is bound to loopback only: nothing outside this host can pull the images. Consumers that deploy from other machines cannot use this registry; keep GHCR for those images and prune old versions instead. - Evidence older than 14 days is deleted daily by
/etc/cron.daily/ci-evidence-prune(scripts/prune-ci-evidence.sh [days]). The registry has no automatic cleanup; delete unused repositories under/srv/registry/docker/registry/v2/repositories/and rundocker exec registry registry garbage-collect /etc/docker/registry/config.yml. - Jobs that run on GitHub-hosted runners (for example macOS and Windows desktop
builds without a native runner) keep using GitHub artifacts; give them a short
retention-days. - Existing hosts: run
./install.shagain to create the directories and the prune job, then./start.shto start the registry. To pull a local image on another workflow, use the samelocalhost:5000/<name>:<tag>reference.
Runners run in the background, across up to three mechanisms per host (Docker
Compose, macOS launchd, Windows Scheduled Tasks) — checking on all of them by
hand means three different commands. dashboard.sh / dashboard.ps1 starts a
small local web server that shows, for every runner on this host: its repo,
whether it's Idle / Running <job> / Starting / Stopped, and a live-tailing
view of its own log — the same signals described in "How to Verify" above, in
one page instead of three commands.
./dashboard.shOn Windows PowerShell:
.\dashboard.ps1Then open http://127.0.0.1:8787. Click a runner's row to open its log panel; both the runner table and an open log panel auto-refresh every few seconds.
This reads only local state — docker compose ps / docker logs, launchd
agent status, and Scheduled Task status plus each runner's own log file — never
the GitHub API, so it needs no extra token or permissions, and it only shows
runners started on the host it's running on (a repo's fleet spanning multiple
hosts needs one dashboard per host). It binds to 127.0.0.1 by default, since
runner logs can contain job output; pass --host to change that only on a
trusted network.
GitHub Actions' free minutes are billed per account, shared across every private repo you own. A private monorepo with several CI workflows can burn through that pool in a single large merge — once it hits zero, every job is refused until the quota resets or you explicitly raise your spending limit above $0. Running jobs on infrastructure you own sidesteps the quota entirely: GitHub only schedules the job and relays its logs, it never executes on GitHub's own compute, so self-hosted runner time is not metered against Actions minutes on any plan.
| Doc | Covers |
|---|---|
| 00_OVERVIEW.md | Problem, goals, non-goals, the personal-account constraint that shapes everything else |
| 01_ARCHITECTURE.md | Runner mechanism, repo-scoped vs org-scoped registration, the two-phase topology |
| 02_DEPLOYMENT_DESIGN.md | Container image, Docker-outside-of-Docker rationale, declarative repo config, token lifecycle |
| 03_SECURITY.md | Why this fleet never serves a public repo's pull_request workflow, credential handling, blast-radius controls |
| 04_ROADMAP.md | Phased plan: repo-scoped MVP → org-scoped account-wide pool → deferred scale work |
MIT — use this however is useful to you.