Actions Runner Controller (ARC)
This guide explains how to set up GitHub Actions Runner Controller (ARC) in a Kubernetes cluster.
Prerequisites
- Kubernetes cluster
- kubectl installed and configured
- GitHub Personal Access Token (PAT) with repo and workflow permissions
Installing Helm (if not installed)
curl https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 | bash
Quick Setup
Install ARC Controller
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
Create namespace and install controller
helm install arc \
--namespace arc-systems \
--create-namespace \
oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller
# Verify installation
kubectl get pods -n arc-systems
Create GitHub PAT
Go to GitHub → Settings → Developer Settings → Personal Access Tokens
Create new token with repo and workflow permissions
Save the token securely
Install Runner Set
# Set your GitHub details
export GITHUB_CONFIG_URL="https://github.com/YOUR_USERNAME/YOUR_REPO"
export GITHUB_PAT="your_pat_here"
# Install runner set
helm install arc-runner-set \
--namespace arc-runners \
--create-namespace \
--set githubConfigUrl="${GITHUB_CONFIG_URL}" \
--set githubConfigSecret.github_token="${GITHUB_PAT}" \
oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-
scale-set
Using in GitHub Actions
In your workflow file (.github/workflows/example.yml)
name: My Workflow
on: [push]
jobs:
build:
runs-on: arc-runner-set
steps:
- uses: actions/checkout@v2
- run: echo "Hello from self-hosted runner!"
Verification
Check if everything is running:
kubectl get pods -n arc-systems
kubectl get pods -n arc-runners
Your runner should appear online in your GitHub repository under Settings → Actions → Runners.
In Another workflow file (.github/workflows/example.yml)
name: CI Pipeline
on:
push:
branches:
- main
pull_request:
branches:
- main
jobs:
# Build Job
build:
runs-on: arc-runner-set
steps:
- name: Check out code
uses: actions/checkout@v2
- name: Build Application
run: echo "Building application..."
# Test Job
test:
runs-on: arc-runner-set
needs: build
steps:
- name: Check out code
uses: actions/checkout@v2
- name: Run Tests
run: echo "Running tests..."
# Lint Job
lint:
runs-on: arc-runner-set
needs: build
steps:
- name: Check out code
uses: actions/checkout@v2
- name: Lint Code
run: echo "Linting code..."
# Deploy Job
deploy:
runs-on: arc-runner-set
needs: [build, test, lint]
steps:
- name: Check out code
uses: actions/checkout@v2
- name: Deploy Application
run: echo "Deploying application..."
Possible outputs:
Troubleshooting
If runners show as offline:
Check runner pods: kubectl get pods -n arc-runners
View logs: kubectl logs -n arc-runners <pod-name>
Verify PAT permissions and expiration
Ensure correct repository URL in configuration
Check Namespace and Pod Status
Ensure both namespaces, arc-systems and arc-runners, are created and pods are running without errors.
Run:
kubectl get pods -n arc-systems
kubectl get pods -n arc-runners
If any pods are in a CrashLoopBackOff or Error state, inspect their logs for errors:
kubectl logs <pod-name> -n arc-systems
kubectl logs <pod-name> -n arc-runners
Cleanup
To remove ARC:
helm uninstall arc-runner-set -n arc-runners
helm uninstall arc -n arc-systems
Top comments (0)