Hosting Self-Hosted GitHub Runners on Kubernetes

In the world of Continuous Integration and Continuous Deployment (CI/CD), GitHub Actions has emerged as a powerful tool, enabling developers to automate their workflows and streamline their software development process. GitHub Actions offers a range of features that help in automating tasks such as building, testing, and deploying code. While GitHub provides hosted runners to execute these workflows, there are scenarios where using a self-hosted runner might be more advantageous.

Self-hosted runners give you the flexibility to configure your build environment exactly as you need it. Whether you require specific hardware, custom software, or a particular environment configuration, self-hosted runners allow you to tailor your CI/CD pipeline to meet these needs. Hosting a self-hosted GitHub Runner on Kubernetes can further enhance this setup by leveraging the scalability, reliability, and resource management features of Kubernetes.

In this blog post, we'll walk you through the process of setting up a self-hosted GitHub Runner on a Kubernetes cluster. By the end of this guide, you’ll have a fully operational GitHub Runner running within your Kubernetes environment, ready to execute your CI/CD workflows.

Prerequisites

Before diving into the setup, make sure you have the following prerequisites in place:

Kubernetes Cluster: You’ll need access to a Kubernetes cluster. This can be a local cluster (like Minikube) or a cloud-based Kubernetes service (such as Google Kubernetes Engine, Azure Kubernetes Service, or Amazon EKS).

GitHub Repository: Ensure you have a GitHub repository where you want to set up Actions. If you don’t have one, you can create a new repository on GitHub.

Helm: Helm is a package manager for Kubernetes that simplifies deploying applications. We’ll use Helm to manage the GitHub Runner deployment.

Configure Self-Hosted Runner:

• Open Developer Settings and from GitHub Profile

• Create a new GitHub App

• Provide the GitHub App Name

• Provide the Website URL for the GitHub App

• Uncheck the Webhook URL, we are not going to expose GitHub Jobs over the internet as per industry standard.

• Expand the Repository permissions and provide Read access to the Actions and Read and Write access to the Administration.

• Provide the account in that GitHub app will be installed and click on create GitHub app.

• Copy the APP ID, Client ID and save it somewhere.

• Scroll down and Generate the a private key and save it in the local.

• Open the tab called Install App and install the app.

• You can choose any specific repo or all repo and install the app

• After installation there will be unique ID in the URl copy the ID and save it for the further use.

• Open the Kubernetes Cluster CLI and follow below commands.

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm search repo cert-manager

• Use the latest version of cert-manager for below command

helm install \
cert-manager jetstack/cert-manager \
--namespace=NAMESPACE-NAME \
--create=namespace \
--version=LATEST-VERSION \
--set prometheus.enabled=false \
--set isntallCRDs=true

• Check the pods are up and running for cert-manager.

kubectl get pods -n NAMESPACE-NAME

• Create a Kubernets secret for the runner.

kubectl create secret generic controller-manager\
-n actions \
--from-literal=github_app_id=APP-ID \
--from-literal=github_app-installation_id=UNIQUE-ID \
--from-literal=fiirhub_app_private_key=PRIVATE-KEY-FILE

• Add helm repo to manage actions.

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

helm search repo actions

• Install the helm repo with the latest version

helm install runner \
actions-runner-controller/actions-runner-controller \
--namespace actions \
--version LATEST-VERSION \
--set syncPeriod=1m

• Check the actions pods are up and running or not with the below command.

kubectl get pods -n actions

• Apply the below Kubernetes yaml file to deploy runner.

apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
  name: arc-runner
  namespace: default
spec:
  template:
    spec:
      repository: # specify name of the repository
      labels:
        - # runner label

kubectl apply -f runnerdeployment.yaml

• For autoscaling of the runner apply below kubernetes yaml file.

apiVersion: actions.summerwind.dev/v1alpha1
kind: HorizontalRunnerAutoscaler
metadata:
  name: k8s-runner-autoscaler
spec:
  scaleTargetRef:
    kind: RunnerDeployment
    name: k8s-runners
  scaleDownDelaySecondsAfterScaleOut: 300
  minReplicas: 1
  maxReplicas: 10
  metrics:
  - type: TotalNumberOfQueuedAndInProgressWorkflowRuns
    repositoryNames:
    - # specify name of the repository

kubectl apply -f hpa.yaml

• After following all the above steps edit the workflow file from GitHub and change the tag runs-on to self-hosted.

Like this you can configure Self-hosted runners for the GitHub.

Thank you for reading the blog!
Content Copyright reserved by Author Harsh Viradia.
Contact: https://www.linkedin.com/in/harsh-viradia/

Comments

[King Triton]

Wow, this guide is incredibly comprehensive! I've been considering setting up a self-hosted GitHub Runner on Kubernetes for a while now, and this step-by-step walkthrough is exactly what I needed. The detailed instructions on configuring the runner and autoscaler will save me a ton of time. Kudos to Harsh Viradia for putting together such a clear and informative post! Time to roll up my sleeves and get to work. 🚀

[Harsh Viradia]

Thank you King Triton, I am glad that my blog helped you.