DevOps / CI/CD

Как развернуть GitLab Runner на macOS самостоятельно? Руководство 2026

Для установки GitLab Runner на macOS GitLab предписывает пользовательский LaunchAgent и не поддерживает системный LaunchDaemon; для сборок iOS и macOS документация рекомендует shell executor (инструкция GitLab по установке на macOS). Поэтому самостоятельное развертывание подходит, если узел выполняет доверенные задачи, а команда готова отдельно проверить пользовательскую сессию, Xcode и ограничения изоляции.

Материал предназначен инженерам, которым нужно запускать сборки Xcode или тесты iOS в GitLab CI/CD.
Он также пригодится DevOps-специалистам, обслуживающим macOS-узел с Windows- или Linux-компьютера.
Командам, выбирающим удалённый Mac для постоянных задач, здесь помогут критерии приёмки и эксплуатации.

Оцените исполнительную среду до установки Runner

GitLab Runner устанавливают на ту macOS-машину, где фактически будут выполняться задания. Установка GitLab Runner не означает, что на Mac нужно размещать сам сервер GitLab: CI-система может оставаться на отдельной инфраструктуре, а Mac выступать зарегистрированным исполнительным узлом.

Это различие влияет на требования к машине. Для исполнения задач важны доступность репозитория и сети, установленные зависимости проекта, права пользователя и нужные инструменты Apple. В частности, наличие записи о Runner в интерфейсе само по себе не доказывает, что на узле есть подходящая среда для сборки.

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

Можно ли установить GitLab Runner на macOS?

Да. Установка на macOS поддерживается, если Runner работает в соответствии с условиями GitLab для этой платформы. Для задач Apple-платформ подходящим вариантом обычно служит macOS shell executor: он запускает команды в среде самой машины, где можно использовать локально установленные инструменты.

До регистрации подготовьте выделенную учётную запись для выполнения CI-задач. Она не должна получать права шире, чем нужно сборке. Продумайте также, кто сможет менять конфигурацию Runner, просматривать его журналы и обновлять зависимости.

Пользовательские параметры регистрации, адрес GitLab и токен в примерах ниже обозначены условными значениями. Подставляйте данные своей инсталляции, не помещайте реальные секреты в публичный репозиторий или вывод CI-журнала. GitLab описывает регистрацию Runner в документации по регистрации; используйте действующие в вашей инсталляции инструкции и способ выдачи токена.

Минимальные условия перед регистрацией:

  • узел работает под macOS и имеет сетевой доступ к GitLab и необходимым зависимостям проекта;
  • учётная запись для Runner выбрана и ограничена в соответствии с политикой команды;
  • инструменты, вызываемые из CI, установлены именно на этом узле;
  • назначена отдельная метка, по которой macOS-задачи можно маршрутизировать адресно;
  • команда понимает, какие проекты и задачи разрешено выполнять на машине.

Проверьте пользовательскую сессию и способ запуска службы

Критически важное отличие macOS-развёртывания — способ управления процессом Runner. GitLab предписывает использовать пользовательский LaunchAgent и прямо указывает, что запуск системным LaunchDaemon не поддерживается (документация GitLab о режиме службы на macOS). Поэтому настройка Runner как системного демона не является эквивалентным способом установки и не должна использоваться как обходное решение.

LaunchAgent относится к пользовательской среде. Это важно, когда задание зависит от доступа к пользовательскому домену, связке ключей или графической сессии; задачи с симулятором также следует проверять в реальных условиях выполнения, а не считать их работоспособность доказанной одним фактом регистрации Runner. Apple отдельно объясняет различия между пользовательскими агентами и системными службами в руководстве по заданиям launchd.

Почему нельзя заменить LaunchAgent на LaunchDaemon?

LaunchAgent работает в пользовательском контексте, а LaunchDaemon предназначен для системного контекста. Подмена одной модели другой меняет доступность пользовательских ресурсов и противоречит указанному GitLab способу запуска Runner на macOS. Если процесс не стартует после выхода пользователя или перезапуска машины так, как ожидает команда, это повод проверить установленный режим службы и условия пользовательской сессии, а не переписывать службу под неподдерживаемый режим.

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

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

Сопоставьте executor с задачами и границами доверия

Какой executor выбрать для macOS Runner?

Для iOS- и macOS-сборок GitLab рекомендует shell executor. Он запускает команды в оболочке на хосте и использует среду установленной macOS, что позволяет задачам обращаться к локальным инструментам. Это не означает, что любой проект безопасно отправлять на такой узел: изоляция shell executor ограничена, поскольку задания выполняются в среде машины (документация GitLab по shell executor).

Сравнение ниже — инструмент выбора, а не утверждение, что варианты взаимозаменяемы для любого проекта.

Вариант Что получает задача Когда рассматривать Основное ограничение
Shell executor на macOS Оболочку и установленную на хосте среду macOS Apple-сборки, которым нужны инструменты узла или его пользовательский контекст Ограниченная изоляция между заданиями; важны доверие к проектам и права учётной записи
Контейнерный executor Среду, организованную через выбранную контейнерную инфраструктуру Задачи, для которых контейнерная модель доступна и соответствует требованиям Не следует считать его автоматической заменой macOS-хосту для работы с инструментами Apple

Если команде требуется надёжное разделение недоверенных задач, не описывайте shell executor как контейнер или как границу безопасности между проектами. Сначала оцените альтернативную архитектуру исполнения, политику выделенных узлов и разделение проектов по уровню доверия. В документации GitLab по безопасности Runner описаны риски самоуправляемых Runner и подходы к управлению ими.

До подключения проекта ответьте на вопросы:

  • Может ли Runner принимать задания только от доверенных проектов и участников?
  • Имеет ли учётная запись доступа к файлам, токенам или связке ключей, не нужным сборке?
  • Может ли задание прочитать остатки предыдущих работ или файлы, оставленные другими процессами?
  • Разделены ли конфигурации и секреты тестовой и релизной сборки?
  • Кто проверяет изменения CI-конфигурации, которые выполняются с правами учётной записи Runner?

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

Подтвердите Xcode и другие зависимости непосредственно на узле

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

На этапе подготовки запишите результат проверки установленного Xcode, активного каталога разработчика и компонентов, которые требуются проекту. Команды запускайте от той учётной записи, под которой будет работать Runner. Для этого пригодятся xcode-select -p и xcodebuild -version; конкретные требования к версии и компонентам сверяйте с документацией Apple и проекта, а не переносите из чужой конфигурации.

Apple описывает установку инструментов командной строки в руководстве по установке Command Line Tools, а получение дополнительных компонентов Xcode — в документации по загрузке и установке компонентов. Наличие Command Line Tools не следует автоматически приравнивать к полной среде, необходимой конкретной сборке: ориентируйтесь на фактические вызовы проекта и его тесты.

Практическая проверка должна содержать:

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

Не кладите секреты подписи в вывод проверки. Если CI использует защищённые переменные или файлы, проверьте, кто и при каких условиях получает к ним доступ. Успешная компиляция без подписи не доказывает, что настроена релизная сборка; успешный запуск тестов без симулятора не доказывает, что симуляторный сценарий готов.

Проверьте регистрацию, метки и результат минимальной задачи

После подготовки среды зарегистрируйте Runner в подходящей области видимости и назначьте ему специализированную метку, например условную macos-ci. Область видимости влияет на то, какие проекты могут использовать Runner; GitLab описывает управление этой настройкой в документации по областям видимости Runner.

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

Пример минимального задания с условными именами:

macos_probe:
  tags:
    - macos-ci
  script:
    - sw_vers
    - xcode-select -p
    - xcodebuild -version

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

Порядок приёмки:

  1. Убедитесь, что Runner зарегистрирован в нужной области, подключён и имеет ожидаемую метку.
  2. Запустите минимальное задание, которое выводит сведения о macOS и активном каталоге разработчика.
  3. Сопоставьте журнал задания с ожидаемым хостом и учётной записью; проверьте, что задача не исполнилась на другом Runner.
  4. Запустите типичную для проекта сборку и проверьте код завершения, журналы и ожидаемые артефакты.
  5. Отдельно выполните требуемые проверки симулятора, подписи и тестов; не выводите готовность этих возможностей из общей успешной сборки.
  6. Зафиксируйте, где искать журналы и как отличать ошибку маршрутизации, окружения, зависимости и самой сборки.

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

Оцените восстановление узла после выхода и обслуживания

Самостоятельный Runner становится частью CI-инфраструктуры только тогда, когда команда понимает его поведение не только во время ручного запуска. Проверьте, как служба ведёт себя после выхода пользователя и перезапуска Mac, как подтверждается её состояние и кто имеет доступ к журналам. Документируйте именно наблюдаемое поведение своей конфигурации; не переносите на неё предположения о постоянно активной графической сессии или доступности ключей.

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

Решение о пригодности узла зависит от последствий простоя и модели задач:

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

Такие уровни — критерии эксплуатации, а не гарантия доступности конкретного хостинга. Фактические условия доступа к удалённому Mac и применимость узла к вашей задаче следует проверять отдельно.

Выберите узел по проверяемым условиям, а не по обещанию «готовности»

Результат проверки удобно зафиксировать в коротком акте приёмки. Поставьте отметку напротив каждого пункта только после проверки на целевом Mac:

  • [ ] Runner установлен на узле, который фактически исполняет задания.
  • [ ] Выбран shell executor, если задаче необходима локальная macOS-среда.
  • [ ] Runner запускается через пользовательский LaunchAgent, а не системный LaunchDaemon.
  • [ ] Учётная запись ограничена, а доступ к узлу и его секретам контролируется.
  • [ ] Xcode, активный каталог разработчика и необходимые компоненты проверены в CI.
  • [ ] Метка macOS задана явно, и тестовая задача попадает на ожидаемый Runner.
  • [ ] Сборка проверена отдельно от симулятора и подписи, если они входят в требования.
  • [ ] Поведение после выхода пользователя, перезапуска и обслуживания соответствует плану команды.
  • [ ] Известно, где искать журналы и как восстановить узел после сбоя.

Если задача ограничивается периодической проверкой проекта и у команды есть собственный подходящий Mac, локальный узел может быть проще в контроле. Но он требует самостоятельного обслуживания, доступности машины и согласованного пользовательского контекста. При необходимости длительно доступной macOS-среды для сборок удалённый Mac может быть удобнее покупки отдельного устройства, однако выбор следует делать после проверки доступа, срока использования, Xcode и правил работы с секретами, а не на основании непроверенных обещаний о скорости или доступности.

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

Самостоятельный Runner на удалённом Mac имеет смысл, если команде нужна macOS-среда, но нет желания выделять и администрировать отдельный физический компьютер. Собственный узел сохраняет контроль над окружением, однако потребует закупки, обслуживания, обновлений и организации удалённого доступа; обычный сервер без macOS не заменит инструменты Apple, а shell executor не станет безопасным вариантом для недоверенных заданий. Если требования к доступности и границам доверия проверены, аренда Mac у KuzCloud может дать более гибкий путь к временному или тестовому узлу. Перед включением его в конвейер сначала подтвердите доступ, период использования и готовность нужной среды, затем проведите ту же приёмку, что и для собственного Mac.

Запустите CI/CD на выделенном Mac от KuzCloud

Получите физический Mac mini M4 с macOS для сборки и тестирования приложений Apple.

Полный root-доступ позволяет установить нужные инструменты и настроить среду под ваши задачи.