From 5419540648effc3c27fd50bcf1f7206bd7fe241b Mon Sep 17 00:00:00 2001
From: Kutesir <kutesa@provoc.ug>
Date: Fri, 3 Jul 2026 02:16:02 +0300
Subject: [PATCH] =?UTF-8?q?docs:=20correct=20act=5Frunner=20setup=20?=
 =?UTF-8?q?=E2=80=94=20binary=20install,=20host=20labels,=20docker-less=20?=
 =?UTF-8?q?config?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CONTRIBUTING.md | 43 ++++++++++++++++++++++++++++++-------------
 1 file changed, 30 insertions(+), 13 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5ccc128..6fb3764 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -48,41 +48,58 @@ Then restart Gitea.
 
 ### 2. Install act_runner on the Mac
 
-```bash
-brew install act-runner
-```
+There is no Homebrew formula — download the official binary:
 
-Or download the binary from your Gitea instance:
-`http://10.10.1.21:3002/-/admin/runners`
+```bash
+curl -sL -o /usr/local/bin/act_runner \
+  https://dl.gitea.com/act_runner/0.6.1/act_runner-0.6.1-darwin-arm64
+chmod +x /usr/local/bin/act_runner
+```
 
 ### 3. Register the runner
 
 Get a registration token from:
 **Repository Settings → Actions → Runners → Create Runner**
+(or via API: `GET /api/v1/repos/kutesir/jarvis/actions/runners/registration-token`)
 
-Then:
+The `:host` label suffix is required — it makes jobs run directly on the Mac
+instead of in Docker (which xcodebuild needs, and the Mac has no Docker):
 
 ```bash
-act_runner register \
+mkdir -p ~/.act_runner && cd ~/.act_runner
+act_runner register --no-interactive \
   --instance http://10.10.1.21:3002 \
   --token <RUNNER_TOKEN> \
   --name "mac-mini" \
-  --labels "self-hosted,macos"
+  --labels "self-hosted:host,macos:host"
 ```
 
-### 4. Start the runner
+### 4. Configure and start the runner
+
+Generate the config, then fix two defaults that break Docker-less Macs
+(the generated config ships Docker-based ubuntu labels that make the daemon
+refuse to start without a Docker socket):
 
 ```bash
-act_runner daemon
+cd ~/.act_runner
+act_runner generate-config > config.yaml
+# 1. labels: [] — empty falls back to the :host labels in .runner
+# 2. docker_host: "-" — never look for a Docker daemon
 ```
 
-To run it as a background service:
+In `config.yaml`, set:
+- `labels: []` (replace the default ubuntu docker labels)
+- `docker_host: "-"` (under `container:`)
+
+Then start it:
 
 ```bash
-brew services start act-runner   # if installed via brew
-# or add a launchd plist manually
+act_runner daemon --config ~/.act_runner/config.yaml
 ```
 
+To keep it running across reboots, load it as a LaunchAgent
+(`~/Library/LaunchAgents/com.gitea.act-runner.plist`, see repo scripts).
+
 The runner must have **Xcode 16+** installed and accepted the license:
 
 ```bash