Self-Hosted GitHub Runners Setup Guide

Imagine your boss wants you to use Github actions to automate the workflow of the developers. So you find this thing called Github actions and on paper it seems like the perfect solution, so you get working on it and find out that the signal to trigger the job in your pipeline is sent from one of Github’s servers.
Now the problem is that your pipeline servers are locked behind a VPN, but Github always sends the trigger signal from 1 of the 1000 IPs that they own. The self-hosted Github runners come in handy in this situation, after setting up a custom runner in a server that has a whitelisted IP in your pipeline server, you will now be able to access automate the action for your developers to trigger straight from their code base.

The installation of a Github runner can be done at 3 levels:

Enterprise
- These runners can be assigned to all organizations and repositories.
Organization
- These runners can be assigned to all repositories under that organization.
Repository
- Runners that are assigned to a specific repository.

Once the runners have been assigned you can then use labels to choose which job you want running on a specific GH runner

All 3 runners are configured using similar steps, but this guide will focus on installing it at an Organization level.

First you will have to click on the drop down next to your profile picture and go into “Your organizations”

Next click on the “Settings” button next to your organization’s name.

Go to “Actions” & “Runners”

Then create a new self-hosted runner.

Next choose your operating system and run the commands that they have displayed within your server that you want to host the runner on.

The following steps are to help you configure a GH runner on a Linux x64 operating system.

Configure Linux User

These commands will be executed assuming you’re running as root.

Create a new user

//This will create a the user runner and set their home directory to their name.
//Replace "runner" with desired username.
adduser -m runner

Create user password

//Replace "runner" with desired username.
passwd runner

Switch to the non-root user

su runner

Install & Run GH Runner

Creates a folder and cd into it

mkdir actions-runner; cd actions-runner

Download the runner package

curl -o actions-runner-linux-x64-2.297.0.tar.gz -L https://github.com/actions/runner/releases/download/v2.297.0/actions-runner-linux-x64-2.297.0.tar.gz

Optional: Validate the hash

echo "eb4e2fa6567d2222686be95ee23210e83fb6356dd0195149f96fd91398323d7f  actions-runner-linux-x64-2.297.0.tar.gz" | shasum -a 256 -c

Extract the installer from the .tar file you just downloaded.

tar xzf ./actions-runner-linux-x64-2.297.0.tar.gz

Create the runner and start the configuration

./config.sh --url https://github.com/<YOUR_ORGANIZATION> --token <GITHUB_PROVIDED_TOKEN>

Run it! (This is a manual process and you will have to run this manually each time)

./run.sh

Note that the directory you installed the GH runner will have a svc.sh file this file can be executed to have your GH runner always operating in case of a server restart as well, instead of always having to manually run the ./run.cmd command.

The svc.sh file can only be executed as root user.

su root

Change to your installation directory.

cd /home/runner/actions-runner

Install the service

./svc.sh install

Start your service

./svc.sh start

Now if you go back to your runners tab within your organization in your Github account, you will be able to note that your self-hosted runner is now in idle status. This means that you currently don’t have any actions running, and that your server is listening for any incoming actions.