privacy-in-design/gitea-migration
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update usage guide with boot-mode native runner details and sudo requirements

Browse Source
This commit is contained in:
S
2026-03-01 08:28:49 -05:00
parent b120ef2e0e
commit 6100d482d2
1 changed files with 36 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
USAGE_GUIDE.md
View File

@@ -280,6 +280,7 @@ This generates ed25519 keys on each host and distributes public keys to the othe
**Fix**:
- For Docker runners: `ssh USER@HOST "docker logs gitea-runner-RUNNER_NAME"` to check logs
- For native runners: `cat ~/gitea-runner/runner.err.log`
- For boot-mode native runners: service management requires `sudo launchctl list | grep com.gitea.runner`
- Common cause: the runner registration token expired. Clear it and re-run Phase 3:
```bash
@@ -401,8 +402,10 @@ grep "GITEA_BACKUP_ADMIN_TOKEN=" .env # Should be empty
ssh USER@UNRAID_IP "docker ps | grep gitea-runner" # Should return nothing
ssh USER@FEDORA_IP "docker ps | grep gitea-runner" # Should return nothing
# Native runner (macOS)
# Native runner (macOS) — login agent
launchctl list | grep com.gitea.runner # Should return nothing
# Native runner (macOS) — boot daemon (if boot=true was used)
sudo launchctl list | grep com.gitea.runner # Should return nothing
# Registration token cleared
grep "GITEA_RUNNER_REGISTRATION_TOKEN=" .env # Should be empty
@@ -612,10 +615,20 @@ macbook-runner local macos native online
### Adding a runner
Define it in `runners.conf`:
Define it in `runners.conf` (INI format):
```
new-runner|192.168.1.30|user|22|/opt/gitea-runner|linux|docker
```ini
[new-runner]
host = custom
type = docker
data_path = /opt/gitea-runner
labels = linux
default_image = catthehacker/ubuntu:act-latest
repos = all
capacity = 2
ssh_host = 192.168.1.30
ssh_user = user
ssh_port = 22
```
Then deploy:
@@ -630,14 +643,31 @@ Then deploy:
./manage_runner.sh remove --name new-runner
```
For Docker runners, this stops and removes the container. For native runners, this unloads the launchd service, removes the plist, and optionally deletes the runner data directory.
For Docker runners, this stops and removes the container. For native runners, this unloads the launchd service, removes the plist, and optionally deletes the runner data directory. If the native runner was deployed with `boot = true`, removal uses `sudo` for `launchctl unload` and plist deletion.
### Runner types
| Type | Deployed On | How It Works |
|------|------------|--------------|
| `docker` | Linux hosts | Docker Compose container, auto-registers via environment variables |
| `native` | macOS | Binary downloaded from Gitea, registered manually, managed via launchd plist |
| `native` | macOS (login) | Binary + launchd agent in `~/Library/LaunchAgents/` — starts when user logs in |
| `native` + `boot=true` | macOS (boot) | Binary + launchd daemon in `/Library/LaunchDaemons/` — starts at boot before login |
### Boot vs login startup (native runners)
Native macOS runners support two startup modes controlled by the `boot` field in `runners.conf`:
| Setting | Plist Location | Starts | Sudo Required | Use Case |
|---------|---------------|--------|---------------|----------|
| `boot = false` (default) | `~/Library/LaunchAgents/` | At user login | No | Developer workstation, shared Mac |
| `boot = true` | `/Library/LaunchDaemons/` | At boot (before login) | Yes | Headless Mac mini, dedicated CI machine |
When `boot = true`, `manage_runner.sh` uses `sudo` for:
- Copying the plist to `/Library/LaunchDaemons/`
- Running `launchctl load` / `launchctl unload`
- Removing the plist on teardown
The plist includes a `<key>UserName</key>` entry so the daemon runs as the deploying user, not root. Log rotation via newsyslog always requires `sudo` regardless of boot mode.
---