From 910cf5be9b0126f10eeab8801c75fa36d355db3d Mon Sep 17 00:00:00 2001
From: casjay <git-admin@casjaysdev.pro>
Date: Fri, 5 Jun 2026 17:03:20 -0400
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Document=20external=20runner=20s?=
 =?UTF-8?q?etup=20for=20native=20arch=20matrix=20builds=20=F0=9F=93=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add "Adding external runners" section covering:
- Getting a registration token from Gitea UI or API
- Installing the act_runner binary with arch auto-detection
- Registering with arch-specific labels (arm64:host, linux/arm64:host)
- Running as a systemd service
- Matrix workflow example targeting amd64 and arm64 natively
- README.md: add external runner setup section

README.md
---
 README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/README.md b/README.md
index 799a06d..41075e2 100644
--- a/README.md
+++ b/README.md
@@ -169,6 +169,91 @@ networks:
 
 ---
 
+## 🏃 Adding external runners
+
+External runners let you add dedicated hardware (e.g. a native ARM64 server) to your Gitea Actions pool without running the full container. Each runner registers directly against your Gitea instance and declares its own labels, so matrix workflows can target it by architecture.
+
+### 1 — Get a registration token
+
+In the Gitea web UI: **Site Administration → Runners → Create Runner Token**
+
+Or via API:
+
+```shell
+curl -s -X POST https://git.example.com/api/v1/user/actions/runners/registration-token \
+  -H "Authorization: token <your-api-token>"
+```
+
+### 2 — Install the act_runner binary
+
+```shell
+# Detect arch
+ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
+VER=v1.0.8
+
+curl -LSsf "https://gitea.com/gitea/runner/releases/download/${VER}/gitea-runner-${VER#v}-linux-${ARCH}" \
+  -o /usr/local/bin/act_runner
+chmod +x /usr/local/bin/act_runner
+```
+
+### 3 — Register against your Gitea instance
+
+```shell
+act_runner register \
+  --instance https://git.example.com \
+  --token    <registration-token> \
+  --name     "arm64-server" \
+  --labels   "arm64:host,linux/arm64:host,ubuntu:docker://ubuntu:latest,alpine:docker://alpine:latest" \
+  --no-interactive
+```
+
+Label format: `name:type` or `name:type:image`
+- `arm64:host` — runs jobs natively on this machine
+- `ubuntu:docker://ubuntu:latest` — spins a Docker container per job (requires Docker on the host)
+
+### 4 — Run as a systemd service
+
+```ini
+# /etc/systemd/system/act_runner.service
+[Unit]
+Description=Gitea Actions Runner
+After=network.target
+
+[Service]
+ExecStart=/usr/local/bin/act_runner daemon
+WorkingDirectory=/var/lib/act_runner
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```shell
+mkdir -p /var/lib/act_runner
+mv .runner /var/lib/act_runner/   # move registration file to working dir
+systemctl daemon-reload
+systemctl enable --now act_runner
+```
+
+### Matrix workflow example
+
+Once both an amd64 and an arm64 runner are registered:
+
+```yaml
+jobs:
+  build:
+    strategy:
+      matrix:
+        arch: [amd64, arm64]
+    runs-on: ${{ matrix.arch }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: uname -m   # confirms native arch
+```
+
+---
+
 ## 🛠️ Development
 
 ### Prerequisites