Install from a binary
The runner is a single binary, gitea-runner, built for Linux, macOS, Windows, and FreeBSD.
Download
Section titled “Download”Download releases from dl.gitea.com/gitea-runner. Each binary has a matching .sha256 checksum file:
VERSION=5.2.0curl -sSLO "https://dl.gitea.com/gitea-runner/$VERSION/gitea-runner-$VERSION-linux-amd64"curl -sSLO "https://dl.gitea.com/gitea-runner/$VERSION/gitea-runner-$VERSION-linux-amd64.sha256"sha256sum -c "gitea-runner-$VERSION-linux-amd64.sha256"sudo install -m 0755 "gitea-runner-$VERSION-linux-amd64" /usr/local/bin/gitea-runnerTo build the runner yourself, run make build in a clone of gitea/runner.
First run
Section titled “First run”gitea-runner register --instance https://gitea.example.com --token <token>gitea-runner daemonregister prompts for the remaining settings and writes the .runner registration file to the working directory. Run daemon from the same directory so it can read the file. See Registration.
systemd
Section titled “systemd”Create a user and a configuration file. Then register the runner as that user from its home directory:
sudo useradd --system --home-dir /var/lib/gitea-runner --create-home gitea-runnersudo mkdir -p /etc/gitea-runnersudo gitea-runner config init -c /etc/gitea-runner/config.yamlsudo chown gitea-runner /etc/gitea-runner/config.yamlcd /var/lib/gitea-runnersudo -u gitea-runner gitea-runner register -c /etc/gitea-runner/config.yaml \ --instance https://gitea.example.com --token <token>Install the unit as /etc/systemd/system/gitea-runner.service:
[Unit]Description=Gitea Actions runnerDocumentation=https://gitea.com/gitea/runnerAfter=network-online.targetWants=network-online.target# Uncomment when jobs use the local Docker daemon:# After=docker.service# Requires=docker.service
[Service]Type=simpleExecStart=/usr/local/bin/gitea-runner daemon --config /etc/gitea-runner/config.yamlWorkingDirectory=/var/lib/gitea-runnerUser=gitea-runnerGroup=gitea-runnerRestart=on-failureRestartSec=5sTimeoutStopSec=3h
[Install]WantedBy=multi-user.targetsudo systemctl daemon-reloadsudo systemctl enable --now gitea-runnerStopping the service cancels running jobs unless runner.shutdown_timeout gives them time to finish. Keep runner.shutdown_timeout below TimeoutStopSec:
sudo -u gitea-runner gitea-runner config set -c /etc/gitea-runner/config.yaml runner.shutdown_timeout 2h50mFor jobs in containers, give the gitea-runner user access to the Docker daemon’s socket, for example through the docker group. That access is equivalent to root on the host. Set the runner’s environment variables, such as proxy settings, with Environment= lines in the unit.
launchd (macOS)
Section titled “launchd (macOS)”On macOS, run the runner in the login session of the user that jobs should run as. Jobs then have that user’s login keychain and the GUI.
Register the runner as that user, with a host label so that jobs run on the Mac itself:
mkdir ~/gitea-runner && cd ~/gitea-runnergitea-runner register --instance https://gitea.example.com --token <token> --labels macos-latest:hostReplace /Users/gitea-runner with the user’s home directory, then save this file as ~/Library/LaunchAgents/com.gitea.runner.plist:
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict> <key>Label</key> <string>com.gitea.runner</string> <key>ProgramArguments</key> <array> <string>/usr/local/bin/gitea-runner</string> <string>daemon</string> </array> <key>WorkingDirectory</key> <string>/Users/gitea-runner/gitea-runner</string> <key>EnvironmentVariables</key> <dict> <key>PATH</key> <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string> </dict> <key>StandardErrorPath</key> <string>/Users/gitea-runner/gitea-runner/runner.log</string> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <true/></dict></plist>Start the runner. From now on, it also starts whenever the user logs in:
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.gitea.runner.plistEnable automatic login for the user in System Settings, so that the runner starts after a restart too. macOS does not offer automatic login while FileVault is on.
The runner does not get the environment of your shell. Set what jobs need, such as proxy settings, in EnvironmentVariables.
Local network access
Section titled “Local network access”macOS blocks a runner that was started this way from other hosts on the Mac’s own subnet, such as the Gitea instance or a shared cache server. The runner then logs no route to host. Commands run in Terminal or over SSH are not blocked, so registering works even when the running runner cannot connect. See local network privacy.
macOS asks on the Mac’s screen whether to allow the access. To allow it without that prompt, exempt the subnet on macOS 15.5 or later and restart the Mac. On Wi-Fi, the key is AllowedWiFiLocalNetworkAddresses:
sudo defaults write com.apple.network.local-network AllowedEthernetLocalNetworkAddresses -array "192.168.1.0/24"Git credentials
Section titled “Git credentials”Git on macOS saves credentials from remote URLs to the keychain, which can stop a job at a dialog that nobody answers. To turn that off, set GIT_CONFIG_NOSYSTEM to 1 in EnvironmentVariables.
Windows
Section titled “Windows”Run gitea-runner daemon with a service wrapper such as WinSW. The runner has no service installer of its own.
On macOS and Windows, jobs usually run directly on the runner’s machine with host labels.