Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
In this guide, you deploy a highly available GitHub Actions controller and self-hosted agents running on Azure Kubernetes Service (AKS). The self-hosted runners use SMB Azure file shares for persistent storage.
Important
Open-source software is mentioned throughout AKS documentation and samples. Software that you deploy is excluded from AKS service-level agreements, limited warranty, and Azure support. As you use open-source technology alongside AKS, consult the support options available from the respective communities and project maintainers to develop a plan.
For example, the Ray GitHub repository describes several platforms that vary in response time, purpose, and support level.
Microsoft takes responsibility for building the open-source packages that we deploy on AKS. That responsibility includes having complete ownership of the build, scan, sign, validate, and hotfix process, along with control over the binaries in container images. For more information, see Vulnerability management for AKS and AKS support coverage.
What is Actions Runner Controller (ARC)?
Actions Runner Controller (ARC) is a Kubernetes operator that orchestrates and scales self-hosted runners for GitHub Actions. ARC relies on persistent volumes (PVs) to share job information between the runner pod and the container job pod. For more information, see About Actions Runner Controller.
Why use self-hosted GitHub Actions on AKS?
Self-hosting GitHub Actions runners on AKS provides organizations with greater control, scalability, and security over their CI/CD infrastructure. Instead of relying on GitHub-hosted runners, which are shared and ephemeral, self-hosted runners offer:
- Custom environments: Tailor runners to match specific build, test, or deployment requirements.
- Performance gains: Leverage persistent storage and caching to reduce build times and improve reliability.
- Cost efficiency at scale: Dynamically scale runners within your own infrastructure, optimizing for frequent or long-running workflows.
- Enhanced security & isolation: Maintain full control over infrastructure and data, which is ideal for regulated industries or sensitive workloads.
Common use cases
- Enterprise CI/CD pipelines: For teams needing consistent, secure, and scalable build environments.
- Large monorepos or ML pipelines: Where caching or artifact persistence is critical.
- Performance optimization: Using Azure Files premium SMB shares to reduce metadata latency and increase IOPS.
Prerequisites
- This guide assumes a basic understanding of core Kubernetes concepts.
- You need the Owner or User Access Administrator and the Contributor Azure built-in roles on a subscription in your Azure account.
You can use the local Azure CLI.
If you prefer, install the Azure CLI to run CLI reference commands.
Local Azure CLI, see how to install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
Sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.
- You need an active GitHub account. Refer to the pricing information based on your repository control.
- You need the following resources installed:
- Azure CLI version 2.56 or later.
- Azure Kubernetes Service (AKS) preview extension.
- jg version 1.5 or later.
- kubectl version 1.21.0 or later.
- openssl version 3.3.1 or later.
- Visual Studio Code or another code editor of your choice.
Deployment process
In this guide, you learn how to:
- Use Azure CLI to create a multizone AKS cluster.
- Deploy an Azure file share to use in AKS persistent volumes.
- Install the GitHub Actions Runner Controller (ARC) on AKS.
- Install an ARC runners scale set and mount the file share on AKS.
- Run a sample workflow using GitHub Actions.
Deployment architecture
This reference architecture illustrates how to implement a GitHub Actions self-hosted runner solution using AKS and Azure File Share (SMB). The solution enables organizations to execute GitHub workflow jobs securely within their own Azure infrastructure while maintaining efficient storage management and scalability.
The architecture consists of three main components:
- GitHub integration layer: Connects workflows from GitHub repositories to your Azure infrastructure.
- AKS orchestration layer: Manages the containerized runner instances and their lifecycle.
- Storage layer: Provides persistent and ephemeral storage capabilities for runners.
GitHub integration layer
The GitHub integration layer connects workflows from GitHub repositories to your Azure infrastructure. Workflow jobs are dispatched from GitHub via api.github.com and githubusercontent.com to self-hosted runners.
AKS cluster orchestration layer
The AKS cluster orchestration layer manages the containerized runner instances and their lifecycle. The cluster is split into two namespaces: arc-controller and arc-runners.
arc-controller manages runner infrastructure and job listeners. arc-runners handles secrets, access control, and runner pods. Runners are containerized, use ephemeral storage, and connect to shared and dedicated volumes.
Storage layer
The Azure File Shares storage layer provides both NuGet file share with ReadWriteMany access for shared dependencies and ephemeral storage for runners, all backed by persistent volume claims.
Next step
Contributors
Microsoft maintains this article. The following contributors originally wrote it:
- Jorge Arterio | Senior Cloud Advocate
- Jeff Patterson | Principal Product Manager
- Rena Shah | Senior Product Manager
- Shekhar Singh Sorot | Product Manager 2
- Erin Schaffer | Content Developer 2