Gotchas

Poll mode is repository-only

This catches many first-time users. Poll mode requires github.repository because GitHub does not expose a cross-repo queued-job listing API for this use case.

Webhook mode is not safe without a secret

The controller deliberately rejects webhook traffic if github.webhook_secret is missing. Without that secret, anyone who can reach the endpoint could try to trigger provisioning.

The image must already contain the runner

The controller does not install the Actions runner dynamically as part of the job flow. Your image must already have the runner files available at runner.install_path.

both mode increases complexity

It is useful, but only after you understand the simpler modes. You gain redundancy and lower latency, but you also rely more heavily on state deduplication.

Host limit still matters

Even though GitHub can queue as many jobs as it likes, your Mac still only has two VM slots in the current setup. RUNNING and PAUSED VMs both count against that limit.

Health server still exists in poll mode

In poll mode there is no webhook handler, but the controller still exposes /healthz on webhook_listen. That is expected.