Nucleic: Gitea Runner macOS VM Support

2026-08-07 01:02:32 -07:00
parent 11019d498b
commit 9edaa3e409
2 changed files with 57 additions and 8 deletions
@@ -29,6 +29,7 @@ gitea-macos-runner service status
 | Job stays queued forever | Label mismatch, or the daemon isn't running/reaching Gitea | Use bare label names in `runs-on`; match `runner.labels`; check daemon logs |
 | `actions/checkout` fails instantly | Node.js missing from the guest image | `gitea-macos-runner image provision <name>` |
 | Runner rows piling up in the Gitea UI | VMs killed uncleanly; registrations orphaned | Reconcile loop cleans them; force it by restarting the daemon; delete manually if needed |
+| `doctor` says `runner download url → 403` but the URL works in a browser | Old build: the check used `HEAD`, and the presigned redirect target is signed per method | Upgrade — the check now uses a ranged `GET`. If it persists, the asset really is missing |
 | Disk filling up | Copy-on-write clones grow as jobs write | Raise `storage.minFreeDiskGB`; delete stale clones in `storeDir/vms` |
 | `image build` appears to hang during install | Normal — macOS install is slow | Wait. **Do not stop the VM mid-install**; if you did, delete the image and rebuild |

@@ -261,6 +262,29 @@ registrations that have already been spent cannot receive jobs).

 ---

+## `doctor` warns "runner download url → 403"
+
+**Symptom.** `doctor` reports the runner download URL as a 403, but pasting the same URL into a
+browser downloads the binary fine:
+
+```
+! runner download url    https://gitea.com/gitea/runner/releases/download/v3.0.2/… → 403
+```
+
+**Cause.** gitea.com does not serve release assets itself. It answers with a `303 See Other`
+pointing at a presigned object-storage URL, and that signature covers the HTTP method of the
+request that minted it. A `HEAD` probe therefore gets a HEAD-signed URL — and then the HTTP client,
+following the 303, rewrites the method to `GET` (RFC 7231 §6.4.4) and replays the signed URL with
+the one verb it was not signed for. The store answers `403 SignatureDoesNotMatch`. Nothing is
+actually wrong with the asset.
+
+**Fix.** Upgrade — the check now probes with a one-byte ranged `GET` (`Range: bytes=0-0`), the same
+verb `image provision` uses for the real download, and falls back to a `HEAD` only if the range is
+rejected. If you still see a 403 after upgrading, the asset really is gone: check `runner.version`
+and `runner.runnerDownloadURL` for a `darwin-arm64` build.
+
+---
+
 ## Disk filling up

 **Symptom.** Free space falls steadily; the daemon starts refusing to launch VMs, citing