GitHub Actions simplifies CI/CD but can become costly with GitHub-hosted runners. Self-hosted runners offer better cost control and customization.

This post covers deploying a self-hosted runner using ArgoCD and the Akuity Platform.

Why ArgoCD and Akuity Platform?

ArgoCD ensures Kubernetes clusters align with Git-defined states, simplifying management and improving consistency. While ArgoCD is powerful, the Akuity Platform enhances it with added security, usability, and its KubeVision tool for efficient Kubernetes resource visualization and troubleshooting.

In the next section, we’ll walk through the step-by-step process of deploying a self-hosted GitHub Actions runner in Kubernetes using ArgoCD and the Akuity Platform. This approach provides a scalable, cost-effective, and easily manageable solution for running GitHub Actions workflows.

1. Prepare Your Kubernetes Cluster

To get started, ensure you have a Kubernetes cluster and the Akuity Agent installed. Additionally, verify that KubeVision is enabled for your Akuity instance and cluster. You can follow the Akuity Platform ArgoCD guide and the Akuity Platform KubeVision guide to set up your cluster and enable KubeVision.

2. Create a GitHub Actions Runner Secret

To authenticate the GitHub Actions Runner with your GitHub organization, you need to create a GitHub App. Follow the steps outlined in the GitHub Actions Runner Controller Authentication guide.

After creating the GitHub App, collect the following information:

  • App ID
  • Installation ID
  • Private Key

Then, use these values to create a Kubernetes secret.

kubectl create namespace arc-runners
kubectl create secret generic pre-defined-secret \
   --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-----********'

Note that both the App ID and Installation ID are numeric values, while the private key is the content of the downloaded .pem file.

3. Deploy the GitHub Actions Runner on ArgoCD

Now, open your ArgoCD UI and create a new application. Use the following manifest to deploy the GitHub Actions Runner. The app is sourced from https://github.com/lumos-run/argo-apps.

Note that this application follows the App of Apps model. In this case:

  • The destination must be set to in-cluster or https://kubernetes.default.svc.
  • The namespace must be argocd.

You may customize the destinationServer to point to your own cluster, which is the cluster where the GitHub Actions Runner will be deployed.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: arc-runner
spec:
  destination:
    namespace: argocd
    server: https://kubernetes.default.svc
  source:
    path: arc-runner
    repoURL: https://github.com/lumos-run/argo-apps
    targetRevision: HEAD
    helm:
      values: "destinationServer: http://cluster-my:8001"
  project: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Once deployed and synced, you can see the GitHub Actions Runner in the ArgoCD UI.

The GitHub Actions Runner Controller creates the arc-systems namespace, which manages the core controller components. Meanwhile, the GitHub Actions Runner creates the arc-runners namespace, where the actual runner pods reside. When GitHub Actions workflows are triggered, new pods will be dynamically created in the arc-runners namespace to execute the jobs.

And arc-runners is the name of the runner installation, which will be used on runs-on in the GitHub Actions workflow.

You can check your GitHub organization settings to see the runner installation.

4. Trigger a GitHub Actions Workflow with Self-hosted Runner!

Now the runner is ready to be used. You can trigger a GitHub Actions workflow with the self-hosted runner by specifying the runner installation name in the runs-on field of the workflow.

name: ARC Runners Demo

on:
  workflow_dispatch:

jobs:
  arc-runners-demo:
    runs-on: arc-runners
    steps:
      - run: echo "🎉 This job uses runner scale set runners!"

This workflow will be executed by the self-hosted runner in the arc-runners namespace.

One More Thing - Monitor Your Actions with KubeVision!

The Akuity Platform offers powerful KubeVision capabilities, enabling seamless monitoring and management of your GitHub Actions workflows!

Start by navigating to the KubeVision UI and switching to the arc-runners namespace.

In the resource tree view, you’ll find a well-organized hierarchical display of your GitHub Actions Runner and its associated pods.

KubeVision provides comprehensive visibility into your runners, including detailed pod information and logs. Simply click on any runner pod to access its event timeline in the events tab.

The infrastructure tab offers an extensive overview of your runner deployment, featuring:

  • Visualization of runner pod distribution across Kubernetes cluster nodes
  • Detailed monitoring of resource allocation and utilization per node (CPU, memory, etc.)
  • Real-time infrastructure health metrics

Try It Out!

Akuity Platform is free to try! Sign up for a free trial and start monitoring your GitHub Actions workflows today!

Sign up for a free trial!