In this post, we will explore the concept of GitHub runners, including the difference between GitHub-hosted and self-hosted runners. We’ll also discuss why some teams prefer using self-hosted runners over the GitHub-hosted option, including the flexibility, performance, and control they offer.

We will also walk through the process of setting up a self-hosted runner, covering the necessary prerequisites and configuration steps. By the end of this article, you should have a clear understanding of both types of runners and how to integrate a self-hosted runner into your CI/CD workflows.

Introduction: What are GitHub-Hosted runners?

Github Runners are virtual machines that execute jobs in a GitHub Actions CI/CD workflow. For example, a runner can clone your repository locally, install testing software, and run commands that evaluate your code.

Type of Runners

1. Github-Hosted Runner

A GitHub-hosted runner is a virtual machine (VM) provided and managed by GitHub that executes jobs in a GitHub Actions workflow, offering pre-installed tools and operating systems like Ubuntu, Windows, or macOS and eliminating the need for users to manage the underlying infrastructure.

Advantages of GitHub-Hosted Runners

• Seamless Integration: Works natively with GitHub Actions, making CI/CD automation easy.

• Managed Infrastructure (GitHub-hosted): GitHub provides pre-configured environments with popular tools and dependencies.

• Scalability: Automatically scales with demand, reducing manual infrastructure management.

• Cross-Platform Support: Available for Linux, macOS, and Windows environments.

• Parallel Execution: Supports running multiple jobs in parallel, speeding up workflows.

Disadvantages of GitHub-Hosted Runners

• Cost: Limited free tier upto 2000 per month - additional usage incurs charges.

• Limited Runtime: Jobs have a maximum execution time (6 hours), which can be restrictive for long-running processes.

• Latency in Cold Start – Sometimes experiences delays when spinning up new runners.

• Limited Customization – Cannot modify system configurations or install persistent dependencies.

2. GitHub Self-Hosted Runner

A self-hosted runner is a system (physical, virtual, container, on-premises, or in the cloud) that you deploy and manage to execute jobs from GitHub Actions workflows, offering more control over hardware, operating systems, and software tools than GitHub-hosted runners.

Advantages of GitHub Self-Hosted Runners

• Custom Environment: You can install custom dependencies, software, and tools tailored to your workflow.

• No Usage Limits: Unlike GitHub-hosted runners, self-hosted runners do not have restrictions on runtime minutes or job concurrency.

• Better Performance: Since self-hosted runners use your infrastructure, you get full control over hardware specifications, leading to potentially faster execution.

• Cost Savings: If you already have the infrastructure available, self-hosted runners can be more - cost-effective compared to paying for additional GitHub-hosted runner minutes.

• Persistent Storage: Unlike GitHub-hosted runners, which reset after every job, self-hosted runners can retain caches, dependencies, and artifacts between builds.

• Security and Privacy: Data remains on your infrastructure, reducing the risk of exposure and enhancing privacy compared to third-party services.

• Intranet/Private Network Support: This can be used to deploy and test applications within private networks without exposing them to the internet.

Disadvantages of GitHub Self-Hosted Runners

• Maintenance Overhead: Requires manual updates, monitoring, and troubleshooting of the runner environment.

• Scalability Challenges: Unlike GitHub-hosted runners, self-hosted runners do not auto-scale dynamically, requiring manual provisioning of additional resources.

• Network Configuration Issues: An additional setup may be needed to ensure proper connectivity with GitHub services if used within a private network.

Steps to Set Up a GitHub Self-Hosted Runner

Prerequisites: To set up a self-hosted runner, we need a machine that can run the runner application and communicate with GitHub Actions, ensuring it has sufficient resources for the workflows you intend to run.

Before setting up the runner, ensure you have:

• A GitHub repository or organization.

• A machine (physical or virtual) with an internet connection.

• Admin access to install the software (Docker, AWSCLI, etc) on the runner machine.

1. Register a Self-Hosted Runner

Step 1: Navigate to GitHub Actions Settings

• Go to your GitHub repository.

• Click on Settings > Actions.

• Scroll down to the Runners section and click Add Runner.

Step 2: Choose the OS and Get the Installation Commands

• Select the OS you want to install the runner on (Linux, Windows, or macOS).

• GitHub provides a set of commands to install and configure the runner.

2. Install and Configure the Runner

Step 1: Download and Extract the Runner

Run the following commands on your self-hosted machine (for Linux):

# Create a directory and download the action runners.
mkdir /actions-runner && cd /actions-runner
curl -o actions-runner-linux-x64-2.321.0.tar.gz -L <https://github.com/actions/runner/releases/download/v2.321.0/actions-runner-linux-x64-2.321.0.tar.gz>

Step 2: Configure the Runner

# Configure the runner, You need Repo and Token.
./config.sh --url <Repo-link> --token <TOKEN>

Step 3: Start the Runner

Step 4: Add the Runner to Your Workflow at runs-on

File: .github/workflows/testing-selfhosted-runner.yaml

Push the changes to your repository, and GitHub Actions will trigger the workflow on your self-hosted runner.

For more details on configuring a self hosted runner, check Github’s official documentation here.

Common Issues and Troubleshooting

These are some common issues you many run into when setting up a github runner:

• Runner Not Picking Up Jobs: Ensure the runner is running and correctly linked to the repository.

• Permission Issues: Make sure the runner has the correct permissions to execute workflows.

• Networking Issues: Verify that your machine can connect to GitHub servers. GitHub runners operate on a pull model, meaning they are not directly exposed to the internet but instead reach out to GitHub servers. Ensure that your runners have the necessary network access to connect to GitHub.

• Upgrade Runner: If you still face issues, try updating the runner by downloading the latest version.

You can also run a self hosted Github runner in Kubernetes by following the instructions in the arc repo here.

Remember that a Github runner is just another machine. By creating a self hosted runner, you are also signing up for the responsibility of its monitoring, maintainence and ensuring that it is updated with latest security patches.

Conclusion

Github runners can be used in both managed and self-hosted mode. When the cost of using a managed runner exceeds that of running a self hosted one, choose setting up a self hosted runner.