# Actions Runner Controller — Self-Hosted GitHub Actions on Kubernetes

> Autoscale self-hosted GitHub Actions runners on Kubernetes, matching runner capacity to workflow demand with scale-to-zero support and ephemeral runner pods.

## Install

Save in your project root:

# Actions Runner Controller — Self-Hosted GitHub Actions on Kubernetes

## Quick Use
```bash
# Install ARC with Helm
helm install arc 
  --namespace arc-systems --create-namespace 
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller

# Deploy a runner scale set
helm install arc-runner-set 
  --namespace arc-runners --create-namespace 
  --set githubConfigUrl="https://github.com/ORG" 
  --set githubConfigSecret.github_token="ghp_xxx" 
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set
```

## Introduction
Actions Runner Controller (ARC) is a Kubernetes operator that manages self-hosted GitHub Actions runners. It automatically scales runner pods up and down based on pending workflow jobs, eliminating the need to maintain a fixed pool of idle VMs while keeping CI/CD jobs close to your infrastructure.

## What Actions Runner Controller Does
- Provisions ephemeral GitHub Actions runner pods on Kubernetes in response to queued workflow jobs
- Scales runner replicas from zero to the configured maximum based on real-time job demand
- Supports organization-level, repository-level, and enterprise-level runner groups
- Cleans up runner pods after each job completes, ensuring a fresh environment for every workflow run
- Integrates with GitHub's official runner scale set API for reliable job assignment

## Architecture Overview
ARC consists of two Helm charts: a controller that watches for pending GitHub Actions jobs, and runner scale sets that define the runner template and scaling parameters. The controller registers with GitHub as a listener for workflow job events. When a job is queued that matches a scale set's labels, the controller creates a runner pod from the configured template. The pod registers itself as a GitHub runner, executes the job, and then terminates. A metrics-based autoscaler adjusts the replica count based on the ratio of pending jobs to available runners.

## Self-Hosting & Configuration
- Install the controller and at least one runner scale set using the official Helm charts from ghcr.io
- Authenticate using a GitHub App (recommended) or a personal access token with repo and admin:org scopes
- Customize the runner pod template with init containers, volume mounts, and resource requests for specialized workloads
- Configure Docker-in-Docker or Kubernetes mode for container actions that need to build images inside the runner
- Set minRunners and maxRunners on each scale set to control autoscaling bounds and cost

## Key Features
- Scale-to-zero eliminates idle runner costs by terminating all pods when no jobs are pending
- Ephemeral runners ensure each workflow job runs in a clean pod, preventing state leakage between jobs
- Runner groups and labels route specific workflows to specialized runner scale sets with GPUs, ARM architecture, or custom toolchains
- Kubernetes-native runner mode executes each job step in a separate container within the pod, avoiding Docker-in-Docker overhead
- Helm-based deployment integrates with GitOps tools like Argo CD and Flux for declarative runner management

## Comparison with Similar Tools
- **GitHub-hosted runners** — zero maintenance but limited customization and network access; ARC runs on your own infrastructure with full control
- **Self-hosted VM runners** — static VMs that must be pre-provisioned; ARC autoscales pods and cleans up after each job
- **Buildkite** — SaaS CI with self-hosted agents; ARC is free, open-source, and tightly integrated with GitHub Actions workflows
- **GitLab Runner** — autoscales on Kubernetes for GitLab CI; ARC does the same specifically for GitHub Actions
- **Jenkins** — general-purpose CI server; ARC provides native GitHub Actions compatibility without maintaining a separate CI system

## FAQ
**Q: Does ARC require a GitHub Enterprise account?**
A: No. ARC works with GitHub.com free and paid plans, as well as GitHub Enterprise Server and Enterprise Cloud.

**Q: How does scale-to-zero work?**
A: When no jobs are pending, the controller scales the runner scale set to zero replicas. New pods are created within seconds when a matching job is queued.

**Q: Can I use Docker inside ARC runners?**
A: Yes. Configure the runner pod with Docker-in-Docker (DinD) sidecar or use Kubernetes mode, which runs each step as a separate container without requiring a Docker daemon.

**Q: What is the difference between ARC and the legacy actions-runner-controller?**
A: The current ARC (gha-runner-scale-set) is the officially supported version maintained by GitHub. The legacy summerwind/actions-runner-controller is a community project that is no longer recommended.

## Sources
- https://github.com/actions/actions-runner-controller
- https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller

---
Source: https://tokrepo.com/en/workflows/d51337a6-3de4-11f1-9bc6-00163e2b0d79
Author: AI Open Source