Setup GitHub Actions Self-Hosted Runner On VMs & Containers

In this guide, you will learn how to set up a Github Actions self-hosted runner on VMs and Containers with practical examples.

GitHub Actions self-hosted runner is a simple way to perform a CI/CD workflow without the use of any external application whenever a change is pushed to the Git repository.

Once you finish the guide you will have a setup where you can run Github Actions workflows on VM and Container.

GitHub Actions Self-Hosted VM Runner Workflow

The below diagram gives you a simple representation of how a GitHub Actions self-hosted VM runner works.

Let me explain the workflow of GitHub Actions self-hosted VM runner.

1. During the setup, the Actions Runner we install on the VM will initialize the connection with the help of the GitHub URL and use the GitHub token for authentication.
2. When the connection is requested by the runner, both the runner and actions exchange a session key for secure communication between them.
3. Once the connection is made GitHub Actions will trigger the workflow by sending the job description to the specified runner.
4. The runner will run the jobs on the working directory of GitHub Actions and send the status of the job in runtime.

GitHub Actions Self-Hosted Container Runner Workflow

The below diagram gives you a simple representation of how a GitHub Actions self-hosted Container runner works.

As you can see the difference between the VM and Container is not much different.

Every setup and configuration will be the same, the only difference is, in the VM the jobs will be run on the VMs work directory which is /_work/github-actions/github-actions and while using the container the jobs will be running on the containers work directory which is /__w/github-actions/github-actions.

The working directory path may differ according to the configuration and repository name, we will see how the working directory path is named later as an example in this blog.

Now, that you have understood how GitHub Actions self-hosted VM and Container runner work, move on to setting up a runner of your own by following the below steps.

Prerequisites

1. GitHub account
2. VM of any cloud provider, I am going to use the AWS instance
3. Docker should be installed in your VM because we are going to use the container as a runner as well.
4. Create a security group and attach it to your VM that should allow ports 22 and 443.

Steps to Configure a Self-Hosted Runner

If the prerequisites are ready, let’s see how to configure a GitHub Actions self-hosted runner for a repository and an organization.

Configure Self-Hosted Runner for a Repository

Follow the below steps to set up a self-hosted runner for a repository

Step 1: Create or choose an existing Repository

Create a new repository or use an existing repository for GitHub Actions.

Step 2: Create a Self-Hosted Runner

In the repo go to Settings -> Actions -> Runners and press the New self-hosted runner button on the top right corner to configure the runner for your GitHub Actions repo.

Step 3: Select Runner Image and Architecture

When you press the New self-hosted runner button a new page will open to select the runner image and architecture for your runner as shown below

As shown in the above image you can select the runner image according to your OS and architecture as per your need.

You will get the configuration commands according to the runner image you select as shown below

Run these commands one by one in your VM to install Actions Self-Hosted Runner and configure it to GitHub Actions.

The commands do the following tasks

1. Create a folder to download the actions-runner files
2. Download the latest runner package
3. Validating and extracting the package
4. Command to run configure script, which registers the runner to GitHub Actions using the repository URL and access token.
5. Run script to run the application, which connects the runner to GitHub Actions

Step 4: Configure Runner to GitHub Actions

When you run the configurations command in your VM, it some questions to configure the runner as shown in the below image

After answering the question the runner will be configured to GitHub Actions, you can see your runner has been registered on GitHub in Settings -> Actions -> Runners as shown below

Now, start the application by running the run.sh script and you will get the following in your terminal

You can also see that your runner is online and ready to run workflows. GitHub Actions uses HTTPs protocol to communicate with the runner through port 443.

Configure a Self-Hosted Runner for an Organization

Follow the below steps to set up a self-hosted runner for an Organization

Step 1: Create or choose an existing organization

Create a new organization or use an existing organization to set up GitHub Actions Runner.

Step 2: Create a self-hosted runner

In the organization go to Settings -> Actions -> Runners press the New Runner button and select the New self-hosted runner option as shown below

After selecting the New self-hosted runner option a new page will open to select the runner image and architecture.

The configuration is the same as setting up Actions Runner for a repository, follow steps 3 and 4 as on the Actions Runner configuration for a repository.

Once the configurations are finished, you can see your runner has been registered on GitHub organization in Settings -> Actions -> Runners as shown below

Start the application by running the run.sh script and you will get the following in your terminal

You can also see that your runner is online and ready to run workflows

Note: If you are using GitHub Enterprise, you can also configure self-hosted runners for enterprise.

Test GitHub Actions Workflow

To check if the GitHub Actions self-hosted runner is working properly, we are going to run jobs on VM and in containers.

Test Workflow on VM Runner

I am going to run the workflow with simple steps to check if the self-hosted runner is working properly.

Create a YML file and your repository structure should be like given below

.
├── README.md
└── .github
    └── workflows
        └── test.yml

In GitHub Actions a YML file will be used to run the workflow which will be placed under the .github/workflows directory as shown in the above structure.

Copy the below contents and paste them into your YML file.

name: Testing

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: self-hosted

    steps:

    - name: Create Folder
      run: mkdir ~/test

What it does:

name: Testing

on:
  push:
    branches:
      - main

This block triggers the workflow whenever a change is pushed to the main branch.

jobs:
  build:
    runs-on: self-hosted

This block runs the build job on the GitHub Actions self-hosted runner labeled as self-hosted.

Make sure to replace the self-hosted label with your runner’s label.

    steps:
    - name: Create Folder
      run: mkdir ~/test

In the steps block, you have to give the tasks it going to perform.

In the above example, the step will create a folder called test.

The default working directory is /_work/<repository-name>/<repository-name>.

For example, if your repository name is github-actions, then your working directory will be like as given below

/_work/github-actions/github-actions

Your working directory may differ if you’re given a different name for your working directory while configuring the runner.

Now the YML file has been created, push the changes to your repository that will trigger the workflow.

You can see if the build process has started by going to your GitHub and selecting the Actions tab as given below.

Once your job has been finished, you can view the summary of the workflow as shown below.

Test Workflow on a Container

Running workflow inside a container is no different from the above test workflow.

Follow the steps to configure a self-hosted runner and to run workflow inside a container, you just have to add a container block in the YML file as given below

name: Testing

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: self-hosted
    container:
      image: ubuntu:latest

    steps:
    - name: Create Folder
      run: mkdir actions-testing

You can see in the above YML file the only difference between running in VM and Container is a new container block is added to the YML file.

The container block runs your jobs inside the container you specify. In the above example, I have given the official Ubuntu image as the container image.

When you run the jobs using a container the steps will run inside the Actions Runner working directory inside the container

Based on the above YML file it creates the folder inside the container Actions Runner working directory, you can see how the folder is created inside the container in the below image

In the above image, /__w/github-actions/github-actions is the Actions Runner working directory inside the container.

Once your job has been finished, you can view the summary of the workflow as shown below.

You can see in the above image, first, it starts the container then it runs the job inside the container, once the job is finished the container will be stopped as shown below

Conclusion

In this blog, you learned about setting up Github Actions runner in VMs and Containers, also you learned about configuring self-hosted runners for repo and a whole organization.

I hope this blog makes it easy to understand the setup of GitHub Actions Runner.