You've learned what runners are and how they are structured in the GitHub cloud environment. In this section, we'll help you discern whether a self-hosted runner is the right choice for your project or organization. You'll learn about scaling considerations and configuration scenarios. We'll also cover some points to help you troubleshoot your runner.
"When should I decide for a self-hosted runner?" There are a number of factors to consider. The first is the flexibility offered to optimize the runner.
Although cloud-based runners offer ease of use, there is a level of flexibility and optimization that only self-hosted runners are better able to provide. They run on your hardware. So, you have full control within your infrastructure, breaking you free from the limitations on performance and configuration encountered with cloud-based runners. You are able to allot the desired amount of hardware resources to each runner. In contrast, a cloud-based runner will have a fixed configuration and require the assistance of a GitHub support team when the time comes to perform any updates or tweaking.
Another reason to opt for self-hosted runners is that they enable you to customize access to your runners. A cloud-hosted runner runs on a repository level. In contrast, runners on your hardware can be configured for access and use on a variety of levels that we cover in this topic.
For optimal performance, there are some minimal requirements that you will want to have in place:
-
A minimum of 4 vCPUs are necessary for installation
-
Make sure that your hardware has any required software installed, including runner dependencies and dependencies for any actions used. Install the following:
- Node.js to enable JavaScript actions.
- Docker to facilitate container actions.
For times when you need to restart the hardware on which your runner lives, you will probably also want your runner to restart automatically. Configure your runner as a service to ensure that machines come back online after a hardware restart.
Refer to the GitHub documentation > Configuring the self-hosted runner application as a service to learn how to configure your runner as a service.
Do not use self-hosted runners in public repos as malicious code submitted through a pull request could be run.
As previously mentioned, hosting runners on your hardware allows you to group several runners and control access to them on several levels. Controlling access ensures the consistent availability of runners only to the teams or users to which you have assigned them.
There are a number of configuration options in place to control access:
You can take advantage of a a wide range of granularity to configure access to runners or runner groups. First, there are various levels at which you can assign runner visibility. These are:
-
Register your runner at the enterprise level to share across all of the organizations of an enterprise.
-
Some repositories are shared across an organization. Register your runner on an organizational level to make it available only to that specific organization across all of its repositories.
-
You can make runners accessible only to certain repositories.
Grouping refers to organizing your runners into groups. Runners that are registered on an enterprise or organizational level can be organized into pools. Access is then granted to or restricted for a specific user or group of users to a certain group of runners. Designate which organizations in the enterprise can use the runners in the group. Specify which repositories inside of an organization can use a group of runners.
It ensures that access is available to a group of runners specifically for teams or employees whose use of the runner has priority.
In the same way individual runners can receive labels, so can runner groups.
In addition to the labels that GitHub assigns to runners, administrators can add customer labels to the runners they create. These labels enable the runner to be targeted at runtime.
For the technical specifics on setting up your custom labels, refer to GitHub documentation - Creating a custom label.
If you are experiencing any issue with your runner, a starting point for troubleshooting is the _diag directory. This location contains log files that you should examine for indications of what has failed.
Note: This directory may not be immediately available until the system produces logs; at which point the system creates the folder.
It is important to note that there are times that a runner may not be in a clean state. This means that artifacts from previous builds could still exist in your working directory and interfere with new builds. Be aware of any stray, leftover artifacts if your build relies on caching.