skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
magnus919/agent-skills123 installs

github-runner

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.

How do I install this agent skill?

npx skills add https://github.com/magnus919/agent-skills --skill github-runner
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubwarn

    This skill provides deployment resources and documentation for self-hosted GitHub Actions runners. Analysis identified that the provided templates include configurations for elevated system privileges, such as passwordless sudo access and host Docker socket mounting. While these are common in CI/CD environments for tasks like building container images, they represent significant security risks if the runner executes malicious code from untrusted pull requests. The skill also facilitates the download of runner software from GitHub's official repositories.

  • Socketwarn

    1 alert: gptSecurity

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

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

TriggerWhat 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

ApproachComplexityAutoscalingBest For
systemd serviceLowManualSingle machine, simple CI
Docker containerMediumManual replicasHomelab, small team
ARC (Kubernetes)HighBuilt-inTeams with K8s expertise
Scale Set ClientHighCustomNon-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).

TokenPurposeExpiry
ACCESS_TOKENRegistration — generates fresh tokens via GitHub APILong-lived (PAT)
RUNNER_TOKENDe-registration only — NOT for initial registration60 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

ProblemCauseFix
404 on POST to runner-registrationRUNNER_TOKEN used instead of ACCESS_TOKENSwitch to ACCESS_TOKEN with PAT
"Could not find any self-hosted runner group named 'Default'"Org uses different group nameCheck groups via gh api, set RUNNER_GROUP
"Ephemeral option is enabled" when not wantedEPHEMERAL=0 — truthy in bashUse EPHEMERAL=false (string)
docker compose down -v wipes credentialsNamed volumes deletedWith ACCESS_TOKEN, auto-recovers
Runner can't see host filesystem pathsRunner runs inside Docker containerWrite deploy configs inline in workflow
Hugo build: "Go not found"No Go on Ubuntu 20.04 runnerhugo mod vendor and commit _vendor/
GHCR pull "unauthorized"No Docker registry auth in deploy jobAdd docker/login-action@v4
Runner offline >14 daysAuto-removed by GitHubRegister 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

Reference Files

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

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/magnus919/agent-skills/github-runner">View github-runner on skillZs</a>