> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ahmadraza.in/llms.txt
> Use this file to discover all available pages before exploring further.

# GithubRunner

# 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:
   ```bash theme={null}
   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.

   ```bash theme={null}
   # 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**:
   ```bash theme={null}
   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**.

   ```bash theme={null}
   ./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.

   ```bash theme={null}
   nano ~/actions-runner/run.sh
   ```

2. **Add the following content** to `run.sh`:
   ```bash theme={null}
   #!/bin/bash
   cd /home/$USER/actions-runner
   ./run.sh --once
   ```

3. **Make `run.sh` executable**:
   ```bash theme={null}
   chmod +x ~/actions-runner/run.sh
   ```

## Step 3: Set Up `systemctl` Service

1. **Create a new systemd service** file for the runner:
   ```bash theme={null}
   sudo nano /etc/systemd/system/github-runner.service
   ```

2. **Add the following configuration** to the service file:

   ```ini theme={null}
   [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
   ```

   ```ini theme={null}
   [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:
   ```bash theme={null}
   sudo systemctl daemon-reload
   ```

4. **Enable and start the service**:
   ```bash theme={null}
   sudo systemctl enable github-runner
   sudo systemctl start github-runner
   ```

5. **Verify the runner is active**:

   ```bash theme={null}
   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:
  ```bash theme={null}
  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**:
   ```bash theme={null}
   sudo systemctl stop github-runner
   ```

2. **Remove the service**:
   ```bash theme={null}
   sudo systemctl disable github-runner
   sudo rm /etc/systemd/system/github-runner.service
   ```

3. **Unregister the runner** in GitHub:
   ```bash theme={null}
   ./config.sh remove --token YOUR_REGISTRATION_TOKEN
   ```

4. **Clean up** by deleting the runner directory:
   ```bash theme={null}
   rm -rf ~/actions-runner
   ```

***