4 min to read

Setting up GitHub Action Self-Hosted Runner on Kubernetes

A comprehensive guide to implementing GitHub Action Hosted Runner with Helm

Featured image


Overview

This guide explores how to create and manage GitHub Action Hosted Runners. We’ll focus on implementing self-hosted runners using Kubernetes and Helm.


Understanding GitHub Action Hosted Runners

Components Overview

1. actions-runner-controller
  • Manages GitHub Actions runners in Kubernetes clusters
  • Handles automatic provisioning and lifecycle management
  • Supports repository, organization, and enterprise-level deployment
  • Uses Kubernetes HPA for auto-scaling

2. gha-runner-scale-set-controller
  • Manages large-scale runner deployments
  • Utilizes Scale Set Runners feature
  • Provides efficient runner management through single endpoint
  • Integrates with GitHub's Scale Set Runners API

3. gha-runner-scale-set
  • Configures and deploys runner scale sets
  • Controls scaling and lifecycle through GitHub Actions API
  • Optimizes communication between workflows and runners


Prerequisites

Authentication Setup

Choose one of the following authentication methods:

Option 1: GitHub PAT Token

Github Organization/Account settings → Settings → Developer settings → GitHub Personal access tokens

Required scopes:
  • Repository Level: repo, workflow
  • Organization Level: read:org, admin:org, workflow
  • Enterprise Level: admin:enterprise, workflow

Option 2: GitHub App

If you have an existing app
If you don’t have an existing app
Get Installation ID
Generate private key


1.Required permissions:
  • Actions: Read and Write
  • Administration: Read and Write
  • Metadata: Read-only
2. Get App ID and Installation ID 3. Generate private key


Installation

1. Add Helm Repository

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

2. Create Namespace

kubectl create namespace actions-runner-system

3. Install Controller

helm install actions-runner-controller actions-runner-controller/actions-runner-controller \
    -n actions-runner-system \
    -f runner.yaml

4. Deploy Runner

kubectl apply -f runner-cr.yaml


Configuration Files

runner.yaml

authSecret:
  enabled: true
  create: true
  name: "controller-manager"
  github_token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxx"

image:
  repository: "summerwind/actions-runner-controller"
  actionsRunnerRepositoryAndTag: "summerwind/actions-runner:latest"
  dindSidecarRepositoryAndTag: "docker:dind"
  pullPolicy: IfNotPresent

rbac:
  allowGrantingKubernetesContainerModePermissions: true

serviceAccount:
  create: true

runner-cr.yaml

apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
  name: example-runner
spec:
  replicas: 1
  template:
    spec:
      repository: "your-github-username/your-repository"
      labels:
        - self-hosted
        - linux
        - x64


Verification

Check Installation

kubectl get po -n actions-runner-system
kubectl get runnerdeployments.actions.summerwind.dev

Verify Runner Connection

Check runners in your repository: Settings → Actions → Runners GitHub Runner

Example Workflow

name: Example Workflow
on:
  workflow_dispatch:

jobs:
  test-job:
    runs-on: self-hosted
    # or runs-on: [self-hosted, linux, x64]
    steps:
      - name: Test Step
        run: echo "Running on self-hosted runner"


Key Considerations

1. Authentication:
  • You must choose between GitHub App or PAT authentication
  • GitHub App is recommended (better security and permissions management)

2. Permissions:
  • Set the proper permissions and resources required for Runner

3. Network Policy:
  • Check network policy and security settings


References