Recently, I have been trying to migrate every component in my home lab to be managed by ArgoCD, and GitHub Actions Runner was one of them. While migrating, I found the process to deploy it has changed since last time, and I wouldn’t call it straightforward. So here is an updated note.

Prerequisites

1. Kubernetes cluster + ArgoCD
2. GitHub organization
3. A GitHub repo in the organization to test the runner

Create a GitHub App

There are multiple ways to authenticate the runner with GitHub, but the recommended way is to use a GitHub App. Follow this guide to create one: Authenticating to the GitHub API

The application will show up like this in your organization:

Keep the following for later steps:

1. App ID
2. Private key (downloaded as a .pem file)

Deploy Actions Runner Controller

We can follow the official guide Quickstart for Actions Runner Controller to set up the ARC, but since I wanted to manage everything declaratively, I created the following ArgoCD application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

project: default
source:
  repoURL: ghcr.io/actions/actions-runner-controller-charts
  targetRevision: 0.12.0
  chart: gha-runner-scale-set-controller
destination:
  server: https://kubernetes.default.svc
  namespace: gh-arc
syncPolicy:
  syncOptions:
    - ServerSideApply=true

This will deploy the ARC in the gh-arc namespace. You can change the namespace to whatever you prefer.

Create a Runner Set

Before deploying the runner set, we need to create a secret with the GitHub App credentials.

1
2
3
4
5
6
7
8
9

apiVersion: v1
kind: Secret
metadata:
  name: gha-runner-app
  namespace: gh-runner
data:
  github_app_id: ++++++++
  github_app_installation_id: ++++++++
  github_app_private_key: ++++++++

I also created an ArgoCD application for the secret, which just refers to the above yml file in a git repo.

Now we can create the runner set.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

project: default
source:
  repoURL: ghcr.io/actions/actions-runner-controller-charts
  targetRevision: 0.12.0
  helm:
    values: |-
      githubConfigUrl: https://github.com/junyi-me
      containerMode:
        type: "dind"
      githubConfigSecret: gha-runner-app
      controllerServiceAccount:
        namespace: gh-arc
        name: gh-arc-gha-rs-controller      
  chart: gha-runner-scale-set
destination:
  server: https://kubernetes.default.svc
  namespace: gh-runner

Make sure this is deployed in the same namespace as the secret we created earlier.

Values:

1. githubConfigUrl: The URL of your GitHub organization or user account.
2. containerMode.type: Set to dind if you want to run containerized workloads in the runner. Otherwise leave it out.
3. githubConfigSecret: The name of the secret we created earlier.
4. controllerServiceAccount: the namespace and name of the service account created by ARC.

If everything is set up correctly, the runner should be visible in the GitHub organization.

Use ARC from a repository

You can use the runner in any repo in the organization by adding the following to your workflow file:

1
2
3

jobs:
  build:
    runs-on: jylab-runner-set

Example: docker-build.yml

Conclusion

For some reason, when I tried the previous method of using ARC with personal access token, it didn’t work. So that’s the reason I switched to using a GitHub App. It’s a bit more complex, but it was a good opportunity to switch to a recommended approach.

(There are some sync issue with the CRDs defined in gh-arc application that keeps recurring even with auto-sync turned on, but it doesn’t affect the functionality.)