Mastering Self-Hosted Runners for GitHub Actions: Setup, Benefits, and Best Practices

What is a Self-Hosted Runner? #

Self-hosted runners allow you to run your workflows on your own infrastructure, such as your own servers, virtual machines, or containers. This can be useful if you have specific security or compliance requirements, need to access local resources, or want to use specific tools or software that are not available in the GitHub-hosted runners. Self-hosted runners also provide additional control over the environment and can help you save costs on compute resources.

Setting up and configuring self-hosted runners for GitHub Actions involves several steps. In this guide, we'll cover the process for setting up a self-hosted runner for a repository. To use self-hosted runners in GitHub Actions, you need to set up and register one or more runners in your own environment, and then configure your workflow file to use them instead of the GitHub-hosted runners.

Implementing Self-Hosted Runners for GitHub Actions #

Prerequisites #

Before setting up a self-hosted runner, ensure you have the following:

A GitHub account with administrative access to the repository.A machine to host the runner (physical, virtual, on-premises, or in the cloud).

Step 1: Add a self-hosted runner to the repository #Go to the main page of the repository on GitHub.com.Click on Settings under your repository name.In the left sidebar, click Actions, then click RunnersClick New self-hosted runner

Step 2: Choose a Platform #Follow the instructions provided on the New self-hosted runner page and select a platform on which to set up your self-hosted runner, such as Linux, macOS, or Windows and architecture (x64, ARM or ARM64).

Github Actions Self hosted runner examples

Self-hosted runner instructions for mac

Step 3: Download and extract the runner application #Depending on the OS and architecture type selected, download and extract the runner application for your platform. This runner software is responsible for listening to queued tasks and executing them.

Step 4: Configure the runner application #Open a terminal or command prompt on the machine where you extracted the runner application.Navigate to the directory containing the extracted runner application.Run the config.sh script (Linux/macOS) or config.cmd script (Windows) with the provided token and repository URL. For example:./config.sh --url https://github.com/your-username/your-repo --token YOUR_TOKENReplace your-username, your-repo, and YOUR_TOKEN with the appropriate values.

Run the run.sh script (Linux/macOS) or run.cmd script (Windows)

Step 5: Install the runner as a service #To ensure the runner starts automatically and runs in the background, install it as a service.

For Linux/macOS #

Run the svc.sh script with the install command:sudo ./svc.sh installStart the runner service:sudo ./svc.sh startFor Windows #During the configuration process in Step 4, you'll be prompted to run the runner as a service. Follow the instructions provided.

Step 5: Verify the runner is online #Go back to the "Runners" page in your repository settings on GitHub.com. You should see your self-hosted runner listed as "online."

Now your self-hosted runner is set up and ready to execute GitHub Actions workflows. To use the self-hosted runner in a workflow, update the runs-on key in your workflow file to use the self-hosted label:

jobs:  your-job:    runs-on: self-hostedFor more information and advanced configuration options, refer to the GitHub Actions documentation

Step 6: Maintain Security #It is important to configure self-hosted runners correctly to avoid security risks. Implement security protocols, such as access control and data encryption, to ensure the self-hosted runner operates within your organization's security guidelines.

Step 7: Monitor and Manage #Regularly monitor and manage your self-hosted runner to ensure optimal performance and address any maintenance or reconfiguration needs.

Self-hosted runners are a valuable tool for organizations looking to optimize resource allocation, improve performance, and maintain strict control over security and data privacy. By understanding the purpose, benefits, and implementation process, you can effectively implement a self-hosted runner for your projects.

Setting up DevZero as a Self-Hosted GitHub Actions Runner #

Our dedicated guide walks you through setting up a DevZero environment as a self-hosted GitHub Actions runner. With this setup, you can enjoy more control over the execution environment. Plus, it's free to use with GitHub actions and will not incur per-minute GitHub charges.

Switching between GitHub-hosted and self-hosted runners #To switch between GitHub-hosted and self-hosted runners in a workflow, you can use the runs-on key in your workflow file. The runs-on key specifies the type of runner to use for a job in the workflow. Here's how to switch between GitHub-hosted and self-hosted runners:

For example, to switch from a GitHub-hosted runner to a self-hosted runner, change the runs-on key from ubuntu-latest to self-hosted:

jobs:  your-job:    runs-on: self-hostedThis tells GitHub to use a self-hosted runner for the job instead of a GitHub-hosted runner.

GitHub-Hosted Runners vs Self-Hosted Runners #GitHub-hosted runners and self-hosted runners offer different advantages and limitations when it comes to running GitHub Actions workflows.

Self-hosted runners - Advantages #

Simplicity: GitHub-hosted runners require minimal setup and maintenance.Automatic Updates: Operating systems, pre-installed packages and tools are consistently updated eliminating manual efforts from the user's side.

Control: They grant users more control over hardware, operating system, and corresponding software tools.Customization: Custom configurations can be implemented to cater to specific requirements.Deployment Flexibility: Can be deployed on physical servers, virtual machines, or container images, and can run on-premises or in a public cloud like Google Cloud, AWS, or Azure.

Self-hosted runners - Limitations #

Limited Configurations: GitHub-hosted runners are limited to the operating systems and hardware configurations provided by GitHub.

Limited Tools: They are also limited to the pre-installed packages and tools provided by GitHub.

Management Effort: They require greater effort in deployment and management.

Security Risks: could be persistently compromised by untrusted code, as they do not guarantee running in ephemeral clean virtual machines.

Self-hosted Runners - Added Benefits #

Self-hosted runners present additional benefits, impelling many towards adopting it:

Control & Compliance: Strict access control and data encryption policies ensure the organization's data privacy and regulatory compliance.Access to Local Resources: Enables access to local resources absent in GitHub-hosted runners.‍

Cost & Performance: Although costs may vary based on hardware and software, the performance is superior due to the control over hardware configurations. This allows for necessary memory and processing power adjustments for larger jobs.

Security & Customization: The possibility of implementing strict access control and encryption policies amplifies security. Customization aids in aligning configurations to project needs.

Cost-Effectiveness: Especially practical for large organizations that maintain their own infrastructure.GitHub-hosted runners offer ease of setup and maintenance, while self-hosted runners provide more control and customization. The choice between the two depends on your specific requirements and preferences.

Best practices #

Use GitHub-hosted runners for standard workflows #

For standard workflows that do not require custom hardware configurations or specialized software tools, use GitHub-hosted runners. GitHub-hosted runners are easy to set up and maintain, and they receive automatic updates for the operating system, pre-installed packages, and tools.

Use self-hosted runners for specialized workflows #

For workflows that require custom hardware configurations or specialized software tools, use self-hosted runners. Self-hosted runners provide more control over hardware, operating system, and software tools than GitHub-hosted runners, allowing for custom hardware configurations that meet specific needs with processing power or memory to run larger jobs.

Use a combination of GitHub-hosted and self-hosted runners for optimal performance #

To optimize performance and reduce costs, use a combination of GitHub-hosted and self-hosted runners. Use GitHub-hosted runners for standard workflows and self-hosted runners for specialized workflows that require custom hardware configurations or specialized software tools.

Use the strategy key to automatically switch between runners #

It is possible to configure a workflow to automatically switch to GitHub-hosted runners if self-hosted runners are busy or unavailable. This allows you to take advantage of the benefits of both types of runners and ensure that your workflows always have access to the compute resources they need.

The strategy key allows you to define a matrix of different configurations for your job, including the runs-on key. You can define multiple configurations for different types of runners, including self-hosted runners and GitHub-hosted runners. GitHub will automatically select the first available runner that matches the configuration.

Here's an example of how to use the strategy key to automatically switch to GitHub-hosted runners if self-hosted runners are busy:

jobs:  your-job:    strategy:      matrix:        runner-type: [self-hosted, ubuntu-latest, windows-latest, macos-latest]    runs-on: ${{ matrix.runner-type }}In this example, the strategy key defines a matrix of different configurations for the runs-on key. The runner-type variable is set to a list of different runner types, including self-hosted, ubuntu-latest, windows-latest, and macos-latest. GitHub will automatically select the first available runner that matches the configuration.

If a self-hosted runner is available, GitHub will use it to run the job. If all self-hosted runners are busy or unavailable, GitHub will automatically switch to a GitHub-hosted runner that matches the configuration.

Monitor runner usage and performance #Monitor runner usage and performance to ensure that your workflows are running efficiently and effectively. Use the GitHub Actions dashboard to monitor runner usage and identify bottlenecks or performance issues. Use the GitHub API to programmatically monitor runner usage and performance and automate scaling and optimization.

Conclusion #In conclusion, self-hosted runners offer greater control, customization, and flexibility in running GitHub Actions workflows, while GitHub-hosted runners provide simplicity and ease of maintenance. By understanding their advantages and limitations, you can choose the most suitable runner type for your projects. Combining both types and employing best practices can help you optimize performance, reduce costs, and maintain security in your workflows.

‍

‍