enhance: add macOS VM executor backend

Replace the Tart-based prototype with a runner-oriented macOS VM executor backed by runner-executor-macos and Apple Virtualization. Assisted-by: Codet:MODEL_VERSION
2026-09-21 19:37:07 +02:00 · 2026-09-05 13:20:03 -07:00
parent 1745c7c841
commit 2db24c7401
18 changed files with 1167 additions and 15 deletions
@@ -0,0 +1,93 @@
+# macOS VM executor
+
+The runner can execute a job in an ephemeral macOS VM by registering a
+`macos-vm` label:
+
+```yaml
+runner:
+  labels:
+    - macos-latest:macos-vm://registry.example.com/macos-15.2-xcode-26.1
+```
+
+The VM is created and managed by `runner-executor-macos`, a dedicated Swift
+binary built on Apple Virtualization.framework. The source VM must include the
+runner guest agent.
+
+## Configuration
+
+```yaml
+macos_vm:
+  executor_path: runner-executor-macos
+  workdir_parent: /Users/admin/runner
+  cpu: 0
+  memory: 0
+  boot_timeout: 5m
+```
+
+`workdir_parent` is the guest directory under which job workspaces are created.
+`executor_path` is the binary to invoke; an empty value uses PATH lookup.
+
+## Executor CLI
+
+The runner uses a narrow, runner-oriented command set:
+
+```text
+runner-executor-macos provision <image> <name> [--cpu N] [--memory MB]
+runner-executor-macos start <name> [--no-graphics]
+runner-executor-macos exec <name> [--stdin] <argv...>
+runner-executor-macos stop <name> [--timeout N]
+runner-executor-macos destroy <name>
+runner-executor-macos list --format json
+runner-executor-macos version
+```
+
+`list --format json` returns:
+
+```json
+[
+  {
+    "name": "GITEA-MACOS-VM-<runner-uuid>-...",
+    "state": "stopped",
+    "running": false,
+    "accessed_at": "2026-09-05T12:00:00Z"
+  }
+]
+```
+
+## Integration test
+
+The end-to-end test is opt-in because it provisions and boots a real VM:
+
+```bash
+MACOS_VM_TEST_IMAGE=/path/or/reference \
+  go test -tags macos_vm_integration ./act/container -run '^TestMacOSVMEnvironmentIntegration$' -v
+```
+
+The test skips when `MACOS_VM_TEST_IMAGE` is unset.
+
+## Orphaned VM cleanup
+
+Job VM names start with `GITEA-MACOS-VM-<runner-uuid>-`. While the runner is
+idle, it lists local VMs and destroys the non-running ones whose name has this
+runner's UUID and whose access time is older than
+`runner.workdir_cleanup_age`.
+
+## Service containers
+
+Service containers are intentionally rejected for macOS VM jobs today. Docker
+service containers live on a Docker network and are reached by workflow service
+id, which a macOS VM cannot resolve.
+
+Possible future designs:
+
+1. **Host-published Docker services + guest host mapping** — publish each
+   service port on the runner host and inject `<service-id> -> <host-ip>` into
+   the VM through the guest agent.
+2. **macOS VM services** — run each service as another VM; this requires
+   service discovery and is much heavier than Docker containers.
+3. **Environment-based discovery** — require workflows to read service
+   addresses from env vars instead of hostnames, breaking GitHub Actions
+   compatibility.
+
+Option 1 is the most compatible direction once the guest agent and host network
+configuration are stable.