The problem with long-lived self-hosted runners
A self-hosted GitHub Actions runner that stays registered keeps its working directory, its tool caches and whatever a previous job left behind. On your own hardware that is convenient until one job leaves state that breaks or leaks into the next one. The safer pattern is one runner per job: start it for the job, remove it when the job ends.
ScaleRunnerGH is an open-source Go service that does this for hosts you own. One instance runs per host and serves one or more GitHub runner scale sets, org-level or repo-level. It is built on actions/scaleset, GitHub's Go client for the runner scale set API.
How a job flows through it
- Register. Each scale set is registered in a runner group at GitHub. Its name and extra labels become the
runs-onlabels, so GitHub matches jobs to it without polling per repository. - Listen. A long-poll message session reports how many jobs are assigned. It is outbound only. The service tells GitHub its current capacity, so GitHub never assigns more than the host can run.
- Guard. Jobs from public repositories and pull requests from forks are never acquired.
- Start. For each assigned job a slot is taken from the host pool and a runner starts with a single-use just-in-time (JIT) config. No registration token is involved.
- Clean up. The runner exits after one job. Its container, with volumes, or its job directory is removed and the slot returns to the pool.
Container or native process
A runner is either a container (Docker backend) or a process on the host (native backend, on Linux and Windows). All scale sets on a host share one slot pool, so a small box never runs more than it can take. max_runners caps the host, and max_heavy caps heavy scale sets, for example one heavy job at a time on a small machine.
Limits that protect the host
Native mode shares the host and the service account with the job, so a workflow can read whatever that account can. Use it only for repositories you fully trust, under a dedicated unprivileged account.
- Hard limits per job container: CPUs, memory (no swap on top), pids, CPU shares, I/O weight and OOM score, with optional disk size and GPUs.
- A load and memory gate, low priority, and a kill-switch file that stops new jobs at once, and running ones if you configure it.
- An optional private Docker daemon inside the job container, destroyed with it, so jobs can use Docker without the host socket. With
dind: truethe job container is privileged, which is acceptable only for trusted private repositories; settingdocker.runtimetosysbox-runcavoids privileged containers. - Credentials as a GitHub App or a PAT, always read from files, never from the config or the environment.
- Prometheus metrics and a Grafana dashboard.
Private repositories only
Running self-hosted runners for public repositories is dangerous, because anyone can open a pull request that executes on your host. ScaleRunnerGH fails closed: the runner group must refuse public repositories or the service will not start, and a guard re-checks every job. Also keep fork pull request workflows for private repositories turned off in the organization settings.
Getting started
- Create a GitHub App (recommended) or a PAT, and store it as a file readable only by the service user.
- Create a runner group with Allow public repositories off and only the repositories that may use it.
- Start from an example config, then validate it with
scalerunnergh --config config.json --check. - Run it with Docker Compose, or natively under systemd on Linux or as a Windows service.
- Point a workflow at it:
runs-on: srg-docker, or the name of your scale set.
Releases ship for Linux amd64 and arm64 and Windows amd64, with a published container image. Nexis Limited builds and runs this kind of CI and DevOps tooling; if you want help setting up CI on your own hosts, get in touch.