Here’s a GitHub Self-Hosted Runners FAQ you can use as a quick reference or to share with your team:

---

GitHub Self-Hosted Runners – FAQ

1. What is a self-hosted runner?

A self-hosted runner is a machine you set up and maintain that runs GitHub Actions workflows. Unlike GitHub-hosted runners (ephemeral, managed by GitHub), self-hosted runners give you full control over hardware, OS, network, and installed tools.

---

2. Why use a self-hosted runner?

• Custom environments – install specific tools, SDKs, or dependencies.
• Private networking – access to internal systems (databases, APIs).
• Cost optimization – avoid GitHub’s per-minute billing on hosted runners.
• Performance – use faster hardware, GPUs, or larger memory machines.
• Compliance/security – keep builds and data within your controlled environment.

---

3. Where can I install self-hosted runners?

• On-prem servers
• VMs (AWS, Azure, GCP, etc.)
• Kubernetes clusters (via Actions Runner Controller – ARC)
• Even edge devices (Raspberry Pi, ARM systems, etc.)

---

4. How do I register a self-hosted runner?

1. Go to your GitHub repository / org / enterprise → Settings → Actions → Runners.
2. Click New self-hosted runner, select OS/arch, and copy the registration token + command.
3. Run the commands on your machine: ./config.sh --url https://github.com/<org>/<repo> --token <TOKEN> ./run.sh
4. (Optional) Install as a service for automatic startup.

---

5. Are self-hosted runners shared across repos?

• Repository-level – runner only available for that repo.
• Organization-level – available to all repos in the org.
• Enterprise-level – available to all orgs in an enterprise account.

---

6. Do self-hosted runners scale automatically?

• By default, no – each runner is static.
• For scaling, use:
  • Actions Runner Controller (ARC) on Kubernetes.
  • Cloud autoscaling scripts (start/stop VMs).
  • Third-party solutions (Terraform modules, GitHub Actions Runner Scale Sets).

---

7. How do I secure self-hosted runners?

• Run in ephemeral mode (one job per runner, auto-cleanup).
• Use network isolation (VPC, firewall rules).
• Regularly patch OS and dependencies.
• Restrict access via labels (only trusted workflows can target runners).
• Store secrets in GitHub Secrets or HashiCorp Vault, not on the runner itself.

---

8. What OS and architectures are supported?

• Linux (x64, ARM64, ARM32)
• Windows (x64)
• macOS (x64, ARM64/Apple Silicon)
• Experimental: custom builds for other archs

---

9. Can I use Docker with self-hosted runners?

Yes. Options:

• Run jobs inside Docker containers on the runner.
• Run the runner itself inside a container.
• Use Kubernetes + ARC for containerized scaling.

---

10. How does billing work?

• No runner usage fees from GitHub.
• You pay only for the infrastructure where the runner runs (your VM, on-prem server, etc.).
• Still subject to GitHub Actions limits (e.g., job concurrency per plan).

---

11. What happens if a runner goes offline?

• GitHub marks it as offline.
• Jobs targeting that runner will stay queued until it comes back, or until another matching runner picks them up.
• Use monitoring (Prometheus, Datadog, GitHub webhooks) for health checks.

---

12. Best practices?

• Use ephemeral runners for untrusted repos.
• Tag runners with labels (linux, gpu, arm, prod).
• Automate runner lifecycle with IaC (Terraform, Ansible).
• Keep secrets & credentials external.
• Monitor and auto-replace unhealthy runners.

---

When you ask, “What are the status of GitHub self-hosted runner”, you’re likely curious about what runner statuses exist and how to check or interpret them.

---

Runner Status Types

GitHub supports three main statuses for self-hosted runners:

• Idle – Runner is connected to GitHub and is ready to take on jobs.
• Active – Runner is currently executing a job.
• Offline – Runner is not connected (e.g. machine down, runner application stopped, or communication issue) (GitHub Docs).

These statuses are visible in the GitHub UI under Settings → Actions → Runners, whether at the repository, organization, or enterprise level (GitHub Docs).

---

How to Check Status via GitHub REST API

You can also retrieve runner status programmatically using GitHub’s REST API:

• For a repository –
  GET /repos/{owner}/{repo}/actions/runners
  The response includes each runner’s status (e.g., online, offline) along with details like id, name, os, and whether it’s busy (GitHub Docs, Orchestra).
• For an organization –
  GET /orgs/{org}/actions/runners
  Returns similar details across all runners in the organization (GitHub Docs, Orchestra).

The REST API status field may use slightly different terminology (e.g. online or offline) but maps directly to the UI’s Idle, Active, or Offline states.

---

Health & Connectivity Checks

To further troubleshoot or check connectivity:

• Run the runner’s config script with --check, supplying --url and --pat, to validate network access to GitHub and see PASS/FAIL outputs (GitHub Docs).
• On the runner machine:
  • Linux/systemd: sudo journalctl -u actions.runner.<org>-<repo>.<runnerName>.service -f
  • **macOS/**launchd or Windows/PowerShell: use system service tools to check the service state or logs (GitHub Docs).

---

Summary Table

Status Source	Status Value	Meaning
GitHub UI	Idle	Runner connected and ready
GitHub UI	Active	Runner currently executing a job
GitHub UI	Offline	Runner disconnected or unreachable
REST API (status)	online/offline	Corresponds to Idle or Offline
Runner service tools/logs	–	Indicate if the runner service is running or encountering errors

---