Миграция CircleCI Machine Runner 3: чек-лист приёмки macOS 2026

Самая опасная ошибка — считать миграцию завершённой сразу после появления нового Runner в консоли. Старый сервис уже перестал принимать задания, новый процесс формально запущен, но рабочая директория недоступна, токен относится к другому resource class или служба не восстанавливается после перезапуска. В результате очередь растёт, а зелёный статус узла создаёт ложное ощущение готовности.

Файл конфигурации, который успешно читается новым Runner, не доказывает совместимость поведения. Отдельно меняются предположения о пути к рабочей директории, пользователе процесса, правах на каталог, очистке файлов, префиксе команд и кэше task-agent. Именно поэтому проверка должна охватывать не только синтаксис, но и полный жизненный цикл задачи.

До начала работ ответственный должен составить минимальный реестр:

• какие macOS-узлы используют старый launch agent;
• какие проекты и resource class направляют на каждый узел;
• какие задания требуют Xcode, приватной сети, SSH checkout key или подписи;
• какой узел считается резервным;
• в какое окно допускается остановка старой службы;
• кто имеет право вернуть старый сервис или переключить проекты на резервный узел;
• где хранятся журнал изменений, результаты тестов и решение об откате.

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

Старый launch agent может оставаться зарегистрированным после копирования нового Runner. Тогда два процесса способны использовать разные каталоги или параметры, конкурировать за задания и по-разному реагировать на перезапуск. Официальная инструкция миграции CircleCI для macOS должна использоваться как контрольная последовательность остановки и удаления старого способа запуска.

Проверка выполняется на пилотной машине, а не на единственном производственном узле:

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

Минимальная команда нужна только для понимания последовательности, а не для слепого копирования:

launchctl list | grep -i circle
ps aux | grep -i runner

Конкретные имена служб, параметры установки и требования к поддерживаемой версии необходимо сверять с актуальным руководством по установке Machine Runner 3 на macOS непосредственно перед изменением. Версии, значения по умолчанию и ограничения могут изменяться; источник для такой проверки — официальный changelog CircleCI, а не старый внутренний скрипт.

Отдельно проверяется происхождение установочного бинарного файла. Для корпоративной приёмки следует сохранить имя пакета, версию, контрольную сумму, сведения о подписи и результат проверки notarization, если они доступны в текущей процедуре установки. Нельзя считать файл доверенным только потому, что он был скачан автоматизацией. В журнале должны остаться источник, дата проверки, пользователь установки и путь, откуда процесс службы загружает исполняемый файл.

Если пилот не проходит, решение должно быть принято заранее: восстановить старый сервис по документированной процедуре или направить задания на резервный узел. Попытка одновременно «починить» старый launch agent и вручную запустить Machine Runner 3 на той же машине превращает откат в неуправляемую комбинацию процессов.

Можно ли использовать прежний config.yaml без изменений?
Его можно взять как основу для миграции только после сверки с официальным справочником конфигурации Machine Runner 3. Успешная загрузка файла подтверждает лишь допустимость синтаксиса. Она не подтверждает правильность путей, пользователя, прав, режима Runner, очистки каталога или поведения кэша.

Проверка должна идти по полям и по результату выполнения:

• working_directory — каталог существует, принадлежит ожидаемому пользователю и не пересекается с рабочей областью другого процесса;
• cleanup_working_directory — после задачи удаляются исходники, временные файлы и результаты, которые не должны переходить следующему заданию;
• runner mode — выбранный режим соответствует способу запуска и модели эксплуатации узла;
• command_prefix — команды не получают неожиданный shell-префикс, другой PATH или другой набор переменных;
• максимальная длительность задачи — значения сверяются с текущей документацией, а не с памятью команды;
• кэш task-agent — проверяется, какие данные сохраняются между задачами и кто имеет к ним доступ.

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

Базовая задача для пилота должна быть безопасной и воспроизводимой. Она не должна содержать производственные секреты и должна последовательно проверить checkout, установку зависимостей, сборку, вывод лога, ненулевой код ошибки и передачу артефакта. Для iOS CI/CD достаточно начать с тестового проекта без ключа распространения, а подпись проверять отдельным контролируемым сценарием.

Следующий риск — задача попадает не на тот Mac. Причиной может быть неверный namespace, resource class, токен или проектная настройка. Внешне Runner остаётся доступным, но доверенный производственный проект и обычный тестовый проект оказываются в одном контуре.

Проверяются следующие связи:

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

Полезно заранее разделить доверенные релизные задачи и обычные тесты. Если на Mac доступна подпись, SSH-доступ или внутренняя сеть, универсальный resource class для всех проектов создаёт слишком широкий доверительный контур. Организационные ограничения следует проверять через документацию CircleCI по политикам для self-hosted Runner.

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

Очистка каталога — не косметическая операция. Если следующий job может прочитать исходники предыдущего, переменные окружения, SSH checkout key, временный Keychain, Provisioning Profile или готовый архив приложения, проблема уже относится к управлению секретами и боковому перемещению внутри CI-инфраструктуры.

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

Проверка подписей включает:

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

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

В середине проверки удобно разделить технические признаки, ожидаемое доказательство и решение по результату. Это не таблица производительности: без записи, полученной на изолированном узле, нельзя утверждать скорость или вместимость.

Финальная классификация должна быть формальной:

• Пройдено — все обязательные проверки успешны, доказательства сохранены, откат выполнен в тестовом режиме.
• Ограниченное расширение — известны ограничения, запрещённые проекты исключены, объём задач и типы релизов ограничены.
• Возврат на доработку — не доказаны очистка, восстановление, маршрутизация, подпись или безопасный откат.

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

Особенно опасен повторный релиз. Если процесс сборки завершился на стороне Mac, но CircleCI не получил финальный статус из-за сетевого сбоя, автоматический повтор может повторно опубликовать артефакт. Базовый тест должен поэтому использовать тестовую среду распространения и проверять идемпотентность шага публикации, а не только успешный зелёный результат.

При кратковременном отключении сети проверяется, не остаётся ли задача в неопределённом состоянии. При завершении процесса — не запускается ли второй экземпляр поверх старого. При перезапуске — доступен ли тот же рабочий каталог и не требуется ли вход в графическую сессию. Если поведение не подтверждено официальной документацией, оно фиксируется как наблюдение пилота, а не как гарантированная функция Machine Runner 3.

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

Технический руководитель может принять решение по следующей развилке:

• Если старый Mac выполняет подпись, имеет физические зависимости или связан с локальным оборудованием, оставить его в отдельном доверенном контуре и мигрировать только после подготовки резервной машины.
• Если требуется проверить Machine Runner 3 без изменения рабочего узла, выбрать изолированный удалённый Mac с root-доступом, удалённым перезапуском и отдельным resource class.
• Если очередь нестабильна, но релизные задания редки, сначала подтвердить поведение на одном пилоте, а не покупать парк заранее.
• Если несколько проектов должны использовать общий Mac, разделить доверенные и недоверенные задачи, а не полагаться только на очистку каталога.
• Если восстановление после перезапуска требует ручного входа или непроверенного скрипта, не переводить узел в роль круглосуточного CI-сервера.
• Если нагрузка стабильно высокая и требуется физический интерфейс, долгосрочная покупка выделенного Mac может быть рациональнее аренды; для миграционного пилота, сезонного релиза или временного увеличения очереди гибкий удалённый узел обычно проще вывести из эксплуатации после проверки.

Руководство по аренде удалённого Mac в NUKCLOUD следует рассматривать именно как вариант изолированного пилотного ресурса, а не как замену всем производственным узлам без анализа требований к физическим интерфейсам, сетевому доступу и сроку хранения ключей.

Перед изменением следующего узла ответственному следует собрать один пакет приёмки:

• идентификатор узла и назначенный resource class;
• зафиксированный источник и версия Machine Runner 3;
• результат удаления старого launch agent;
• проверенный владелец рабочей директории и права;
• конфигурация с закрытыми секретами;
• успешный базовый job без производционных ключей;
• отрицательный тест межпроектного чтения;
• результат теста временного Keychain и Provisioning Profile;
• результат перезапуска и аварийного завершения процесса;
• журнал сетевого сбоя и проверки повторного запуска;
• список разрешённых и запрещённых проектов;
• инструкция отката и имя дежурного ответственного.

Для аудита также полезно связать каждое утверждение с источником: поля конфигурации — со справочником Machine Runner 3, порядок установки — с официальным руководством, политики доступа — с документом по конфигурационным политикам, а изменения поддержки — с changelog. Данные о времени выполнения, очереди, восстановлении и ручных действиях должны быть только результатом конкретного теста на конкретном узле; их нельзя заменять типичными значениями из другой инфраструктуры.

Для компаний, которым нужно отдельно описать хранение данных и доступ администраторов, в документацию к закупке можно включить политику конфиденциальности NUKCLOUD, но она не заменяет собственную модель угроз и процедуру работы с ключами подписи.

Переход со старого launch agent на Machine Runner 3 оправдан как направление развития macOS-узлов CircleCI, однако совместимость конфигурации не является доказательством безопасной эксплуатации. Решение о включении в производство принимается только после проверки пяти независимых зон: службы, поведения конфигурации, маршрутизации, очистки секретов и восстановления.

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

Если текущая инфраструктура не даёт отдельного Mac для проверки, использует единственный производственный узел или требует быстро добавить временную ёмкость, аренда NUKCLOUD может быть удобнее покупки дополнительного оборудования: не требуется заранее замораживать бюджет в аппаратуре, проще выделить отдельный ресурс для пилота и проверить удалённый перезапуск в реальном CI-контуре. При этом для постоянной высокой нагрузки, обязательного физического доступа или долгосрочного хранения производственных ключей сначала следует сравнить аренду с выделенным собственным Mac по требованиям безопасности и TCO. Начинать стоит не с полной замены, а с одной изолированной машины, на которой можно доказать безопасный путь к производственному переключению.