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 |
1---2name: github-runner3description: >-4 Deploy, manage, and troubleshoot self-hosted GitHub Actions runners. Covers systemd5 service, Docker containers, Kubernetes (Actions Runner Controller), and the Scale Set6 Client. Use when setting up a CI runner, debugging registration failures, designing7 autoscaling, or hardening runner security. Do not use this skill for unrelated requests;8 route to the nearest named specialist.9license: MIT10compatibility: Linux, macOS, or Windows target hosts. Docker for containerized runners.11 Kubernetes for ARC deployments.12metadata:13 tags: github-actions, ci-cd, runners, devops, docker, kubernetes, autoscaling14 source: https://skillmd.com/skills/magnus919/github-runner15 upstream: https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners16 version: 1.0.217---1819# Self-Hosted GitHub Actions Runner2021Deploy 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.2223## When to Use2425| Trigger | What to do |26|---------|------------|27| "Set up CI for my project", "deploy a self-hosted runner for [repo/org]" | Read [deployment](references/deployment.md) — choose systemd, Docker, or ARC |28| "Runner won't register / keeps failing", "runner gets 404", "registration token expired" | Read [management](references/management.md) — ACCESS_TOKEN vs RUNNER_TOKEN, groups |29| "How to scale runners automatically", "auto-scale runners", "too many queued jobs" | Read [scaling](references/scaling.md) — ARC, Scale Set Client, ephemeral |30| "Secure my self-hosted runners", "hardening runners", "runner security", "public repo risk" | Read [security](references/security.md) — public repo risks, ephemeral, JIT, groups |31| "Make a custom runner image", "build a runner Dockerfile", "custom runner with Python" | Read [custom-images](references/custom-images.md) — Dockerfile, ARC container modes |32| "What domains does a runner need to reach?", "runner firewall rules", "runner network setup" | Read [network](references/network.md) — firewall rules, TLS, proxy |33| "Labels, groups, or both for routing?", "how to target specific runners" | Read [management](references/management.md) — labels and groups sections |34| "Monitor / troubleshoot runner issues", "runner offline", "runner not picking up jobs" | Read [management](references/management.md) — monitoring and troubleshooting sections |3536## Quick Reference3738### Deployment Spectrum3940| Approach | Complexity | Autoscaling | Best For |41|----------|------------|-------------|----------|42| systemd service | Low | Manual | Single machine, simple CI |43| Docker container | Medium | Manual replicas | Homelab, small team |44| ARC (Kubernetes) | High | Built-in | Teams with K8s expertise |45| Scale Set Client | High | Custom | Non-K8s platform teams |4647### Critical: ACCESS_TOKEN vs RUNNER_TOKEN4849This 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).5051| Token | Purpose | Expiry |52|-------|---------|--------|53| `ACCESS_TOKEN` | Registration — generates fresh tokens via GitHub API | Long-lived (PAT) |54| `RUNNER_TOKEN` | **De-registration only** — NOT for initial registration | 60 min |5556**PAT scopes:**57- Repo-level: `repo`58- Org-level: `admin:org`59- Enterprise-level: `manage_runners:enterprise`6061### Labels Strategy6263Default labels: `self-hosted` + OS (`linux`/`windows`/`macOS`) + arch (`x64`/`ARM`/`ARM32`/`ARM64`)6465Common convention: `self-hosted,<hostname>,<os>,<arch>,<project>`. In workflows:6667```yaml68runs-on: [self-hosted, linux, x64, gpu]69```7071All labels must match (AND logic). Use `--no-default-labels` to strip OS/arch auto-labels.7273### Key Pitfalls7475| Problem | Cause | Fix |76|---------|-------|-----|77| 404 on POST to runner-registration | `RUNNER_TOKEN` used instead of `ACCESS_TOKEN` | Switch to `ACCESS_TOKEN` with PAT |78| "Could not find any self-hosted runner group named 'Default'" | Org uses different group name | Check groups via `gh api`, set `RUNNER_GROUP` |79| "Ephemeral option is enabled" when not wanted | `EPHEMERAL=0` — truthy in bash | Use `EPHEMERAL=false` (string) |80| `docker compose down -v` wipes credentials | Named volumes deleted | With `ACCESS_TOKEN`, auto-recovers |81| Runner can't see host filesystem paths | Runner runs inside Docker container | Write deploy configs inline in workflow |82| Hugo build: "Go not found" | No Go on Ubuntu 20.04 runner | `hugo mod vendor` and commit `_vendor/` |83| GHCR pull "unauthorized" | No Docker registry auth in deploy job | Add `docker/login-action@v4` |84| Runner offline >14 days | Auto-removed by GitHub | Register a new runner |8586## Sequential Workflow8788### 1. Choose deployment approach8990Read [deployment](references/deployment.md) and select systemd, Docker, ARC, or Scale Set Client.9192### 2. Figure out what runner scope you need9394- **Repo-level**: Runner scoped to a single repo — you need admin access95- **Org-level**: Runner shared across repos in an org — you need org owner access96- **Enterprise-level**: Runner shared across orgs in an enterprise — you need enterprise access9798### 3. Register the runner99100Read the [architecture](references/architecture.md) reference for the registration flow.101102### 4. Route jobs to the runner103104Use `runs-on` with labels and optionally groups. Read [management](references/management.md) labels section.105106### 5. Monitor and troubleshoot107108Read the [management](references/management.md) troubleshooting section when things go wrong.109110### 6. Plan for security and scaling111112Read [security](references/security.md) and [scaling](references/scaling.md) for production deployments.113114## Templates115116- [templates/docker-compose.yml](templates/docker-compose.yml) — Docker runner with `myoung34/github-runner`117- [templates/custom-runner.Dockerfile](templates/custom-runner.Dockerfile) — Custom runner image for ARC118119## Reference Files120121| File | Load when |122|------|-----------|123| [references/architecture.md](references/architecture.md) | You need to understand registration flow, job lifecycle, or runner communication |124| [references/deployment.md](references/deployment.md) | You need to deploy a runner — systemd, Docker, ARC, or Scale Set Client |125| [references/security.md](references/security.md) | You need to harden runners, set up ephemeral/JIT, configure groups |126| [references/scaling.md](references/scaling.md) | You need autoscaling — ARC, Scale Set Client, or webhook-driven |127| [references/management.md](references/management.md) | You need groups, labels, monitoring, troubleshooting, or cleanup |128| [references/custom-images.md](references/custom-images.md) | You need a custom runner Dockerfile, ARC Kubernetes mode |129| [references/network.md](references/network.md) | You need firewall rules, proxy config, or are troubleshooting connectivity |