Run GitHub Actions on your Kubernetes cluster

If you are working with GitHub Actions, you are re probably already familiar with the concept of runners. Runners are the machines that execute jobs in a GitHub Actions workflow. For example, a runner can clone your repository locally, install testing software, and then run commands that evaluate your code.

You can have GitHub host and manage runners for you or you could choose to host your own runners “self-hosted runners”. Using self-hosted runners, offers more control of hardware, operating system, and software tools where you can create custom hardware configurations that meet your needs with processing power or memory to run larger jobs, install software available on your local network, and choose an operating system not offered by GitHub-hosted runners. Self-hosted runners also helps you meet regulatory and compliance requirements. They can be physical, virtual, in a container, on-premises, or in a cloud.

In this article, we are going to explore how you can host self-hosted runners in your Kubernetes clusters using the Actions Runner Controller (ARC).


NOTE I have an AKS (Azure Kubernetes Service) cluster that I will use to demonstrate hosting self-hosted runners but you can leverage any Kubernetes cluster.

To start using the Actions Runner Controller, there are some pre-requisites we need to prepare.

Create a GitHub personal access token with repo permissions on my GitHub account

Screenshot showing creating a personal access token on GitHub

We need to install cert-manager on our cluster

kubectl apply -f

Screenshot showing installing cert-manager using kubectl

We can now deploy the Actions Runner Controller on our cluster, I will use Helm to deploy it

helm repo add actions-runner-controller

helm upgrade --install --namespace actions-runner-system --create-namespace\
  --wait actions-runner-controller actions-runner-controller/actions-runner-controller

Screenshot showing adding helm repository

Screenshot showing installing actions runner controller using helm

Last step is to create a new self-hosted runner and configure it to run against our GitHub repository

Screenshot showing creating a github self-hosted runner configuration

In this yaml file, we are first creating a new self-hosted runner and registering it with my repository sebassem/actions-runners, then we are creating a horizontal runner scaler object to automatically scale our runners based on the PercentageRunnersBusy metric.

Let’s now apply this Kubernetes manifest to our cluster

Screenshot showing applying the github self-hosted runner configuration to our cluster

We can see that we have our runner deployed on the cluster

Screenshot showing running status for our runner

Screenshot showing running pods for our runner

Going back to GitHub, we can see that our runner has been successfully registered to our sebassem/actions-runners repository

Screenshot showing the runner registered on our repository

Finally, let’s put this setup to a test, I will create a very simple GitHub action to echo “Hello World”. You can see that I’ve selected the On property to be self-hosted so this action uses only self-hosted runners

Screenshot showing a github action

After the action has run successfully, we can see navigate to its logs to see that it has actually run on our self-hosted runner which runs on our Kubernetes cluster.

Screenshot showing the github action workflow steps

Screenshot showing the logs of the github action


  • To learn more about Actions Runner Controller (ARC), check out its docs
Share on:

You May Also Like