How and when to run Github Actions jobs on your own machine?

In a previous blog, I wrote about using your own Docker images with Github actions. One of the comments was about contacting private or custom docker registries (like Amazon’s ECR). It also mentioned Self Hosted runners as a means to run on your own machine (and hence, your own docker image).

I appreciate Anony’s comment, and in this article, we will talk about self-hosted runners in github actions.

Why run self-hosted runners?

Special Hardware Needs

In the 2 ways to use docker with github actions article, I already mention one reason: when you want to use ARM (Advanced RISC Machines) architecture related artifacts and builds. For instance, images built on an ARM machine will not always run on an x86 machine and vice versa. You can setup a self-hosted runner on an ARM machine (either locally or on any cloud vendor) and run your workflow on it.

Another reason is mentioned in the 7 tricks for github actions beginners article. MacOS github runners are slow. Not only they are slow, for some reason they have a slow internet connection. We got timeouts plenty of times just for running npm install for projects. By running the flow on your own MacOS machine, you can get a faster machine and also cut costs, as MacOS machines cost much more than linux.

All in all, if you need a stronger or specific machine, you can get one from your cloud vendor or use your own laptop and set it up as a sefl-hosted runner.

Large Images

This reason was mentioned in the comment. It might be that your image is heavy in size – or even some installation. A machine that already has this image locally can save you a lot of time as opposed to a github actions standard machine that needs to pull the image.

Debugging

When you are running on your own machine, you have full access to it. You can SSH into the machine and control it, change code, read logs and everything you’d do on… well… your own machine 🙂

Security

You can set up a non-internet-facing machine (e.g. behind some VPN) and ensure more privacy for your flow’s internals.

How do self-hosted runners work?

Self-hosted runners are machines that run the self-hosted runner script (see “Install a local runner” for more details). When you run the script, you set the self-hosted key you get from your github UI (see “Setup a self-hosted runner in the repo”).

Once the script runs on the machine, it opens a long poll connection (50 seconds) with github.

In an action in the repository you set the action’s trigger to be self-hosted and github actions knows to send messages to the machine running the script above. These messages are the commands laid out in the workflow that was triggered.

Setup a self-hosted runner in the repo

Let’s get to business. The first step is to go to your repository’s settings (red square). In there, select runners under Actions (blue square) and click on New self-hosted runner (gree square).

This will lead you to the set up page. You’ll be able to download the runner script for the OS and hardware you need with clear to follow instructions:

Below that, you will have configuration setup instructions:

Note the --token part (I hid it for obvious reasons). This will make sure the script handshakes with the right repository.

If you follow the steps above, you will see the runner working on your machine.

For instance, I just opened a new folder on my machine, ran the install commands, configured the token and ran the script. This resulted in this:

Yea! My machine is listening for jobs!

The next step was to set the trigger of the action (the on property) to self-hosted. Once I did that, the actions started running on my machine. You can see the run here.

A Word about Security

Self-hosted runners are meant to be used in private github repositories. Why? Because forks of the main repository might be able to run the jobs on your self-hosted runner. Just make sure you’re good with that. In addition, I mentioned you can set a VPN-only access to the machine and allow github actions access only via your VPN token (or however you enforce it 🙂 ).

Summary

Github actions allow you to run workflows on a set hardware spec. Self-hosted runners allow you to run your workflows on a machine of your own choosing.

Its other benefits should be considered vs. the obvious cons like higher maintenance, more configuration and possible high cloud costs (depending on your needs of course).

Our team (vivid) does not use it, as we have no need, but for many people (especially with complex hardware-dependent builds) it can be a lifesaver.

Thanks a lot to Keren Kenzi for her thorough and kind review.