Merge nucleic/mellow-dewy-falcon-rjhr into main

2026-08-07 00:44:36 -07:00
parent 749f0be4fb
commit bc2b6cd33b
47 changed files with 13159 additions and 0 deletions
@@ -0,0 +1,135 @@
+# gitea-macos-runner
+
+A Swift daemon that gives a self-hosted Gitea instance on-demand macOS CI capacity from a single
+Apple Silicon Mac. It polls Gitea for queued Actions jobs that request macOS, boots a fresh
+ephemeral macOS VM through Apple's Virtualization.framework for each one, lets Gitea's own
+`gitea-runner` execute exactly one job inside that VM, and then destroys the VM. Nothing from a
+job survives into the next: every build starts from an identical, freshly cloned base image.
+
+## How it works
+
+```
+  Gitea                          host daemon                        ephemeral VM
+    │                                 │                                   │
+    │  GET /api/v1/admin/actions/     │                                   │
+    │      jobs?status=queued         │                                   │
+    │◄────────────────────────────────┤  poll every 5s                    │
+    │  [{id, labels: ["macos-arm64"]}]│                                   │
+    ├────────────────────────────────►│                                   │
+    │                                 │ APFS clone base image (instant)   │
+    │                                 ├──────────────────────────────────►│
+    │                                 │ boot headless, NAT networking     │
+    │                                 │ resolve IP (/var/db/dhcpd_leases) │
+    │                                 │ ssh in                            │
+    │                                 ├──────────────────────────────────►│
+    │                                 │ gitea-runner register --ephemeral │
+    │◄────────────────────────────────┼───────────────────────────────────┤
+    │  runner appears, job dispatched │                                   │
+    ├─────────────────────────────────┼──────────────────────────────────►│
+    │                                 │        gitea-runner daemon        │
+    │  job completes; server refuses   │        runs ONE job              │
+    │  a second job and deletes the   │                                   │
+    │  ephemeral registration          │                                  │
+    │                                 │ destroy VM + clone                │
+    │                                 ├───────────────────────────────► ✗ │
+```
+
+A background reconcile loop (every 5 minutes) deletes runner registrations left behind by VMs that
+were killed uncleanly, so the Gitea runner list does not accumulate dead entries.
+
+## Requirements
+
+- **Apple Silicon Mac.** Virtualization.framework macOS guests are ARM-only.
+- **macOS 26 or newer on the host; macOS 27 or newer strongly recommended.** The automated image
+  builder uses `VZMacGuestProvisioningOptions` (macOS 27) to create the admin user and skip Setup
+  Assistant. Both host *and* guest must be 27+ — an older guest silently ignores the options and
+  stalls at Setup Assistant.
+- **Disk:** ~60 GB free for a vanilla image (IPSW ~15 GB plus a sparse ASIF disk); 140 GB+ if you
+  provision Xcode.
+- **RAM:** 16 GB minimum. Each guest defaults to 8 GB, and macOS caps the host at **2 concurrent
+  macOS VMs** regardless of hardware.
+- **Gitea 1.25 or newer** (1.26+ recommended). 1.25 added the admin jobs API with the `labels`
+  field this daemon depends on.
+- A code-signed app bundle. The binary must carry the `com.apple.security.virtualization`
+  entitlement; ad-hoc signing (`codesign -s -`) is sufficient, so no paid Apple developer account
+  is required.
+
+## Quickstart
+
+```sh
+git clone <this repo> && cd gitea-macos-runner
+
+# Build, bundle (binary + Resources + Info.plist), ad-hoc sign with the
+# virtualization entitlement, then copy to ~/Applications and symlink the CLI
+# into /usr/local/bin.
+make install                      # = make build bundle sign, then the install step
+
+# Write a starter config to ~/.config/gitea-macos-runner/config.json
+gitea-macos-runner config init
+
+# Fill in gitea.instanceURL, gitea.adminTokenFile, and the registration token settings.
+$EDITOR "$(gitea-macos-runner config path)"
+
+# Read the config back with secrets redacted, to confirm it parses and validates.
+gitea-macos-runner config show
+
+# Verify entitlements, config, Gitea reachability, disk space, and host/guest versions.
+gitea-macos-runner doctor
+
+# Build a base image from an IPSW (long — installs macOS, then provisions the guest).
+# The image is named "default", which is also what `daemon` and `vm boot` look for.
+gitea-macos-runner image build --ipsw ~/Downloads/UniversalMac_27.0_*.ipsw
+
+# Optional: add Xcode to the image.
+gitea-macos-runner image provision default --xcode-xip ~/Downloads/Xcode_XX.xip
+
+# Install and start the LaunchAgent (runs in your GUI login session — not a LaunchDaemon).
+gitea-macos-runner service install
+gitea-macos-runner service status
+```
+
+Then push a workflow that targets the runner:
+
+```yaml
+# .gitea/workflows/macos.yml
+name: macOS build
+on: [push]
+jobs:
+  build:
+    runs-on: macos-arm64
+    steps:
+      - uses: actions/checkout@v4
+      - run: sw_vers && swift build
+```
+
+The daemon picks the job up within one poll interval, boots a VM, and tears it down when the job
+finishes.
+
+## Documentation
+
+- [docs/setup.md](docs/setup.md) — full Gitea-side and host-side walkthrough, config reference,
+  image building, service installation, verification.
+- [docs/security.md](docs/security.md) — threat model, isolation boundaries, token handling.
+- [docs/troubleshooting.md](docs/troubleshooting.md) — symptom → cause → fix.
+
+## Command reference
+
+Every subcommand accepts the global options `--config PATH` (`-c`, default
+`~/.config/gitea-macos-runner/config.json`) and `--verbose`.
+
+| Command | Purpose |
+| --- | --- |
+| `daemon [--image NAME] [--once]` | The scheduler loop. Normally started by launchd via `service install`. `--image` defaults to `default`; `--once` runs a single scheduling tick and exits. |
+| `image build [--name NAME] [--ipsw PATH] [--disk-gb N]` | Install macOS into a new base image and provision it. `--name` defaults to `default`; without `--ipsw` the latest supported restore image is downloaded. `--disk-gb` overrides `guest.diskGB`. |
+| `image provision NAME [--xcode-xip PATH]` | Re-run guest provisioning on an existing image; optionally install Xcode from a `.xip`. |
+| `image list` | List base images in the store. |
+| `image delete NAME [--force]` | Delete a base image and its disk. `--force` (`-f`) skips the confirmation prompt. |
+| `vm boot [--image NAME] [--slot N] [--keep]` | Clone an image, boot it, print its IP, and wait for Ctrl-C. `--slot` picks which persistent per-slot MAC to use (default `0`); `--keep` leaves the clone on disk. |
+| `vm list` | List ephemeral VM clones on disk. |
+| `service install [--executable PATH]` | Write and load `~/Library/LaunchAgents/xyz.blakeslee.gitea-macos-runner.plist`. |
+| `service uninstall` | Unload the LaunchAgent and remove its plist. |
+| `service status` | Report LaunchAgent installation and run state. |
+| `doctor [--json] [--no-fail]` | Preflight checks. `--json` emits machine-readable results; `--no-fail` exits zero even when checks fail. |
+| `config init [--force] [--instance-url URL]` | Write the annotated example config. `--force` (`-f`) overwrites an existing file. |
+| `config show` | Print the effective configuration with secrets redacted. |
+| `config path` | Print the configuration file path. |