1. Overview
2. Instructions
3. Modernization

This is the installer project for GitHub Runner instances.

In it present form, the installer consists of a bash script (./install_runner.sh) and a Helm Chart. The helm invocation will create the following kubernetes artifacts:

• a deployment
• 1 of 2 secrets (pat or github-app)
• config map

./Chart.yaml
./values.yaml
templates
├── deployment.yaml
├── github-app-secret.yml
├── pat-secret.yaml
└── pki-configmap.yaml (embedded CA trust bundle)

Once the deployment is instantiated, a pod will attempt to register with a GitHub repository.
To register, it must authenticate either via the PAT or GitHub App.

Runners in this project are scoped to individual repositories. This is NOT ideal. A best case scenario would have runners that are scoped to an organization and reusable across projects.

It looks like it is possible to add a runner to an Organization Group. This would be the ideal scenario.

A follow on iteration of this project should register the runner with the Organization Group. To accomplish this, you need to have a GitHub Enterprise Account.

The runner installation process allows for authentication to GitHub using 1 of 2 methods:

GitHub PAT authentication requires 3 inputs:

• Personal Access Token
  • Navigation via GitHub UI:
    • Profile / Settings / Developer Settings / Personal Access Tokens
    • Types of Tokens
      • Fine-Grained Token OR
      • Classic Token

ℹ️ You will need to keep a copy of the token, once created. You only get access to token data once, upon creation.

GitHub Applications are a type of integration that allow granting access to GitHub resources at specific levels. You can attach GitHub applications to individual GitHub accounts or you can attach a GitHub App to an Enterprise account.

This demo uses a GitHub application attached to an individual GitHub Account. As the enterprise level GitHub App requires a GitHub Enterprise account.

Navigate to: Profile / Settings / Developer Settings / GitHub Apps Click New GitHub App button.

Required fields:

• GitHub App Name
• Homepage URL
• Un-check Webhook / Active
• Enable Only on this account
• Update repository permissions
• Click Create GitHub App button

Just set the permissions mentioned in the table below. This applies RBAC specific to the repository to any process that integrates via the GitHub Application.

You will need to set env vars based on the type of authentication you select.

For PAT authentication you will need:

• GITHUB_PAT: Your individual GitHub account PAT
• GITHUB_REPO: The short name for the repository (ex. springboot-demo)
• GITHUB_OWNER: The owner of the repository (ex. abryson-redhat)

For GitHub App authentication you will need:

• GITHUB_APP_ID: App Id from the Edit GitHub App page
• GITHUB_APP_INSTALL_ID: See this article
• GITHUB_APP_PEM: Contents of Pem file. Private key generated from the Edit GitHub App page.

⚠️ You must generate a private key at the bottom of the Edit page. It will download a .pem file

Additionally, GITHUB_REPO and GITHUB_OWNER are required.

./install_runner.sh <helm release name> <runner label names> <runner image pull spec> 

• release name will also be used to prefix the deployment and pod resource names
• runner label names are registered to GitHub
  • can be used by GitHub workflows in a runs-on: clause
• runner image pull spec (ex. quay.io/abryson/buildah-runner)

example call:

./install_runner.sh "actions-runner-java-runtime-11" "{local,java-runtime}" "quay.io/abryson/java-runtime-11-runner"

Check that you have a runner pod executing in the desired namespace. I created a github namespace for housing all github related integration artifacts.

oc get pods -n github

You might additionally check the pod logs.

oc logs -f <pod name>

Once the pod is ready, it will indicate it is listening for GitHub requests.

This application may be adapted to work in a GitOps framework. If using ArgoCD, you might create an Application resource that invokes the Helm installation, bypassing the script.

This will take some planning, as there are many dependencies that need to be in place for the execution to succeed. Additionally, you want to trigger this process after you've updated an existing runner image or created a new runner image.

The custom runner images are part of another project.