​

GitHub Self-Hosted Runner Setup on Ubuntu with systemctl Service

This guide provides steps to set up a GitHub self-hosted runner on an Ubuntu server and run it as a service using systemctl.

​

Prerequisites

• Ubuntu server with root or sudo access.
• GitHub repository or organization where the runner will be connected.
• A GitHub personal access token with the necessary permissions to add self-hosted runners.

​

Step 1: Download and Configure the GitHub Runner

1. Create a directory for the runner:
   mkdir -p ~/actions-runner && cd ~/actions-runner
   
2. Download the GitHub runner binary: Replace REPO_OWNER and REPO_NAME with the owner and repository names, or use your organization name if you’re adding a runner to an organization.
   # Replace version with the latest from https://github.com/actions/runner/releases
   curl -o actions-runner-linux-x64.tar.gz -L https://github.com/actions/runner/releases/download/v2.305.0/actions-runner-linux-x64-2.305.0.tar.gz
   
3. Extract the runner:
   tar xzf actions-runner-linux-x64.tar.gz
   
4. Configure the runner: You can find the registration token in the GitHub repository or organization settings under Settings > Actions > Runners.
   ./config.sh --url https://github.com/REPO_OWNER/REPO_NAME --token YOUR_REGISTRATION_TOKEN
   

​

Step 2: Create the run.sh Script

1. Create run.sh to ensure the runner restarts automatically in case of failure.
   nano ~/actions-runner/run.sh
   
2. Add the following content to run.sh:
   #!/bin/bash
   cd /home/$USER/actions-runner
   ./run.sh --once
   
3. Make run.sh executable:
   chmod +x ~/actions-runner/run.sh
   

​

Step 3: Set Up systemctl Service

1. Create a new systemd service file for the runner:
   sudo nano /etc/systemd/system/github-runner.service
   
2. Add the following configuration to the service file:
   [Unit]
   Description=GitHub Actions Runner
   After=network.target
   
   [Service]
   ExecStart=/home/$USER/actions-runner/run.sh
   User=$USER
   WorkingDirectory=/home/$USER/actions-runner
   Restart=always
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target
   
   [Unit]
   Description=GitHub Self-Hosted Runner
   After=network.target
   
   [Service]
   # Change these paths to your runner's installation directory
   ExecStart=/home/ubuntu/runners/magic/run.sh
   User=ubuntu
   WorkingDirectory=/home/ubuntu/runners/magic
   Environment="RUNNER_ALLOW_RUNASROOT=1"
   # If you want to restart the service automatically in case of failure
   Restart=always
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target
   

   Replace $USER with your actual username or use $USER if applicable in this context. NOTE: Github runner cannot be run as root

3. Reload the systemd daemon to recognize the new service:
   sudo systemctl daemon-reload
   
4. Enable and start the service:
   sudo systemctl enable github-runner
   sudo systemctl start github-runner
   
5. Verify the runner is active:
   sudo systemctl status github-runner
   
   You should see an “active (running)” status if the service is correctly set up.

​

Step 4: Confirm Runner Connection in GitHub

Go to your GitHub repository or organization settings under Settings > Actions > Runners to check if the runner is connected and ready.

​

Managing the GitHub Runner Service

• Start the service: sudo systemctl start github-runner
• Stop the service: sudo systemctl stop github-runner
• Restart the service: sudo systemctl restart github-runner
• Check service status: sudo systemctl status github-runner

​

Troubleshooting

• Check the runner logs:
  journalctl -u github-runner -f
  
• Make sure your GitHub registration token is up to date.

​

Unregistering the Runner

If you need to unregister the runner, stop the service and remove it:

1. Stop the service:
   sudo systemctl stop github-runner
   
2. Remove the service:
   sudo systemctl disable github-runner
   sudo rm /etc/systemd/system/github-runner.service
   
3. Unregister the runner in GitHub:
   ./config.sh remove --token YOUR_REGISTRATION_TOKEN
   
4. Clean up by deleting the runner directory:
   rm -rf ~/actions-runner
   

---