Self-hosted runners for GitHub Actions

Reading Time: 4 minutes

Self-hosted runners offer more control of hardware, operating system, and software tools than GitHub-hosted runners. It provide us with ability to create custom hardware and software configuration with more processing ability to run larger jobs. Runners can be physical, virtual, in a container, on-premises, or in a cloud. In this blog, we will be adding a runner in cloud. For introduction to CI/CD using GitHub Actions check this blog.

Advantages of self-hosted runners

Self-hosted runners offer various advantages when the hosted virtual environments don’t meets all our requirements. Some of them are following :

  • Your environment, your tools: Your workflow may require software that’s proprietary, expensive, or difficult to install on virtual environments. Or maybe you need more flexibility with platforms like a different Linux distribution or architecture. Self-hosted runners allow you to create the perfect environment for your workflow. See the product documentation for details on supported platforms and architectures.
  • Any size machine or configuration: Self-hosted runners allow you to use the specific hardware you need, whether that’s more memory or cores, or different configurations like GPUs or ARM-based CPUs. 
  • Secure access and networking: We received feedback that securely networking to and from hosted virtual environments can be challenging. Self-hosted runners make this easier by allowing you to more easily enable access to fire-walled on-premises resources or RDP into the environment that’s running your job.
  • Large workload support: In some cases, your jobs benefit from using techniques like incremental source fetches, package caches, or other configurations that require persistence. Self-hosted runners give you the opportunity to persist whatever you like for your jobs.

Differences between GitHub-hosted and self-hosted runners

GitHub-hosted runners offer a quicker, simpler way to run your workflows, while self-hosted runners are a highly configurable way to run workflows in your own custom environment.

GitHub-hosted runners:

  • Receive automatic updates for the operating system, pre-installed packages and tools, and the self-hosted runner application.
  • They are managed and maintained by GitHub.
  • Provide a clean instance for every job execution.
  • Use free minutes on your GitHub plan, with per-minute rates applied after surpassing the free minutes.

For more details on GitHub-hosted runner: GitHub-hosted runners

Self-hosted runners:

  • Receive automatic updates for the self-hosted runner application only. You are responsible for updating the operating system and all other software.
  • Can use cloud services or local machines that you already pay for.
  • Are customizable to your hardware, operating system, software, and security requirements.
  • Don’t need to have a clean instance for every job execution.
  • Are free to use with Github Actions, but you are responsible for the cost of maintaining your runner machines.

For more details on GitHub-hosted runner: Self-hosted runners

Downloading and configuring the runner

You must be an administrator to change any configurations. Once logged in, navigate to the Actions tab from your repository’s settings. You should see a new section where you can manage your self-hosted runners.

Click the Add runner button, select the platform you’re targeting, and then follow the sequence of shell commands to download, configure, and run your runner.

During configuration, the CLI will prompt you to answer a few questions, including naming the runner, and determining the output directory for any jobs.

Once your runner is successfully configured and listening for jobs. It will display as Idle which means you’re ready to update your workflow.

Using the runner

To support using self-hosted runners in your workflows, we’ve expanded the experience of using the runs-on key. When registering your self-hosted runners, they’re each given a read-only label self-hosted which you can use with runs-on. Here’s an example:

# Use Any available Self-hosted runners connected to repo
runs-on: self-hosted

In addition to the self-hosted label, each runner is also given read-only labels that identify its platform and architecture.

  • Platforms: windowslinuxmacos
  • Architectures: x64 is available today. ARM64ARM32, and x86 will be available shortly after Actions GA

Since self-hosted runners have more than one label, you can provide a single label, or array of labels to runs-on. These allow you to filter the runners to only those that include the specific label values you specify. Here’s an example where we filter labels:

# Use an ARM32 linux based self-hosted runner
runs-on: [self-hosted, linux, ARM32]

# Use only macos based based self-hosted runners
runs-on: [self-hosted, macos]

# Use an linux based based self-hosted runners with custom label Runner1
runs-on: [self-hosted, linux, Runner1]

To use docker based action in the self-hosted runner, you need to install docker in your runner and later change permission of docker.sock file to run docker with following command.

sudo chmod 666 /var/run/docker.sock

Points to Remember

1 . You can add self-hosted runners at various levels in the management hierarchy:

  • Repository-level runners are dedicated to a single repository.
  • Organization-level runners can process jobs for multiple repositories in an organization.
  • Enterprise-level runners can be assigned to multiple organizations in an enterprise account.

2. GitHub automatically removes a self-hosted runner after 30 days. If it has not connected to GitHub Actions.

3. Queue time for a job on self-hosted runner is maximum of 24 hours and GitHub Action terminates the job after this limit.

4. GitHub recommend that you only use self-hosted runners with private repositories. This is because forks of your repository can potentially run dangerous code on your self-hosted runner machine by creating a pull request that executes the code in a workflow.

Leave a Reply