Setting Up a Self-Hosted GitHub Action Runner on Kubernetes: A Comprehensive Guide

GitHub Actions provide powerful automation capabilities directly integrated into GitHub repositories. Setting up a self-hosted GitHub Action runner on Kubernetes offers flexibility and scalability for running continuous integration and deployment workflows tailored to specific needs.

A self-hosted GitHub Action runner is a customizable environment where developers can run GitHub Actions workflows. Unlike GitHub-hosted runners, self-hosted runners provide greater control over the execution environment, allowing for the installation of specific software, dependencies, and configurations tailored to project needs. These runners can be deployed on local machines, virtual machines, or in cloud environments, such as Kubernetes clusters, offering scalability and resource management benefits. Utilizing self-hosted runners can also help manage costs by leveraging existing infrastructure and can enhance security by keeping sensitive code and data within a controlled environment. This flexibility and control make self-hosted runners an attractive option for teams with specific CI/CD requirements.

The Given steps mentioned below are on a high level understanding purpose. This will fulfil the basic requirement to setup a self-hosted GitHub runner on Kubernetes. The Actual requirement and workflow may vary from case to case.

Introduction

I recently set up a self-hosted GitHub Action Runner on Kubernetes using the Action Runner Controller. GitHub Actions enable automating workflows, such as CI/CD pipelines, directly within GitHub repositories. By setting up a self-hosted runner on Kubernetes, you can leverage Kubernetes' orchestration capabilities to manage and scale your runner environment efficiently.

Prerequisites

Before starting, ensure you have:

- A GitHub account and repository where the self-hosted runner will be integrated.

- Access to a Kubernetes cluster (e.g., Azure Kubernetes Service, Google Kubernetes Engine) with kubectl configured.

- Basic understanding of Kubernetes concepts and command-line interface (CLI).

Step 1: Setting Up Kubernetes

First, you need to set up a Kubernetes cluster if you haven't already. To create and configure your Kubernetes environment.

1. Create a Kubernetes Cluster: Using your cloud provider (e.g., AKS, GKE), create a Kubernetes cluster where you'll deploy the self-hosted runner. Below is example for Azure Kubernetes Service.

az aks create --resource-group myResourceGroup --name myAKSCluster --node-count 3 --enable-addons monitoring --generate-ssh-keys        

az aks get-credentials --resource-group myResourceGroup --name myAKSCluster        

2. Install kubectl and Helm: Helm is a package manager for Kubernetes that simplifies deploying and managing applications.

Step 2: Installing GitHub Actions Runner Controller

The GitHub Actions Runner Controller manages the lifecycle of GitHub self-hosted runners on Kubernetes.

1. Clone the Action Runner Controller Repository:

git clone https://github.com/actions/actions-runner-controller.git
cd actions-runner-controller           

This clones the repository containing the action runner controller.

2. Install CustomResourceDefinition and Controller:

kubectl create -f https://github.com/actions/actions-runner-controller/releases/download/v0.22.0/actions-runner-controller.yaml        

This applies the necessary CustomResourceDefinition (CRD) and installs the controller in your cluster.

3. Create a Namespace for the Runner:

kubectl create namespace actions-runner-system        

Step 3: Configuring GitHub Authentication

To authenticate with GitHub, you'll need to create a GitHub Personal Access Token (PAT) and store it securely in Kubernetes:

1. Generate GitHub PAT: Navigate to GitHub > Settings > Developer settings > Personal access tokens > Generate new token with repo scope.

2. Create Kubernetes Secret: Store the GitHub PAT as a Kubernetes secret.

kubectl create secret generic github-secret --namespace actions-runner-system --from-literal=token=YOUR_GITHUB_PAT        

Step 4: Creating Ephemeral Runner Deployment

Ephemeral runners allow dynamic scaling based on workload demands. Define the runner configuration in a Kubernetes manifest file (ephemeral-runner-set.yaml):

apiVersion: actions.summerwind.dev/v1alpha1
kind: EphemeralRunnerSet
metadata:
  name: example-ephemeral-runner-set
  namespace: actions-runner-system
spec:
  repository: your-username/your-repo-name
  template:
    spec:
      image: summerwind/actions-runner:latest
      resources:
        limits:
          cpu: "1"
          memory: "1Gi"
      env:
        - name: RUNNER_SCALE_SET_NAME
          value: "example-ephemeral-runner-set"        

Replace your-username/your-repo-name with your GitHub repository details.

Apply the configuration to your Kubernetes cluster:

kubectl apply -f ephemeral-runner-set.yaml        

Step 5: Setting Up Autoscaling

Configure Horizontal Pod Autoscaler (HPA) to automatically scale runner instances based on CPU utilization:

kubectl autoscale deploy/example-ephemeral-runner-set --cpu-percent=50 --min=1 --max=10        

Adjust --cpu-percent, --min, and --max values as per your workload requirements.

Step 6: Running Workflows

Create a GitHub Actions workflow file (e.g., .github/workflows/ci.yml) in your repository:

name: CI Workflow
on: [push]
jobs:
  build:
    runs-on: self-hosted
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v2
      - name: Build and Test
        run: |
          npm install
          npm test        

Commit and push the workflow file to your GitHub repository. Monitor workflow execution and view logs in the GitHub Actions tab.

Conclusion

By following this guide, we've successfully set up a self-hosted GitHub Action runner on Kubernetes. This setup enhances your CI/CD workflows with scalability, flexibility, and control over execution environments. For further customization or troubleshooting, refer to GitHub and Kubernetes documentation.

Start automating your workflows efficiently with GitHub Actions and Kubernetes!