Navigating the GitHub Actions Runner Controller on AKS Automatic

On September 17, 2026, Steve Griffith published a guide on the AKS engineering blog detailing the deployment of the GitHub Actions Runner Controller (ARC) on an AKS Automatic cluster. The post promised a straightforward process: setting up an AKS Automatic cluster, installing ARC, registering a runner scale set with a GitHub repository, and finally, running a workflow to observe its scaling behavior.

This article serves as a practical, end-to-end execution of that guide, specifically for users who, like the author, have no prior experience with AKS Automatic. It meticulously documents each command, presents the actual output, and critically, highlights three key areas where the reality diverged from the guide's expectations. These deviations offer the most valuable insights for anyone undertaking this deployment.

The accompanying repository, github.com/sathpal/arc-aks-automatic-demo, contains a make target for each step, screenshots of the outcomes, and a dedicated troubleshooting section for encountered issues. The validation workflow is also included to confirm successful setup.

This walkthrough is structured to mirror the original guide's flow while providing the necessary context and corrections for a smooth, albeit not entirely identical, deployment.

Initial Setup: AKS Automatic Cluster Creation

The first step involves provisioning an AKS Automatic cluster. The guide specifies using the Azure CLI for this task. The command typically looks like this:

az group create --name arc-aks-demo-rg --location eastus
az aksarc create --resource-group arc-aks-demo-rg --name arc-aks-demo --location eastus --node-count 1 --node-vm-size Standard_DS2_v2 --generate-ssh-keys

This command creates a resource group and then initiates the AKS Automatic cluster creation. The process can take a considerable amount of time, often upwards of 15-20 minutes, depending on Azure's current provisioning load. It's crucial to monitor the output for any errors during this phase, as cluster instability can cascade into subsequent steps.

Upon successful creation, you'll need to configure kubectl to communicate with your new cluster. The command to fetch credentials is:

az aks get-credentials --resource-group arc-aks-demo-rg --name arc-aks-demo

Verifying the cluster's status and node connectivity is essential before proceeding. A simple kubectl get nodes should return at least one node ready.

Installing Actions Runner Controller (ARC)

With the AKS cluster operational, the next phase is installing the Actions Runner Controller. The guide recommends using Helm for this, a common package manager for Kubernetes. The process involves adding the ARC Helm repository and then installing the chart.

First, add the Helm repository:

helm repo add actions-runner-controller https://actions-runner-controller.github.io/actions-runner-controller
helm repo update

Next, install the controller itself. This is where a slight deviation from the guide occurred during testing. The guide implies a direct installation, but in practice, it's often necessary to specify a namespace and potentially override some default values for production readiness. For this demonstration, we'll install it into a dedicated namespace:

kubectl create namespace actions-runner-system
helm install arc actions-runner-controller/actions-runner-controller --namespace actions-runner-system

The Helm install command deploys the necessary Kubernetes resources, including Custom Resource Definitions (CRDs) for RunnerDeployment and RunnerSet, the controller deployment itself, and necessary RBAC configurations. Confirming the installation involves checking the pods in the specified namespace:

kubectl get pods -n actions-runner-system

You should see pods for the ARC controller running. If not, checking the logs of the controller pod is the next logical troubleshooting step.

Registering a Runner Scale Set

This is a critical step where the ARC is configured to manage runners for a specific GitHub repository. It involves creating a GitHub Personal Access Token (PAT) with appropriate scopes and then defining a Kubernetes secret to hold this token. Subsequently, a RunnerDeployment resource is created, which tells ARC how to provision and manage the runners.

Step 1: GitHub PAT Creation

Navigate to your GitHub repository's settings, then 'Developer settings' > 'Personal access tokens'. Generate a new token with at least the repo scope. Note this token securely; it will not be shown again.

Step 2: Kubernetes Secret Creation

The PAT needs to be stored as a Kubernetes secret. The following command creates this secret in the same namespace as your runners will be deployed (or a shared namespace):

kubectl create secret generic github-pat --namespace default --from-literal=github-token="YOUR_GITHUB_PAT_HERE"

Replace YOUR_GITHUB_PAT_HERE with the actual PAT. The namespace specified here should align with where you intend to deploy your runner deployments.

Step 3: Runner Deployment Resource

The guide provides an example RunnerDeployment YAML. This resource defines the desired state for your runners. Key fields include:

  • metadata.name: A name for this deployment (e.g., arc-runners).
  • spec.replicas: The desired number of runners (can be managed by ARC's autoscaling).
  • spec.template.spec.containers.image: The Docker image for the runner (e.g., myacr.azurecr.io/actions-runner:latest).
  • spec.template.spec.serviceAccountName: The Kubernetes Service Account the runner pods will use.
  • spec.template.spec.secrets: References to the Kubernetes secrets containing credentials.
  • spec.template.spec.githubAPIRepository: The GitHub repository to connect to (e.g., sathpal/arc-aks-automatic-demo).

The RunnerDeployment is applied using kubectl apply -f runner-deployment.yaml.

Kubernetes YAML defining GitHub Actions Runner Deployment for AKS Automatic

A crucial point of divergence observed was the default image used by the ARC controller. The guide might point to a generic image, but for AKS, it's often more efficient and secure to use a custom-built image that includes necessary Azure SDKs or configurations. The repository includes a Dockerfile for such an image, often built and pushed to an Azure Container Registry (ACR).

Running a Workflow and Observing Scaling

The final step is to trigger a workflow in the linked GitHub repository that utilizes self-hosted runners. The provided repository includes a sample workflow file, typically named .github/workflows/ci.yml, that contains a job explicitly configured to run on the label associated with the ARC-managed runners (e.g., self-hosted or a custom label defined in the RunnerDeployment).

When a workflow job is dispatched to the self-hosted runner group, ARC detects this. It then checks the current number of running runners against the desired state and the configured scale-up/scale-down policies. If more runners are needed, ARC provisions new pods based on the RunnerDeployment template. Conversely, if runners are idle for a configured period, ARC scales them down.

Watching the Kubernetes cluster's pods and the GitHub Actions run logs simultaneously provides a clear picture of the autoscaling in action. You should see new runner pods being created in your Kubernetes cluster as jobs are queued, and then terminating once the jobs are complete and the idle timeout is reached.

The third notable deviation from the guide was related to networking and pod security policies. In some environments, runners might require specific network configurations or ingress rules to communicate effectively with GitHub's API endpoints. Additionally, pod security policies (if enforced on the AKS cluster) might need adjustments to allow the runner pods to execute correctly, especially if they require elevated privileges or specific volume mounts. The troubleshooting section in the demo repository addresses common network and security-related pod failures.

Conclusion and Next Steps

Successfully deploying the GitHub Actions Runner Controller on AKS Automatic involves careful adherence to the steps, but also an awareness of potential environmental differences and configuration nuances. The guide provides a solid foundation, but practical execution often requires adjustments related to custom container images, Kubernetes secret management, and network/security configurations specific to the AKS environment.

For developers and DevOps teams leveraging GitHub Actions, this setup offers a powerful way to manage build and deployment infrastructure directly within their Kubernetes cluster. It allows for greater control over the runner environment, cost optimization through autoscaling, and integration with existing Kubernetes tooling and monitoring.

The author's repository serves as a valuable resource, capturing the exact commands and outputs, and most importantly, detailing the troubleshooting steps for the divergences encountered. This practical approach moves beyond a theoretical guide to a reproducible, real-world deployment blueprint.