Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

github_self-hosted_runner

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.

Repository layout

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

Runner Environment & OS Specifications

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

GitHub PAT Permission Requirements

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.

Required Permissions

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.

Why Administration instead of Actions?

  • Infrastructure vs. Workflow: The Actions permission 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.

Quickstart

Linux host (Ubuntu/Debian): one-shot install

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 done

It 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 that docker works without sudo.
  • 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.

macOS host requirements

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.sh selects the matching official runner archive automatically.
  • A logged-in GUI user session. The launcher creates user-level launchd agents; do not run it with sudo.
  • Python 3 with PyYAML (python3 -m pip install -r requirements.txt), plus the built-in curl, jq, tar, shasum, and launchctl commands.
  • 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.

Windows host requirements (Linux container fleet)

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.txt

Important

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.

Windows host requirements (native Windows runners)

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.ps1 selects the matching official runner archive automatically.
  • PowerShell 7+ (pwsh.exe) — the generated Scheduled Task runs windows-runner-loop.ps1 under pwsh, 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-in Expand-Archive, Get-FileHash, and Task Scheduler (schtasks / ScheduledTasks module) 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.

1. Configure Credentials

Copy .env.example to .env and fill in your Fine-grained PAT:

cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env
GH_PAT=github_pat_xxxxxxxxxxxxxxxxxxxx

2. Configure Target Repositories

Copy config/repos.yaml.example to config/repos.yaml:

cp config/repos.yaml.example config/repos.yaml

On Windows PowerShell:

Copy-Item config/repos.yaml.example config/repos.yaml

Define 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

3. Start Runners

./start.sh

On Windows PowerShell:

.\start.ps1

On macOS, start only the optional macos: runner entries:

./start-macos.sh

On Windows PowerShell, start only the optional windows: runner entries:

.\start-windows.ps1

Check live logs to confirm runners are connected and Listening for Jobs:

docker compose -f compose.generated.yaml logs -f

For native macOS runners:

tail -f .runner-macos/logs/*.log

For 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 -d only creates the missing containers. (If the runner image changed, --build recreates existing ones too; use docker compose -f compose.generated.yaml up -d --no-build --no-recreate while jobs are running.)
  • Scale down: run ./scale-down.sh (add --dry-run to 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.sh

On Windows PowerShell:

.\stop.ps1

On macOS:

./stop-macos.sh

For native Windows runners, on Windows PowerShell:

.\stop-windows.ps1

4. Update Target Repository Workflows

In 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-hosted

For 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.

How to Verify (Confirming Success)

You can verify that your runners are properly registered and working at three levels:

1. Local Container Logs

Check the live runner logs:

docker compose -f compose.generated.yaml logs -f

A 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.

2. GitHub Web UI (Repository Settings)

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 green Idle badge.
  • Labels: Verify that the labels (e.g. self-hosted, linux, x64, docker) match your config/repos.yaml.

3. Workflow Execution

When a workflow job with runs-on: [self-hosted, ...] is triggered:

  • GitHub UI: The runner status changes from Idle to Active.
  • 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.

Local artifacts and images

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 localhost registries 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 run docker 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.sh again to create the directories and the prune job, then ./start.sh to start the registry. To pull a local image on another workflow, use the same localhost:5000/<name>:<tag> reference.

Monitoring Dashboard

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.sh

On Windows PowerShell:

.\dashboard.ps1

Then 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.

Why

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.

Design docs

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

License

MIT — use this however is useful to you.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages