How to deploy GitHub Actions Self Hosted Runner on Kubernetes using HELM

Unlock the full potential of GitHub Actions by seamlessly integrating self-hosted runners into your Kubernetes environment. This step-by-step tutorial guides you through the deployment process, covering two key aspects: Helm deployment of the runner on Kubernetes and the creation/configuration of a GitHub App for secure authentication with GitHub.

Key Highlights:

1. Helm Deployment on Kubernetes:

  • Learn how to set up and configure Helm, the Kubernetes package manager, for efficient deployment.
  • Walkthrough the installation process of the GitHub Actions self-hosted runner using Helm charts tailored for Kubernetes environments.
  • Explore best practices for customizing runner settings to match your specific workflow requirements.

2. GitHub App Creation and Configuration:

  • Understand the importance of creating a GitHub App for secure authentication between your self-hosted runner and GitHub.
  • Step-by-step guide to creating a GitHub App with the necessary permissions and access scopes.
  • In-depth configuration instructions to link your self-hosted runner to GitHub securely.

3. Seamless Integration:

  • Witness the seamless integration of your self-hosted runner with GitHub Actions, optimizing your CI/CD workflows.
  • Troubleshooting tips and common issues addressed to ensure a smooth deployment process.

Who Should Follow This Tutorial:

  • DevOps engineers
  • Kubernetes administrators
  • GitHub Actions enthusiasts
  • Anyone looking to optimize CI/CD workflows with self-hosted runners

Get ready to elevate your GitHub Actions experience with this comprehensive tutorial!

Prerequisites:

  • A Kubernetes cluster
  • HELM installed
  • GitHub account with a private repo

let’s clone the arc repo locally and make some modifications

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

Installing GitHub Actions Runner Controller

To install the operator and the custom resource definitions (CRDs) in your cluster, do the following.

  • In your Helm chart, update the NAMESPACE value to the location you want your operator pods to be created. This namespace must allow access to the Kubernetes API server.
  • Install the Helm chart.

    The following example installs the latest version of the chart. To install a specific version, you can pass the –version argument along with the version of the chart you wish to install. You can find the list of releases in the GitHub Container Registry.
NAMESPACE="arc-systems"
helm install --dry-run arc /home/rke/stmp/helm-charts/actions-runner-controller/charts/gha-runner-scale-set-controller \
    --namespace "${NAMESPACE}" \
    --create-namespace

Authenticating the selfhosted runner.

To enable ARC to authenticate to GitHub, create an APP.
     a. Log in to your GitHub account 
     b. from the profile menu on the upper right corner select ‘Settings’
     c. from the left menu select ‘Developer settings’
     d. on ‘GitHub Apps’ menu click on ‘New GitHub App’

1. Create a GitHub App that is owned by an organization.

     a. For “Homepage URL,” enter http://github.com/actions/actions-runner-controller

     b. Under “Permissions,” click Repository permissions. Then use the dropdown menus to select the following access permissions.
     – Administration: Read and write
     – Metadata: Read-only

     c. Under “Permissions,” click Organization permissions. Then use the dropdown menus to select the following access permissions.
     – Self-hosted runners: Read and write

2. After creating the GitHub App, on the GitHub App’s page, notice the value for “App ID”. You will use this value later.

3. Under “Private keys”, click Generate a private key, and save the .pem file. You will use this key later.

4. In the menu at the top-left corner of the page, click Install app, and next to your organization, click Install to install the app on your organization.

5. After confirming the installation permissions on your organization, note the app installation ID. You will use it later. You can find the app installation ID on the app installation page, which has the following URL format:

     https://github.com/organizations/ORGANIZATION/settings/installations/INSTALLATION_ID

6. Register the app ID, installation ID, and the downloaded .pem private key file from the previous steps to Kubernetes as a secret.

Create namespace for secret (and runners).

kubectl create ns arc-runners

To create a Kubernetes secret in the “arc-runners” NS (the key is the .pem file) with the values of your GitHub App, run the following command.

kubectl create secret generic pre-defined-secret-for-github-runner \
   --namespace=arc-runners \
   --from-literal=github_app_id=123456 \
   --from-literal=github_app_installation_id=654321 \
   --from-literal=github_app_private_key='-----BEGIN RSA PRIVATE KEY-----********'

Then using the ‘githubConfigSecret: pre-defined-secret-for-github-runner’
property in your copy of the values.yaml file, pass the secret name as a reference.
mark the TOKEN line, we don’t use tokens now.
#  github_token: “”
(…/charts/gha-runner-scale-set/values.yaml)

Configuring a runner scale set

To configure your runner scale set, run the following command in your terminal, using values from your ARC configuration.
When you run the command, keep the following in mind.

  • Update the INSTALLATION_NAME value carefully. You will use the installation name as the value of runs-on in your workflows.
  • Update the NAMESPACE value to the location you want the runner pods to be created.
  • Set GITHUB_CONFIG_URL to the URL of your repository, organization, or enterprise. This is the entity that the runners will belong to.
  • This example command installs the latest version of the Helm chart. To install a specific version, you can pass the –version argument with the version of the chart you wish to install.

Note:
As a security best practice, create your runner pods in a different namespace than the namespace containing youoperator pods.

INSTALLATION_NAME="arc-runner-set"
NAMESPACE="arc-runners"
GITHUB_CONFIG_URL="https://github.com/<your-org>"
helm install --dry-run "${INSTALLATION_NAME}" /home/rke/stmp/helm-charts/actions-runner-controller/charts/gha-runner-scale-set \
    --namespace "${NAMESPACE}" \
    --set githubConfigUrl="${GITHUB_CONFIG_URL}"

Right after deploying check the ‘arc-systems’ PODS, it should look like the following example, one POD is the ‘controller’ we deployed earlier, and the second is the listener we just deployed.

Check your GitHub Actions, you will see the runner added,
you can recognize it by it’s tags and name which is the name of the deployment.

Now you can create the workflow yaml.
Browse to your repo and create the workflow file
.github/workflows/main.yml

     on:
     workflow_dispatch:

Means that will be triggered only by hand

    runs-on: arc-runner-set

This is the TAG of the selfhosted runner.

name: Actions Runner Controller Demo
on:
  workflow_dispatch:

jobs:
  Explore-GitHub-Actions:
    # You need to use the INSTALLATION_NAME from the previous step
    runs-on: arc-runner-set
    steps:
    - run: echo "🎉 This job uses runner scale set runners!"

next you can start the workflow and watch by yourself that it actually works.

The runner POD will be created for the execution of the flow, it will be deleted right after flow is complete.

In conclusion,


deploying GitHub Actions self-hosted runners on Kubernetes opens up a world of possibilities for enhancing the efficiency and flexibility of your CI/CD workflows. This tutorial has equipped you with the knowledge and hands-on guidance needed to seamlessly integrate these powerful components into your development pipeline.

By mastering Helm deployment on Kubernetes, you gaine the ability to tailor the runner environment to your specific needs. Additionally, creating and configuring a GitHub App ensures a secure and authenticated connection between your self-hosted runner and GitHub, contributing to a robust and reliable CI/CD ecosystem.

Whether you’re a seasoned DevOps engineer, a Kubernetes administrator, or someone eager to enhance your GitHub Actions proficiency, this tutorial provides a solid foundation for success. Realize the full potential of GitHub Actions by leveraging self-hosted runners on Kubernetes and witness the transformative impact on your development workflows.