If you’re like most people, you probably use Github to keep track of your projects and share them with others. But what if you want to run your own builds on your own servers? That’s where self-hosted runners come in. A self-hosted runner is a program that runs the actions that are associated with a given repository on your own server. This means that you can control how often the runner runs, how long it takes to complete each action, and even which repositories it runs on. There are a few things you need in order to set up a self-hosted runner:

  1. A Github account - You’ll need an account on Github in order to create and manage runners.
  2. A server - You’ll need a server in order to host the runners and their repositories. We recommend using DigitalOcean or AWS for this purpose.
  3. An SSH key - You’ll need an SSH key in order to access the server from outside of your computer (you can find these online).

Github Actions are automation pipelines that can be used to run CI testing and builds. It runs in the cloud through Github’s servers, but there are some cases, such as intensive code compiling, where you might prefer running them on your own dedicated worker nodes.

Why Use Self-Hosted Runners?

One of the major benefits of Github Actions is that it’s free and integrated nicely into Github’s system. Making new commits or release tags will directly trigger an action pipeline if you set it up to do so.

Github Actions are billed in “minutes,” and open-source public repositories have an unlimited number of minutes. If you’re working on a private repository though, you will only have 2000, or 3000 with Github Pro or Teams plans. You can buy more minutes directly, or upgrade to Github Enterprise, which comes with 50,000.

However, Github also supports the ability to self-host the machine that runs the pipeline. You can use any kind of machine as the self-hosted runner, including local machines, dedicated servers, or cloud VPS instances. This can be quite useful, especially if you have spare hardware lying around.

This has a number of benefits beyond just cost savings for high activity workloads. Often, code compilation can be a very intensive task. While Github Actions builds aren’t necessarily sluggish, they’re still running on shared cloud compute, so it may benefit you to be running the build on a high-performance dedicated server. The same is true for memory-intensive applications that may need a lot of RAM to finish.

On top of performance, self-hosting also allows you to control the environment for the build. Perhaps you need to integrate with on-premises servers or software, or you need to run an operating system that isn’t available with Github’s default runners (it does support Linux, Windows, and macOS, just not specific Linux builds besides Ubuntu).

Setting Up a Self-Hosted Runner

Setting up a runner is pretty simple. Basically, you’ll need to install the runner software on your machine and connect it to Github. Once it’s available, you can configure certain Github Actions to use your self-hosted runner instead of the default ones.

You can either add runners to a specific repository or add them to a Github Organization. Adding them organization-wide is generally a lot more useful, but the setup for either one is the same.

Head over to your organization’s settings, and under Actions > Runners, add a new runner.

Github provides steps to set up and install the runner here. You can copy paste these commands, but you can also use a Docker image if you prefer running it that way.

The next section has you link it with Github. This uses a generated token so it can access your account and verify the runner.

You can choose on this screen the name of the runner, the group it’s assigned to, and any labels associated with it. These can be used to filter out runners in action configurations.

Then, you’ll need to start the runner. You’ll probably want to run this under tmux or set up a service to run it automatically.

RELATED: How To Add Your Own Services to systemd For Easier Management

If you’re using a public repository, the ability to use self-hosted runners is disabled by default. This is because running builds on your own hardware is a potential security risk if you’re running builds for third party pull requests. If you’re not doing pull request builds, it’s not a problem, and you can toggle it on from the default “Runner Group” settings.

Then, you can use the self-hosted tag to make builds execute on this runner.

The runner should pick it up almost immediately.