top of page

Boost Your CI/CD with a Self-Hosted GitHub Runner on a VM

Updated: Jan 30

 

Table of Contents

 

Learn how to configure your own GitHub runner on a virtual machine to improve CI/CD performance, control environments, and optimize workflows.

Overview

GitHub offers support for self-hosted runners, providing enhanced control over hardware, operating systems, and software tools compared to hosted runners. This allows for increased CPU and memory capacity to accommodate larger tasks. Furthermore, you can pre-install all necessary software and packages to minimize overall build and deployment time. Self-hosted runners offer the flexibility to choose any operating system, unlike GitHub-hosted runners, which predominantly operate on Ubuntu for the Linux platform. These self-hosted runners can be implemented on physical or virtual machines, within containers, on-premises, or in the cloud.


Self-hosted runners can be integrated at different levels within the management hierarchy:

  1. Repository-level: These runners are exclusively assigned to a specific repository.

  2. Organization-level: These runners are capable of handling jobs across multiple repositories within an organization.

  3. Enterprise-level: These runners can be utilized by multiple organizations within an enterprise account.

Your self-hosted runners connect to GitHub using the GitHub Actions self-hosted runner application.


The GitHub Actions runner application is open source and available here. A self-hosted runner is automatically removed from GitHub if it has not connected to GitHub Actions for more than 30 days.


Differences Between GitHub-hosted and Self-Hosted Runners


GitHub-hosted runners provide an efficient and straightforward solution for executing workflows, whereas self-hosted runners offer a highly customizable option for running workflows within your own tailored environment.

GitHub-hosted runners

  • Automatically receive updates for the operating system, preinstalled packages and tools, and the self-hosted runner application.

  • Managed and maintained by GitHub.

  • Offer a fresh instance for each job execution.

  • Utilize complimentary minutes included in your GitHub plan, with per-minute charges applied once the free minutes are exceeded.

Self-hosted runners

  • Receive automatic updates exclusively for the self-hosted runner application. You are responsible for updating the operating system and all other software.

  • Utilize cloud services or local machines that you are already financing.

  • Offer customization according to your hardware, operating system, software, and security requirements.

  • Do not require a clean instance for every job execution.

  • Are available for free with GitHub Actions, but you are responsible for the maintenance costs of your runner machines.

Supported Architectures and OS for Self-Hosted Runners


GitHub's self-hosted runner is compatible with the following operating systems and architectures.

Linux

  • Red Hat Enterprise Linux 7 or later

  • CentOS 7 or later

  • Oracle Linux 7

  • Fedora 29 or later

  • Debian 9 or later

  • Ubuntu 16.04 or later

  • Linux Mint 18 or later

  • openSUSE 15 or later

  • SUSE Enterprise Linux (SLES) 12 SP2 or later

Windows

  • Windows 7 64-bit

  • Windows 8.1 64-bit

  • Windows 10 64-bit

  • Windows Server 2012 R2 64-bit

  • Windows Server 2016 64-bit

  • Windows Server 2019 64-bit

macOS

  • macOS 10.13 (High Sierra) or later

Architectures

  • x64 - Linux, macOS, Windows.

  • ARM64 - Linux only.

  • ARM32 - Linux only.

Communication Between Self-Hosted Runners and GitHub


The self-hosted runner periodically checks GitHub to obtain application updates and determine if any jobs are queued for processing. It employs an HTTPS long poll method, establishing a connection to GitHub for a duration of 50 seconds. If no response is received within this timeframe, the connection times out, and a new long poll is initiated. It is essential for the application to be operational on the machine to accept and execute GitHub Actions jobs.


It is imperative to ensure that the machine possesses the necessary network access to communicate with the GitHub URLs listed below.

github.com
api.github.com
*.actions.githubusercontent.com
github-releases.githubusercontent.com
github-registry-files.githubusercontent.com
codeload.github.com
*.pkg.github.com
pkg-cache.githubusercontent.com
pkg-containers.githubusercontent.com
pkg-containers-az.githubusercontent.com
*.blob.core.windows.net

If you use an IP address allow list for your GitHub organization or enterprise account, you must add your self-hosted runner's IP address to the allow list. Click here for more details.

Requirements for Self-Hosted Runner Machines


Any machine can function as a self-hosted runner provided it satisfies the following criteria:

  • The self-hosted runner application can be installed and operated on the machine. All previously mentioned architectures and operating systems are compatible with self-hosted runners.

  • The machine must be capable of communicating with GitHub Actions as specified above.

  • The runner machine should possess adequate hardware resources for the workflows you intend to execute.

  • For workflows utilizing Docker container actions or service containers, a Linux machine is required, and Docker must be installed.

Pre-Requisites

  • For a repository-level runner, you need to possess at least repository admin rights.

  • For an organization-level runner, you must have organization admin rights.


Setting Up Repository Level Runners

  • Login to your GitHub account

  • Go to the GitHub repository and click on Settings > Actions > Runners as shown in below screenshot:

  • Click on New self-hosted runner button as shown in below screenshot:

  • It will outline the steps for setting up GitHub self-hosted runners on all supported operating systems and architectures, as depicted in the screenshot below:


  • After completing all the steps, the GitHub self-hosted runner will appear in the repository and be prepared to initiate the jobs, as demonstrated in the screenshot below.


Setting Up Organization Level Runners

Organization-level runners have the capability to handle jobs across multiple repositories within an organization. To set up organization-level runners, follow the steps outlined below:


  • Login to your GitHub account

  • Make sure you have relevant permission to add runner at GitHub organization level.

  • Click on your GitHub organization e.g. anantacloud in this example.

  • Next, click on Settings link as shown in below screenshot:



  • Click on Actions > Runners

  • Click on New runner button as shown in below screenshot:


  • It will outline the steps for setting up GitHub self-hosted runners at the organization level for all supported operating systems and architectures, as illustrated in the screenshot below:

  • After completing all the steps, you will notice that the GitHub self-hosted runner has been added at the organization level.


Using Self-Hosted Runners in GitHub Actions

To utilize GitHub self-hosted runners, include the following code in your workflow YAML file for each job. You can also add any other specific label in your workflow file.

runs-on: self-hosted


We have developed a standard Terraform module to set up and configure GitHub self-hosted runners at both the repository and organization levels on major public cloud platforms like AWS, GCP, Digital Ocean Cloud, Oracle Cloud, and Azure.


Conclusion

In conclusion, configuring a self-hosted GitHub runner on a virtual machine offers greater flexibility, control, and performance for your CI/CD pipelines. By following the steps outlined in this guide, you can optimize your build process, reduce dependency on GitHub’s hosted runners, and tailor the environment to better suit your project’s needs. Whether you're working with private repositories, specific dependencies, or custom configurations, a self-hosted runner provides a scalable solution for efficient and secure continuous integration


References


If you found this article helpful, hit subscribe for more in-depth content 🔔, share your thoughts in the comments 💬, and spread the word to others who could benefit 📣! Don’t forget to rate this blog ⭐ to encourage the writer to create more insightful content.



Comments

Rated 0 out of 5 stars.
No ratings yet

Add a rating
average rating is 4 out of 5, based on 150 votes, Recommend it

Subscribe For Updates

Stay updated with the latest cloud insights and best practices, delivered directly to your inbox.

91585408_VEC004.jpg
Collaborate and Share Your Expertise To The World!
Ananta Cloud welcomes talented writers and tech enthusiasts to collaborate on blog. Share your expertise in cloud technologies and industry trends while building your personal brand. Contributing insightful content allows you to reach a broader audience and explore monetization opportunities. Join us in fostering a community that values your ideas and experiences.
business-professionals-exchanging-handshakes.png
bottom of page