Why a Dedicated Mac for Jenkins?
Jenkins is the most widely used CI/CD platform, running over 50% of enterprise build pipelines. However, building iOS apps with Jenkins requires macOS, and macOS can only legally run on Apple hardware. A dedicated Mac Mini M4 gives you:
-
Consistent Build Environment
Same hardware, same OS, same tools every build. No flaky builds due to environment drift.
-
Full Root Access
Install any tools, configure system settings, manage keychains for code signing.
-
Apple Silicon Performance
M4 chip delivers 2-3x faster Xcode builds compared to Intel Mac Minis.
-
Persistent Caches
DerivedData, CocoaPods, and SPM caches survive between builds.
Prerequisites
- A dedicated Mac mini M4 build server from My Remote Mac (from $85/mo, USD, excl. tax)
- A Jenkins controller (can be on Linux, Docker, or any cloud VM)
- SSH access to your Mac Mini
- Xcode, preinstalled on every My Remote Mac server (our GitHub Actions guide shows how to check it and add other versions)
Step 1: Install Java JDK on macOS
Jenkins agents require a Java Runtime Environment. Current Jenkins releases support Java 21 and Java 25 (Java 17 is no longer supported), so we install JDK 21 (LTS) via Homebrew for easy management.
# Put the preinstalled Homebrew on your PATH (once per account)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
# Install Java JDK 21 (LTS) with Homebrew
# (current Jenkins releases support Java 21 and 25)
brew install openjdk@21
# Create the symlink for system Java wrappers
sudo ln -sfn /opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk \
/Library/Java/JavaVirtualMachines/openjdk-21.jdk
# Add to PATH
echo 'export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
# Verify Java installation (should report version 21)
java -version
# Tools used by the pipeline in Step 3 (CocoaPods only if you use a Podfile)
brew install xcbeautify cocoapods
Step 2: Configure Jenkins Agent
There are two primary methods to connect a Jenkins agent: an inbound agent (the agent connects to the controller; formerly called JNLP) and SSH (the controller connects to the agent). We cover both.
Method A: SSH Agent (Recommended)
This is the most reliable approach. Jenkins connects to the Mac via SSH and manages the agent process remotely.
# On the Mac mini: create a dedicated, non-admin Jenkins user
sudo sysadminctl -addUser jenkins -fullName "Jenkins Agent" -password "STRONG_PASSWORD_HERE"
# Create its home folder from the macOS template (includes ~/Library)
sudo createhomedir -c -u jenkins
# If Remote Login is limited to some users (System Settings > General >
# Sharing > Remote Login), allow the jenkins user to connect over SSH
sudo dseditgroup -o edit -a jenkins -t user com.apple.access_ssh
# Create SSH directory and add the Jenkins controller's public key
sudo mkdir -p /Users/jenkins/.ssh
sudo sh -c 'echo "ssh-rsa YOUR_JENKINS_CONTROLLER_PUBLIC_KEY" > /Users/jenkins/.ssh/authorized_keys'
sudo chmod 700 /Users/jenkins/.ssh
sudo chmod 600 /Users/jenkins/.ssh/authorized_keys
sudo chown -R jenkins:staff /Users/jenkins/.ssh
# Create a workspace directory
sudo mkdir -p /Users/jenkins/workspace
sudo chown jenkins:staff /Users/jenkins/workspace
Now configure the agent in Jenkins:
- Go to Manage Jenkins > Nodes > New Node
- Set the name to
mac-mini-m4 - Set Remote root directory to
/Users/jenkins/workspace - Labels:
mac macos apple-silicon m4 ios - Launch method: Launch agents via SSH
- Host: Your Mac Mini's IP address
- Credentials: Add the SSH private key matching the authorized_keys on the Mac
- Host Key Verification Strategy: Known hosts file Verification Strategy. Before the first launch, connect once from the controller as the user that runs Jenkins (
ssh jenkins@YOUR_MAC_IP) to add the Mac to its~/.ssh/known_hosts
Method B: Inbound Agent (WebSocket)
Use this method when the Jenkins controller cannot reach the Mac directly (e.g., the Mac is behind a firewall). The agent initiates the connection. With the -webSocket option it only uses the controller's web port (HTTP or HTTPS), not a separate TCP agent port.
# First, create the node in Jenkins UI:
# Manage Jenkins > Nodes > New Node
# Launch method: "Launch agent by connecting it to the controller"
# Note the secret token from the node configuration page
# On the Mac mini, download the agent JAR as the jenkins user
# (download it again after each Jenkins controller upgrade)
sudo -u jenkins mkdir -p /Users/jenkins/jenkins-agent
sudo -u jenkins curl -fsSL -o /Users/jenkins/jenkins-agent/agent.jar \
https://your-jenkins-url/jnlpJars/agent.jar
# Test the agent connection. -webSocket goes through the controller's
# HTTP(S) port: no separate TCP agent port to open
sudo -u jenkins /opt/homebrew/opt/openjdk@21/bin/java \
-jar /Users/jenkins/jenkins-agent/agent.jar \
-url https://your-jenkins-url \
-secret YOUR_AGENT_SECRET \
-name "mac-mini-m4" \
-webSocket \
-workDir "/Users/jenkins/workspace"
Run the Inbound Agent as a launchd Service
The agent runs as a LaunchAgent of the jenkins user, so it starts when that user's session starts, not at boot. On a headless Mac, turn on automatic login for the jenkins user (System Settings > Users & Groups; not available while FileVault is on) so the agent comes back online after a reboot. That logged-in session also gives Simulators, UI tests and the login keychain the user environment they need.
# Create the LaunchAgent in the jenkins user's own Library
sudo -u jenkins mkdir -p /Users/jenkins/Library/LaunchAgents
sudo -u jenkins tee /Users/jenkins/Library/LaunchAgents/io.jenkins.agent.plist > /dev/null <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>io.jenkins.agent</string>
<key>ProgramArguments</key>
<array>
<string>/opt/homebrew/opt/openjdk@21/bin/java</string>
<string>-jar</string>
<string>/Users/jenkins/jenkins-agent/agent.jar</string>
<string>-url</string>
<string>https://your-jenkins-url</string>
<string>-secret</string>
<string>YOUR_AGENT_SECRET</string>
<string>-name</string>
<string>mac-mini-m4</string>
<string>-webSocket</string>
<string>-workDir</string>
<string>/Users/jenkins/workspace</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>/Users/jenkins/jenkins-agent/stdout.log</string>
<key>StandardErrorPath</key>
<string>/Users/jenkins/jenkins-agent/stderr.log</string>
</dict>
</plist>
EOF
# The agent loads at every login of the jenkins user. On a headless Mac,
# connect over VNC as an admin, open System Settings > Users & Groups and set
# "Automatically log in as" to jenkins (unavailable while FileVault is on),
# then restart:
sudo shutdown -r now
# After the restart, verify it's running
sudo launchctl print gui/$(id -u jenkins)/io.jenkins.agent | grep state
Step 3: Create iOS Build Pipeline
Create a Jenkinsfile in your repository root. This declarative pipeline builds, tests, and optionally archives your iOS app.
pipeline {
agent { label 'mac && m4' }
environment {
// Pick the Xcode for every stage without sudo
// (preinstalled Xcode; for another version, use the path from xcodes installed)
DEVELOPER_DIR = '/Applications/Xcode.app/Contents/Developer'
SCHEME = 'MyApp'
// Not WORKSPACE: Jenkins already uses it for the job's workspace path
XC_WORKSPACE = 'MyApp.xcworkspace'
// Any device listed by: xcrun simctl list devices available
DESTINATION = 'platform=iOS Simulator,name=iPhone 17,OS=latest'
// Relative to the job workspace, kept between builds
DERIVED_DATA = 'DerivedData'
}
options {
timeout(time: 30, unit: 'MINUTES')
buildDiscarder(logRotator(numToKeepStr: '20'))
}
stages {
stage('Checkout') {
steps {
checkout scm
}
}
stage('Install Dependencies') {
steps {
sh '''
# Homebrew tools are not on the PATH of a non-interactive SSH session
export PATH="/opt/homebrew/bin:$PATH"
# Xcode comes from DEVELOPER_DIR: no sudo xcode-select in a pipeline
xcodebuild -version
# Install CocoaPods dependencies
if [ -f "Podfile" ]; then
pod install --repo-update
fi
'''
}
}
stage('Build') {
steps {
sh '''
# Jenkins runs sh -xe: without pipefail, xcbeautify's exit status would hide a failed build
set -o pipefail
export PATH="/opt/homebrew/bin:$PATH"
xcodebuild build \
-workspace "${XC_WORKSPACE}" \
-scheme "${SCHEME}" \
-destination "${DESTINATION}" \
-derivedDataPath "${DERIVED_DATA}" \
CODE_SIGNING_ALLOWED=NO \
| xcbeautify
'''
}
}
stage('Test') {
steps {
sh '''
set -o pipefail
export PATH="/opt/homebrew/bin:$PATH"
rm -rf TestResults.xcresult
xcodebuild test \
-workspace "${XC_WORKSPACE}" \
-scheme "${SCHEME}" \
-destination "${DESTINATION}" \
-derivedDataPath "${DERIVED_DATA}" \
-resultBundlePath "TestResults.xcresult" \
-parallel-testing-enabled YES \
| xcbeautify --report junit --report-path build/reports
'''
}
post {
always {
junit allowEmptyResults: true, testResults: 'build/reports/junit.xml'
archiveArtifacts artifacts: 'TestResults.xcresult/**', allowEmptyArchive: true
}
}
}
stage('Archive') {
when {
branch 'main'
}
steps {
sh '''
set -o pipefail
export PATH="/opt/homebrew/bin:$PATH"
# Unsigned archive: checks that the Release build compiles.
# Fastlane signs and uploads the real build in Step 4.
xcodebuild archive \
-workspace "${XC_WORKSPACE}" \
-scheme "${SCHEME}" \
-archivePath "${DERIVED_DATA}/MyApp.xcarchive" \
-destination "generic/platform=iOS" \
CODE_SIGNING_ALLOWED=NO \
| xcbeautify
'''
}
}
}
post {
success {
echo 'Build and tests passed!'
}
failure {
echo 'Build or tests failed.'
}
cleanup {
sh 'xcrun simctl shutdown all 2>/dev/null || true'
}
}
}
Step 4: Integrate Fastlane for Deployment
Fastlane simplifies code signing and TestFlight deployment. Install it once on the Mac:
# Install Fastlane on the Mac mini (one-time setup)
brew install fastlane
Add a deploy stage to your Jenkinsfile:
stage('Deploy to TestFlight') {
when {
branch 'main'
}
environment {
APP_STORE_CONNECT_API_KEY_ID = credentials('app-store-key-id')
APP_STORE_CONNECT_API_ISSUER_ID = credentials('app-store-issuer-id')
APP_STORE_CONNECT_API_KEY_CONTENT = credentials('app-store-key-content')
MATCH_PASSWORD = credentials('match-password')
}
steps {
sh '''
export PATH="/opt/homebrew/bin:$PATH"
fastlane beta
'''
}
}
And create a matching fastlane/Fastfile:
default_platform(:ios)
platform :ios do
desc "Push a new beta build to TestFlight"
lane :beta do
setup_ci
# Fetch code signing certificates via match
match(type: "appstore", readonly: true)
# Increment build number
increment_build_number(
build_number: ENV["BUILD_NUMBER"]
)
# Build the app
build_app(
workspace: "MyApp.xcworkspace",
scheme: "MyApp",
export_method: "app-store",
derived_data_path: "DerivedData"
)
# Upload to TestFlight
upload_to_testflight(
skip_waiting_for_build_processing: true,
api_key: app_store_connect_api_key(
key_id: ENV["APP_STORE_CONNECT_API_KEY_ID"],
issuer_id: ENV["APP_STORE_CONNECT_API_ISSUER_ID"],
key_content: ENV["APP_STORE_CONNECT_API_KEY_CONTENT"]
)
)
end
end
Security Best Practices
-
Use a dedicated Jenkins user
Never run the Jenkins agent as root. Create a dedicated user with minimal permissions.
-
Store secrets in Jenkins Credentials
Never hardcode certificates, API keys, or passwords in Jenkinsfiles. Use the Jenkins Credentials plugin.
-
Enable SSH key-based authentication only
Disable password authentication for SSH. Use Ed25519 or RSA 4096-bit keys.
-
Use the macOS Firewall
Restrict incoming connections to only the Jenkins controller IP. My Remote Mac provides a managed firewall with API access.
-
Keep macOS and Xcode updated
Apply security patches promptly. Use
softwareupdate -lto check for updates.
FAQ
Can I run the Jenkins controller on the same Mac?
How many concurrent builds can a Mac Mini M4 handle?
Do I need a GUI session for iOS simulators?
How do I handle code signing on a headless server?
security unlock-keychain.