Skip to content

Concepts

Modes

The controller supports three operating modes:

  • poll: periodically list queued workflow jobs
  • webhook: receive workflow_job events
  • both: run both in parallel and deduplicate work via the state store

Labels are the scheduling contract

GitHub workflow jobs declare runs-on. The controller matches those labels against the labels: section in config. Each matching label describes:

  • the image to boot
  • optional CPU
  • optional memory
  • optional disk

No label match means no provisioning.

If an image and resource overrides are both configured, the controller creates the VM from the image first and patches resources before starting it. That matches the current Jeballto API contract.

Native Actions execution

Unlike a generic SSH job runner, this controller boots the official Actions runner inside the VM. That is why the job keeps native GitHub Actions behavior like:

  • artifact upload
  • cache actions
  • marketplace actions
  • OIDC and token flows

State store and deduplication

The controller stores job state on disk so it can:

  • avoid provisioning the same job twice
  • reconnect cleanup to jobs already in progress
  • deduplicate poll events and webhook deliveries

This matters most in both mode, where the same job may be observed through two different event sources.

Garbage collection

The controller is not purely event-driven. It also runs periodic GC so a missed completion event or a controller restart does not leave VMs running forever.

Two-VM host limit

The host-level limit still applies. The controller's max_concurrent_vms should match the actual host limit, which is two VM slots on the current Apple Virtualization setup. Both RUNNING and PAUSED VMs consume a slot.