Шаг iOS-сборки попадает на Linux Agent, а команда не понимает, почему Xcode недоступен.
Быстрое решение: оставьте Buildkite для оркестрации, направьте задачи, зависящие от macOS и Xcode, на Mac Agent, а переносимые проверки выполняйте в подходящей им среде. Очередь маршрутизирует работу, но не изолирует хост и не защищает ключи подписи.
Эта инструкция для платформенных инженеров, которые подключают существующий iOS-проект к Buildkite.
Она также пригодится IT-руководителям, отвечающим за учётную запись и обслуживание Mac-узла.
Руководителям выпуска и безопасности — чтобы отделить тестовые сборки от доступа к production-подписи.
[ SECTION_01 ] Этап 1. Границы задач: подключение корпоративного iOS CI в Buildkite к Mac
Buildkite распределяет этапы и передаёт их агентам, а Mac Agent исполняет назначенные ему команды в macOS. Это не означает, что на Mac нужно переносить весь конвейер. Сначала разберите зависимости каждого шага: часть проверок может выполняться вне Apple-платформы, тогда как xcodebuild, задачи с симулятором и операции, которым требуются инструменты Xcode, должны получить подходящую среду. Описание модели Agent и маршрутизации приведено в документации Buildkite Agent.
Начните с инвентаризации существующего pipeline:
- Отметьте шаги, которые вызывают Xcode,
xcodebuildили инструменты Apple. - Выделите этапы, которым нужен симулятор, архивирование приложения либо доступ к signing identity.
- Отделите проверки исходного кода и иные задачи без зависимости от macOS, если они уже надёжно выполняются в другой среде.
- Для каждого шага запишите входные данные, необходимые секреты, получаемые артефакты и того, кто вправе запускать задачу.
Такое разбиение полезно и для диагностики. Если единый длинный шаг завершился ошибкой, по логам сложнее понять, проблема ли это исходного кода, инструментария, подписи или доступности хоста. Разделённый pipeline делает границы исполнения явными. Он также уменьшает количество шагов, которым вообще нужен доступ к чувствительному окружению.
| Тип задачи | Подходящая среда | Что проверять |
|---|---|---|
| Проверки, не зависящие от Apple-инструментов | Текущий совместимый исполнитель | Требования скрипта и его зависимости |
| Сборка проекта iOS с Xcode | Mac Agent с доступным Xcode | Путь к Xcode и результат xcodebuild |
| Тесты с Apple-инструментами или симулятором | Mac Agent, подготовленный для проекта | Фактический выбор Xcode и результаты тестирования |
| Выпускная задача с production-подписью | Контролируемое окружение с ограниченным доступом | Допуск к секретам, согласование и следы аудита |
Apple описывает настройку активных инструментов командной строки отдельно от наличия Xcode на диске. Поэтому факт установленного Xcode сам по себе не подтверждает, что агент использует нужный набор инструментов. Сверяйте выбор инструментов по документации Apple о настройках Xcode для командной строки.
[ SECTION_02 ] Этап 2. Подготовка Mac: узел, пользователь и инструменты
До установки зафиксируйте характеристики узла и договоритесь, кто отвечает за изменения. Для сборочной машины важны не только название модели и доступность удалённого экрана. Команда должна знать используемую версию macOS, архитектуру процессора, установленный Xcode и порядок его обновления. Если это не определено, обновление хоста может изменить среду сборки без явного изменения pipeline.
Соберите исходные данные из самой машины:
sw_vers -productVersion
uname -m
xcode-select -p
xcodebuild -version
Эти команды выводят версию macOS, архитектуру, путь выбранных инструментов командной строки и сведения о версии Xcode. Сохраните их в журнале диагностики или артефактах приёмки. Настройка xcode-select и сведения об инструментах командной строки описаны в руководстве Apple по настройке Xcode.
Отдельно назначьте macOS-пользователя, от имени которого запускается Agent. Не исходите из того, что это учётная запись администратора, пользователь интерактивной сессии или тот, кто установил программу. Проверьте доступ именно из контекста Agent: чтение рабочего каталога, получение исходного кода, запись артефактов и использование инструментов. Если сборка обращается к связке ключей, проверьте доступность нужных элементов для этой учётной записи и при выбранном способе запуска службы.
| Область подготовки | Что зафиксировать | Критерий готовности |
|---|---|---|
| macOS и архитектура | Вывод диагностических команд с узла | Значения сохранены и соответствуют требованиям проекта |
| Xcode | Путь активных инструментов и вывод xcodebuild |
Версия и путь совпадают с ожидаемыми для сборки |
| Учетная запись Agent | Имя пользователя и нужные разрешения | Рабочие файлы доступны без избыточных прав |
| Секреты | Хранение Agent Token, репозиторных и подписывающих данных | Секреты не зашиты в скрипты, настройки проекта или журналы |
| Эксплуатация | Ответственные за обновление, перезапуск и проверку | Понятно, кто восстанавливает узел и подтверждает его готовность |
Токен Agent и учётные данные репозитория выполняют разные задачи. Не храните их как обычные значения в pipeline или выводе диагностических команд. Способ выдачи и применения токенов сверяйте с официальным описанием Buildkite Agent Token. Доступ к репозиторию настраивайте отдельно и предоставляйте ровно тот объём прав, который нужен агенту для получения исходного кода.
Для первичной оценки примените качественную шкалу готовности: «не готово», если неизвестен пользователь процесса или текущий Xcode; «условно готово», если узел собран, но запуск после перезагрузки не проверен; «готово к пилоту», если идентичность, инструменты и восстановление подтверждены по журналам. Это оценка готовности к тестированию, а не доказательство изоляции или соответствия требованиям безопасности.
[ SECTION_03 ] Этап 3. Установка и запуск Buildkite Mac Agent
Используйте актуальный для команды способ установки и запуска из инструкции Buildkite по установке Agent на macOS. До запуска проверьте, куда устанавливаются файлы, где хранится конфигурация и какая учётная запись получит доступ к ней. Токен нельзя помещать в открытый скрипт или оставлять в диагностическом выводе.
Различайте запуск из текущего терминала и постоянный запуск под управлением launchd. Первый подходит для контролируемой проверки установки: завершение сессии или самого процесса может остановить Agent. Для постоянной работы используйте предусмотренный и документированный командой способ управления службой. Не считайте имя процесса или наличие запущенной службы достаточным подтверждением работоспособности.
Проверяйте цепочку восстановления целиком:
- Agent стартует после предусмотренного перезапуска или входа, в зависимости от выбранной модели.
- Процесс работает от согласованной учётной записи.
- Агент аутентифицируется в Buildkite и появляется в ожидаемом состоянии.
- Задача из тестового pipeline действительно принимается этим агентом.
- Рабочие каталоги и диагностические журналы доступны для проверки, но секреты в них не раскрываются.
Если Agent отображается онлайн, но не принимает нужную задачу, проверьте его очередь, настройки и условия маршрутизации. Если сборка работает из Terminal, но не из CI, сначала сопоставьте пользовательский контекст, переменные окружения, права на файлы и доступ к связке ключей. Это чаще помогает, чем повторная установка без проверки причины.
[ SECTION_04 ] Этап 4. Маршрутизация: очередь и правила выбора Mac-узла
Назначьте отдельную очередь для задач, которым требуется macOS, и явно укажите её в соответствующих шагах pipeline. Пример структуры:
steps:
- label: "iOS: build and test"
command: "xcodebuild ..."
agents:
queue: "macos"
Имя macos здесь — пример, а не автоматически существующая очередь: замените его на значение, настроенное в вашей организации. Сопоставление очередей и управление ими описаны в документации Buildkite по очередям. Для проверки откройте журнал выполнения и подтвердите, какой Agent принял шаг и на каком узле он исполнялся.
Очередь сообщает системе, куда направить работу. Она не подтверждает версию macOS, архитектуру, установленный Xcode или состояние изоляции. Если несколько Mac-узлов отвечают требованиям проекта, используйте дополнительные согласованные атрибуты и проверяйте их по реальным данным агента. Не выводите характеристики машины только из названия очереди.
| Элемент маршрутизации | Что он подтверждает | Чего он не подтверждает |
|---|---|---|
| Значение очереди в шаге | Куда направляется задача | Какой Xcode установлен на узле |
| Agent, принявший шаг | Какой исполнитель обработал задачу | Что хост изолирован от других работ |
| Диагностический вывод внутри шага | Какая система и инструменты доступны процессу | Что настройки сохранятся после обновления |
| Журнал тестирования и артефакты | Как завершился выбранный прогон | Что production-секреты доступны только разрешённым задачам |
Это разделение удобно применять и к смешанным pipeline. Сборку можно направлять на Mac, а шаги, не требующие Apple-инструментов, оставлять в имеющейся среде. Сохраняйте зависимости между этапами явными: следующий шаг должен получить нужные артефакты, а не полагаться на случайное состояние рабочего каталога на другом агенте.
[ SECTION_05 ] Этап 5. Граница доверия: тестирование, непроверенный код и подпись
Проверьте, какие события могут запустить шаги с секретами. Обычная тестовая сборка, сборка непроверенного pull request и выпуск, использующий production signing identity, имеют разные требования к доверию. Вопрос состоит не только в том, кто получил задачу, но и в том, какой код исполняется, какие данные ему доступны и какие действия он может совершить.
Очереди полезны для разделения маршрутов, но не обеспечивают сами по себе изоляцию процессов, файлов или ключей. Если разные уровни доверия используют один хост, оцените возможность доступа задач к оставшимся файлам, кэшу, журналам и учётным данным. Для production-подписи рассматривайте отдельный контролируемый контекст, ограниченный допуск к секретам и утверждённый процесс запуска. Подход к проверкам конфигурации и полномочий можно сверить с контрольным списком безопасности Buildkite.
Распределите ответственность по каждому секрету: кто его создаёт, где он хранится, какие задачи могут его использовать и как подтверждается использование. Удаляйте значения секретов из отладочного вывода. Проверяйте не только YAML pipeline, но и вызываемые им скрипты: они тоже могут напечатать переменные, пути или содержимое файлов.
Примените следующие условия выбора:
- Если шагу не нужны инструменты Apple и секреты подписи, оставьте его в совместимой текущей среде; иначе направьте его на подходящий Mac Agent.
- Если сборку запускает непроверенный код, не предоставляйте ей production-подпись; если проверка требует чувствительных ресурсов, сначала определите отдельный контроль доступа и среду исполнения.
- Если production-подпись нужна для выпуска, допускайте её только в процессе с подтверждённым источником кода и разрешением; если такие условия не выполняются, остановите выпускной шаг.
- Если задача должна быть изолирована от других работ, подтвердите свойства изоляции на уровне хоста и политик; если подтверждения нет, не считайте отдельную очередь достаточной защитой.
Правила должны совпадать с фактическим поведением pipeline. Например, скрытая команда в скрипте может использовать секрет даже тогда, когда основной шаг помечен как обычная тестовая сборка. Документируйте не только назначение очередей, но и причины, по которым конкретная категория кода получает доступ к конкретной среде.
[ SECTION_06 ] Этап 6. Приёмка: сквозной прогон проекта iOS
Выберите представительный проект и проверьте его на реальном маршруте — от получения исходного кода до сохранения результата. Успешное появление Agent в интерфейсе подтверждает только доступность агента, но не корректность Xcode, тестов или подписи. Приёмка должна оставлять доказательства каждого критичного перехода.
Проведите проверку последовательно:
- Запустите тестовый pipeline и убедитесь, что исходный код получен ожидаемым способом.
- В диагностическом шаге запишите macOS, архитектуру,
xcode-select -pи результатxcodebuild -version. - Запустите фактическую команду проекта, а не только короткую проверку наличия Xcode.
- Проверьте результаты тестирования и приложите их к сборке. Apple описывает запуск тестов и интерпретацию результатов в документации Xcode по тестам.
- Подтвердите, что артефакты доступны получателям и соответствуют тому шагу, который их создал.
- Если в область приёмки входит архивирование или подписание, выполните этот сценарий только с разрешёнными материалами и зафиксируйте согласование выпуска.
На каждом этапе сохраняйте понятные свидетельства: запись о принятом Agent, версию инструментов, журнал команды, результат теста и сведения о выпускном согласовании, если оно применялось. Секреты в доказательства не включайте. Если журнал раскрывает токен, закрытый путь или содержимое ключа, исправьте маскирование до того, как расширять использование pipeline.
При отказе классифицируйте проблему по месту возникновения. Задача не стартовала — смотрите очередь и доступность Agent. Сборка не находит ожидаемый Xcode — проверяйте путь инструментов в контексте службы. Тесты завершились ошибкой — анализируйте их результаты, а не только общий статус pipeline. Подпись недоступна — сверяйте пользователя процесса, права и утверждённый доступ к ключу. Такой разбор не позволяет ошибочно лечить проблему маршрутизации сменой сертификата или переустановкой агента.
Если команда рассматривает удалённый Mac как способ размещения узла, оценивайте его после определения требований pipeline: кто получает доступ, как выполняются перезапуск и обновление, как собираются логи и где хранятся артефакты. Конкретные условия аренды, конфигурации и расположение узлов нужно сверять с доступными предложениями, а не выводить из этой инструкции. Для сравнения доступных вариантов можно посмотреть информацию о Mac у NOVAKVM; решение о размещении должно учитывать обязанности команды по доступу, секретам и обслуживанию.
[ SECTION_07 ] Частые вопросы перед запуском
Можно ли направить все этапы iOS pipeline на Mac Agent?
Можно, но это не означает, что так следует делать. Сначала определите, какие команды действительно зависят от macOS, Xcode или связки ключей. Перенос остальных шагов увеличивает число задач на Mac-узле без технической необходимости и затрудняет понимание, какой среде принадлежит ошибка. Маршрутизируйте работу по фактическим зависимостям.
Нужно ли запускать Agent от администратора macOS?
Не автоматически. Выбирайте управляемую учётную запись с правами, достаточными для исходного кода, инструментов и рабочих файлов. Проверьте сценарии обновления, записи артефактов и доступа к связке ключей именно от этого пользователя. Если отдельная операция требует расширенных прав, оцените её отдельно, вместо того чтобы постоянно запускать весь агент с административными полномочиями.
Достаточно ли отдельной очереди для production-сборки?
Нет. Очередь помогает выбрать исполнителя, но не заменяет политику доверия и защиту хоста. Для production-сценария определите допустимые источники кода, круг лиц, способ выдачи подписывающих материалов и подтверждение выпуска. Если эти меры не реализованы, ограничение только на уровне имени очереди не считается достаточным контролем.
Почему успешная интерактивная проверка Xcode не подтверждает работу CI?
Терминал разработчика и процесс Agent могут работать от разных пользователей и иметь разные переменные среды, права и доступ к связке ключей. Поэтому выводите путь инструментов и версию Xcode внутри самого шага pipeline. Сопоставьте их с ожидаемой конфигурацией и сохраните результат вместе с тестами и журналом сборки.
Если текущая схема опирается на Linux для задач с Xcode, она не сможет выполнить Apple-зависимую команду; если все разработчики должны получить собственное физическое устройство, покупка добавит отдельные задачи учёта и обслуживания. Удалённый Mac тоже не снимает ответственность за настройку учётных записей, очередей и подписи. После сквозной приёмки сравните эти обязанности с потребностью в гибком удалённом узле: для временной нагрузки или отдельной сборочной среды можно оценить варианты Mac mini у NOVAKVM. При постоянно высокой нагрузке или необходимости физических интерфейсов собственный Mac может быть практичнее; аренду имеет смысл рассматривать, когда важнее не закреплять за пилотом отдельное оборудование и заранее проверены доступ, эксплуатация и восстановление.