Today we will be going through how to deploy GitHub self-hosted runners on AKS and connect them to GitHub Enterprise.

GitHub self-hosted runners provides you with the ability to choose custom hardware configuration with more processing power or memory to run larger jobs, install software available on your local network, and choose an operating system not offered by GitHub-hosted runners. Self-hosted runners can be physical, virtual, in a container, on-premises, or in a cloud.

The deployment will be leveraging a lot of the hard work from here to deploy a controller that operates self-hosted runners on your AKS cluster. So a big thanks and kudos to the team!

Pre–requisites

• AKS deployed and running
• cert-manager installed on AKS- GitHub Enterprise account (either GitHub Enterprise Cloud or Server)
• GitHub Personal Access Token

cert-manager

If you don’t have cert-manager installed on your AKS cluster you can simply install it by deploying the following helm chart. This is allows the controller to conduct certificate management of Admission Webhook.

helm repo add jetstack https://charts.jetstack.io

helm repo update

helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.5.4 \
  --set installCRDs=true

Personal Access Token

Personal Access Tokens are used to register the self-hosted runners to your GitHub Enterprise account (using GitHub App Authentication to register self-hosted runners to GitHub Enterprise is not currently supported).

Log-in with a GitHub account that has admin privileges for the enterprise, and create a personal access token with the appropriate scopes listed below:

• admin:enterprise (Full control)

Deployment

1. Download the actions-runner-controller helm chart

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

2. Untar helm chart

tar xf actions-runner-controller-0.13.2.tgz

3. Update the helm chart (values.yaml) with;

• your GitHub Enterprise URL
• Personal Access Token
• webhook server (required for autoscaling)

# values.yaml
    authSecret:
    create: true
    name: "controller-manager"
    ### GitHub Apps Configuration
    #github_app_id: ""
    #github_app_installation_id: ""
    #github_app_private_key: |
    ### GitHub PAT Configuration
    github_token: "<personal-access-token>"
    ---
    env:
    GITHUB_ENTERPRISE_URL: "https://github.com/enterprises/<enterprise-name>"
    # http_proxy: "proxy.com:8080"
    # https_proxy: "proxy.com:8080"
    # no_proxy: ""
    ---
    githubWebhookServer:
      enabled: true
      replicaCount: 1
      syncPeriod: 10m

    scope:
    # If true, the controller will only watch custom resources in a single namespace
    singleNamespace: false
    # If `scope.singleNamespace=true`, the controller will only watch custom resources in this namespace
    # The default value is "", which means the namespace of the controller
    watchNamespace: ""

4. Deploy controller to AKS

   helm upgrade --install --namespace actions-runner-system --create-namespace \
       --wait actions-runner-controller ./

5. Once the controller is deployed to AKS you need to create a manifest file to deploy self-hosted runners to AKS and register them to GitHub Enterprise

example below.

# runner.yml
   apiVersion: actions.summerwind.dev/v1alpha1
   kind: RunnerDeployment
   metadata:
   name: demo-runners
   namespace: default
   spec:
   replicas: 2
   template:
     spec:
     enterprise: enterprise-name

6. Deploy self-hosted runners to AKS

kubectl apply -f runner.yml

We’re done! The GitHub runners will now be deployed onto AKS and registered and available for use with GitHub Enterprise.

Scaling

Manual Scaling

You can manually scale by configuring replicas to the desired amount. To remove the GitHub runners either delete the runner deployment, or update it to have replicas: 0, so that there will be 0 runner pods in the cluster.

Autoscaling

There are numerous ways to configure autoscaling for GitHub runners on AKS. A great option is to use webhook driven scaling which utilises GitHub Webhook events such as workflow_job, pull_request, push etc. to scale. It is also far quicker than regular AKS pod scaling as it allows you to immediately add “resource slack” for future GitHub Actions job runs.

The example below scales demo-runners by 1 replica for 5 minutes on each workflow_job event.

# runner.yml
apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
name: demo-runners
namespace: default
spec:
replicas: 2
template:
  spec:
  enterprise: enterprise-name
---
apiVersion: actions.summerwind.dev/v1alpha1
kind: HorizontalRunnerAutoscaler
metadata:
  name: demo-runners-autoscaler
spec:
  scaleTargetRef:
    name: demo-runners
  scaleUpTriggers:
    - githubEvent: {}
      duration: "5m"
      amount: 1