GitHub Actions Day 26: Self-Hosted Runners

December 26, 2019

This is day 26 of my GitHub Actions Advent Calendar. If you want to see the whole list of tips as they're published, see the index.

Advent calendars usually run through Christmas, but I'm going to keep posting about GitHub Actions through the end of December. Consider it bonus content!

This month I've talked a lot about the software installed on the runners that GitHub provides for running your workflows, and how to install new software.

But what if you wanted to customize your own runner instead of using the ones that GitHub Actions provides? You can use the GitHub Actions self-hosted runner to run workflows on any infrastructure that you have, whether it's an on-premises machine or a runner that you configure in the cloud.

Being able to set up a self-hosted runner is important if you have incredibly custom dependencies -- some people still need to use software that has heavy license dependencies like hardware dongles. Or you might want to run a build on an ARM device that you have, instead of the GitHub Actions runners, which are amd64.

More commonly, you might want to talk to machines within your firewall to run tests against them. Or do a deployment step to servers within your firewall.

To set up a self-hosted runner, you first need to download the software to the machine you want to configure. To go the Settings tab in your repository, then select Actions in the left hand menu. There you can configure your self-hosted runners.

Self-Hosted Runners

Just click "Add Runner", and follow the instructions.


Once you've set up and started the self-hosted runner, it will start polling GitHub to look for workflow runs. You can configure a workflow to run on your self-hosted runner by setting the runs-on to self-hosted. Here I have a simple workflow that will run on my laptop, it just runs uname -a.

When I trigger this workflow, you can see that it accepts the job and then runs in.


And in GitHub itself, you can see the results of the run.


It's easy to get workflows running on the GitHub Actions runners, or on a self-hosted runner within your network. And the GitHub Actions self-hosted runner will poll GitHub so that you don't need a hole in your firewall to be able to run workflows on machines located inside your firewall.