Skip to content

Getting Started

What this component does

The GitLab executor is a small Go binary that GitLab Runner calls as a custom executor. It translates each GitLab job into a Jeballto VM lifecycle:

  1. pick an image
  2. create a VM
  3. start it and wait for SSH
  4. run the job script
  5. force-delete the VM

Prerequisites

Before you configure anything, make sure you have:

  • an Apple Silicon Mac running macOS 26.0+
  • a working Jeballto Agent on that Mac
  • GitLab Runner installed on the same machine
  • at least one OCI image that boots a usable macOS VM
  • credentials for the Jeballto API and for SSH inside the VM

First decisions to make

Image strategy

Jobs can request an image directly in .gitlab-ci.yml:

macos-build:
  image: ghcr.io/your-org/macos-ci:xcode-26
  script:
    - xcodebuild -version

Decide whether to allow that per-job choice or enforce one runner-level default:

  • open image selection: enable job-level overrides and optionally constrain them with an allowlist
  • fixed image selection: set JEBALLTO_DEFAULT_IMAGE and disable overrides

Resource strategy

Choose whether to let the Jeballto image decide defaults or to override CPU, memory, and disk from the executor environment. The executor supports both, but the host is still limited to two VM slots and RUNNING plus PAUSED VMs both consume a slot.

SSH strategy

The executor expects password-based SSH. The default login is admin / admin, but production images should use explicit credentials configured through environment variables.

For a low-risk first deployment:

  1. keep GitLab Runner and the Jeballto Agent on the same Mac
  2. set one default image
  3. keep the default two-VM capacity
  4. run one simple smoke-test job
  5. only then turn on image overrides or custom resource profiles

Next step

Continue to Installation to install the released binary, then wire GitLab Runner in Configuration.