Skip to main content
When you move CI to a new macOS version, rebuild your CI image on the base image for that version instead of running Software Update inside a VM you already have. A scripted rebuild is repeatable, starts clean, and avoids the problems in-place updates run into.

Why not update in place

  • In-place updates to some versions currently fail inside VMs. Updates to macOS 15.x and 26.x targets either never finish booting or leave the VM with capped memory. A workaround exists, but it adds steps to every update. See the known issue in the Orka compatibility matrix.
  • Resized VMs can fail to update. If your image was grown with orka vm resize, a macOS update inside it might fail. See the limitations in Apple silicon Mac servers in Orka.
  • An updated image carries its history. Leftover files, caches, and settings from every earlier version stay in the image. A rebuild contains only what your build script puts there.

Script the image build

Keep the steps that turn a base image into your CI image in a script or a Packer template: install Xcode and toolchains, configure macOS, then push. A macOS update then becomes:
  1. Point the build at the base image for the new version, such as ghcr.io/macstadium/orka-images/tahoe:<TAG>, or ghcr.io/macstadium/orka-images/golden-gate:latest for macOS 27. The orka-images repository lists the available images and tags.
  2. Run the build and push the result to a new versioned tag.
  3. Deploy a VM from the new tag and run real jobs on it.
  4. Point your pipelines at the new tag.
Keep the previous tag in your registry until the new one has run cleanly for a while, so you can roll back by switching the tag back.

Check host requirements first

Each guest macOS version needs a minimum host macOS version. For example, macOS 27 guests need hosts on macOS 26.6.2 or later. Check the Orka compatibility matrix before you move, and contact MacStadium support if your nodes need a host update first.