Skip to content

Jenkins Mac Build Agent: Complete Setup Guide

Configure a Jenkins build agent on a dedicated Mac Mini M4. Automate Xcode builds, run iOS tests, and deploy to TestFlight with full control over your build infrastructure.

CI/CD 35 min read Updated October 2026

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:

  1. Go to Manage Jenkins > Nodes > New Node
  2. Set the name to mac-mini-m4
  3. Set Remote root directory to /Users/jenkins/workspace
  4. Labels: mac macos apple-silicon m4 ios
  5. Launch method: Launch agents via SSH
  6. Host: Your Mac Mini's IP address
  7. Credentials: Add the SSH private key matching the authorized_keys on the Mac
  8. 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 -l to check for updates.

FAQ

Can I run the Jenkins controller on the same Mac?
Yes, but we recommend separating them. Run the controller on a Linux VM or Docker container, and use the Mac exclusively as a build agent. This avoids resource contention during heavy builds.
How many concurrent builds can a Mac Mini M4 handle?
A Mac Mini M4 with 16GB RAM can comfortably handle 2 concurrent Xcode builds. With 24GB, you can push to 3. The M4 Pro with 48GB handles 4+ concurrent builds easily. Configure the "Number of executors" in your Jenkins node settings accordingly.
Do I need a GUI session for iOS simulators?
No. iOS simulators work in headless mode over SSH. However, if you need a GUI (e.g., for UI testing screenshots), use VNC to log in to the Mac and ensure a GUI session is active.
How do I handle code signing on a headless server?
Use Fastlane Match to sync certificates from a Git repo or cloud storage. Alternatively, import certificates into the macOS keychain and unlock it in your pipeline using security unlock-keychain.

Ready to Supercharge Your Jenkins Builds?

Get a dedicated Mac Mini M4 for your Jenkins CI/CD pipeline. Starting at $85/month.

My Remote Mac prices in USD, excluding tax.

Looking for more detail?

Browse the full documentation for step-by-step setup, configuration references, and troubleshooting.

Open the documentation →