Quickstart¶

This smoke test assumes the executor is already installed. See Installation first.

1. Configure GitLab Runner¶

Add the custom executor hooks to ~/.gitlab-runner/config.toml:

concurrent = 2

[[runners]]
  name = "jeballto"
  url = "https://gitlab.example.com"
  token = "REDACTED"
  executor = "custom"
  shell = "bash"
  limit = 2
  request_concurrency = 2
  environment = [
    "JEBALLTO_BASE_URL=http://127.0.0.1:8011/v1",
    "JEBALLTO_DEFAULT_IMAGE=ghcr.io/jeballto/macos-ci:xcode-26",
    "JEBALLTO_VM_LIFETIME_SECONDS=7200",
    "JEBALLTO_SSH_USER=admin",
    "JEBALLTO_VM_PASSWORD=admin"
  ]

  [runners.custom]
    config_exec = "/usr/local/bin/jeballto-gitlab-executor"
    config_args = ["config"]
    prepare_exec = "/usr/local/bin/jeballto-gitlab-executor"
    prepare_args = ["prepare"]
    run_exec = "/usr/local/bin/jeballto-gitlab-executor"
    run_args = ["run"]
    cleanup_exec = "/usr/local/bin/jeballto-gitlab-executor"
    cleanup_args = ["cleanup"]
    prepare_exec_timeout = 9000
    cleanup_exec_timeout = 300

If the token is not available through the default Jeballto config path, set JEBALLTO_TOKEN too.

2. Restart GitLab Runner¶

Restart the runner process so it picks up the custom executor configuration and environment variables.

3. Run a smoke test job¶

stages:
  - test

macos-test:
  stage: test
  script:
    - sw_vers
    - xcodebuild -version

If you prefer explicit job-level image selection:

macos-build:
  image: ghcr.io/jeballto/macos-ci:xcode-26
  script:
    - sw_vers
    - xcodebuild -version

4. Confirm the lifecycle¶

On a healthy run you should see:

The image is resolved and pulled if needed.
A VM is created and started.
SSH forwarding is enabled.
The job script runs in the VM.
The VM and local state are removed.

Fast failure checks live in Troubleshooting.