Zum Inhalt springen

Jenkins Mac Build Agent: Vollständige Einrichtungsanleitung

Konfigurieren Sie einen Jenkins-Build-Agenten auf einem dedizierten Mac Mini M4. Automatisieren Sie Xcode-Builds, führen Sie iOS-Tests aus und deployen Sie zu TestFlight mit voller Kontrolle über Ihre Build-Infrastruktur.

CI/CD 35 Min. Lesezeit Aktualisiert im Oktober 2026

Warum ein dedizierter Mac für Jenkins?

Jenkins ist die am weitesten verbreitete CI/CD-Plattform und betreibt über 50 % der Enterprise-Build-Pipelines. Das Bauen von iOS-Apps mit Jenkins erfordert jedoch macOS, und macOS darf rechtlich nur auf Apple-Hardware laufen. Ein dedizierter Mac Mini M4 bietet Ihnen:

  • Konsistente Build-Umgebung

    Gleiche Hardware, gleiches OS, gleiche Tools bei jedem Build. Keine instabilen Builds durch Umgebungsdrift.

  • Voller Root-Zugriff

    Installieren Sie beliebige Tools, konfigurieren Sie Systemeinstellungen und verwalten Sie Schlüsselbunde für die Code-Signierung.

  • Apple-Silicon-Performance

    Der M4-Chip liefert 2-3x schnellere Xcode-Builds im Vergleich zu Intel-Mac-Minis.

  • Persistente Caches

    DerivedData-, CocoaPods- und SPM-Caches bleiben zwischen Builds erhalten.

Voraussetzungen

  • Einen dedizierten Mac mini M4 Build Server von My Remote Mac (ab 85 $/Monat, USD, exkl. Steuern)
  • Einen Jenkins-Controller (kann auf Linux, Docker oder einer beliebigen Cloud-VM laufen)
  • SSH-Zugriff auf Ihren Mac Mini
  • Xcode, auf jedem Server von My Remote Mac vorinstalliert (unsere GitHub Actions-Anleitung zeigt, wie Sie es prüfen und weitere Versionen hinzufügen)

Schritt 1: Java JDK unter macOS installieren

Jenkins-Agenten benötigen eine Java Runtime Environment. Aktuelle Jenkins-Versionen unterstützen Java 21 und Java 25 (Java 17 wird nicht mehr unterstützt), daher installieren wir JDK 21 (LTS) über Homebrew für einfache Verwaltung.

# 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

Schritt 2: Jenkins-Agent konfigurieren

Es gibt zwei Hauptmethoden, um einen Jenkins-Agenten zu verbinden: einen eingehenden Agenten (der Agent verbindet sich mit dem Controller; früher JNLP genannt) und SSH (der Controller verbindet sich mit dem Agenten). Wir behandeln beide.

Methode A: SSH-Agent (empfohlen)

Dies ist der zuverlässigste Ansatz. Jenkins verbindet sich per SSH mit dem Mac und verwaltet den Agentenprozess remote.

# 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

Konfigurieren Sie nun den Agenten in Jenkins:

  1. Gehen Sie zu Manage Jenkins > Nodes > New Node
  2. Setzen Sie den Namen auf mac-mini-m4
  3. Setzen Sie das Remote-Root-Verzeichnis auf /Users/jenkins/workspace
  4. Labels: mac macos apple-silicon m4 ios
  5. Startmethode: Launch agents via SSH
  6. Host: Die IP-Adresse Ihres Mac Mini
  7. Anmeldedaten: Fügen Sie den privaten SSH-Schlüssel hinzu, der zu den authorized_keys auf dem Mac passt
  8. Host Key Verification Strategy: Known hosts file Verification Strategy. Verbinden Sie sich vor dem ersten Start einmal vom Controller aus als der Benutzer, unter dem Jenkins läuft (ssh jenkins@YOUR_MAC_IP), um den Mac zu dessen ~/.ssh/known_hosts hinzuzufügen

Methode B: Eingehender Agent (WebSocket)

Verwenden Sie diese Methode, wenn der Jenkins-Controller den Mac nicht direkt erreichen kann (z. B. wenn der Mac hinter einer Firewall steht). Der Agent initiiert die Verbindung. Mit der Option -webSocket nutzt er nur den Web-Port des Controllers (HTTP oder HTTPS), keinen separaten 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"

Eingehenden Agenten als launchd-Dienst ausführen

Der Agent läuft als LaunchAgent des Benutzers jenkins und startet daher bei dessen Anmeldung, nicht beim Booten. Aktivieren Sie auf einem headless Mac die automatische Anmeldung für den Benutzer jenkins (Systemeinstellungen > Benutzer & Gruppen; nicht verfügbar, solange FileVault aktiv ist), damit der Agent nach einem Neustart wieder online ist. Diese angemeldete Sitzung gibt auch Simulatoren, UI-Tests und dem Anmelde-Schlüsselbund die Benutzerumgebung, die sie brauchen.

# 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

Schritt 3: iOS-Build-Pipeline erstellen

Erstellen Sie ein Jenkinsfile im Stammverzeichnis Ihres Repositorys. Diese deklarative Pipeline baut, testet und archiviert optional Ihre 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'
        }
    }
}

Schritt 4: Fastlane für das Deployment integrieren

Fastlane vereinfacht die Code-Signierung und das TestFlight-Deployment. Installieren Sie es einmalig auf dem Mac:

# Install Fastlane on the Mac mini (one-time setup)
brew install fastlane

Fügen Sie eine Deploy-Stage zu Ihrem Jenkinsfile hinzu:

        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
                '''
            }
        }

Und erstellen Sie ein passendes 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

Best Practices für die Sicherheit

  • Verwenden Sie einen dedizierten Jenkins-Benutzer

    Führen Sie den Jenkins-Agenten niemals als Root aus. Erstellen Sie einen dedizierten Benutzer mit minimalen Berechtigungen.

  • Speichern Sie Secrets in Jenkins Credentials

    Codieren Sie Zertifikate, API-Schlüssel oder Passwörter niemals fest in Jenkinsfiles. Verwenden Sie das Jenkins Credentials-Plugin.

  • Aktivieren Sie ausschließlich SSH-Key-basierte Authentifizierung

    Deaktivieren Sie die Passwort-Authentifizierung für SSH. Verwenden Sie Ed25519- oder RSA-4096-Bit-Schlüssel.

  • Verwenden Sie die macOS-Firewall

    Beschränken Sie eingehende Verbindungen nur auf die IP des Jenkins-Controllers. My Remote Mac bietet eine verwaltete Firewall mit API-Zugriff.

  • Halten Sie macOS und Xcode aktuell

    Wenden Sie Sicherheitspatches zeitnah an. Verwenden Sie softwareupdate -l, um nach Updates zu suchen.

FAQ

Kann ich den Jenkins-Controller auf demselben Mac ausführen?
Ja, aber wir empfehlen, sie zu trennen. Führen Sie den Controller auf einer Linux-VM oder in einem Docker-Container aus und verwenden Sie den Mac ausschließlich als Build-Agenten. Dies vermeidet Ressourcenkonflikte bei aufwändigen Builds.
Wie viele gleichzeitige Builds kann ein Mac Mini M4 bewältigen?
Ein Mac Mini M4 mit 16 GB RAM bewältigt problemlos 2 gleichzeitige Xcode-Builds. Mit 24 GB können Sie auf 3 erhöhen. Der M4 Pro mit 48 GB bewältigt 4+ gleichzeitige Builds mit Leichtigkeit. Konfigurieren Sie die "Number of executors" in den Einstellungen Ihres Jenkins-Nodes entsprechend.
Benötige ich eine GUI-Sitzung für iOS-Simulatoren?
Nein. iOS-Simulatoren funktionieren im Headless-Modus über SSH. Wenn Sie jedoch eine GUI benötigen (z. B. für UI-Test-Screenshots), verwenden Sie VNC, um sich am Mac anzumelden, und stellen Sie sicher, dass eine GUI-Sitzung aktiv ist.
Wie handhabe ich die Code-Signierung auf einem Headless-Server?
Verwenden Sie Fastlane Match, um Zertifikate aus einem Git-Repo oder Cloud-Speicher zu synchronisieren. Alternativ importieren Sie Zertifikate in den macOS-Schlüsselbund und entsperren ihn in Ihrer Pipeline mit security unlock-keychain.

Bereit, Ihre Jenkins-Builds zu beschleunigen?

Holen Sie sich einen dedizierten Mac Mini M4 für Ihre Jenkins CI/CD-Pipeline. Ab 85 $/Monat.

Preise von My Remote Mac in USD, exkl. Steuern.

Mehr Details gesucht?

Durchsuchen Sie die vollständige Dokumentation für Schritt-für-Schritt-Anleitungen, Konfigurationsreferenzen und Fehlerbehebung.

Dokumentation öffnen →