What do I need to know about using macOS agents with Jenkins?

You have a need to build software for macOS or iOS devices, and so need to set up macOS agents in Jenkins.

In one sense, because the macOS operating system is Unix-based, macOS agents can be treated similarly to any other Unix or Linux agent. You can enable an SSH server on the agent and have Jenkins connect to it that way, or you can configure it as a JNLP agent so that the agent connects back to Jenkins if desired. However, there are some additional things you will need to keep in mind as you start using macOS in a Continuous Integration process.

First, the terms of Apple’s macOS license do not allow you to run macOS on non-Apple hardware. You can run it in a virtual machine, but the VM has to be running on a physical Mac system. So step one for building on macOS will be to get access to Mac hardware. Many teams start out by using Mac Mini systems that they host themselves, either in their office or in a datacenter. If you choose to self-host a Mac for this purpose, there are some challenges that come along with it. Macs don’t have any built-in remote power management the way most server-class systems do, so if the host crashes there is no way to power-cycle it remotely unless it is plugged into a networked power strip. There also isn’t a way to fully automate the installation of OS updates - some UI interaction is always required to complete the install and reboot the system. If you’re just running one Mac Mini on a desk in your office, these challenges might be minor, but if you need the system to be hosted in a datacenter it can be more complicated.

As an alternative to self-hosting Mac systems, you can use a cloud hosting provider that specializes in Macs. MacStadium is the best-known provider in this space. They have custom solutions to address OS updates, power management, and other issues that come up when using Macs in a datacenter environment. You can spin up single Mac Minis for your use directly from their web site, or get access to more complex environments by working with their Sales team. Alternatively, Amazon now offers EC2 instances running macOS, which may be a good solution if you already use AWS in your environment.

Once you have a Mac that you can build on, you can essentially set it up like any other Jenkins agent. Enabling an SSH server on the Mac and configuring it in Jenkins as an SSH agent would be the easiest approach. Configuring an SSH agent is documented under Managing agents - this is not Mac-specific. You can also configure it as a JNLP agent, where the agent host will connect back to the Jenkins controller, but this is more commonly used for Windows agents where running SSHd is not as simple.

If you are going to be targeting multiple versions of macOS or iOS with your builds, multiple versions of Apple’s Xcode build tools may be required, and there is no way to have more than one version of Xcode installed on a single host. So in most cases when users get into that situation, they move to using macOS in a VM rather than on the bare-metal host, so that they can easily maintain different build environments and start and stop them quickly. Veertu offers a set of Docker-like tools for working with macOS VMs, which make CLI interactions much easier.

Finally, many iOS app developers who are using a CI process use the Fastlane tools. These provide a command-line, scripting-friendly interface to perform all the functions required to build, test, and deploy applications to the App Store in an automated way.

This article mentions the following solutions/products: MacStadium, AWS EC2, Veertu, and Fastlane. We do not maintain or commercially support these solutions. They are offered here only as suggested components of a system for building macOS and iOS applications, based on feedback we have received from the software development community. Users will need to make their own evaluation of these solutions to determine whether they suit their use cases.