Aller au contenu

Agent de build Jenkins Mac : guide complet de configuration

Configurez un agent de build Jenkins sur un Mac Mini M4 dédié. Automatisez les builds Xcode, exécutez des tests iOS et déployez sur TestFlight avec un contrôle total sur votre infrastructure de build.

CI/CD 35 min de lecture Mis à jour en octobre 2026

Pourquoi un Mac dédié pour Jenkins ?

Jenkins est la plateforme CI/CD la plus utilisée, exécutant plus de 50 % des pipelines de build en entreprise. Cependant, compiler des applications iOS avec Jenkins nécessite macOS, et macOS ne peut légalement fonctionner que sur du matériel Apple. Un Mac Mini M4 dédié vous offre :

  • Environnement de build cohérent

    Le même matériel, le même OS, les mêmes outils à chaque build. Plus de builds instables dus à la dérive d'environnement.

  • Accès root complet

    Installez n'importe quel outil, configurez les paramètres système, gérez les trousseaux pour la signature de code.

  • Performances Apple Silicon

    La puce M4 offre des builds Xcode 2 à 3 fois plus rapides par rapport aux Mac Mini Intel.

  • Caches persistants

    DerivedData, CocoaPods et les caches SPM survivent entre les builds.

Prérequis

  • Un serveur de build Mac mini M4 dédié chez My Remote Mac (à partir de 85 $/mois, USD, hors taxes)
  • Un contrôleur Jenkins (peut être sur Linux, Docker ou n'importe quelle VM cloud)
  • Un accès SSH à votre Mac Mini
  • Xcode, préinstallé sur chaque serveur My Remote Mac (notre guide GitHub Actions montre comment le vérifier et ajouter d'autres versions)

Étape 1 : Installer le JDK Java sur macOS

Les agents Jenkins nécessitent un environnement d'exécution Java. Les versions actuelles de Jenkins prennent en charge Java 21 et Java 25 (Java 17 n'est plus pris en charge) : nous installons donc le JDK 21 (LTS) via Homebrew pour une gestion facile.

# 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

Étape 2 : Configurer l'agent Jenkins

Il existe deux méthodes principales pour connecter un agent Jenkins : un agent entrant (l'agent se connecte au contrôleur ; anciennement appelé JNLP) et SSH (le contrôleur se connecte à l'agent). Nous couvrons les deux.

Méthode A : Agent SSH (recommandé)

C'est l'approche la plus fiable. Jenkins se connecte au Mac via SSH et gère le processus de l'agent à distance.

# 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

Configurez maintenant l'agent dans Jenkins :

  1. Allez dans Manage Jenkins > Nodes > New Node
  2. Définissez le nom sur mac-mini-m4
  3. Définissez le répertoire racine distant sur /Users/jenkins/workspace
  4. Labels : mac macos apple-silicon m4 ios
  5. Méthode de lancement : Launch agents via SSH
  6. Hôte : l'adresse IP de votre Mac Mini
  7. Identifiants : ajoutez la clé privée SSH correspondant aux authorized_keys du Mac
  8. Host Key Verification Strategy : Known hosts file Verification Strategy. Avant le premier lancement, connectez-vous une fois depuis le contrôleur avec l'utilisateur qui exécute Jenkins (ssh jenkins@YOUR_MAC_IP) pour ajouter le Mac à son ~/.ssh/known_hosts

Méthode B : Agent entrant (WebSocket)

Utilisez cette méthode lorsque le contrôleur Jenkins ne peut pas atteindre directement le Mac (par ex., le Mac est derrière un pare-feu). L'agent initie la connexion. Avec l'option -webSocket, il n'utilise que le port web du contrôleur (HTTP ou HTTPS), sans port TCP d'agent séparé.

# 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"

Exécuter l'agent entrant en tant que service launchd

L'agent tourne comme LaunchAgent de l'utilisateur jenkins : il démarre à l'ouverture de la session de cet utilisateur, pas au démarrage du Mac. Sur un Mac sans écran, activez l'ouverture de session automatique pour l'utilisateur jenkins (Réglages Système > Utilisateurs et groupes ; indisponible tant que FileVault est activé) afin que l'agent revienne en ligne après un redémarrage. Cette session ouverte donne aussi aux simulateurs, aux tests UI et au trousseau de session l'environnement utilisateur dont ils ont besoin.

# 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

Étape 3 : Créer un pipeline de build iOS

Créez un Jenkinsfile à la racine de votre dépôt. Ce pipeline déclaratif compile, teste et archive optionnellement votre application iOS.

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

Étape 4 : Intégrer Fastlane pour le déploiement

Fastlane simplifie la signature de code et le déploiement TestFlight. Installez-le une fois sur le Mac :

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

Ajoutez une étape de déploiement à votre 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
                '''
            }
        }

Et créez un fastlane/Fastfile correspondant :

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

Bonnes pratiques de sécurité

  • Utiliser un utilisateur Jenkins dédié

    N'exécutez jamais l'agent Jenkins en tant que root. Créez un utilisateur dédié avec des permissions minimales.

  • Stocker les secrets dans les identifiants Jenkins

    Ne codez jamais en dur les certificats, clés API ou mots de passe dans les Jenkinsfiles. Utilisez le plugin Jenkins Credentials.

  • Activer uniquement l'authentification par clé SSH

    Désactivez l'authentification par mot de passe pour SSH. Utilisez des clés Ed25519 ou RSA 4096 bits.

  • Utiliser le pare-feu macOS

    Restreignez les connexions entrantes à l'IP du contrôleur Jenkins uniquement. My Remote Mac fournit un pare-feu géré avec accès API.

  • Maintenir macOS et Xcode à jour

    Appliquez les correctifs de sécurité rapidement. Utilisez softwareupdate -l pour vérifier les mises à jour.

FAQ

Puis-je exécuter le contrôleur Jenkins sur le même Mac ?
Oui, mais nous recommandons de les séparer. Exécutez le contrôleur sur une VM Linux ou un conteneur Docker, et utilisez le Mac exclusivement comme agent de build. Cela évite la contention des ressources pendant les builds lourds.
Combien de builds simultanés un Mac Mini M4 peut-il gérer ?
Un Mac Mini M4 avec 16 Go de RAM peut gérer confortablement 2 builds Xcode simultanés. Avec 24 Go, vous pouvez aller jusqu'à 3. Le M4 Pro avec 48 Go gère facilement 4+ builds simultanés. Configurez le "Number of executors" dans les paramètres de votre nœud Jenkins en conséquence.
Ai-je besoin d'une session graphique pour les simulateurs iOS ?
Non. Les simulateurs iOS fonctionnent en mode headless via SSH. Cependant, si vous avez besoin d'un affichage graphique (par ex., pour les captures d'écran de tests UI), utilisez VNC pour vous connecter au Mac et assurez-vous qu'une session GUI est active.
Comment gérer la signature de code sur un serveur sans écran ?
Utilisez Fastlane Match pour synchroniser les certificats depuis un dépôt Git ou un stockage cloud. Alternativement, importez les certificats dans le trousseau macOS et déverrouillez-le dans votre pipeline en utilisant security unlock-keychain.

Prêt à booster vos builds Jenkins ?

Obtenez un Mac Mini M4 dédié pour votre pipeline CI/CD Jenkins. À partir de 85 $/mois.

Prix My Remote Mac en USD, hors taxes.

Besoin de plus de détails ?

Parcourez la documentation complète : guides pas à pas, références de configuration et dépannage.

Ouvrir la documentation →