Actions Runner Controller (ARC) Setup Guide Using Kubernetes-cluster.

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