github-runner

name	github-runner
description	Deploy, manage, and troubleshoot self-hosted GitHub Actions runners. Covers systemd service, Docker containers, Kubernetes (Actions Runner Controller), and the Scale Set Client. Use when setting up a CI runner, debugging registration failures, designing autoscaling, or hardening runner security.
license	MIT
compatibility	Linux, macOS, or Windows target hosts. Docker for containerized runners. Kubernetes for ARC deployments.
metadata	{"tags":"github-actions, ci-cd, runners, devops, docker, kubernetes, autoscaling","source":"https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners","version":"1.0.2"}

Self-Hosted GitHub Actions Runner

Deploy and manage self-hosted GitHub Actions runners — the machines that execute CI/CD workflow jobs. Self-hosted runners give you control over hardware, OS, and toolchain, at the cost of requiring you to maintain the environment.

When to Use

Trigger	What to do
"Set up CI for my project", "deploy a self-hosted runner for [repo/org]"	Read deployment — choose systemd, Docker, or ARC
"Runner won't register / keeps failing", "runner gets 404", "registration token expired"	Read management — ACCESS_TOKEN vs RUNNER_TOKEN, groups
"How to scale runners automatically", "auto-scale runners", "too many queued jobs"	Read scaling — ARC, Scale Set Client, ephemeral
"Secure my self-hosted runners", "hardening runners", "runner security", "public repo risk"	Read security — public repo risks, ephemeral, JIT, groups
"Make a custom runner image", "build a runner Dockerfile", "custom runner with Python"	Read custom-images — Dockerfile, ARC container modes
"What domains does a runner need to reach?", "runner firewall rules", "runner network setup"	Read network — firewall rules, TLS, proxy
"Labels, groups, or both for routing?", "how to target specific runners"	Read management — labels and groups sections
"Monitor / troubleshoot runner issues", "runner offline", "runner not picking up jobs"	Read management — monitoring and troubleshooting sections

Quick Reference

Deployment Spectrum

Approach	Complexity	Autoscaling	Best For
systemd service	Low	Manual	Single machine, simple CI
Docker container	Medium	Manual replicas	Homelab, small team
ARC (Kubernetes)	High	Built-in	Teams with K8s expertise
Scale Set Client	High	Custom	Non-K8s platform teams

Critical: ACCESS_TOKEN vs RUNNER_TOKEN

This is the most common setup failure. The myoung34/github-runner Docker entrypoint unexports RUNNER_TOKEN at startup — it's only used for de-registration. Registration requires ACCESS_TOKEN (a GitHub PAT).

Token	Purpose	Expiry
ACCESS_TOKEN	Registration — generates fresh tokens via GitHub API	Long-lived (PAT)
RUNNER_TOKEN	De-registration only — NOT for initial registration	60 min

PAT scopes:

• Repo-level: repo
• Org-level: admin:org
• Enterprise-level: manage_runners:enterprise

Labels Strategy

Default labels: self-hosted + OS (linux/windows/macOS) + arch (x64/ARM/ARM32/ARM64)

Common convention: self-hosted,<hostname>,<os>,<arch>,<project>. In workflows:

runs-on: [self-hosted, linux, x64, gpu]

All labels must match (AND logic). Use --no-default-labels to strip OS/arch auto-labels.

Key Pitfalls

Problem	Cause	Fix
404 on POST to runner-registration	RUNNER_TOKEN used instead of ACCESS_TOKEN	Switch to ACCESS_TOKEN with PAT
"Could not find any self-hosted runner group named 'Default'"	Org uses different group name	Check groups via gh api, set RUNNER_GROUP
"Ephemeral option is enabled" when not wanted	EPHEMERAL=0 — truthy in bash	Use EPHEMERAL=false (string)
docker compose down -v wipes credentials	Named volumes deleted	With ACCESS_TOKEN, auto-recovers
Runner can't see host filesystem paths	Runner runs inside Docker container	Write deploy configs inline in workflow
Hugo build: "Go not found"	No Go on Ubuntu 20.04 runner	hugo mod vendor and commit _vendor/
GHCR pull "unauthorized"	No Docker registry auth in deploy job	Add docker/login-action@v4
Runner offline >14 days	Auto-removed by GitHub	Register a new runner

Sequential Workflow

1. Choose deployment approach

Read deployment and select systemd, Docker, ARC, or Scale Set Client.

2. Figure out what runner scope you need

• Repo-level: Runner scoped to a single repo — you need admin access
• Org-level: Runner shared across repos in an org — you need org owner access
• Enterprise-level: Runner shared across orgs in an enterprise — you need enterprise access

3. Register the runner

Read the architecture reference for the registration flow.

4. Route jobs to the runner

Use runs-on with labels and optionally groups. Read management labels section.

5. Monitor and troubleshoot

Read the management troubleshooting section when things go wrong.

6. Plan for security and scaling

Read security and scaling for production deployments.

Templates

• templates/docker-compose.yml — Docker runner with myoung34/github-runner
• templates/custom-runner.Dockerfile — Custom runner image for ARC

Reference Files

File	Load when
references/architecture.md	You need to understand registration flow, job lifecycle, or runner communication
references/deployment.md	You need to deploy a runner — systemd, Docker, ARC, or Scale Set Client
references/security.md	You need to harden runners, set up ephemeral/JIT, configure groups
references/scaling.md	You need autoscaling — ARC, Scale Set Client, or webhook-driven
references/management.md	You need groups, labels, monitoring, troubleshooting, or cleanup
references/custom-images.md	You need a custom runner Dockerfile, ARC Kubernetes mode
references/network.md	You need firewall rules, proxy config, or are troubleshooting connectivity