Gitea Runner Registration Guide

Important Note:
The gitea_runner register command creates the .runner registration file in the current working directory where the command is executed. Because the systemd service defines WorkingDirectory=/var/lib/gitea_runner (or your custom service directory), you must execute the registration command inside that directory so the daemon can locate it.

Step-by-Step Setup

1. Stop the runner service

sudo systemctl stop gitea-runner.service

2. Navigate to the service working directory

cd /var/lib/gitea_runner

3. Remove any stale/invalid `.runner` file

If you previously registered or deleted the runner from Gitea, clean up the old credentials:

sudo rm -f .runner

4. Register the new runner with multiple labels

Execute the registration command from within the runner's working directory.
Multiple labels are passed as a comma-separated string without spaces (label1:host,label2:host).

For Host 1:

sudo gitea_runner register \
--no-interactive \
--instance "https://gitea.example.com" \
--token "<YOUR_GITEA_REGISTRATION_TOKEN>" \
--name "host1" \
--labels "haproxy-host:host,host1:host"

For Host 2:

sudo gitea_runner register \
--no-interactive \
--instance "https://gitea.example.com" \
--token "<YOUR_GITEA_REGISTRATION_TOKEN>" \
--name "host2" \
--labels "haproxy-host:host,host2:host"

5. Set correct file ownership

Ensure that the system user running the systemd service (e.g. runner_user) owns the newly generated .runner file:

sudo chown runner_user:runner_user .runner

6. Restart and verify the service

# Restart the service
sudo systemctl restart gitea-runner.service

# Check service status
sudo systemctl status gitea-runner.service

Troubleshooting Checklist

open .runner: no such file or directory: Indicates .runner was generated in a different directory (e.g., /root or /home/<username>). Always make sure .runner exists inside the WorkingDirectory specified in your systemd service.
unregistered runner: Indicates the runner was deleted in the Gitea UI. Delete .runner, generate a new registration token in Gitea, and re-register.