Configuration¶

Overview¶

The plugin configuration has two layers:

cloud-level label mappings
per-host agent configurations

Both must be wired correctly before Jenkins can provision a macOS VM.

Add a Jeballto Cloud¶

In Jenkins:

Manage Jenkins -> Clouds -> New Cloud -> Jeballto Cloud

Agent configuration fields¶

Field	Description	Default
Name	Unique host identifier used in VM names	required
Jeballto URL	REST API endpoint for the host	required
API Token	Secret text credential for the API bearer token used by Jeballto	required for provisioning and Test Credentials
SSH Credentials	Jenkins SSH credentials for the VM guest	required
CPU Count	vCPUs per VM, `0` means host default	`0`
Memory (GB)	Memory per VM, `0` means host default	`0`
Disk (GB)	Disk per VM, `0` means host default	`0`
Max Instances	Concurrent VM cap on this host	`2`
Remote FS	Jenkins working directory inside the VM	`/Users/admin`
SSH Host Override	Override target host for SSH when Jenkins and guest networking differ	auto-detect

Use Test Connection and Test Credentials before saving.

The VM image must include a Java runtime compatible with the Jenkins controller. See the Jenkins Java support policy: https://www.jenkins.io/doc/book/platform-information/support-policy-java/

Label assignment fields¶

Field	Description
Label	Single Jenkins label atom, such as `xcode26`
OCI Image	Image reference used when that label is requested
Lifetime Seconds	Max VM lifetime in seconds, `0` means no limit
Priority	Higher value wins when multiple global label mappings match the same requested label

Lifetime Seconds is passed to Jeballto as lifetimeSeconds. Positive values must be between 1 and 604800 seconds.

Use lifetime as a CI/CD safety guard. Set it slightly higher than the Jenkins job timeout because the VM still needs time to boot, connect as a Jenkins agent, and start the build after creation. Image pull happens before VM creation, so it does not need to be included in this buffer. For example, if builds can run for 60 minutes, use a VM lifetime such as 3900 or 4200 seconds.

Recommended first layout¶

One host, one label¶

Agent Configuration: mac-mini-01
  assigned labels: xcode26
  max instances: 2

Label Assignment:
  label: xcode26
  image: ghcr.io/org/macos-ci:xcode-26
  lifetime seconds: 7200
  priority: 10

Two hosts, same label¶

Use this when you want failover:

Label Assignment:
  label: ci-macos
  image: registry.local/ci:latest
  priority: 10

Agent Configurations:
  mac-mini-01 assigned to ci-macos
  mac-mini-02 assigned to ci-macos

The plugin will try those hosts in the order they appear in the cloud configuration, skipping any host that is in cooldown or already at maxInstances.

Networking note¶

If Jenkins runs from a network namespace that cannot reach the Jeballto URL host directly, set SSH Host Override to a reachable IP or hostname. This is one of the most common first-time issues.