Skip to main content

​
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