Self-Hosted GitHub Actions Runner on Kubernetes Using Helmfile

Introduction

When it comes to automating your CI/CD pipelines, GitHub Actions is a great tool. But what if you want more control over your environment? That's where a self-hosted GitHub Actions runner comes in.

Self-hosted github actions runner allows you to run the builds inside your infrastructure, within your private network in an environment of your choice.

In this post, we'll walk you through setting up a self-hosted runner on Kubernetes using Helmfile.

Why Choose a Self-Hosted GitHub Actions Runner?

GitHub Actions is a powerful way to automate tasks in your projects. However, sometimes you might need more control over the environment where your workflows run. A self-hosted runner lets you use your own infrastructure, which can help with cost management, customization, and keeping your data secure.

Kubernetes makes managing these runners easier. It allows you to scale your setup according to your needs, and with Kubernetes, you can keep your runners running smoothly.

Prerequisites

Before we start, you’ll need a few things:

1. A Kubernetes Cluster: Make sure you have access to a Kubernetes cluster. This is where your runner will be deployed.
2. Helm and Helmfile Installed: Helmfile helps manage Helm charts, which are packages for Kubernetes. You’ll need both Helm and Helmfile installed on your local machine.
3. GitHub Token: You’ll need a GitHub token with the right permissions. This token allows the runner to connect to your GitHub repository.

Setting Up the Self-Hosted Runner

Now, let's set up the self-hosted runner.

Step 1: Setting Up Helmfile

First, create a Helmfile that includes the configuration for the GitHub Actions Runner Controller. Here's a sample configuration:

repositories:
- name: actions-runner-controller 
  url: https://actions-runner-controller.github.io/actions-runner-controller
releases:
  - chart: actions-runner-controller/actions-runner-controller
    namespace: actions-runner-system
    createNamespace: true
    name: actions-runner-controller
    set:
      - name: authSecret.github_token
        value: <github_runner_token>
      - name: authSecret.create
        value: true

This configuration adds the necessary Helm repository and sets up the Actions Runner Controller in a Kubernetes namespace called actions-runner-system.

Step 2: Deploying the Runner Controller

Next, deploy the Runner Controller with Helmfile. This controller manages your runners on Kubernetes.

Run the following command in the directory where your Helmfile is located:

helmfile apply

This command will deploy the controller to your Kubernetes cluster, setting up the environment for your self-hosted runner.

Step 3: Applying the RunnerDeployment

Finally, create a RunnerDeployment to specify how your runner will connect to GitHub. Here’s a sample YAML file:

apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
  name: example-runnerdeploy
  namespace: actions-runner-system
spec:
  replicas: 1
  template:
    spec:
      repository: kubenine/cookiecutter-lightweight-django

Apply this file with the following command:

kubectl apply -f runnerdeployment.yaml

This configuration tells Kubernetes to create a runner that connects to the specified GitHub repository.

Verifying the Setup

Once everything is deployed, you’ll want to make sure the runner is working correctly.

Check Runner Status

You can check the status of your runner pods with this command:

kubectl get pods -n actions-runner-system

Look for a pod that matches the runner name. If it’s running, your setup is successful.

Testing with a Simple Workflow

To test your runner, create a simple GitHub Actions workflow in your repository:

name: Test Runner
on: [push]
jobs:
  test:
    runs-on: self-hosted
    steps:
    - name: Run a one-liner script
      run: echo "Success! Your self-hosted runner is working."

Push this workflow to your repository. If the workflow runs and you see the success message, everything is set up correctly.

Scaling and Managing Runners

As your needs grow, you might need more runners. You can scale up by increasing the number of replicas in the RunnerDeployment YAML file.

spec:
  replicas: 3

Updating this field to 3 will start three runners, allowing more jobs to run simultaneously.

Troubleshooting Common Issues

If you run into issues, here are some common problems and solutions:

1. Runner Not Showing Up in GitHub

If your runner doesn’t appear in GitHub, check that your GitHub token is correct and that the runner pod is running.

2. Pod Crashes

If your pod crashes, use kubectl logs to see what went wrong. This command will show you the pod's logs, which can help you diagnose the issue.

3. Token Expiration

GitHub tokens can expire. If your runner stops working, try generating a new token and updating your Helmfile.

Conclusion

Setting up a self-hosted GitHub Actions runner on Kubernetes gives you more control over your CI/CD pipelines. By following the steps above, you can have your own runner up and running in no time. If you have any questions or run into issues, feel free to leave a comment below.

Checkout our article on all the new features in Kubernetes 1.30 at: https://www.kubeblogs.com/explore-all-the-new-features-in-kubernetes-1-30/