Introduction

This guide provides a comprehensive walkthrough of setting up a self-hosted GitHub Actions runner on a Linux machine, covering user creation, service setup, and runner configuration.

Prerequisites

• A Linux server (this guide uses Ubuntu as an example)
• Access to the GitHub repository or organization where you want to use the runner

Creating a Dedicated User

Creating a dedicated user for the runner enhances security and helps isolate its operations.

sudo useradd -m -d /home/runner -s /bin/bash runner
sudo passwd runner  # Set a password for the runner user

This creates a user named runner with its home directory at /home/runner and Bash as its default shell. Remember to replace runner with your preferred username if desired.

Downloading and Extracting the Runner Package

From step 2 onwards, I strongly recommend you follow the self-hosted runners guide inside the repository's actions area, for it will prepare the access token and runner configuration for you. You can find it like this: Repository -> Actions -> New runner -> New self-hosted runner -> Follow the instructions. Here is just a example of how this can be done, you will still have to visit the repository's actions area to get the access token and runner configuration.

1. Log in as the runner user:

su - runner

2. Create the runner directory and navigate to it:

mkdir actions-runner && cd actions-runner

3. Download the latest runner package from the GitHub Actions releases page. Make sure to choose the appropriate package for your operating system and architecture. Here's an example for Linux x64:

curl -O -L https://github.com/actions/runner/releases/download/v<LATEST_VERSION>/actions-runner-linux-x64-<LATEST_VERSION>.tar.gz

Replace <LATEST_VERSION> with the actual latest version number.

4. Extract the downloaded package:

tar xzf actions-runner-linux-x64-<LATEST_VERSION>.tar.gz

Configuring the Runner

Run the configuration script:

./config.sh --url https://github.com/<YOUR_ORGANIZATION_OR_USERNAME>/<YOUR_REPOSITORY> --token <YOUR_PERSONAL_ACCESS_TOKEN>

Replace the placeholders with your actual values:

• <YOUR_ORGANIZATION_OR_USERNAME>: Your GitHub organization or username.
• <YOUR_REPOSITORY>: The repository where you want to add the runner. (Omit this part if configuring a runner at the organization level).
• <YOUR_PERSONAL_ACCESS_TOKEN>: The PAT you generated earlier.

The script will prompt you for information such as the runner's name, labels, and group. Provide these details as needed.

Creating a Systemd Service

The GitHub's guide will provide you with a run.sh script that you can use to start the runner, but it will not run as a service in background, which means if you close the terminal, the runner will stop.

You can create a systemd service to manage the runner as a background service.

Creating a systemd service ensures that the runner starts automatically upon system reboot.

1. Create the service file:

sudo nano /etc/systemd/system/actions-runner.service

2. Paste the following content into the file, replacing <username> with the runner user's username (e.g., runner):

[Unit]
Description=GitHub Actions Runner
After=network.target

[Service]
User=<username> # Replace with the runner user's username
Group=<username> # Replace with the runner user's username
WorkingDirectory=/home/<username>/actions-runner # Replace with the runner user's home directory
ExecStart=/home/<username>/actions-runner/run.sh # Replace with the runner user's home directory
Restart=always

[Install]
WantedBy=multi-user.target

3. Save the file and enable/start the service:

sudo systemctl enable actions-runner
sudo systemctl start actions-runner

Verifying the Runner

Check the runner's status on GitHub in your repository's or organization's settings under "Actions" -> "Runners". It should appear as "idle" when ready to accept jobs. You can also check the service status on your server using sudo systemctl status actions-runner.

Conclusion

You have successfully set up a self-hosted GitHub Actions runner on your Linux server. You can now utilize this runner to execute your workflows in your own environment. Remember to review the security best practices recommended by GitHub for self-hosted runners.