Moving My GitHub Actions Runner to My Own VPS

GitHub Actions is a tool I frequently use to manage my CI/CD workflows. Especially for many of my projects, automating build and test steps has been a huge convenience. However, I eventually realized that GitHub's hosted runners could be costly, especially for projects with intense workloads and long-running builds. This led me to wonder if I could reduce these costs by taking control of my own runner.

With this thought in mind, I embarked on the journey of moving my GitHub Actions runner to my own virtual private server (VPS). This process not only helped me optimize costs but also gave me more control over my build environment. Having my own runner has proven to be invaluable for handling specific software dependencies, custom network configurations, or high-performance requirements.

Why Did I Need My Own GitHub Actions Runner?

GitHub's hosted runners are an excellent solution for many scenarios. However, as a developer with specific needs, I encountered some limitations. The primary reasons I decided to set up my own runner were:

Cost Optimization

For some of my projects, build times were becoming excessively long, especially when dealing with large dependencies. This led to high costs with GitHub's free tiers. By hosting my runner on my VPS, I could utilize the existing resources more efficiently and reduce costs. For instance, one of my side projects had a CI/CD pipeline that consumed over 2000 hours of usage per month, which translated to a significant cost with GitHub.

ℹ️ Cost Calculation

I was paying a fixed monthly fee for my VPS, whereas with GitHub, I was charged on a per-minute basis. Although this was beneficial when build times were short or usage was low, it became more cost-effective to use my VPS when dealing with high usage and long build times.

Custom Environment and Dependencies

Sometimes, I needed software dependencies or custom network configurations that weren't available in GitHub's default runner images. By hosting my own runner, I could easily install and configure the required software and dependencies. For example, I had an old C++ project that required a specific GCC version or a custom netcat variant for network testing.

Performance Requirements

For large monorepos or complex build processes, projects might require more CPU, RAM, or faster disk I/O. While GitHub's standard runners offer a certain level of performance, I could upgrade my VPS to a more powerful instance or utilize the existing resources more efficiently. This was particularly beneficial for Docker builds, where disk I/O was critical.

Preparation Phase: VPS and Prerequisites

Before setting up my runner, I needed to choose a suitable VPS and ensure the necessary prerequisites were in place.

VPS Selection and Characteristics

I typically prefer Ubuntu or Debian-based Linux distributions due to their stability, extensive package repository, and seamless systemd integration. For a runner, the minimum requirements depend on the project's size, but a general starting point would be:

• CPU: 2 vCPU
• RAM: 4 GB
• Disk: 60 GB SSD (adequate space for build caches and dependencies)

My choice was a VPS with 4 vCPU, 8 GB RAM, and 160 GB NVMe disk, which allowed me to utilize existing resources more efficiently.

Installation of Required Packages

After SSHing into my VPS, I installed the basic tools required for the runner's operation.

sudo apt update
sudo apt upgrade -y
sudo apt install -y curl git jq

• curl: For downloading the GitHub Actions runner package.
• git: For cloning repositories and performing operations.
• jq: For processing JSON output (often used in runner scripts).

⚠️ System Update is Crucial

Before proceeding with the installation, running apt update and apt upgrade ensures your system is up-to-date and prevents potential dependency issues. I learned this the hard way when I skipped this step and encountered issues with missing libraries.

GitHub Actions Runner Installation: Step-by-Step

Now, let's move on to the actual installation process of the runner software.

1. Obtain a Runner Token

First, I needed to obtain a runner token from GitHub. This token enables secure communication between the runner and GitHub. I retrieved the token by navigating to my repository's or organization's settings:

• Repository Level: Your repository -> Settings -> Actions -> Runners -> New self-hosted runner
• Organization Level: Your organization -> Settings -> Actions -> Runners -> New self-hosted runner

The token is provided, and you should copy it for use in the next steps.

2. Create the Runner Directory and Set Permissions

It's essential to create a dedicated directory for the runner and set the correct permissions.

sudo mkdir /actions-runner
sudo chown mustafa:mustafa /actions-runner # Replace with your username
cd /actions-runner

I used my own username, mustafa. You should replace this with your actual username.

3. Download and Extract the Runner Software

Using the GitHub-provided commands, I downloaded and extracted the runner package.

bash
# Example commands (check the GitHub page for the latest version)

<figure>
  <Image src={cover} alt="A server rack with the GitHub Actions logo, symbolizing the self-hosted runner concept." />
</figure>

curl -o actions-runner-linux-x64-