The Complete Production SOP: How to Deploy and Run Actions Runner Controller (ARC) Autoscaling on Kubernetes in Autonomous AI Agents
Deploy Actions Runner Controller (ARC) autoscaling on Kubernetes with AI agents in Claude Code, Codex, and Cursor. Complete SOP with Helm and CRD manifests.
Technical Overview & Architectural Context
Autonomous coding agents frequently fail when configuring self-hosted continuous integration runners inside Kubernetes. They hallucinate legacy ARC deployments (using the deprecated runner-deployment CRD rather than modern AutoscalingRunnerSet), mishandle mutual TLS and ephemeral pod lifecycles, and place GitHub App private keys directly into git-tracked configuration files. Without deterministic boundaries, agents also generate invalid Kubernetes Helm values that lead to scale-listener crash loops and unmanaged orphaned pods. The 'runner-scale-set-gha-kubernetes' skill enforces strict procedural guardrails for AI agents operating across Codex, Claude Code, Cursor, and Windsurf. By constraining agent outputs to modern OCI Helm charts (oci://ghcr.io/actions/actions-runner-controller-charts/*), isolating secret provisioning to dedicated Kubernetes Secret manifests, and setting explicit 0-to-N autoscaling boundaries, this skill eliminates runtime hallucinations and ensures deterministic, production-grade GitHub Actions runner autoscaling.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the verified ARC autoscaling skill into the agent runtime directory.
Create the local skill manifest hierarchy inside your project or user agent directory. Autonomous agents scan ~/.agents/skills or project-level .cursor/skills/ to register deterministic procedural capabilities before processing infrastructure requests.
mkdir -p .agents/skills/runner-scale-set-gha-kubernetes && curl -fsSL https://askills.dev/api/skills/runner-scale-set-gha-kubernetes/raw -o .agents/skills/runner-scale-set-gha-kubernetes/SKILL.md---
name: "runner-scale-set-gha-kubernetes"
description: "Autoscale ephemeral, self-hosted GitHub Actions runners inside Kubernetes clusters with ARC."
metadata:
author: "Actions"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "install actions runner controller arc"
- "autoscalingrunnerset kubernetes"
- "self-hosted gha runners"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Store the skill in the workspace root at `.agents/skills/` so both Cursor agent mode and Claude Code CLI pick up the exact same triggers without context bloat.
The skill enforces `shell_exec: false` by default; ensure your agent generates verifiable Helm charts and YAML manifests rather than attempting unauthorized in-cluster command execution.
GitHub App Secret & Helm Repository Validation
Configure runner credentials and reference official OCI charts safely without embedding keys.
ARC requires three parameters to establish listener connectivity: GitHub App ID, Installation ID, and Private Key. Enforce the creation of an isolated namespace (`arc-runners` and `arc-systems`) and create the Kubernetes secret before running scale-set installations.
kubectl create namespace arc-systems && kubectl create namespace arc-runners && kubectl create secret generic arc-github-app-secret -n arc-runners --from-literal=github_app_id="${GITHUB_APP_ID}" --from-literal=github_app_installation_id="${GITHUB_APP_INSTALLATION_ID}" --from-file=github_app_private_key="/path/to/private-key.pem"githubConfigUrl: "https://github.com/my-enterprise-org"
githubConfigSecret: "arc-github-app-secret"
minRunners: 0
maxRunners: 25
containerMode:
type: "dind"
template:
spec:
containers:
- name: runner
image: "ghcr.io/actions/actions-runner:latest"
command: ["/home/runner/run.sh"]
resources:
limits:
cpu: "4"
memory: "8Gi"
requests:
cpu: "1"
memory: "2Gi"Instruct the agent to use `containerMode: dind` only when jobs require Docker-in-Docker to prevent security vulnerabilities and privileged container proliferation.
Never allow the agent to echo raw GitHub App private keys inside `.env` or commit them into Helm values; reference existing Kubernetes secrets exclusively.
Triggering ARC Autoscaling Deployment via Natural Language
Execute the procedural skill using tested deterministic triggers in Claude Code or Codex.
Provide high-precision prompts referencing the explicit trigger phrases declared in the SKILL.md frontmatter to ensure deterministic SOP execution across all runtimes.
claude "install actions runner controller arc and deploy autoscalingrunnerset kubernetes for organization my-enterprise-org with scale-to-zero"# Deploy ARC Controller Pod
helm install arc-controller \
oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller \
--namespace arc-systems \
--create-namespace
# Deploy Ephemeral Runner Scale Set
helm install enterprise-runner-set \
oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set \
--namespace arc-runners \
--values helm/arc-values.yamlExplicitly prompt the agent with 'verify minRunners: 0' to prevent cost overruns on idle Kubernetes worker nodes.
The new ARC architecture requires both the controller and listener; deploying only the scale-set listener without the gha-runner-scale-set-controller results in unmanaged CRDs.
Verification, Linting & Ephemeral Scale-Set Gate
Run automated YAML validation and verify listener registration with GitHub Actions.
Before accepting generated manifests, ensure your agent validates the Kubernetes CRDs using kubeconform and inspects workflow runs-on targeting.
kubectl get autoscalingrunnersets.actions.github.com -n arc-runners && kubectl get pods -n arc-systemsname: CI Pipeline
on: [push]
jobs:
build:
runs-on: enterprise-runner-set
steps:
- uses: actions/checkout@v4
- name: Verify Kubernetes Runner
run: |
uname -a
echo "Successfully executed on ephemeral ARC pod!"Use `kubeconform -summary -ignore-missing-schemas helm/arc-values.yaml` in your agent verification pipeline to catch syntax bugs before cluster application.
The `runs-on` label in GitHub Actions workflow files must match the Helm release name (`enterprise-runner-set`) exactly, not the namespace or pod name.
Real-World Scenario: Deploying Ephemeral GHA Autoscaling Runners for a High-Throughput Monorepo
“Set up self-hosted gha runners using actions runner controller arc in our EKS cluster. I need ephemeral pods that autoscale from 0 up to 30 workers for our GitHub organization 'fintech-core', authenticated via an existing secret 'arc-github-app-secret'. Generate the Helm values and verified workflow example.”
Runtime Troubleshooting & Failure Modes
Root Cause: Agent hallucinated outdated Helm repo URLs or missed logging in to the GitHub Container Registry (ghcr.io) OCI endpoint.
helm install enterprise-runner-set oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set --namespace arc-runners --values helm/arc-values.yaml --version 0.9.3Root Cause: The GitHub App Private Key, App ID, or Installation ID in the referenced Kubernetes Secret does not match the organization target.
kubectl delete secret arc-github-app-secret -n arc-runners && kubectl create secret generic arc-github-app-secret -n arc-runners --from-literal=github_app_id="$CORRECT_APP_ID" --from-literal=github_app_installation_id="$CORRECT_INSTALLATION_ID" --from-file=github_app_private_key="./private-key.pem" && kubectl rollout restart deployment -n arc-runnersFrequently Asked Questions (Actions Runner Controller (ARC) Autoscaling on Kubernetes SOP)
Q:Can I use Actions Runner Controller (ARC) Autoscaling on Kubernetes across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. By storing this file in `.agents/skills/runner-scale-set-gha-kubernetes/SKILL.md` or linking it to runtime-specific skill folders, Codex, Claude Code, Cursor, and Windsurf can read the procedural rules and trigger instructions natively.
Q:How does Actions Runner Controller (ARC) Autoscaling on Kubernetes prevent context window overflow during long agent sessions?
The skill provides tight procedural rules and minimal manifest structures instead of passing entire Helm documentation pages to the LLM. It limits agent actions to workspace file creation and outputs deterministic values files, saving up to 80% of context tokens during CI/CD infrastructure generation.
Q:Does this skill require escalated root or container permissions?
No. The skill runs with a security score of 98/100 with `fs_read: true`, `fs_write: 'workspace'`, `shell_exec: false`, and `net_access: false`. It instructs the agent to create Helm values and configuration manifests locally; cluster deployment commands are output for human or controlled CI execution rather than unmonitored runtime execution.
Ready to equip your autonomous agent with Actions Runner Controller (ARC) Autoscaling on Kubernetes?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.