Github self hosted runners

Overview

So, I’ve been using Github Actions for the longest time and the idea of using a self hosted runner has always piqued my interest but the cloud service from Github is so good, I’ve never had the need.

Until now.

I had a quick look through the documentation and, while overly long, it’s actually quite simple to set up. I’m going to walk you through the process. You’ll need a Github account obviously.

Create a directory structure

Create a directory structure for your runner. I’m using /opt/github-runner. I’m gong to create a runner called hoth and so I’ll create the directory and a binaries directory to hold the runner binary, soft linking them to the runner directories:

export RUNNER_VERSION=2.311.0
export REPO=clicktechnology
export PROJECT=cloudguyinbroadstone.com
mkdir -p /opt/github-runner/{binaries,hoth}
cd /opt/github-runner
curl -o binaries/actions-runner-linux-x64-$RUNNER_VERSION.tar.gz -L https://github.com/actions/runner/releases/download/v2.311.0/actions-runner-linux-x64-$RUNNER_VERSION.tar.gz
echo "29fc8cf2dab4c195bb147384e7e2c94cfd4d4022c793b346a6175435265aa278  binaries/actions-runner-linux-x64-2.311.0.tar.gz" | shasum -a 256 -c

Create a runner

Go to your Github repo and click on the “Settings” tab.
Go to Settings -> Actions -> Runners and click “New self-hosted runner”.
Pick an OS and architecture. I’m using Linux and x64.

In your terminal, run the following:

cd /opt/github-runner/hoth
ln -s ../binaries/actions-runner-linux-x64-$RUNNER_VERSION/actions-runner .
tar xzf actions-runner-linux-x64-$RUNNER_VERSION.tar.gz

Configure the runner

Simple enough, just run the following and follow the prompts:

./config.sh --url https://github.com/$REPO/$PROJECT --token ABCDEFGHIJKLMNOPQRSTUVWXYZABC

The token is the one you get from the “New self-hosted runner” page.

Startup the runner

It’s as simple as:

./run.sh

and you get..

√ Connected to GitHub

Current runner version: '2.311.0'
2023-12-01 12:44:24Z: Listening for Jobs

Using the runner

All we need to do now is to replace the typical runs-on: ubuntu-latest with runs-on: self-hosted within the Github workflow in .github/workflows/<instruction-file.yml> and we’re good to go.

Here’s a simple example:

name: Build and deploy

on:
  push:
    branches:
      - master

jobs:
  build:
    name: Build and deploy
    runs-on: self-hosted # was     runs-on: ubuntu-latest
    steps:
      - name: Checkout the repository
        uses: actions/checkout@v3
        with:
          submodules: true
          fetch-depth: 0

Results

Very good. The runner built and uploaded the code first time. I’m impressed.

√ Connected to GitHub

Current runner version: '2.311.0'
2023-12-01 12:50:35Z: Listening for Jobs
2023-12-01 12:51:37Z: Running job: Build and deploy
2023-12-01 12:53:19Z: Job Build and deploy completed with result: Succeeded

Conclusion

Very easy to set up and use and worked first time running off my local workstation. This would be a great option if you had very large builds requiring a lot of resources and wanted to spin up assets in AWS to do the work using a pre-baked image you’ve created. If you have lower bandwidth, then probably stick with the cloud runners. As it’s so slick, in prod, I’d more likely pay for a commercial license and pay for use of the cloud runners to avoid the management overhead (depending on costs), but in practise, this is an excellent and very workable solution.

There’s also some nice configuration options like --ephemeral which will delete the runner after the job has completed, a sort of one-and-done option. Also the _diag directory in the runner folder contains helpful logs about the runner and the job.

Nice product, works well. Top marks Github.

Overview#

Create a directory structure#

Create a runner#

Configure the runner#

Startup the runner#

Using the runner#

Results#

Conclusion#