Concepts

Global mappings versus host templates

This is the central idea of the plugin.

Global label mappings

These answer:

• which OCI image should a given Jenkins label use?

Agent configurations

These answer:

• which physical Mac can serve that label?
• how many VMs can it run?
• which API and SSH credentials should it use?

Priority routing

Priority applies to global label mappings, not to host selection.

If multiple LabelAssignment entries match a requested label, the plugin picks the highest-priority mapping first. That determines which OCI image will be used.

Host selection order

After the image is chosen, the plugin gathers every host template assigned to that label and tries them in the order they appear in the Jenkins cloud configuration.

This enables:

• a simple primary-then-fallback order by reordering templates
• gradual host cutovers without changing the label-to-image mapping
• shared image policy across multiple Macs

Semaphores enforce local capacity

Each host template has an in-memory semaphore keyed to maxInstances. That is how the plugin prevents Jenkins from over-provisioning a single host.

Circuit breaker

After repeated provisioning failures, the plugin places the template into a short cooldown. This prevents Jenkins from hammering a broken host continuously.

Orphan cleanup

The plugin runs a background orphan cleanup process so leftover VMs do not accumulate after failures or restarts.

One-shot agents

Every VM is intended for one build. The plugin is designed around one-shot ephemeral agents, not reusable long-lived workers.