Перейти к содержимому

Jenkins Mac Build Agent: полное руководство по настройке

Настройте Jenkins build agent на выделенном Mac Mini M4. Автоматизируйте сборки Xcode, запускайте тесты iOS и деплойте в TestFlight с полным контролем над инфраструктурой сборки.

CI/CD 35 мин чтения Обновлено в октябре 2026

Зачем нужен выделенный Mac для Jenkins?

Jenkins, это наиболее широко используемая платформа CI/CD, обслуживающая более 50% корпоративных пайплайнов сборки. Однако сборка iOS-приложений с Jenkins требует macOS, а macOS может легально работать только на оборудовании Apple. Выделенный Mac Mini M4 даёт вам:

  • Стабильная среда сборки

    Одинаковое оборудование, одна ОС, одни инструменты при каждой сборке. Никаких нестабильных сборок из-за различий в окружении.

  • Полный root-доступ

    Устанавливайте любые инструменты, настраивайте системные параметры, управляйте связками ключей для подписи кода.

  • Производительность Apple Silicon

    Чип M4 обеспечивает сборки в Xcode в 2-3 раза быстрее по сравнению с Intel Mac Mini.

  • Постоянные кэши

    DerivedData, CocoaPods и кэши SPM сохраняются между сборками.

Предварительные требования

  • Выделенный сервер сборки Mac mini M4 от My Remote Mac (от $85/мес., USD, без налогов)
  • Контроллер Jenkins (может быть на Linux, Docker или любой облачной ВМ)
  • SSH-доступ к вашему Mac Mini
  • Xcode, предустановленный на каждом сервере My Remote Mac (в нашем руководстве по GitHub Actions показано, как его проверить и добавить другие версии)

Шаг 1: Установка Java JDK на macOS

Jenkins agent требует Java Runtime Environment. Текущие версии Jenkins поддерживают Java 21 и Java 25 (Java 17 больше не поддерживается), поэтому мы устанавливаем JDK 21 (LTS) через Homebrew для удобного управления.

# 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

Шаг 2: Настройка Jenkins Agent

Существует два основных метода подключения Jenkins agent: входящий агент (агент подключается к контроллеру; раньше назывался JNLP) и SSH (контроллер подключается к агенту). Мы рассмотрим оба.

Метод A: SSH Agent (рекомендуется)

Это наиболее надёжный подход. Jenkins подключается к Mac через SSH и управляет процессом agent удалённо.

# 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

Теперь настройте agent в Jenkins:

  1. Перейдите в Manage Jenkins > Nodes > New Node
  2. Задайте имя mac-mini-m4
  3. Укажите Remote root directory: /Users/jenkins/workspace
  4. Labels: mac macos apple-silicon m4 ios
  5. Launch method: Launch agents via SSH
  6. Host: IP-адрес вашего Mac Mini
  7. Credentials: добавьте SSH-закрытый ключ, соответствующий authorized_keys на Mac
  8. Host Key Verification Strategy: Known hosts file Verification Strategy. Перед первым запуском один раз подключитесь с контроллера от имени пользователя, под которым работает Jenkins (ssh jenkins@YOUR_MAC_IP), чтобы добавить Mac в его ~/.ssh/known_hosts

Метод B: входящий агент (WebSocket)

Используйте этот метод, когда контроллер Jenkins не может подключиться к Mac напрямую (например, Mac находится за файрволом). Agent инициирует подключение. С параметром -webSocket он использует только веб-порт контроллера (HTTP или HTTPS), без отдельного TCP-порта для агентов.

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

Запуск входящего агента как службы launchd

Агент работает как LaunchAgent пользователя jenkins, поэтому запускается при входе этого пользователя в систему, а не при загрузке. На headless Mac включите автоматический вход для пользователя jenkins (Системные настройки > Пользователи и группы; недоступно, пока включён FileVault), чтобы агент снова был онлайн после перезагрузки. Эта открытая сессия также даёт симуляторам, UI-тестам и связке ключей входа нужное им пользовательское окружение.

# 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

Шаг 3: Создание пайплайна сборки iOS

Создайте файл Jenkinsfile в корне вашего репозитория. Этот декларативный пайплайн собирает, тестирует и при необходимости архивирует ваше 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'
        }
    }
}

Шаг 4: Интеграция Fastlane для деплоя

Fastlane упрощает подпись кода и деплой в TestFlight. Установите его на Mac один раз:

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

Добавьте этап деплоя в ваш 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
                '''
            }
        }

И создайте соответствующий 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

Лучшие практики безопасности

  • Используйте выделенного пользователя Jenkins

    Никогда не запускайте Jenkins agent от имени root. Создайте выделенного пользователя с минимальными правами.

  • Храните секреты в Jenkins Credentials

    Никогда не вставляйте сертификаты, API-ключи или пароли напрямую в Jenkinsfile. Используйте плагин Jenkins Credentials.

  • Включите только аутентификацию по SSH-ключам

    Отключите аутентификацию по паролю для SSH. Используйте ключи Ed25519 или RSA 4096 бит.

  • Используйте файрвол macOS

    Ограничьте входящие подключения только IP-адресом контроллера Jenkins. My Remote Mac предоставляет управляемый файрвол с доступом через API.

  • Обновляйте macOS и Xcode

    Своевременно устанавливайте патчи безопасности. Используйте softwareupdate -l для проверки обновлений.

FAQ

Можно ли запускать контроллер Jenkins на том же Mac?
Да, но мы рекомендуем разделять их. Запускайте контроллер на виртуальной машине Linux или в Docker-контейнере, а Mac используйте исключительно как build agent. Это позволит избежать конкуренции за ресурсы во время тяжёлых сборок.
Сколько параллельных сборок выдержит Mac Mini M4?
Mac Mini M4 с 16 ГБ RAM комфортно справляется с 2 параллельными сборками Xcode. С 24 ГБ можно увеличить до 3. M4 Pro с 48 ГБ легко выдерживает 4+ параллельных сборок. Настройте «Number of executors» в настройках узла Jenkins соответственно.
Нужна ли GUI-сессия для симуляторов iOS?
Нет. Симуляторы iOS работают в headless-режиме через SSH. Однако если вам нужен GUI (например, для скриншотов UI-тестов), подключитесь по VNC к Mac и убедитесь, что GUI-сессия активна.
Как управлять подписью кода на headless-сервере?
Используйте Fastlane Match для синхронизации сертификатов из Git-репозитория или облачного хранилища. Альтернативно, импортируйте сертификаты в связку ключей macOS и разблокируйте её в пайплайне с помощью security unlock-keychain.

Готовы ускорить ваши сборки Jenkins?

Получите выделенный Mac Mini M4 для вашего пайплайна Jenkins CI/CD. От $85/мес.

Цены My Remote Mac указаны в USD, без налогов.

Нужно больше деталей?

Полная документация: пошаговые инструкции по настройке, справочники по конфигурации и решение проблем.

Открыть документацию →