Self-Hosted Runners in GitHub Actions Workflows - Setup Guide

Costa Paigin

Head of DevOps

April 25, 2023

Share your Social Media

As software development workflows become more complex and demanding, the importance of efficient and flexible automation tools cannot be overstated. GitHub Actions is one such tool that has gained immense popularity in recent years. It's a powerful platform that enables developers to build, test, and deploy software using customizable workflows. 

Source: GitHub

While GitHub provides virtual environments for running actions, there are times when you may need to run your workflows on your own infrastructure. This is where self-hosted runners come in, providing an invaluable solution for running your GitHub Actions workflows on your own hardware, whether it's on-premises or in the cloud. In this article, we'll delve into the basics of setting up and using self-hosted runners with GitHub Actions, helping you optimize your workflows and improve your development process.

Setting Up a Self-Hosted Runner

Before you start using a self-hosted runner, you must meet certain prerequisites. Here's what you'll need:

  • Hardware: You'll need a machine that can run the GitHub Actions runner application, such as a virtual machine, cloud instance, or a physical server.
  • Operating System: The runner application can run on Windows, Linux, or macOS. Ensure that your machine meets the system requirements for the OS you plan on using.
  • GitHub Account: You'll need a GitHub account and configure permissions to create and manage runners in your repository or organization.

Once you've met these prerequisites, you can proceed to install and configure the GitHub Actions runner application on your machine. Here's how:

  1. Download the runner application for your OS from the GitHub Actions runner releases page.
  1. Extract the runner application to a directory on your machine, open a terminal or command prompt and navigate to the directory where you extracted the runner application.
  1. Now, run the ‘./’ (Linux/macOS) or ‘config.cmd’ (Windows) script to configure the runner. You'll need to provide your GitHub account credentials and answer a few questions about the runner configuration.
  1. After the runner is configured, run the ‘./’ (Linux/macOS) or ‘run.cmd’ (Windows) script to start the runner. This script will register the runner with your repository.
  1. As a last step, verify that the runner is indeed registered by going to the "Settings" tab in your repository or organization, selecting "Actions" from the left menu, and checking that your runner is listed under "Runners".

Using Self-Hosted Runners in GitHub Actions Workflows

Now that you've set up your self-hosted runner, let's look at how you can use it in your GitHub Actions workflows. Here's what you need to know:

Specifying the runner label in your workflow file

To run a job on your self-hosted runner, you need to specify the runner label in your workflow file. The runner label is a unique identifier that you assigned to your runner during the registration process. Here's an example of how to specify the runner label in your workflow file:

runs-on: self-hosted
- name: Checkout code
uses: actions/checkout@v2
- name: Build and test
run: |
make build
make test
- my-runner

In this example, we're running a job named "build" on a self-hosted runner with the label "my-runner". Note that we're specifying self-hosted as the runs-on value, which tells GitHub Actions to look for a runner with the specified label.

Running jobs on your self-hosted runner 

Once you've specified the runner label in your workflow file, you can start running jobs on your self-hosted runner. GitHub Actions will automatically route the job to the runner with the specified label. The job will run on your self-hosted runner just like it would on a GitHub-hosted runner.

Source: Chips Alliance

Understanding the benefits of using self-hosted runners

Using self-hosted runners offers several benefits over using GitHub-hosted runners. Here are some of the key advantages:

  • Control: With self-hosted runners, you have complete control over the hardware and software environment used to run your workflows. This can be especially important if you have specific requirements for your development process.
  • Customizability: Self-hosted runners can be customized to meet the specific needs of your workflows. For example, you can install additional software or libraries on the runner to support your development process.
  • Scalability: You can easily add more self-hosted runners as your development needs grow, providing additional capacity and flexibility.
  • Security: Self-hosted runners can be configured to run behind a firewall or other security measures, providing an additional layer of protection for your workflows.

By using self-hosted runners, you can optimize your workflows and improve your development process, all while maintaining control, customizability, scalability, and security.

Best Practices for Managing Self-Hosted Runners

To get the most out of your GitHub Actions workflows, it's important to follow best practices for managing your self-hosted runners. Here are some key points to keep in mind:

  1. Keeping your runners up to date with the latest software and security patches: This will help ensure that your runners are running smoothly and securely. You should regularly check for updates to the GitHub Actions runner application and any other software running on your runner.
  1. Managing the number of self-hosted runners you have running: Having too few runners can lead to slow or stalled workflows while having too many runners can be wasteful and unnecessary. You should monitor your workflows and adjust the number of runners as needed to maintain optimal performance.
  1. Monitoring and logging your self-hosted runners: This can help you identify issues and troubleshoot problems. You should set up monitoring and logging for your runners, including metrics such as CPU and memory usage, network traffic, and error rates. You can use tools such as Prometheus, Grafana, or Elasticsearch for monitoring and logging.

Manage GitHub Actions Directly from Slack

All in all, self-hosted runners are a powerful tool for developers using GitHub Actions workflows. They offer a level of flexibility and customization that cannot be achieved with GitHub's hosted runners. With the ability to install and configure the runner application on your own machine, you have complete control over the resources used for your workflows. Additionally, self-hosted runners allow you to access resources and data that may not be available on GitHub's hosted runners. If you follow the best practices for managing your runners, you can ensure they remain secure and efficient.

If you're looking to give Devs (and any other users) easy and secure access to manage GitHub Actions directly from Slack, feel free to explore Kubiya’s solution for GitHub Actions. Kubiya also makes it easy to set up and manage self-hosted runners, so you can customize your workflows to suit your needs. 


What’s Interesting ?


Artificial intelligence