How to Add Your Own Runner Hosts to GitHub Actions

1. What GitHub Actions Is

In an earlier post I put the CI capabilities GitLab provides into practice — click here to see. The advantages of using GitLab are that it can be deployed privately, it allows an unlimited number of private repositories, its CI configuration is simple, and it can connect to self-hosted Runners. But as GitHub becomes more and more open, these advantages of GitLab are gradually being lost.

From the CICD perspective, the closer a feature is to the Git repository, the closer it is to developers. In the future developer market, SaaS platforms like GitHub, GitLab, Coding, and Gitee will have remarkable staying power.

GitHub Actions is a service similar to GitLab CI. GitLab uses the .gitlab-ci.yml file by default to describe the CICD pipeline, while GitHub uses yaml files under the .github/workflows directory. The biggest difference is that GitHub provides an Actions marketplace, and developers can use these atoms to orchestrate pipelines quickly.

In the post Deploying Hexo Static Pages with an Image, I used the following yaml configuration to build and push the image:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
name: build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Build image
        run: make build

      - name: Login Registry
        uses: docker/login-action@v1
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GHCR_TOKEN }}

      - name: Push image
        run: docker push ghcr.io/shaowenchen/documents:latest

After every code push, Actions runs automatically, as shown below:

This approach is very developer-friendly, and when the network is smooth, GitHub Actions can meet the CICD needs of many teams.

2. When You Need to Connect Your Own Runner

2.1 Requirements on the Build Machine

Currently, GitLab only provides the following kinds of runtime environments:

windows
ubuntu
macos

But not every version of each system is supported — you can only use the specified versions, and you cannot specify the CPU architecture.

On the other hand, during the build process the build machines GitHub provides also have physical resource limits. The configuration of the build VM is as follows:

2 core CPUs
7 GB of RAM memory
14 GB of SSD disk space

These physical resource configurations may improve in the future, but there will always be limits. When you need to build certain large projects, especially C++ projects, this kind of physical resource configuration cannot meet the requirements.

2.2 Private Repositories Need a Lot of Builds

The figure below shows GitHub’s official build pricing:

Fortunately, public repositories are free to use; only private repositories have quota limits. Users on different paid tiers get different build minutes. Note that the duration here refers to Linux build time. One minute on Windows counts as two minutes of Linux; one minute on MacOS counts as ten minutes of Linux.

For projects with heavy build demands on private repositories, using the build machines GitHub Actions provides is not cost-effective.

3. Adding a Host Runner

The Runner here refers to the execution environment for GitHub Actions — that is, the environment in which the instructions in the yaml files under the .github/workflows folder run. Here we mainly add a host Runner; to add a container or Kubernetes Runner you need to package actions-runner into an image and then run it to connect to GitHub Actions — there is no other difference.

First, go into the project and find Actions on the Settings page.

Click Add runner in the figure above to reach the add-host page below, which likewise supports three operating systems: macOS, Linux, and Windows.

After choosing the operating system and architecture on the page, just follow the installation instructions.

Create a user runner:runner

1
2
3
4
groupadd -g 1234 runner
useradd runner -u 1234 -g 1234
su runner
cd ~

Download the Runner

1
2
3
mkdir actions-runner && cd actions-runner
curl -O -L https://github.com/actions/runner/releases/download/v2.274.2/actions-runner-linux-x64-2.274.2.tar.gz
tar xzf ./actions-runner-linux-x64-2.274.2.tar.gz

Configure the Runner

In this step, you may need to follow the prompts. Run the command su root to switch to the root user, then run ./bin/installdependencies.sh to install dependencies.

Run config.sh to start configuring:

1
./config.sh --url https://github.com/shaowenchen/pipeline-test --token AKNLJON6JWRTO35GV3PXGVS7ZHPZO

Following the command’s prompts, the interaction goes as follows:

Enter the name of runner: [press Enter for node1] mycentos

This runner will have the following labels: 'self-hosted', 'Linux', 'X64'
Enter any additional labels (ex. label-1,label-2): [press Enter to skip] centos

√ Runner successfully added
√ Runner connection is good

# Runner settings

Enter name of work folder: [press Enter for _work] /home/runner/workspaces

√ Settings Saved.

Run the Runner

1
./run.sh

View the Runner on the page

You can see the newly added Runner on GitHub’s Actions page.

4. Usage Test

Add a workflows file

On the project’s master branch, add the file .github/workflows/blank.yml with the following content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
name: CI
on:
  push:
    branches: [master]

jobs:
  hello:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v2

      - name: Run a multi-line script
        run: |
          date
          uname -a          

View the run result

After you commit the file, Actions starts running right away; the result is shown below:

View the workspaces on the node

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
tree -L 3 /home/runner/workspaces/

/home/runner/workspaces/
|-- _actions
|   `-- actions
|       `-- checkout
|-- _PipelineMapping
|   `-- shaowenchen
|       `-- pipeline-test
|-- pipeline-test
|   `-- pipeline-test
|       |-- a
|       |-- choice
|       |-- deploy
|       |-- Jenkinsfile
|       |-- plain-credential
|       `-- readme.md
|-- _temp
`-- _tool

From the files in workspaces you can see that Actions checked the code out onto the host and then ran the orchestration commands on the host.