mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-11 20:47:53 +00:00
Document running the macOS runner in the login session (#644)
Rewrites the `launchd (macOS)` section of the runner's binary installation page, in the develop and version 5 docs. The old steps started the runner at boot as a service user, with directories that do not exist on macOS and a `PATH` that missed Homebrew on Apple silicon. Jobs started that way have no login keychain and no GUI. The section now describes one setup: the runner runs in the login session of an existing user, with automatic login. It 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. The runner repository gets the same content as an example in https://gitea.com/gitea/runner/pulls/1408. Reviewed-on: https://gitea.com/gitea/docs/pulls/644 Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com> Co-authored-by: silverwind <me@silverwind.io>
This commit is contained in:
silverwind authored and 
silverwind committed
1 parent
e707e2838a
commit
fa8c890d01
2 files changed
+68
-22
No files matched your search
@@ -84,7 +84,16 @@ For jobs in containers, give the `gitea-runner` user access to the Docker daemon
|
||||
|
||||
## launchd (macOS)
|
||||
|
||||
Adjust the paths and user for your setup, then save this file as `/Library/LaunchDaemons/com.gitea.runner.plist`:
|
||||
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](../labels.md) so that jobs run on the Mac itself:
|
||||
|
||||
```bash
|
||||
mkdir ~/gitea-runner && cd ~/gitea-runner
|
||||
gitea-runner register --instance https://gitea.example.com --token <token> --labels macos-latest:host
|
||||
```
|
||||
|
||||
Replace `/Users/gitea-runner` with the user's home directory, then save this file as `~/Library/LaunchAgents/com.gitea.runner.plist`:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
@@ -97,22 +106,16 @@ Adjust the paths and user for your setup, then save this file as `/Library/Launc
|
||||
<array>
|
||||
<string>/usr/local/bin/gitea-runner</string>
|
||||
<string>daemon</string>
|
||||
<string>--config</string>
|
||||
<string>/etc/gitea-runner/config.yaml</string>
|
||||
</array>
|
||||
<key>UserName</key>
|
||||
<string>_gitea-runner</string>
|
||||
<key>WorkingDirectory</key>
|
||||
<string>/var/lib/gitea-runner</string>
|
||||
<string>/Users/gitea-runner/gitea-runner</string>
|
||||
<key>EnvironmentVariables</key>
|
||||
<dict>
|
||||
<key>PATH</key>
|
||||
<string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
|
||||
<key>HOME</key>
|
||||
<string>/var/lib/gitea-runner</string>
|
||||
<string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
|
||||
</dict>
|
||||
<key>StandardErrorPath</key>
|
||||
<string>/var/lib/gitea-runner/runner.log</string>
|
||||
<string>/Users/gitea-runner/gitea-runner/runner.log</string>
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
<key>KeepAlive</key>
|
||||
@@ -121,10 +124,30 @@ Adjust the paths and user for your setup, then save this file as `/Library/Launc
|
||||
</plist>
|
||||
```
|
||||
|
||||
Start the runner. From now on, it also starts whenever the user logs in:
|
||||
|
||||
```bash
|
||||
sudo launchctl bootstrap system /Library/LaunchDaemons/com.gitea.runner.plist
|
||||
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 settings](../proxy.md), 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](https://developer.apple.com/documentation/technotes/tn3179-understanding-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`:
|
||||
|
||||
```bash
|
||||
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`.
|
||||
|
||||
## Windows
|
||||
|
||||
Run `gitea-runner daemon` with a service wrapper such as [WinSW](https://github.com/winsw/winsw). The runner has no service installer of its own.
|
||||
|
||||
@@ -84,7 +84,16 @@ For jobs in containers, give the `gitea-runner` user access to the Docker daemon
|
||||
|
||||
## launchd (macOS)
|
||||
|
||||
Adjust the paths and user for your setup, then save this file as `/Library/LaunchDaemons/com.gitea.runner.plist`:
|
||||
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](../labels.md) so that jobs run on the Mac itself:
|
||||
|
||||
```bash
|
||||
mkdir ~/gitea-runner && cd ~/gitea-runner
|
||||
gitea-runner register --instance https://gitea.example.com --token <token> --labels macos-latest:host
|
||||
```
|
||||
|
||||
Replace `/Users/gitea-runner` with the user's home directory, then save this file as `~/Library/LaunchAgents/com.gitea.runner.plist`:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
@@ -97,22 +106,16 @@ Adjust the paths and user for your setup, then save this file as `/Library/Launc
|
||||
<array>
|
||||
<string>/usr/local/bin/gitea-runner</string>
|
||||
<string>daemon</string>
|
||||
<string>--config</string>
|
||||
<string>/etc/gitea-runner/config.yaml</string>
|
||||
</array>
|
||||
<key>UserName</key>
|
||||
<string>_gitea-runner</string>
|
||||
<key>WorkingDirectory</key>
|
||||
<string>/var/lib/gitea-runner</string>
|
||||
<string>/Users/gitea-runner/gitea-runner</string>
|
||||
<key>EnvironmentVariables</key>
|
||||
<dict>
|
||||
<key>PATH</key>
|
||||
<string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
|
||||
<key>HOME</key>
|
||||
<string>/var/lib/gitea-runner</string>
|
||||
<string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
|
||||
</dict>
|
||||
<key>StandardErrorPath</key>
|
||||
<string>/var/lib/gitea-runner/runner.log</string>
|
||||
<string>/Users/gitea-runner/gitea-runner/runner.log</string>
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
<key>KeepAlive</key>
|
||||
@@ -121,10 +124,30 @@ Adjust the paths and user for your setup, then save this file as `/Library/Launc
|
||||
</plist>
|
||||
```
|
||||
|
||||
Start the runner. From now on, it also starts whenever the user logs in:
|
||||
|
||||
```bash
|
||||
sudo launchctl bootstrap system /Library/LaunchDaemons/com.gitea.runner.plist
|
||||
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 settings](../proxy.md), 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](https://developer.apple.com/documentation/technotes/tn3179-understanding-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`:
|
||||
|
||||
```bash
|
||||
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`.
|
||||
|
||||
## Windows
|
||||
|
||||
Run `gitea-runner daemon` with a service wrapper such as [WinSW](https://github.com/winsw/winsw). The runner has no service installer of its own.
|
||||
|
||||
Reference in new issue
Block a user