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: 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. Do not use this skill for unrelated requests; route to the nearest named specialist.4license: MIT5---67# Self-Hosted GitHub Actions Runner89Deploy 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.1011## When to Use1213| Trigger | What to do |14|---------|------------|15| "Set up CI for my project", "deploy a self-hosted runner for [repo/org]" | Read [deployment](references/deployment.md) — choose systemd, Docker, or ARC |16| "Runner won't register / keeps failing", "runner gets 404", "registration token expired" | Read [management](references/management.md) — ACCESS_TOKEN vs RUNNER_TOKEN, groups |17| "How to scale runners automatically", "auto-scale runners", "too many queued jobs" | Read [scaling](references/scaling.md) — ARC, Scale Set Client, ephemeral |18| "Secure my self-hosted runners", "hardening runners", "runner security", "public repo risk" | Read [security](references/security.md) — public repo risks, ephemeral, JIT, groups |19| "Make a custom runner image", "build a runner Dockerfile", "custom runner with Python" | Read [custom-images](references/custom-images.md) — Dockerfile, ARC container modes |20| "What domains does a runner need to reach?", "runner firewall rules", "runner network setup" | Read [network](references/network.md) — firewall rules, TLS, proxy |21| "Labels, groups, or both for routing?", "how to target specific runners" | Read [management](references/management.md) — labels and groups sections |22| "Monitor / troubleshoot runner issues", "runner offline", "runner not picking up jobs" | Read [management](references/management.md) — monitoring and troubleshooting sections |2324## Quick Reference2526### Deployment Spectrum2728| Approach | Complexity | Autoscaling | Best For |29|----------|------------|-------------|----------|30| systemd service | Low | Manual | Single machine, simple CI |31| Docker container | Medium | Manual replicas | Homelab, small team |32| ARC (Kubernetes) | High | Built-in | Teams with K8s expertise |33| Scale Set Client | High | Custom | Non-K8s platform teams |3435### Critical: ACCESS_TOKEN vs RUNNER_TOKEN3637This 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).3839| Token | Purpose | Expiry |40|-------|---------|--------|41| `ACCESS_TOKEN` | Registration — generates fresh tokens via GitHub API | Long-lived (PAT) |42| `RUNNER_TOKEN` | **De-registration only** — NOT for initial registration | 60 min |4344**PAT scopes:**45- Repo-level: `repo`46- Org-level: `admin:org`47- Enterprise-level: `manage_runners:enterprise`4849### Labels Strategy5051Default labels: `self-hosted` + OS (`linux`/`windows`/`macOS`) + arch (`x64`/`ARM`/`ARM32`/`ARM64`)5253Common convention: `self-hosted,<hostname>,<os>,<arch>,<project>`. In workflows:5455```yaml56runs-on: [self-hosted, linux, x64, gpu]57```5859All labels must match (AND logic). Use `--no-default-labels` to strip OS/arch auto-labels.6061### Key Pitfalls6263| Problem | Cause | Fix |64|---------|-------|-----|65| 404 on POST to runner-registration | `RUNNER_TOKEN` used instead of `ACCESS_TOKEN` | Switch to `ACCESS_TOKEN` with PAT |66| "Could not find any self-hosted runner group named 'Default'" | Org uses different group name | Check groups via `gh api`, set `RUNNER_GROUP` |67| "Ephemeral option is enabled" when not wanted | `EPHEMERAL=0` — truthy in bash | Use `EPHEMERAL=false` (string) |68| `docker compose down -v` wipes credentials | Named volumes deleted | With `ACCESS_TOKEN`, auto-recovers |69| Runner can't see host filesystem paths | Runner runs inside Docker container | Write deploy configs inline in workflow |70| Hugo build: "Go not found" | No Go on Ubuntu 20.04 runner | `hugo mod vendor` and commit `_vendor/` |71| GHCR pull "unauthorized" | No Docker registry auth in deploy job | Add `docker/login-action@v4` |72| Runner offline >14 days | Auto-removed by GitHub | Register a new runner |7374## Sequential Workflow7576### 1. Choose deployment approach7778Read [deployment](references/deployment.md) and select systemd, Docker, ARC, or Scale Set Client.7980### 2. Figure out what runner scope you need8182- **Repo-level**: Runner scoped to a single repo — you need admin access83- **Org-level**: Runner shared across repos in an org — you need org owner access84- **Enterprise-level**: Runner shared across orgs in an enterprise — you need enterprise access8586### 3. Register the runner8788Read the [architecture](references/architecture.md) reference for the registration flow.8990### 4. Route jobs to the runner9192Use `runs-on` with labels and optionally groups. Read [management](references/management.md) labels section.9394### 5. Monitor and troubleshoot9596Read the [management](references/management.md) troubleshooting section when things go wrong.9798### 6. Plan for security and scaling99100Read [security](references/security.md) and [scaling](references/scaling.md) for production deployments.101102## Templates103104- [templates/docker-compose.yml](templates/docker-compose.yml) — Docker runner with `myoung34/github-runner`105- [templates/custom-runner.Dockerfile](templates/custom-runner.Dockerfile) — Custom runner image for ARC106107## Reference Files108109| File | Load when |110|------|-----------|111| [references/architecture.md](references/architecture.md) | You need to understand registration flow, job lifecycle, or runner communication |112| [references/deployment.md](references/deployment.md) | You need to deploy a runner — systemd, Docker, ARC, or Scale Set Client |113| [references/security.md](references/security.md) | You need to harden runners, set up ephemeral/JIT, configure groups |114| [references/scaling.md](references/scaling.md) | You need autoscaling — ARC, Scale Set Client, or webhook-driven |115| [references/management.md](references/management.md) | You need groups, labels, monitoring, troubleshooting, or cleanup |116| [references/custom-images.md](references/custom-images.md) | You need a custom runner Dockerfile, ARC Kubernetes mode |117| [references/network.md](references/network.md) | You need firewall rules, proxy config, or are troubleshooting connectivity |
magnus919