Jeballto GitLab Executor¶

Run GitLab CI jobs inside fresh macOS VMs on Apple Silicon.

The Jeballto GitLab executor bridges GitLab Runner custom executor hooks with the Jeballto VM Agent. Every job gets an ephemeral VM, a deterministic setup flow, and aggressive cleanup.

Why this exists¶

GitLab Runner does not natively provision disposable macOS build machines. This executor fills that gap by:

creating a fresh VM for each job
starting the job over SSH inside the VM
deleting the VM after the job finishes
handling the host's two-VM capacity limit without manual operator intervention

What you will find in this site¶

Get running fast

Start with Getting Started, then follow Installation and Quickstart.

Configure safely

Use Configuration and Image Policy to wire GitLab Runner, image selection, and environment variables.

Debug the hard parts

Read Concepts, How It Works, and Troubleshooting when a job does not behave as expected.

Requirements at a glance¶

Apple Silicon host
macOS 26.0+
Jeballto Agent 0.3.3+
GitLab Runner with the custom executor enabled

Mental model¶

GitLab job
  -> image is selected from job or runner config
  -> VM boots from that image
  -> job script runs over SSH
  -> VM and local job state are removed

Detailed hook behavior lives in How It Works.

Suggested first path¶

Read Getting Started.
Install the released binary with Installation.
Wire config.toml using Configuration.
Run the one-host smoke test in Quickstart.
Keep Troubleshooting open during the first real pipeline.