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

Как настроить self-hosted раннер CircleCI на Mac Mini M4

Полное пошаговое руководство по установке и настройке self-hosted machine раннера CircleCI на выделенном Mac mini M4. Нативная производительность Apple Silicon, постоянное кеширование и до 90% экономии по сравнению с облачными macOS ресурсами CircleCI.

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

Зачем использовать self-hosted раннер CircleCI на Mac?

CircleCI предлагает облачные среды выполнения macOS, но они имеют значительные затраты и ограничения. CircleCI тарифицирует задачи macOS в кредитах: класс ресурсов m4pro.medium расходует 200 кредитов в минуту (около $0.12), а m4pro.large 400 (около $0.24), на октябрь 2026 г. Для команд, часто выполняющих сборки iOS, это может быстро составить $300-$500 в месяц и более.

Self-hosted раннер на выделенном Mac Mini M4 от MyRemoteMac полностью устраняет поминутную оплату. Вы получаете выделенную машину Apple Silicon с постоянным хранилищем, тёплыми кешами и полным root-доступом за фиксированную месячную плату от $85/месяц. Вот детальное сравнение:

Зачем использовать self-hosted раннер CircleCI на Mac?
Self-hosted MyRemoteMac Облачный macOS CircleCI
Модель оплаты $85/мес фиксированно (неограниченные минуты) 200 кредитов/мин на m4pro.medium (~$0.12/мин)
Архитектура Физический Mac на Apple M4, выделенный 1:1 Виртуальная машина M4 Pro (6 vCPU, 28 ГБ)
Скорость сборки ~5 мин (тот же проект) ~14 мин (средний iOS-проект)
Сохранение кеша Постоянный на диске (мгновенно) Эфемерный (восстановление при каждой задаче)
Время ожидания в очереди 0 с (выделенное оборудование) 30 с, 5 мин (зависит от тарифа)
Конфиденциальность / Контроль данных Выделенная машина, полный контроль Общая инфраструктура
Пользовательское ПО Полный root-доступ, любое ПО Только предустановленный образ

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

Ключевое преимущество: При использовании постоянного self-hosted раннера DerivedData, кеши Swift Package Manager и CocoaPods сохраняются между сборками. Одно это может сократить время сборки на 50–70% по сравнению с эфемерными облачными macOS окружениями CircleCI, которые каждый раз начинают с нуля. В сочетании с превосходной однопоточной производительностью чипа M4 ваши сборки iOS будут значительно быстрее.

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

Прежде чем начать, убедитесь, что у вас есть следующее:

  • Выделенный сервер сборки Mac mini M4 от My Remote Mac (от $85/мес, USD, без налогов)
  • Организация в CircleCI, в которой вы администратор (self-hosted раннеры доступны на всех тарифах, включая Free, где на октябрь 2026 г. разрешено 5 одновременных self-hosted задач)
  • SSH-доступ к вашему Mac Mini (предоставляется с подпиской MyRemoteMac)
  • Аккаунт Apple Developer (для подписи кода и профилей обеспечения)
  • Базовое знакомство с YAML, конфигурацией CircleCI и командами терминала

Шаг 1: Проверка Xcode и установка зависимостей

Сначала подключитесь к Mac Mini M4 через SSH с учётными данными, полученными при настройке сервера MyRemoteMac. Xcode, его Command Line Tools и Homebrew уже установлены, поэтому перед настройкой раннера CircleCI остаётся добавить только инструменты сборки, нужные вашему iOS-конвейеру.

Подключение через SSH

# Connect to your Mac mini M4
ssh admin@your-server-ip

# Verify you're on Apple Silicon
uname -m
# Expected output: arm64

# Show the macOS version
sw_vers

Проверка Homebrew и Xcode Command Line Tools

# Homebrew comes preinstalled: put it on your PATH for your zsh sessions
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
brew --version

# Add Homebrew to PATH for CircleCI job steps
# (CircleCI runs macOS steps in a bash login shell)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bash_profile

# Xcode and its Command Line Tools come preinstalled
xcode-select -p
# /Applications/Xcode.app/Contents/Developer

# Accept the Xcode license if it asks
sudo xcodebuild -license accept

Проверка Xcode и добавление других версий

Для сборок iOS вам нужно полное приложение Xcode. С 28 апреля 2026 г. App Store Connect принимает только сборки, сделанные в Xcode 26 или новее, и предустановленный на вашем сервере Xcode этому требованию соответствует. Устанавливайте другую версию рядом с помощью xcodes, только если она нужна вашему проекту:

# Check the preinstalled Xcode
xcodebuild -version
# Xcode 27.2

# Optional: add other Xcode releases side by side with the xcodes CLI
brew install xcodes
xcodes list

# Install an older release next to the preinstalled one (asks for your Apple Account)
xcodes install 26.6

# Show the installed versions and their paths
xcodes installed
# e.g. /Applications/Xcode.app and /Applications/Xcode-26.6.0.app

# Set the default Xcode (sudo asks for your password)
# preinstalled Xcode; for another version, use the path from xcodes installed
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Установка iOS-симуляторов и инструментов сборки

# Install the current iOS simulator runtime
xcodebuild -downloadPlatform iOS

# Verify simulator availability
xcrun simctl list runtimes

# Install additional build tools
brew install xcbeautify fastlane swiftlint

Шаг 2: Установка агента раннера CircleCI

Machine runner 3 от CircleCI подключает ваш Mac mini к CircleCI: он получает задачи и выполняет их прямо на хосте macOS. На macOS CircleCI рекомендует устанавливать его через пакет Homebrew. Это отличается от container runner (который работает только на Linux).

Выбор пользователя, который выполняет задачи

Machine runner 3 выполняет каждую задачу от имени пользователя macOS, который его запустил, с его Homebrew, связкой ключей и Xcode. Устанавливайте и запускайте его от своего администратора, которому принадлежит Homebrew, а не от root: Homebrew отказывается работать от root.

# Run the steps below as the user that will run CI jobs, not with sudo
whoami

# Homebrew must work for this user (prints /opt/homebrew)
brew --prefix

Установка machine runner 3 через Homebrew

# Add CircleCI's Homebrew tap and install machine runner 3
brew tap circleci-public/circleci
brew install circleci-runner

# Check that macOS accepts the binary notarized by CircleCI
spctl -a -vvv -t install "$(brew --prefix)/bin/circleci-runner"
# Expected: accepted, source=Notarized Developer ID,
# origin=Developer ID Application: Circle Internet Services Inc.

# Remove the quarantine attribute (asks for your macOS password)
sudo xattr -r -d com.apple.quarantine "$(brew --prefix)/bin/circleci-runner"

Настройка агента раннера

Пакет Homebrew создаёт файл конфигурации. Вам понадобится токен аутентификации раннера из веб-приложения CircleCI (описано в Шаге 3). Пока задайте имя раннера и оставьте заглушку вместо токена:

# Open the configuration file created by the Homebrew package
nano "$HOME/Library/Preferences/com.circleci.runner/config.yaml"

# Contents (the token comes in Step 3):
runner:
  name: "mac-mini-m4-runner"
  working_directory: "/Users/$USER/Library/com.circleci.runner/workdir"
  cleanup_working_directory: true
api:
  auth_token: "YOUR_RUNNER_TOKEN_HERE"

# The file will hold a secret: make it readable by you only
chmod 600 "$HOME/Library/Preferences/com.circleci.runner/config.yaml"

Подготовка службы launchd для Mac без монитора

Пакет Homebrew также устанавливает агент launchd com.circleci.runner. Агент обычно запускается при входе вашего пользователя в систему; на Mac, к которому вы подключаетесь только по SSH, конфигурация CircleCI для headless-режима переносит его в /Library/LaunchAgents, чтобы он загружался после перезагрузки. Запустите его в Шаге 3, когда токен будет на месте:

# The launchd agent installed by the Homebrew package
ls ~/Library/LaunchAgents/com.circleci.runner.plist

# Headless Mac reached over SSH only: move it to the per-user agents
# folder so it loads after a reboot (CircleCI's headless setup)
sudo mv ~/Library/LaunchAgents/com.circleci.runner.plist /Library/LaunchAgents/

Важно: Раннер не подключится, пока в config.yaml нет действительного токена аутентификации. Сгенерируйте его в Шаге 3, добавьте в файл, затем запустите службу.

Шаг 3: Настройка раннера в панели управления CircleCI

Теперь вам нужно зарегистрировать раннер в веб-интерфейсе CircleCI и сгенерировать токен аутентификации. Это связывает ваш Mac Mini с вашей организацией CircleCI.

Создание класса ресурсов

В CircleCI self-hosted раннеры организованы по классам ресурсов. Класс ресурсов, это метка, которая связывает ваш .circleci/config.yml с определённым набором раннеров.

  1. В веб-приложении CircleCI откройте Runners на боковой панели (нужны права администратора организации)
  2. Нажмите "Create Resource Class"
  3. Задайте Namespace, имя вашей организации (например, your-org)
  4. Задайте имя Resource Class, описательное (например, mac-runner)
  5. Это создаст идентификатор класса ресурсов: your-org/mac-runner

Генерация токена аутентификации раннера

  1. Нажмите "Save and continue": CircleCI создаст класс ресурсов и покажет его токен аутентификации
  2. Сразу скопируйте токен и сохраните его в надёжном месте: он показывается только один раз
  3. Потеряли? Создайте новый через CircleCI CLI: circleci runner token create your-org/mac-runner mac-mini-m4

Добавление токена и запуск раннера

# SSH back into your Mac mini
ssh admin@your-server-ip

# Replace YOUR_RUNNER_TOKEN_HERE with the resource class token
nano "$HOME/Library/Preferences/com.circleci.runner/config.yaml"

# Start the service. Headless Mac (plist moved to /Library/LaunchAgents):
launchctl bootstrap user/$(id -u) /Library/LaunchAgents/com.circleci.runner.plist
launchctl enable user/$(id -u)/com.circleci.runner
launchctl kickstart -k user/$(id -u)/com.circleci.runner

# Or, from a desktop session (VNC), with the plist left in ~/Library/LaunchAgents:
# launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.circleci.runner.plist
# launchctl enable gui/$(id -u)/com.circleci.runner
# launchctl kickstart -k gui/$(id -u)/com.circleci.runner

# Verify the service, then read the runner log
launchctl print user/$(id -u)/com.circleci.runner
tail -20 "$HOME/Library/Logs/com.circleci.runner/runner.log"

После подключения раннер появляется в разделе Runners веб-приложения CircleCI, его также показывает circleci runner instance list your-org/mac-runner. Если он не появляется в течение 60 секунд, проверьте файл логов на наличие ошибок.

Использование CircleCI CLI (альтернативный способ)

Вы также можете управлять раннерами через CircleCI CLI:

# Install the CircleCI CLI
brew install circleci

# Authenticate with CircleCI
circleci setup

# Create the namespace (once per organization)
circleci namespace create your-org --org-id YOUR_ORGANIZATION_ID

# Create the resource class and print its token
circleci runner resource-class create your-org/mac-runner \
  "Mac mini M4 runner" --generate-token

# List the runners connected to this resource class
circleci runner instance list your-org/mac-runner

Шаг 4: Создание .circleci/config.yml для сборок iOS

Создайте файл .circleci/config.yml в корне вашего репозитория. Ключевое отличие от стандартной конфигурации CircleCI, использование machine: true с вашим пользовательским resource_class для направления задач на self-hosted раннер.

version: 2.1

jobs:
  build-and-test:
    machine: true
    resource_class: your-org/mac-runner

    environment:
      # Xcode for this job, without sudo
      # (preinstalled Xcode; for another version, use the path from `xcodes installed`)
      DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"
      SCHEME: "MyApp"
      # Any device listed by: xcrun simctl list devices available
      DESTINATION: "platform=iOS Simulator,name=iPhone 17,OS=latest"

    steps:
      - checkout

      - run:
          name: Show the Xcode version
          command: xcodebuild -version

      # Caches live in $HOME, outside the job's working directory,
      # so they survive cleanup_working_directory between jobs
      - run:
          name: Resolve Swift Package Dependencies
          command: |
            xcodebuild -resolvePackageDependencies \
              -scheme "$SCHEME" \
              -clonedSourcePackagesDirPath "$HOME/spm-cache"

      - run:
          name: Build the app
          command: |
            xcodebuild build \
              -scheme "$SCHEME" \
              -destination "generic/platform=iOS Simulator" \
              -clonedSourcePackagesDirPath "$HOME/spm-cache" \
              -derivedDataPath "$HOME/DerivedData/$SCHEME" \
              | xcbeautify

      # store_test_results needs JUnit XML: xcbeautify writes test-results/junit.xml
      - run:
          name: Run unit tests
          command: |
            xcodebuild test \
              -scheme "$SCHEME" \
              -destination "$DESTINATION" \
              -clonedSourcePackagesDirPath "$HOME/spm-cache" \
              -derivedDataPath "$HOME/DerivedData/$SCHEME" \
              -resultBundlePath TestResults.xcresult \
              | xcbeautify --report junit --report-path test-results

      - store_test_results:
          path: test-results

      - store_artifacts:
          path: TestResults.xcresult
          destination: test-results

workflows:
  ios-pipeline:
    jobs:
      - build-and-test:
          filters:
            branches:
              only:
                - main
                - develop

Примечание: Значение resource_class: your-org/mac-runner должно точно совпадать с классом ресурсов, который вы создали в панели управления CircleCI. Если значение не совпадает, задачи будут оставаться в очереди бесконечно.

Шаг 5: Оптимизация с помощью кеширования и параллелизма

Одно из главных преимуществ self-hosted раннера, постоянное кеширование. Поскольку файловая система раннера постоянна, вам не нужно загружать и скачивать кеши, как при использовании облачных ресурсов CircleCI. Однако есть дополнительные оптимизации для максимальной скорости сборки.

Использование постоянного DerivedData

Поскольку диск раннера сохраняется между сборками, DerivedData уже кешируется автоматически. Используйте постоянный путь:

# In your config.yml steps, always use a consistent DerivedData path:
- run:
    name: Build with persistent cache
    command: |
      xcodebuild build \
        -scheme "$SCHEME" \
        -destination "$DESTINATION" \
        -derivedDataPath ~/DerivedData/"$SCHEME" \
        -clonedSourcePackagesDirPath ~/spm-cache \
        | xcbeautify

# Periodically clean old DerivedData on the runner (cron job):
# 0 3 * * 0 find ~/DerivedData -mindepth 1 -maxdepth 1 -mtime +7 -exec rm -rf {} +

Сохранение рабочего пространства между задачами

Используйте рабочие пространства CircleCI, чтобы передать собранные продукты задаче тестирования, которая может выполняться на другом Mac того же класса ресурсов:

jobs:
  build:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Build for testing
          command: |
            xcodebuild build-for-testing \
              -scheme "MyApp" \
              -destination "generic/platform=iOS Simulator" \
              -derivedDataPath DerivedData \
              | xcbeautify
      # Pass only the built products, not the whole DerivedData
      - persist_to_workspace:
          root: .
          paths:
            - DerivedData/Build/Products

  test:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Run the tests built by the previous job
          command: |
            xcodebuild test-without-building \
              -xctestrun "$(ls DerivedData/Build/Products/*.xctestrun | head -n 1)" \
              -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
              | xcbeautify --report junit --report-path test-results
      - store_test_results:
          path: test-results

workflows:
  build-test:
    jobs:
      - build
      - test:
          requires:
            - build

Параллельное выполнение тестов

- run:
    name: Run tests in parallel
    command: |
      # Xcode clones the simulator and runs test classes on up to 4 clones
      xcodebuild test \
        -scheme "MyApp" \
        -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
        -parallel-testing-enabled YES \
        -maximum-parallel-testing-workers 4 \
        -derivedDataPath ~/DerivedData/MyApp \
        | xcbeautify

Разделение тестов CircleCI

Для больших наборов тестов разделение тестов CircleCI распределяет тестовые классы между параллельными задачами. Каждой задаче нужен собственный раннер, поэтому parallelism: 3 требует трёх Mac в классе ресурсов; на одном Mac задачи выполняются по очереди:

jobs:
  test:
    machine: true
    resource_class: your-org/mac-runner
    # One task per runner: 3 tasks need 3 Macs in this resource class
    parallelism: 3
    steps:
      - checkout
      - run:
          name: Split test classes and run this task's share
          command: |
            # One XCTest class per file, named like the file (LoginTests.swift)
            CLASSES=$(circleci tests glob "MyAppTests/**/*Tests.swift" \
              | xargs -n1 basename | sed 's/\.swift$//' \
              | circleci tests split)

            # -only-testing takes Target/Class identifiers, not file paths
            ONLY_TESTING=""
            for CLASS in $CLASSES; do
              ONLY_TESTING="$ONLY_TESTING -only-testing:MyAppTests/$CLASS"
            done

            xcodebuild test \
              -scheme "MyApp" \
              -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
              $ONLY_TESTING \
              | xcbeautify --report junit --report-path test-results
      - store_test_results:
          path: test-results

Примеры рабочих процессов

Вот полные, готовые к продакшену примеры рабочих процессов для типичных сценариев iOS CI/CD.

Полный пайплайн сборки, тестирования и деплоя iOS

version: 2.1

jobs:
  lint:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Run SwiftLint
          command: swiftlint lint --reporter json > swiftlint-results.json || true
      - store_artifacts:
          path: swiftlint-results.json

  build-and-test:
    machine: true
    resource_class: your-org/mac-runner
    environment:
      # Xcode for this job, without sudo
      # (preinstalled Xcode; for another version, use the path from `xcodes installed`)
      DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"
    steps:
      - checkout
      - run:
          name: Resolve dependencies
          command: |
            xcodebuild -resolvePackageDependencies \
              -scheme "MyApp" \
              -clonedSourcePackagesDirPath ~/spm-cache
      - run:
          name: Build and test
          command: |
            xcodebuild test \
              -scheme "MyApp" \
              -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
              -clonedSourcePackagesDirPath ~/spm-cache \
              -derivedDataPath ~/DerivedData/MyApp \
              -resultBundlePath TestResults.xcresult \
              -parallel-testing-enabled YES \
              | xcbeautify --report junit --report-path test-results
      - store_test_results:
          path: test-results
      - store_artifacts:
          path: TestResults.xcresult

  deploy-testflight:
    machine: true
    resource_class: your-org/mac-runner
    environment:
      DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: bundle install
      # MATCH_PASSWORD and the App Store Connect API key variables
      # (ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_CONTENT) come from a CircleCI
      # context or the project's environment variables
      - run:
          name: Build and upload to TestFlight
          command: bundle exec fastlane beta

workflows:
  ios-pipeline:
    jobs:
      - lint
      - build-and-test:
          requires:
            - lint
      - deploy-testflight:
          requires:
            - build-and-test
          filters:
            branches:
              only: main

Пример интеграции с Fastlane

Если вы используете Fastlane для автоматизации сборки, вот как интегрировать его с self-hosted раннером CircleCI:

# Fastfile (fastlane/Fastfile)
default_platform(:ios)

platform :ios do
  desc "Run tests"
  lane :test do
    scan(
      scheme: "MyApp",
      device: "iPhone 17",
      derived_data_path: File.expand_path("~/DerivedData/MyApp"),
      result_bundle: true,
      output_directory: "./test_output",
      # store_test_results reads JUnit XML
      output_types: "junit",
      output_files: "junit.xml"
    )
  end

  desc "Build and push to TestFlight"
  lane :beta do
    # App Store Connect API key: no Apple ID password or 2FA on the runner
    app_store_connect_api_key(
      key_id: ENV["ASC_KEY_ID"],
      issuer_id: ENV["ASC_ISSUER_ID"],
      key_content: ENV["ASC_KEY_CONTENT"]
    )
    match(type: "appstore", readonly: true)
    increment_build_number(
      build_number: ENV["CIRCLE_BUILD_NUM"]
    )
    gym(
      scheme: "MyApp",
      export_method: "app-store",
      derived_data_path: File.expand_path("~/DerivedData/MyApp")
    )
    pilot(skip_waiting_for_build_processing: true)
  end
end
# .circleci/config.yml using Fastlane
version: 2.1

jobs:
  fastlane-test:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: bundle install
      - run:
          name: Run Fastlane tests
          command: bundle exec fastlane test
      - store_test_results:
          path: ./test_output
      - store_artifacts:
          path: ./test_output

  fastlane-deploy:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: bundle install
      - run:
          name: Deploy to TestFlight
          command: bundle exec fastlane beta

workflows:
  ios-workflow:
    jobs:
      - fastlane-test
      - fastlane-deploy:
          requires:
            - fastlane-test
          filters:
            branches:
              only: main

Сравнение производительности

Вот детальное сравнение производительности и стоимости между облачными macOS ресурсами CircleCI и self-hosted Mac Mini M4 от MyRemoteMac:

Бенчмарки времени сборки

Бенчмарки времени сборки
Self-hosted Mac Mini M4 Облачный macOS CircleCI Улучшение
Чистая сборка (средний проект) 5 мин 14 мин В 2.8 раза быстрее
Инкрементальная сборка 1.5 мин 14 мин (без кеша) В 9.3 раза быстрее
Разрешение зависимостей SPM 5 сек (кеш на диске) 3–5 мин (загрузка каждый раз) ~В 60 раз быстрее
Набор unit-тестов (500 тестов) 2.5 мин 8 мин В 3.2 раза быстрее
Время ожидания в очереди 0 сек 30 с, 5 мин Мгновенно

Анализ месячных расходов

Анализ месячных расходов
Размер команды Стоимость MyRemoteMac Сборок/месяц Стоимость облака CircleCI Ежемесячная экономия
Один разработчик $85/мес 100 сборок (в среднем 10 мин) $120/мес $35/мес
Малая команда (5) $85/мес 500 сборок (в среднем 10 мин) $600/мес $515/мес
Средняя команда (15) $229/мес (M4 Pro) 1500 сборок (в среднем 10 мин) $1,800/мес $1,571/мес
Корпоративная (50+) $458/мес (2x M4 Pro) 5000+ сборок $6,000+/мес $5,542+/мес

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

Итог: По тарифу CircleCI для класса m4pro.medium (200 кредитов, около $0.12 в минуту, на октябрь 2026 г.) 10-минутная сборка стоит около $1.20, поэтому выделенный Mac mini M4 за $85/мес (USD, без налогов) обходится дешевле уже примерно с 71 сборки в месяц. Тёплые кеши постоянного Mac к тому же сокращают время, которое команда ждёт каждую сборку.

Устранение типичных проблем

Раннер отключается или отображается как "Offline"

Раннер может потерять соединение после сетевого сбоя, аварийного завершения или перезагрузки. Запущенный в домене gui, он возвращается только после входа своего пользователя в систему; конфигурация headless из Шага 2 этого избегает. Проверьте службу и её журнал:

# Check the service (use gui/ instead of user/ if you started it
# from a desktop session)
launchctl print user/$(id -u)/com.circleci.runner

# View the runner log
tail -50 "$HOME/Library/Logs/com.circleci.runner/runner.log"

# Restart the service
launchctl kickstart -k user/$(id -u)/com.circleci.runner

# If the token was revoked, create a new one, put it in
# ~/Library/Preferences/com.circleci.runner/config.yaml and restart
circleci runner token create your-org/mac-runner mac-mini-m4

resource_class не найден или задачи зависают в очереди

Если задачи остаются в очереди с сообщением "No matching runner found", класс ресурсов в вашей конфигурации не совпадает с панелью управления:

# Verify the exact resource class name in the CircleCI web app:
# Runners (sidebar) lists your resource classes

# The resource_class in .circleci/config.yml must match exactly:
# resource_class: your-org/mac-runner  (case-sensitive!)

# Check your runner is online:
circleci runner instance list your-org/mac-runner

# Common mistakes:
# - Wrong namespace (org name vs personal namespace)
# - Typo in resource class name
# - Runner is offline or token is invalid
# - Using 'docker' executor instead of 'machine: true'

Ошибки подписи кода Xcode

Подпись кода на CI-машине требует тщательного управления Keychain. Процесс раннера может не иметь доступа к login keychain:

# Option 1: Use Fastlane Match (recommended)
# In your Fastfile:
match(type: "appstore", readonly: true)

# Option 2: Manual keychain management in your job steps
- run:
    name: Setup code signing
    command: |
      # Decode and import the certificate
      echo "$BUILD_CERTIFICATE_BASE64" | base64 --decode > /tmp/cert.p12

      # Create a temporary keychain
      security create-keychain -p "ci" /tmp/ci.keychain
      security set-keychain-settings -lut 21600 /tmp/ci.keychain
      security unlock-keychain -p "ci" /tmp/ci.keychain

      # Import the certificate
      security import /tmp/cert.p12 -P "$P12_PASSWORD" \
        -A -t cert -f pkcs12 -k /tmp/ci.keychain
      # Let codesign use the key without a GUI prompt
      security set-key-partition-list -S apple-tool:,apple:,codesign: \
        -s -k "ci" /tmp/ci.keychain
      security list-keychain -d user -s /tmp/ci.keychain

      # Install the provisioning profile (Xcode 16 and later location)
      PROFILES=~/Library/Developer/Xcode/UserData/Provisioning\ Profiles
      mkdir -p "$PROFILES"
      echo "$PROVISIONING_PROFILE_BASE64" | base64 --decode \
        > "$PROFILES/profile.mobileprovision"

Симулятор не запускается или превышает время ожидания

Симуляторы могут перейти в нерабочее состояние на долго работающих CI-машинах. Сбрасывайте их между сборками:

# Add a pre-build step to clean simulators
- run:
    name: Reset simulators
    command: |
      xcrun simctl shutdown all 2>/dev/null || true
      xcrun simctl erase all 2>/dev/null || true

# If a specific runtime is missing, reinstall it:
xcodebuild -downloadPlatform iOS

# List available simulators
xcrun simctl list devices available

Заканчивается дисковое пространство

Сборки Xcode генерируют значительные объёмы данных. Настройте автоматическую очистку на вашем раннере:

# Check available disk space
df -h /

# Clean DerivedData folders unused for a week
find ~/DerivedData ~/Library/Developer/Xcode/DerivedData \
  -mindepth 1 -maxdepth 1 -mtime +7 -exec rm -rf {} +

# Delete simulators the current Xcode no longer supports
xcrun simctl delete unavailable

# List simulator runtimes, then delete the ones you no longer test on
xcrun simctl runtime list
# xcrun simctl runtime delete <runtime-identifier>

# Clean Homebrew cache
brew cleanup --prune=7

# Set up a weekly cron job for automatic cleanup
(crontab -l 2>/dev/null; echo "0 4 * * 0 find ~/DerivedData -mindepth 1 -maxdepth 1 -mtime +7 -exec rm -rf {} + ; /opt/homebrew/bin/brew cleanup --prune=7") | crontab -

Часто задаваемые вопросы

Сколько стоит self-hosted раннер CircleCI на Mac Mini M4?
Выделенный Mac mini M4 от My Remote Mac стоит от $85/мес (USD, без налогов) с неограниченным временем сборки, а CircleCI не берёт поминутную плату за сборки на self-hosted раннерах. Облачные macOS-задачи CircleCI стоят около $0.12 в минуту на классе m4pro.medium (200 кредитов по $0.0006, на октябрь 2026 г.), то есть примерно $300-500 в месяц для активных команд. С собственным раннером расходы остаются предсказуемыми при любом объёме сборок.
Можно ли использовать self-hosted раннер CircleCI для сборок iOS и macOS?
Да. Self-hosted раннер на Mac Mini M4 может выполнять любые задачи macOS, включая сборку iOS, сборку приложений macOS, тестирование Swift-пакетов, UI-тесты Xcode и автоматизацию с Fastlane. Поскольку он работает нативно на Apple Silicon, сборки быстрее, чем на эмулированных или Intel-раннерах в облаке.
В чём разница между machine runner и container runner в CircleCI?
CircleCI machine runner выполняет задачи непосредственно в операционной системе хост-машины, что необходимо для сборок macOS/iOS, требующих Xcode, симуляторов и фреймворков Apple. Container runner выполняет задачи внутри контейнеров Docker и доступен только на Linux. Для сборок Mac необходимо использовать machine runner.
Как обновлять self-hosted раннер CircleCI?
Machine runner 3 не обновляется сам: с пакетом Homebrew вы сами решаете, когда обновиться, выполнив brew upgrade circleci-runner, а затем перезапускаете службу. Проверяйте changelog раннера ежемесячно и поддерживайте Xcode и macOS в актуальном состоянии.
Быстрее ли self-hosted раннер, чем облачный macOS CircleCI?
Да, обычно в 2-3 раза быстрее для чистых сборок и до 9 раз быстрее для инкрементальных сборок. CircleCI выполняет каждую облачную macOS-задачу в новой виртуальной машине M4 Pro, поэтому DerivedData и кеши пакетов приходится восстанавливать каждый раз. Self-hosted Mac mini M4 представляет собой физическую машину, выделенную только вам, с постоянными кешами DerivedData и SPM и без ожидания запуска облачной машины.
Можно ли запускать несколько задач CircleCI одновременно на одном Mac Mini?
Не с одним раннером. CircleCI поддерживает один machine runner на машину, и каждый раннер берёт одну задачу за раз, поэтому задачи, отправленные в один класс ресурсов, ждут, пока Mac освободится. Чтобы выполнять задачи параллельно, добавьте по одному Mac на каждую дополнительную одновременную задачу и зарегистрируйте его в том же классе ресурсов: CircleCI отправит каждую задачу из очереди свободному раннеру в пределах лимита одновременных self-hosted задач вашего тарифа (5 на Free, 20 на Performance, на октябрь 2026 г.). Внутри одной задачи Xcode по-прежнему может запускать тесты параллельно на нескольких симуляторах. Для более тяжёлых задач Mac mini M4 Pro (12-ядерный CPU, 24 ГБ, от $229/мес, USD, без налогов) даёт больший запас.

Начните с Mac Mini M4 для ваших пайплайнов CircleCI

Разверните выделенный Mac Mini M4 как self-hosted раннер CircleCI. Неограниченные минуты сборки от $85/месяц.

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

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

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

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