Разворачивайте CircleCI Machine Runner 3 на удалённом Mac только тогда, когда вам нужен фиксированный Xcode, доступ к внутренним зависимостям или контроль ключей подписи; обычные стандартизированные задачи оставляйте на управляемом исполнителе. До выхода в production проверьте не только статус «online», но и маршрутизацию задания, сборку Xcode, восстановление после перезагрузки и очистку рабочей директории.

Эта инструкция предназначена для вас, если вы:

  • поддерживаете CircleCI-пайплайны для iOS или macOS и зависите от конкретной среды Xcode;
  • подключаете к CI подпись, приватный репозиторий или сервис во внутренней сети;
  • отвечаете за права, обновления и восстановление удалённого Mac-узла.

Последнее обновление: 29 августа 2026 года. Статус поддержки, способ установки, конфигурационные поля и требования к macOS необходимо повторно сверить с официальной инструкцией CircleCI для установки Machine Runner 3 на macOS перед каждым новым развёртыванием.

01

Нулевая точка: выбор задач

Граница между управляемым и собственным исполнителем

CircleCI Machine Runner 3 нужен не для того, чтобы заменить все задания одним удалённым компьютером. Его смысл — дать конкретному заданию доступ к заранее подготовленному хосту. В модели Runner задача использует среду узла напрямую, поэтому установленные инструменты, права пользователя, кэш и состояние macOS становятся частью результата сборки. Это описано в обзоре модели CircleCI Runner.

Переносите задачу на удалённый Mac, если выполняется хотя бы одно условие:

  • проект собирается только с нужной версией Xcode или macOS;
  • требуется Apple SDK, симулятор или инструмент, которого нет в стандартной среде;
  • сборка обращается к приватным пакетам через внутреннюю сеть;
  • подпись должна выполняться в изолированной среде;
  • вам нужно контролировать длительное состояние узла и его обновления.

Оставляйте задачу на управляемом исполнителе, если она состоит из переносимых проверок: линтинг, статический анализ, обработка текстовых файлов или тесты, не зависящие от macOS. Так вы не добавите себе обслуживание отдельного компьютера без технической причины.

Условия выбора

Используйте следующий раздел как развилку перед созданием узла:

  • Если задача требует фиксированного Xcode, приватной сети или локальных ключей подписи, выбирайте CircleCI self-hosted runner на отдельном удалённом Mac.
  • Если задача не зависит от macOS и не требует особых прав, оставляйте её на управляемом исполнителе.
  • Если только часть пайплайна требует Apple-инструментов, выбирайте двухконтурную схему: общие проверки выполняются отдельно, а сборка и подпись направляются на Mac.
  • Если один и тот же узел должен одновременно обслуживать тестовый и релизный контуры, сначала разделите учётные записи, resource class или сами машины. Не рассчитывайте только на название задания.
  • Если вам нужен физический интерфейс, локальное устройство или постоянная аппаратная отладка, не выбирайте удалённый узел как единственную среду. Проверьте, какие операции действительно доступны через удалённый доступ.
02

Час до установки: учётная запись и границы

Отдельный пользователь

Не регистрируйте Runner под личной административной учётной записью. Создайте отдельного локального пользователя, например <ci-user>, без доступа к чужим домашним каталогам и без повседневных прав администратора. Имя здесь условное: замените его на внутреннее обозначение, не копируя его в публичный репозиторий.

Подготовьте отдельные каталоги:

/Users/<ci-user>/ci-runner
/Users/<ci-user>/ci-work
/Users/<ci-user>/ci-cache
/Users/<ci-user>/ci-logs

Разделение нужно не ради красоты. Рабочее дерево может содержать исходники и промежуточные файлы. Кэш способен сохранить зависимости или артефакты предыдущей задачи. Логи могут раскрыть параметры запуска. Каталог с ключами подписи не должен быть частью общего рабочего пространства.

Проверьте фактического пользователя и права до установки:

whoami
id
pwd
ls -ld /Users/<ci-user>/ci-runner
ls -ld /Users/<ci-user>/ci-work

Если whoami возвращает администратора или другой аккаунт, остановите установку. Исправьте владельца каталогов и только после этого продолжайте. Команды изменения владельца и удаления файлов не вставляйте в автоматический сценарий без отдельного окна восстановления: ошибка в пути может затронуть данные за пределами Runner.

Namespace и resource class

Сначала создайте в CircleCI namespace и resource class по актуальной процедуре. В конфигурации задания указывается адресация вида:

resource_class: <namespace>/<resource-class>

<namespace> и <resource-class> — заполнители. Реальные значения должны соответствовать созданным объектам в вашей организации. В документации по resource class объясняется, как этот идентификатор связывает задание с нужным типом исполнителя.

Подготовьте отдельный токен resource class. Не добавляйте его в .circleci/config.yml, коммиты, сообщения об ошибках или команды, которые печатают окружение. Храните значение в защищённом хранилище CircleCI или в другом утверждённом секретном хранилище команды. Зафиксируйте владельца токена, дату последней ротации и процедуру отзыва.

Обязательная проверка перед продолжением:

  • namespace существует и принадлежит правильной организации;
  • resource class не указывает на тестовый контур;
  • токен можно отозвать без потери доступа к другим системам;
  • имя узла не содержит секретов, номеров заявок или персональных данных;
  • журнал запуска не выводит токен через диагностику окружения.
03

Первый час: установка Machine Runner 3

Официальная процедура

Для Apple Silicon Mac используйте именно текущую macOS-процедуру CircleCI. Официальные материалы подтверждают установку Machine Runner 3 по macOS-инструкции; конкретные требования к поддерживаемым версиям и способу загрузки нужно сверять в день установки, а не переносить из старого скрипта.

Не подставляйте в статью или репозиторий настоящий токен. Рабочая схема должна выглядеть как набор заполнителей:

runner_name: <runner-name>
work_directory: /Users/<ci-user>/ci-work
resource_class: <namespace>/<resource-class>
token: <resource-class-token>

Точные имена полей, формат конфигурационного файла и расположение каталога берите из справочника конфигурации Machine Runner 3. Если CircleCI изменил структуру файла или процедуру регистрации, старый конфиг не следует считать совместимым автоматически.

Проверка macOS-безопасности

Загруженный исполняемый файл может быть остановлен проверкой подписи, нотарификации или карантинного атрибута macOS. Не отключайте системную защиту глобально и не добавляйте широкое исключение «на всякий случай». Сначала определите, какое именно предупреждение появилось, и применяйте только шаги из официальной инструкции CircleCI.

После установки проверьте:

command -v <runner-binary>
<runner-binary> --help

Если документация для текущего выпуска предусматривает другой путь к программе, используйте его. Эти команды — диагностический шаблон, а не замена официальной команде установки.

Затем запустите Runner способом, предусмотренным документацией, и проверьте три независимых источника:

  • процесс на самом Mac;
  • запись узла в inventory CircleCI;
  • локальный журнал запуска.

Статус «online» в веб-консоли доказывает только связь с платформой. Он не доказывает, что узел может принять задание, открыть рабочий каталог или вызвать Xcode от имени нужного пользователя.

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

04

Первый pipeline: проверка маршрута и Xcode

Минимальная тестовая задача

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

jobs:
  verify-mac-runner:
    machine: true
    resource_class: <namespace>/<resource-class>
    steps:
      - checkout
      - run:
          name: Проверка узла
          command: |
            whoami
            sw_vers
            xcode-select -p
            xcodebuild -version
      - run:
          name: Проверка рабочей директории
          command: |
            pwd
            ls -la

Этот фрагмент показывает принцип, а не гарантирует точную структуру вашего конфигурационного файла. Сверьте синтаксис executor и steps с текущей документацией CircleCI перед коммитом.

Для Apple-инструментов отдельно проверьте Command Line Tools. Документация Apple по установке Command Line Tools описывает их назначение, а инструкция по выбору активных инструментов командной строки показывает, как проверить выбранный путь. Команда xcode-select -p должна возвращать ожидаемый каталог, а xcodebuild -version — запускаться без интерактивного диалога.

Может ли Machine Runner 3 работать на Mac с Apple Silicon?
Ориентируйтесь на актуальную официальную macOS-инструкцию CircleCI и требования конкретного выпуска. Сам факт запуска Mac на Apple Silicon не заменяет проверку архитектуры зависимостей, скриптов и плагинов проекта. Непереносимый бинарный инструмент может сломаться уже после успешной регистрации Runner.

Что считать доказательством маршрутизации

В результате задания сохраните:

  • имя resource class;
  • имя фактического узла;
  • имя пользователя, от которого выполнена команда;
  • путь активных Command Line Tools;
  • версию Xcode, если проект её выводит;
  • код завершения;
  • лог и тестовый результат.

Задание должно попасть именно на нужный удалённый Mac. Если оно выполняется в другом окружении, проверяйте namespace, resource class, доступность узла и совпадение организации. Официальная модель self-hosted Runner помогает отделить проблему маршрутизации от ошибки локального инструмента.

05

Перед выпуском: сборка и подпись

Разделение контуров

Не объединяйте обычную сборку, тесты и публикацию в одну непрозрачную задачу. Для минимизации доступа сделайте отдельные этапы:

  • сборка и тесты без сертификатов;
  • подготовка артефактов;
  • подпись и публикация в отдельном задании;
  • очистка рабочей области после завершения.

Для подписи используйте отдельный resource class или отдельный Mac, если риск и требования проекта это оправдывают. На тестовом узле не храните релизные ключи. На релизном узле не разрешайте произвольным веткам запускать публикацию.

Изоляция Keychain и файлов

Учетная запись <ci-user> должна иметь только те права, которые нужны для операции. Не записывайте реальные названия сертификатов, идентификаторы команды, пароли Keychain и токены в конфигурацию или примеры.

Проверьте:

security list-keychains
security find-identity -v -p codesigning

Вывод этих команд очищайте от чувствительных данных перед публикацией. Если ключ подписи не находится в неинтерактивном режиме, не отключайте защиту Keychain вслепую. Сначала определите, какой шаг ожидает разблокированный доступ и где должен храниться секрет.

Как запускать Xcode-сборку из self-hosted Runner?
Сборка запускается обычными командами проекта через xcodebuild, но только после проверки активного Xcode, схемы, зависимостей и прав пользователя. Сначала используйте тестовый проект без подписи. Затем добавляйте приватные зависимости и сертификаты по одному, фиксируя, на каком этапе появляется потребность в дополнительном доступе.

Плюсы такого разделения:

  • проще определить источник сбоя;
  • меньше область действия утёкшего секрета;
  • тестовый узел можно пересоздать без блокировки релиза;
  • журналы обычной сборки не обязаны содержать данные подписывающего контура.

Минусы:

  • появляются дополнительные resource class и правила доступа;
  • нужно обслуживать кэш и зависимости;
  • обновление Xcode требует повторной приёмки;
  • очередь может увеличиться, если выделен только один узел.
06

День выхода: перезагрузка и непрерывная работа

Плановая перезагрузка

До допуска в production выполните плановую перезагрузку в согласованное окно. Перед ней сохраните конфигурацию, журнал и канал удалённого доступа. Не удаляйте рабочие каталоги и не отзывайте токен в рамках первого теста: это разные операции с разными способами восстановления.

После запуска Mac проверьте по порядку:

  • доступ по SSH или через согласованный удалённый канал;
  • наличие процесса Runner;
  • повторную регистрацию узла в inventory;
  • получение нового тестового задания;
  • выполнение xcode-select и xcodebuild;
  • отсутствие зависшего задания в очереди;
  • корректную очистку рабочей директории.

Как сделать автоматическое восстановление Runner после перезагрузки удалённого Mac?
Настройте автозапуск тем способом, который указан в актуальной macOS-инструкции CircleCI для Machine Runner 3. Затем подтвердите восстановление фактической перезагрузкой, а не только повторным запуском процесса вручную. После входа в систему Runner должен сам вернуться в inventory и принять безопасную тестовую задачу от имени <ci-user>.

Проверьте также сценарий сбоя задания. Намеренно завершите тестовую сборку с ошибкой и убедитесь, что:

  • рабочая директория не содержит секретов;
  • временные файлы не попадают в следующий запуск;
  • кэш не подменяет исходники или параметры;
  • лог сохраняется достаточно долго для расследования;
  • повторный запуск не использует сломанное состояние.

Для проблем с подключением и зависшими заданиями используйте официальный раздел CircleCI по диагностике self-hosted Runner. Дополнительные проверки соединения собраны в справке CircleCI по неполадкам Machine Runner и Container Runner.

Матрица финальной приёмки

Проверка Ожидаемое наблюдение Стоп-условие
Регистрация Узел виден с нужным именем и resource class В inventory отображается другой контур
Маршрутизация Задание выполняется на выбранном удалённом Mac Лог не подтверждает фактический узел
Учётная запись Команды выполняются от <ci-user> Используется администратор или личный аккаунт
Xcode Активный путь и версия соответствуют проекту xcodebuild требует ручного вмешательства
Подпись Тестовый релизный шаг видит только разрешённые секреты Сертификаты доступны обычным задачам
Перезагрузка Runner возвращается без ручной регистрации Узел остаётся offline
Очистка Следующая задача получает чистое рабочее состояние Остались артефакты или секреты предыдущего запуска
Отказ Ошибка попадает в журнал и не блокирует восстановление После сбоя очередь зависает

Эксплуатационные границы

Обновляйте Xcode, macOS и зависимости не прямо на единственном релизном узле, а через отдельное окно приёмки. Сначала проверьте копию конфигурации и тестовый ресурс class, затем переносите изменение в production.

Не выполняйте автоматическую очистку всего домашнего каталога пользователя. Рабочая область, кэш и логи должны иметь разные правила удаления. Перед разрушительной очисткой определите, какие артефакты нужны для расследования, и оставьте канал восстановления доступа.

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

07

Выбор среды для реального проекта

CircleCI self-hosted runner на удалённом Mac оправдан, когда вам нужна постоянная среда Xcode, доступ к приватной сети и управляемое хранение подписей. Но такой узел становится частью вашей инженерной ответственности: вы обслуживаете macOS, обновляете инструменты, проверяете права и расследуете загрязнение рабочего каталога.

Покупка собственного Mac mini лучше подходит для длительной стабильной нагрузки, физического доступа и команд, которые уже имеют помещение, сеть и процесс обслуживания оборудования. Виртуальная или неподходящая macOS-среда не является хорошей заменой, если проект зависит от реального Apple-инструментария и воспроизводимой подписи.

Если вам нужно быстро проверить пайплайн, изолировать релизный контур или получить Mac только на период проекта, аренда Mac mini для CI-задач обычно снимает часть начальных расходов и не требует заранее покупать отдельный компьютер. Для выбора по периоду и задаче сначала сопоставьте требования к Xcode, времени работы и доступу к узлу с доступными вариантами удалённого Mac.

В вашем текущем варианте — например, на личном Mac, общей машине команды или Linux-сервере — обычно остаются три слабых места: среда может измениться без контроля, подпись смешивается с обычными задачами, а перезагрузка или занятость компьютера останавливает очередь. Если нужен временный, но настоящий macOS-узел, разумно арендовать Mac через VpsMesh, развернуть сначала тестовый resource class и прогнать безымянную сборку, проверку перезагрузки и очистку рабочей области. Только после этих трёх проверок переносите задачи с сертификатами и публикацией. Узнать условия можно на странице аренды Mac mini.