tarabutgateway/github-runner repository overview

⁠github-runner

This repo builds an Ubuntu image with a specific version of runner⁠. This enables us to create a self-hosted github runner.

We need to host our own runner because some of our k8 clusters are private therefore we can not use cloud hosted runners through github.

We can configure the self-hosted runner by providing the relevant token which it then authenticates with github and sits idle waiting for jobs.

The docker file and its associated config files are custom created to enable a javascript listener to actively try and connect with github and alert the pods in the event of failure.

⁠Runner Version

The Github runner⁠ version we use is controlled through RUNNER_VERSION variable in the Dockerfile.

You can find the latest version by visiting this link: runner version⁠

⁠Useful links

• github runner auth diagram⁠

⁠Usage

Below you will find some key variables which are needed to configure each runner accordingly.

Before you start you need to determine if you want the runner to be associated to a single repository or organisation. Runners configured at organisation level allow you to run workflows from different repos. And repository only runners will only handle specific workflows in the repo.

⁠Organisation specific runner

Key variables:

• RUNNER_NAME=
• RUNNER_ORG=tarabutgateway
• RUNNER_TOKEN=${REPO_TOKEN}
• RUNNER_LABELS=

⁠Repository specific runner

Key variables:

• RUNNER_NAME=example-name
• RUNNER_REPO=example-repo
• RUNNER_ORG=tarabutgateway
• RUNNER_TOKEN=${REPO_TOKEN}
• RUNNER_LABELS=

⁠Obtaining the RUNNER_TOKEN

Organisation Token⁠:

1 - Visit this link⁠

2 - Click on New Runner

3 - You will find instructions for setup, scroll down to configure and copy the token value.

Repo Token⁠:

1 - Very similar to the above, you will need to click on settings tab for the repo

2 - From the list on the left click on Actions drop down list

3 - Click Runners from drop down list

4 - Click on New self-hosted runner at the top right-hand corner

5 - You will find instructions for setup, scroll down to configure and copy the token value.

⁠Labels⁠

Labels allow you to send workflow jobs to specific types of self-hosted runners, based on their shared characteristics. For example, if your job requires a particular hardware component or software package, you can assign a custom label to a runner and then configure your job to only execute on runners with that label.

⁠Kubernetes & Docker

You can try out the runner locally using your personal github account. You just need to configure it so that you are using passing the variables from the Repository specific runner setup above.

The same applies to the k8 example included in this repo. You just need to ensure that the env variables in the config include the repo specific setup.

For the k8 local secret you can update the existing token which is a placehodler with the token you have obtained from the steps above using this command:

kubectl create secret generic local-runner-secret --from-literal=RUNNER_TOKEN=PLACEHOLDERTOKEN \
    -n local-runner --dry-run=client -o yaml \
    | kubectl apply -f -