GitLab CI/CD runners on Orka macOS VMs

How to use GitLab with your Orka environment. MacStadium provides seamless integration between Orka and GitLab. Both Shell and custom executors are supported. MacStadium provides scripts and a template configuration for custom executors. New to Orka? See how teams use it for CI/CD.

Current release: v2.0.1.

Set Up a Shell Executor

Shell executors are useful when you need permanent executors that you can reuse across builds. For the latest information about how to work with a Shell executor in Orka, see Using a GitLab Shell Executor to Run CI/CD Pipelines in Orka.

Set Up a Custom Executor

Custom executors are useful when you need to work with ephemeral executors and automate their management. With a custom executor, an executor is created before the pipeline is run and destroyed after the pipeline is complete. For the latest information about how to work with a custom executor in Orka, see Using a GitLab Custom Executor to Run CI/CD Pipelines in Orka.

Cache restoration and artifact downloading require the gitlab-runner binary to be present inside the Orka VM. If your pipeline logs show “Missing gitlab-runner. Extracting cache is disabled.” or “Missing gitlab-runner. Artifacts downloading is disabled.”, install the gitlab-runner binary in your base image before creating your VM config.

Run concurrent builds

By default, the config template sets concurrent = 1, which means only one build runs at a time. To run multiple builds simultaneously, update two settings in your config.toml:

concurrent (global): the total number of jobs that can run at the same time across all runners.
limit (per runner, under [[runners]]): the maximum number of jobs this specific runner handles concurrently.

Both values should match. For example, to allow 10 concurrent builds:

concurrent = 10

[[runners]]
  name = "orka-runner"
  executor = "custom"
  limit = 10
  ...

See the GitLab Runner advanced configuration for the full list of options.

Custom executor environment variables

The custom executor reads its configuration from environment variables, set either as GitLab CI/CD variables (Settings → CI/CD → Variables, for anything the runner scripts need during job execution) or passed to the runner container at startup (for anything needed at the container level, like ORKA_ENDPOINT). Mask ORKA_TOKEN and ORKA_SSH_KEY_FILE in GitLab since they’re sensitive.

Variable	Required	Description
`ORKA_TOKEN`	Yes	Service account token, from `orka3 sa token <SERVICE_ACCOUNT_NAME>`. Not a personal token. Personal tokens expire in 1 hour.
`ORKA_ENDPOINT`	Yes	Your Orka API URL, with protocol and no trailing slash, for example `http://10.221.188.20`.
`ORKA_CONFIG_NAME`	Yes	VM config template name, from `orka3 vm-config create <VM_CONFIGURATION_NAME> --image <IMAGE_NAME> --cpu <CPU_COUNT>`. Set as a CI/CD variable rather than at the container level if you want different pipelines to deploy different configs from the same runner. Otherwise, the runner is locked to one config.
`ORKA_SSH_KEY_FILE`	Yes	Private SSH key contents. Prefer mounting the key file into the runner container over storing key contents as a GitLab variable.
`ORKA_VM_USER`	No	SSH user on the deployed VM. Defaults to `admin`.
`ORKA_VM_NAME_PREFIX`	No	Prefix applied to deployed VM names. Defaults to `gl-runner`.
`VM_DEPLOYMENT_ATTEMPTS`	No	Retry count for VM deployment. Defaults to `1`.

Beyond a single executor

Image caching. If cold starts on a new base image are slow, see Image Caching to pre-cache it on specific nodes ahead of time.
Burst capacity. If a fixed pool isn’t enough during peak build periods, Orka Burst adds on-demand elastic capacity without a long-term hardware commitment.

Troubleshooting

Symptom	Likely cause	Fix
VM deployment or `orka3` commands fail with “unauthorized”	`ORKA_TOKEN` is invalid or expired	Generate a new service account token with `orka3 sa token <SERVICE_ACCOUNT_NAME>` and update `ORKA_TOKEN`. Service account tokens last 1 year by default; use `--duration` for a custom length, or `--no-expiration` if your Kubernetes control plane (for example EKS) doesn’t allow long-lived tokens.
CLI commands fail before authentication, with “config not found,” “no such host,” or a DNS lookup error	`ORKA_ENDPOINT` is unset or malformed	Check the format: include the protocol, no trailing slash (`http://10.221.188.20`, not `10.221.188.20` or `http://10.221.188.20/`).
Deployment fails with “VM deployment failed”	`ORKA_CONFIG_NAME` doesn’t exist or is misspelled, or no node has enough free resources	Confirm the config exists (`orka3 vm-config create <VM_CONFIGURATION_NAME> --image <IMAGE_NAME> --cpu <CPU_COUNT>` if not), and check node capacity with `orka3 node list`. Set `VM_DEPLOYMENT_ATTEMPTS` higher if deployments are failing due to transient resource contention.
VM deploys, but connection info extraction fails (“Invalid ip: null”)	The VM is in a failed state, or the deployment returned unexpected output	Deploy a VM manually with `orka3 vm deploy test-vm --config "$ORKA_CONFIG_NAME" -o json` and inspect the JSON. If a manual deploy also fails, contact support with the full error, then `orka3 vm delete test-vm` to clean up.
SSH connection times out (“Waited 30 seconds for sshd to start”)	SSH isn’t enabled on the base image, no key is configured on the VM, or the VM is still booting	Deploy a test VM and connect over Screen Sharing to confirm Remote Login is enabled and your public key is in `~/.ssh/authorized_keys`, then test `ssh -i <KEY_FILE> -p <SSH_PORT> admin@<VM_IP> "echo ok"` directly.
SSH connection refused (“Permission denied (publickey)“)	The SSH key has a passphrase (not supported), `ORKA_VM_USER` doesn’t match the VM’s actual user, or the key isn’t in the VM’s `authorized_keys`	Confirm the key has no passphrase (`ssh-keygen -y -f <KEY_FILE>` shouldn’t prompt for one), regenerate without one if needed, and confirm `ORKA_VM_USER` matches the account on the image (default `admin`).
SSH connects to the wrong IP, or “No route to host”	Private/public IP mismatch on your network	Configure IP mapping in `/var/custom-executor/settings.json` with your `private_host`/`public_host` pairs.
VMs remain after a job completes	The runner crashed before cleanup, or a network issue interrupted it	Delete manually with `orka3 vm delete <VM_NAME>`.

If your build script itself fails, that’s a script problem, not an integration problem. The custom executor distinguishes build failures (your script’s exit code) from system failures (infrastructure, always exit code 1). For anything not covered here, check the runner logs (gitlab-runner --debug run) before contacting support.

Support

Open a ticket in the MacStadium Portal and include your gitlab-runner --debug run output.

MacStadium

Orka

MacStadium VDI

IaaS

GitLab CI/CD runners on Orka macOS VMs

Set Up a Shell Executor

Set Up a Custom Executor

Run concurrent builds

Custom executor environment variables

Beyond a single executor

Troubleshooting

Support

​Set Up a Shell Executor

​Set Up a Custom Executor

​Run concurrent builds

​Custom executor environment variables

​Beyond a single executor

​Troubleshooting

​Support

Set Up a Shell Executor

Set Up a Custom Executor

Run concurrent builds

Custom executor environment variables

Beyond a single executor

Troubleshooting

Support