Skip to main content
This guide details how to install the build tools needed to set up a CI Build Node using Homebrew. Minimum requirements:
It is a good practice to have a bot user whose only responsibility is to build your OSX/iOS projects. This means such a user with the correct permissions should be created, so the user can build OSX/iOS projects.
Do this via VNC or via the Web Console, or to enable Remote Login in the macOS settings, set SSH in.

Install Homebrew

Homebrew is a package manager for macOS and used for managing installation of the various tools needed for iOS and macOS CI efforts. This step takes about 15 minutes, and requires the password at least once.

Install Ruby

Lots of tooling requires a modern Ruby installed (fastlane for instance), so we also update our system Ruby:

Install fastlane

fastlane provides an easy way to automate beta deployments and releases for iOS and Android apps. To install it, run:

Install CocoaPods

CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects. It is installed via ruby gem:

Install Node.js

To install the latest version of Node.js run:
To install the latest LTS run:
This installs Node.js 10 LTS and links it to /usr/local/bin so it is available in PATH.
Consider using nvm to manage different Node.js versions. To install nvm run:

Install Java 8

To setup a Jenkins agent, Java 8 must be installed on the machine. To do that, run:

Install Xcode

Do this is via a VNC/screen-sharing session. If working from a Mac, open the Finder and press “cntrl k”. This opens the machine’s built-in VNC GUI. Collect your public IP and screen-sharing port, and pass them in the GUI.
  1. Enter the user credentials.
  2. Open a web browser via the screen-sharing connection.
  3. Navigate to developer.apple.com
  4. Log in
  5. Navigate to developer.apple.com/downloads/more
  6. Download and install the preferred version of Xcode by clicking the download link and double-clicking on the resulting download.

Creating Dedicated Build User

MacStadium recommends having a dedicated user that is responsible for building OSX/iOS applications. First, create a group for this user. The group needs to have a unique ID. List the current group IDs in a numerical order by running:
Choose a number that is not in the list. Then run by replacing {GroupName} and {GroupID} with the desired values:
Pick a unique ID for the user. It is done in a similar fashion to the way we chose the group ID:
Finally, run by replacing the placeholders:
Ensure a home folder is created for the user:

Creating Default Keychain for the Build User

Since the build user will not log into the OSX machine, a default keychain will never be created.
This could cause build and/or code sign issues (especially when using fastlane).
To create a default keychain for the build user, switch to the build user in the terminal:
Execute commands as the build user:
This creates new keychain called login.keychainand makes it default for the build user.
The security command line tool has a bug and does not add the new keychain to the list of available keychains. To fix this, call:
Proceed with the rest of the setup. To switch back to the previous user type:

Logging Remotely with the Build User

Remote logging is required. To log remotely with the newly created build user and ensure the user can log remotely:
Create an SSH key pair to use for remote logging. If an SSH key pair does not exist, then create one by executing:
For increased security, it is recommended to associate a passphrase to the private key.
The command creates two files:
  • buildMachine_rsa - This is the private key. Keep it safe and do not share it with anyone.
  • buildMachine_rsa.pub - This is the public key.
To copy the private key to a secure machine, use scp. This command executes copy over SSH; run:
To create a authorized_keys file. It lists all keys that can be used to log remotely with a given user:
Use the private key to log to the machine remotely using the newly created user: