silverwind
b5305c6785
Adds `examples/launchd` with a plist and the steps to run the runner on macOS, next to the existing systemd example. The runner runs in the login session of the user that jobs should run as, which gives jobs the login keychain and the GUI. The README also covers the two problems that setup runs into: macOS blocks the runner from hosts on the Mac's own subnet, and Git's keychain helper can stop a job at a dialog. _Written by Claude (Fable 5.2)._ Reviewed-on: https://gitea.com/gitea/runner/pulls/1408 Reviewed-by: bircni <[email protected]> Co-authored-by: silverwind <[email protected]>
Running the runner with launchd on macOS
com.gitea.runner.plist runs 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.
Setup
-
Install the
gitea-runnerbinary (e.g. to/usr/local/bin/gitea-runner). -
Register as that user, with a host label so that jobs run on the Mac itself:
mkdir ~/gitea-runner && cd ~/gitea-runner gitea-runner register --instance https://gitea.example.com --token <token> --labels macos-latest:host -
Replace
/Users/gitea-runnerin the file with the user's home directory, then install it and start the runner. From now on, it also starts whenever the user logs in:mkdir -p ~/Library/LaunchAgents cp com.gitea.runner.plist ~/Library/LaunchAgents/ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.gitea.runner.plist -
Enable 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 variables, in EnvironmentVariables.
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
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.