Table of Contents
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:
Repository-level: These runners are exclusively assigned to a specific repository.
Organization-level: These runners are capable of handling jobs across multiple repositories within an organization.
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.netIf 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