Skip to content

Setting up a self-hosted GitHub Runner

This article explains how to set up a self-hosted GitHub Runner in eclean's infrastructure. Following these steps ensures that all runners are configured consistently and securely.

Security sensitive

This document includes security-sensitive information about our infrastructure configuration. Before proceeding, make sure to follow security protocols and have correct authorisation.

Prerequisites

Your own toolset

Self-hosted GitHub Actions runners do not come with their own tool set, as they do on the cloud. You must manually install all dependencies required by your repository, unless you are utilizing the "github-act-runner" setup and running just Ubuntu workloads, in which case you can use the given Docker image.

Before starting the runner configuration process, make sure you have:

  • A Windows machine with administrator access
  • Required firewall rules documented and authorised
  • GitHub repository access with permissions to add runners

Runner Configuration Steps

1. System Updates and WSL

Start by updating Windows and installing WSL (Windows Subsystem for Linux).

Update Windows

  1. Open Windows Settings
  2. Go to Windows Update
  3. Check for updates and install all available updates
  4. Restart if required

Install and Update WSL

wsl --install
wsl --update

2. Install Package Manager and Core Tools

We use Scoop as our package manager for Windows. Install it using PowerShell:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Install Scoop
iex "& {$(irm get.scoop.sh)} -RunAsAdmin"

# Install core development tools
scoop install main/git main/nvm main/bun main/rustup

# Add extras bucket
scoop bucket add extras

# Install additional tools
scoop install extras/brave extras/vscodium extras/vcredist2022 extras/wiztree extras/bleachbit extras/everything

PATH and file associations

Scoop will automatically provide most of the required instructions for adding freshly installed applications to the PATH and file associations.

To ensure optimal GitHub Runner functionality, add the PATH variables to the system PATH variable rather than only the user PATH variable (which Scoop will do by default).

3. Manual Application Installation

Some applications need to be installed manually due to licensing or specific configuration requirements.

Docker Desktop

  1. Download Docker Desktop from the official website
  2. Run the installer with default settings.
  3. Restart your computer after installation.

Portmaster

  1. Download Portmaster from safing.io
  2. Install with default settings

  3. Configure DNS settings:

    1
2
3
4
5
6
7
    # Cloudflare Family
dns://1.1.1.3
dns://1.0.0.3

# DNS0 ZERO
dns://193.110.81.9
dns://185.253.5.9

    Disable the "Block Secure DNS Bypassing" option in "Global Settings > Privacy Filter > Advanced".

  4. Configure RDP security:

    • Block all connections except YOUR_COUNTRY_TWO_LETTER_CODE TCP/3389 and YOUR_COUNTRY_TWO_LETTER_CODE UDP/3389 on the "Windows Service: Term Service" process
      • E.g. SE TCP/3389 and SE UDP/3389 for Sweden

Node.js via nvm

GitHub Actions runners require Node.js v20.x. Install it using nvm:

nvm install 20

The command to use Node.js v20.x will show in the output of the previous command.

4. System Optimization

Compress Windows Installation

Run the following command to enable system compression:

Compact.exe /CompactOS:always

5. HetrixTools Setup

Creating the uptime monitor

Use the " Setup Ubuntu 24.04 server" guide to create the HetrixTools uptime monitor before proceeding.

  1. Install the HetrixTools server monitoring agent for Windows
  2. Configure Portmaster to allow ICMP echo requests from HetrixTools IPs:
  3. Configure the Windows Firewall to allow ICMP echo requests:
    1. Open the Windows Firewall with Advanced Security
    2. Go to "Inbound Rules"
    3. Click "New Rule"
    4. Under "Rule type", select "Custom"
    5. Under "Protocol and ports", select "ICMPv4"
      1. Click "Customize"
      2. Under "Specific ICMP types", select "Echo Request"
    6. Give the rule a name and description, then apply the rule

6. GitHub Runner Installation

Runner Registration

You'll need a runner registration token from the GitHub repository or organization settings to complete this step.

Runner image

We recommend pulling the Docker image used for Ubuntu support from the catthehacker/docker_images repository to save time later when the Actions workflows need to be run.

You will most likely require either ghcr.io/catthehacker/ubuntu:act-latest or ghcr.io/catthehacker/ubuntu:full-latest. However, full-latest provides a more comprehensive collection of tools and is generally recommended, but it also takes up more disk space (60GB when uncompressed).

Please select the suitable image based on your requirements and your system's specifications and capabilities.

Do you have all dependencies installed?

Before proceeding, ensure that Docker Desktop is installed and setup for WSL 2 integration. You may also need to enable the "Expose daemon on tcp://localhost:2375 without TLS" option in Docker Desktop to allow the runner to connect.

  1. Download the ChristopherHX/github-act-runner binary
  2. Place the downloaded binary in C:\github-act-runner

  3. Create a new .env file in the same directory as the binary with the following content: 

    1
2
    HOME=<path-to-your-runner-directory>
PATH=<copy-of-your-SYSTEM-PATH-variable>

    Note: The PATH variable should be a copy of your system PATH variable, not just the user PATH variable. A production example of the PATH variable is provided below:

    %SystemRoot%;%SystemRoot%\system32;%SystemRoot%\System32\Wbem;%SYSTEMROOT%\System32\OpenSSH\;%SYSTEMROOT%\System32\WindowsPowerShell\v1.0\;C:\Program Files\Docker\Docker\resources\bin;C:\Users\Administrator\AppData\Local\Microsoft\WindowsApps;C:\Users\Administrator\scoop\shims;C:\Users\Administrator\scoop\apps\git\current;C:\Users\Administrator\scoop\apps\nvm\current;C:\Users\Administrator\scoop\apps\nvm\current\nodejs\nodejs;C:\Users\Administrator\scoop\persist\nvm\nodejs\nodejs;C:\Users\Administrator\scoop\apps\bun\current;C:\Users\Administrator\scoop\apps\rustup\current;C:\Users\Administrator\scoop\apps\rustup\current\.cargo\bin;C:\Users\Administrator\scoop\persist\rustup\.cargo\bin;C:\Users\Administrator\scoop\persist\rustup\.rustup\toolchains\stable-x86_64-pc-windows-msvc\bin;C:\Users\Administrator\scoop\apps\vscodium\current\bin;C:\actions-runner\bin;C:\github-act-runner-v0.9.0;

  4. Run the configure.bat script and follow the instructions

    • When asked for runner labels, make sure to include windows, ubuntu, and act-runner, as well as the hosting provider (e.g., azure, aws, royalehosting, etc.)
      • Windows and Ubuntu identify the runner as able to run Windows and Ubuntu workloads, respectively.
      • act-runner recognizes the runner as a "github-act-runner".
      • The hosting provider is optional but preferred because it assists with filtering and grouping runners in the GitHub repository settings.
  5. Run ./github-act-runner.exe svc install to install the runner as a service
  6. Run ./github-act-runner.exe svc start to start the runner as a service
  7. Update your workflows to use the self-hosted runner correctly:
    • Use the runs-on setting to specify the runner labels
      • E.g. runs-on: ["self-hosted", "ubuntu", "act-runner"]
    • Use the container setting to specify the Docker image to use
      • E.g. container: ghcr.io/catthehacker/ubuntu:act-latest

Do you have all dependencies installed?

Before proceeding, ensure that Docker Desktop is installed and setup for WSL 2 integration. You may also need to enable the "Expose daemon on tcp://localhost:2375 without TLS" option in Docker Desktop to allow the runner to connect.

  1. Download the GitHub Actions runner for Windows
  2. Extract the downloaded archive to C:\actions-runner
  3. Follow the official GitHub documentation to complete the runner configuration
    • When asked for runner labels, make sure to include windows, gha-native, and the hosting provider (e.g., azure, aws, royalehosting, etc.)
      • windows identifies the runner as able to run Windows workloads
      • gha-native identifies the runner as a native GitHub Actions runner
      • The hosting provider is optional but preferred because it assists with filtering and grouping runners in the GitHub repository settings.
  4. Update your workflows to use the self-hosted runner correctly:
    • Use the runs-on setting to specify the runner labels
      • E.g. runs-on: ["self-hosted", "windows", "gha-native"]