Adding a Self-hosted Runner

Still want to use Github Actions to run CI and sad that there’s no more Github Actions minutes? Read on!

Self-hosted runners provide the same service that Github Actions runners provide, but do not have monthly minute limits and provide you with more control over the software/hardware that your code runs on. Self-hosted runners support up to 1000 API calls an hour, jobs timeout after 72 hours, and jobs can queue for at most 24 hours. Runners can be configured on Linux, macOS, and Windows, as well as on x86, ARM, and ARM64 platforms.

Prerequisites

Here are the resources you’ll need to add a runner to your repository:

1. A machine (virtual or physical) that is always on, i.e. physical server, VPC instance, etc.

• The machine should match the current Github Actions machine type. For example, if your runs-on machine is ubuntu-latest, you would want a x86-64 machine running Linux.
• If you don’t already have a physical server or cloud-based virtual machine, you can obtain a free instance through any number of hosting platforms like AWS, GCP, Azure, or Oracle. You can also access more powerful instances through the Github Student pack, as well as the educational trials that many hosting providers have.

2. Compute resources sufficient for your actions jobs.

• For most jobs, 1vCPU, 1 GB of RAM, and 1GB of free disk space will be plenty. Unless your tests are very very hungry you could probably set the runner up on a RasPi Zero and still be fine.

3. Root access on the actions machine.
4. Admin access to your CS130 repository.

Installation

1. Go to the homepage of your repository.

2. Open Settings from underneath the repository name. If you don’t see the Settings option, you do not have admin access to the repo and will need to request it.

3. Click on Actions in the left sidebar.

4. At the bottom of the page under Self-hosted runners, click Add runner.

5. Choose the appropriate OS and Architecture from the dropdown menus. For most cases, choose Linux and x64.

6. Follow the instructions provided by pasting them into a shell prompt to download and configure a runner. Missing dependencies on Linux/macOS can be installed with sudo bin/installdependencies.sh. If your workflows execute jobs that require other tools such as Docker, those will have to be installed manually through the package manager of the system. If you’re just using the standard checkout@v2 action and manual run commands, no dependencies other than those installed by the script are necessary. A list of dependencies required by platform can be found on the repository page: https://github.com/actions/runner.

7. The runner can then be started either with ./run.sh, or optionally installed as a macOS launchd or Linux systemd service by executing sudo ./svc.sh install. If not installed as a service, the run.sh command should be run within a detachable process such as screen or tmux to ensure a broken ssh connection does not terminate the runner. If installed as a service, the runner will automatically start on boot, so a detachable process is not required.

8. If everything executed correctly, you should now see the runner listed under Self-hosted runners on the Actions page.

Usage

To change Github Actions workflows to use the self-hosted runners, change the runs-on line in your workflow definition file to be runs-on: self-hosted. Subsequent Actions runs will be executed on the self-hosted worker instead of the Github-hosted workers. Note that self-hosted runners do not fully reinitialise the environment on every run. If you find that this behaviour is incompatible with your tests, consider a Docker or Kubernetes based runner such as https://github.com/tcardonne/docker-github-runner.