Jenkins plugin for Orka macOS build agents

The Orka by MacStadium plugin lets Jenkins provision macOS build agents as Orka VMs, either permanent agents you manage yourself or ephemeral agents Jenkins creates and destroys per build. Ephemeral agents are the reason most teams install this. Every job gets a clean macOS VM from a known image, so build failures trace back to code instead of environment drift on a shared Mac, and capacity scales with queue depth instead of with the number of Macs you bought. Permanent agents are the right choice when you need a long-lived, hand-tuned machine and want to control its lifecycle yourself. You do not need Kubernetes knowledge to use this integration. The plugin talks to the Orka API with a service account token. New to Orka? See how teams use it for CI/CD.

Requires plugin v2.00 or later. Current release: v2.10.

Prerequisites

Have all of these in place before step 1.

Requirement	Notes
Orka 3.0+ cluster	Access managed through the MacStadium Customer Portal. See Cluster Access Management.
Network path from Jenkins to Orka	Your Orka cluster sits behind a firewall. The Jenkins controller must reach it. Use a VPN client to test, or a site-to-site tunnel (AWS, GCP) for production.
Your Orka API URL	From the IP Allocation table in My Cloud. Usually the `.20` address on `Private-1`, for example `http://10.221.188.20`. An Orka domain or custom domain works too, as long as Jenkins can resolve it.
Orka3 CLI	Download and install, then run `orka3 config set --api-url <ORKA_API_URL>`.
Jenkins 2.205 or later	The menu paths below assume 2.205+.
A macOS image and its SSH credentials	MacStadium’s public images at `ghcr.io/macstadium/orka-images` default to `admin`/`admin`. Change this.

Setup steps

1. Create a service account and token

Personal SSO tokens expire after one hour and will break your pipeline overnight. Service account tokens last one year.

orka3 sa create jenkins
orka3 sa token jenkins

Both commands act on the orka-default namespace. To deploy into a different namespace, create the service account there or configure role bindings. Copy the token. You will store it in Jenkins in step 3.

2. Install the plugin

In Jenkins, go to Manage Jenkins → Plugins → Available plugins, search for Orka by MacStadium, install, and restart. See Managing Plugins. To build and package it yourself, use the plugin repository.

3. Store your credentials in Jenkins

Add two credentials under Manage Jenkins → Credentials:

Credential	Kind	Used for
Orka token	Secret text	Authenticating the plugin to the Orka API
VM credentials	Username with password, or SSH username with private key	SSH from the Jenkins controller into the deployed VM

4a. Configure an ephemeral agent pool

This is the path most CI teams want. Jenkins deploys a VM when the queue needs one and deletes it after an idle period.

Go to Manage Jenkins → Nodes and Clouds → Configure Clouds → Add a new cloud.
Select Orka Cloud.
Set Name of this Cloud, Orka Token (the secret text from step 3), and Orka Endpoint (your Orka API URL).
Click Add Orka Template. This is the spec Jenkins uses for each new agent.
Set Image, # of CPUs, Memory, Namespace, and VM Credentials. Add a Label so jobs can target this pool.
Save.

4b. Or configure a permanent agent

Go to Manage Jenkins → Nodes and Clouds → New Node.
Enter a Node name and select Agent running under Orka by MacStadium, then click OK.
Set Orka Token, Orka Endpoint, Namespace, Node, Image, # of CPUs, Memory, and VM Credentials.
Save.

The VM deploys immediately and stays up until you delete it.

5. Run a test job

Point a job at the label you assigned:

pipeline {
    agent { label 'orka-macos' }
    stages {
        stage('Verify') {
            steps {
                sh 'sw_vers && xcodebuild -version'
            }
        }
    }
}

A successful run confirms the whole chain: token, network path, VM deployment, and SSH.

Initial boot on an Apple silicon node takes longer than on subsequent runs. Increase the Jenkins agent connection timeout before your first ARM deployment.

Configuration reference

Orka Cloud (ephemeral agents)

Field	Default	What it controls
Name of this Cloud	none	Label for this cloud in Jenkins
Orka Token	none	Service account token used to authenticate to Orka
Orka Endpoint	none	Orka API URL the plugin calls
Max Jenkins Agents Limit (Advanced)	none	Ceiling on concurrent Orka VMs this cloud can create
Deployment Timeout (sec) (Advanced)	600	How long to wait for a VM before failing the request
HTTP Timeout (sec) (Advanced)	300	How long to wait for a response from the Orka API before failing. Covers all HTTP operations except VM deploy, which uses Deployment Timeout above instead. Tune that one if deploys are timing out
Node Mappings (Advanced)	private node address	Overrides the host address used to SSH into the VM. Public node addresses come from MacStadium
Use Jenkins HTTP Proxy Settings (Advanced)	off	Routes calls to the Orka API through Jenkins’ own configured HTTP proxy
Ignore SSL Errors (Advanced)	off	Skips TLS certificate validation on the connection to the Orka API
No Delay Provisioning (Advanced)	off	Skips Jenkins’ normal provisioning delay so this cloud’s agents come up immediately

Orka Template and permanent agent

Field	Default	What it controls
Image	none	Base image the VM deploys from
# of CPUs	none	CPU count for the VM
Memory	none	Memory for the VM
Namespace	none	Namespace the VM deploys into. Must match your service account’s access
VM Credentials	none	SSH credentials used to connect to the deployed VM
Name Prefix	none	Prefix applied to the deployed VM name
Tag	none	Prefers a node marked with this tag
Tag Required	false	Requires a node marked with this tag
Use Net Boost	off	Improves network performance on Intel VMs. Required for Intel macOS Ventura. macOS Big Sur and later only
Use Legacy IO	off	Legacy IO network stack. Intel only, macOS 10.14.5 and below only
Use GPU Passthrough	off	Gives the VM the node’s GPU. Must be enabled cluster-wide first
Display Settings (Advanced)	1920x1080, 90 DPI	Display height, width, and DPI of the VM
Scheduler (template only)	none	Scheduler used to place the VM
Node (permanent only)	none	Specific Orka node to deploy on
Public Host (permanent only)	node’s default address	Public node address used to reach the VM

Migrating from Orka 2.x templates

Existing agent templates show a radio group:

Orka 3.x Deployment: no VM config required. Settings from Create a new VM config migrate here automatically.
Orka 2.x Deployment: legacy path, read-only. To change anything, move the template to Orka 3.x Deployment.

Beyond a single agent pool

Once a basic pool is working, a few Orka features are worth knowing about as your Jenkins usage grows:

Tags and scheduling. Use Tag / Tag Required to route specific job types (for example, GPU-dependent builds) to specific nodes, and Scheduler to control how templates place VMs across a pool with mixed hardware.
GPU passthrough. If your builds need the node’s GPU, Use GPU Passthrough exposes it to the VM, but it has to be enabled cluster-wide first. Ask MacStadium Support to turn it on.
Image caching. If cold starts on a new image are slow, see Image Caching to pre-cache images on specific nodes ahead of time.
Burst capacity. If your fixed node pool isn’t enough during peak build periods, Orka Burst adds on-demand elastic capacity without a long-term hardware commitment.

Troubleshooting

Enable plugin logging

Go to Manage Jenkins → System Log → Add new log recorder.
Name it, for example Orka Plugin Logs.
Under Loggers, click Add and enter io.jenkins.plugins.orka.
Set Log Level to All and save.

Logs appear under Manage Jenkins → System Log under your recorder name. Keep the scope at io.jenkins.plugins.orka. Narrowing to a single class can drop the lines you need. All is verbose and adds overhead on busy controllers.

Common failure modes

Symptom	Likely cause	Fix
Agent worked for a while, then started failing to authenticate	A personal SSO token was used instead of a service account token. Personal tokens expire after one hour.	Create a service account token (step 1) and use that instead.
VM deployment fails with a permission or forbidden error	The service account doesn’t have access to the target namespace.	Configure a role binding for the service account, or create it directly in that namespace.
First deployment to an Apple silicon node times out	Initial ARM boot takes longer than the default Jenkins agent connection timeout.	Increase the connection timeout before your first ARM deployment.
VPN or site-to-site tunnel shows connected, but the plugin still can’t reach Orka	The tunnel is up, but routing between the Jenkins controller’s network and Orka’s private network isn’t fully configured in both directions.	See AWS troubleshooting for the routing checks that apply to any site-to-site connection into Orka.
SSH connection refused when deploying from a custom or ISO-built image	The image doesn’t have the VM credentials configured in Jenkins, or Remote Login (SSH) isn’t enabled on it.	Confirm the VM Credentials in Jenkins match an account that actually exists on the image, and that SSH is enabled.

This list covers the most common failure modes. If you hit something not listed here, the plugin log (above) is the fastest way to narrow it down before contacting support.

Support

Open a ticket in the MacStadium Portal and include your plugin log output.

MacStadium

Orka

MacStadium VDI

IaaS

Jenkins plugin for Orka macOS build agents

Prerequisites

Setup steps

1. Create a service account and token

2. Install the plugin

3. Store your credentials in Jenkins

4a. Configure an ephemeral agent pool

4b. Or configure a permanent agent

5. Run a test job

Configuration reference

Orka Cloud (ephemeral agents)

Orka Template and permanent agent

Migrating from Orka 2.x templates

Beyond a single agent pool

Troubleshooting

Enable plugin logging

Common failure modes

Support

​Prerequisites

​Setup steps

​1. Create a service account and token

​2. Install the plugin

​3. Store your credentials in Jenkins

​4a. Configure an ephemeral agent pool

​4b. Or configure a permanent agent

​5. Run a test job

​Configuration reference

​Orka Cloud (ephemeral agents)

​Orka Template and permanent agent

​Migrating from Orka 2.x templates

​Beyond a single agent pool

​Troubleshooting

​Enable plugin logging

​Common failure modes

​Support

Prerequisites

Setup steps

1. Create a service account and token

2. Install the plugin

3. Store your credentials in Jenkins

4a. Configure an ephemeral agent pool

4b. Or configure a permanent agent

5. Run a test job

Configuration reference

Orka Cloud (ephemeral agents)

Orka Template and permanent agent

Migrating from Orka 2.x templates

Beyond a single agent pool

Troubleshooting

Enable plugin logging

Common failure modes

Support