Как подключить Gemini CLI к Xcode CI на удалённом Mac? Приёмка развёртывания 2026

Симптом: Gemini CLI отвечает на запрос, но вы не понимаете, означает ли это успешную сборку и можно ли доверять результату в CI.

Быстрый путь: запускайте Gemini CLI на удалённом Mac как ограниченный инструмент для задачи с кодом, а сборку и тесты поручайте отдельному скрипту с xcodebuild; до включения в рабочую цепочку проверьте права, журналы и повторяемость.

Эта инструкция для разработчиков Apple-проектов, которым нужно проверять изменения через удалённый Mac.
Она пригодится инженерам, поддерживающим GitHub Actions или другую CI-систему с Mac-узлом.
Она также адресована платформенным специалистам, отвечающим за ключи, доступ к репозиториям и публикацию.

1. До запуска: какую часть цепочки поручить Gemini CLI?

Gemini CLI можно запускать на удалённом Mac и вызывать из скрипта или автоматизированного процесса. Но это не встроенная интеграция с Xcode и не CI-планировщик: CLI получает задачу, а отдельные инструменты выполняют сборку, запускают тесты и фиксируют их результат. Описание автоматизации и режимов без интерактивного диалога приведено в документации Gemini CLI по автоматизации и руководстве по headless-режиму.

Разделите ответственность заранее:

Такое разделение важно при диагностике. Ответ «готово» от Agent — это его текстовый вывод, а не подтверждение успешной компиляции. Даже если Gemini CLI предложил исправление и объяснил его, CI должен независимо проверить, какие файлы изменились, что вернул xcodebuild и появились ли ожидаемые результаты тестирования.

Можно ли запускать Gemini CLI на удалённом Mac? Да, если на узле установлены нужные инструменты, настроена подходящая авторизация и у процесса есть только необходимые права. Подключение по SSH даёт способ управлять узлом, но само по себе не определяет ни полномочия Agent, ни безопасность файлов проекта.

Сначала выберите режим работы, а не начинайте с передачи Agent всей сборочной цепочки:

Почему нельзя считать текстовый ответ Agent итогом Xcode CI? Потому что результатом сборки управляет команда Xcode, а результат тестирования нужно проверять по данным тестового запуска. Apple описывает работу командных инструментов Xcode и параметры xcodebuild в справочнике по инструментам командной строки Xcode. Это отдельный слой относительно ответа Gemini CLI.

2. Подготовка узла: что проверить до первой автоматизации?

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

Перед запуском зафиксируйте базовую конфигурацию в журнале задания:

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

Сведения о способах входа и вариантах авторизации сверяйте с официальным руководством Gemini CLI по аутентификации. Не переносите секреты из локальной пользовательской сессии на узел «на всякий случай»: для CI должен быть понятен владелец учётных данных, срок их действия, доступные им ресурсы и процедура отзыва.

Проверьте, что среда проекта уже собирается без участия Agent. Для этого запустите известный команде проекта сценарий xcodebuild вручную или на тестовом задании CI, сохраните команду и результат. Если исходная конфигурация сама по себе нестабильна, последующий сбой после запуска Gemini CLI нельзя будет достоверно связать с его изменениями.

Передайте в пробный запрос только нужные файлы и контекст. Файл .env, сертификаты, приватные ключи и данные из пользовательского каталога не должны попадать в рабочую область Agent без обоснованной необходимости.

Шаг 1: зафиксируйте границу задачи

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

Шаг 2: проверьте рабочую директорию

Перед каждым запуском определяйте commit и состояние дерева Git. Если проба должна начинаться с чистого состояния, остановите задание при наличии незапланированных изменений. После ответа Agent сохраните git diff и проверьте его до запуска сборки: неожиданный файл, изменение схемы или затронутый скрипт должен быть основанием приостановить автоматическую цепочку.

3. Первый запуск: как проверить автоматический вызов и его вывод?

Как Gemini CLI вызывает xcodebuild в CI? Не за счёт встроенной связи с Xcode: оркестратор запускает Gemini CLI, а затем ваш скрипт отдельно выполняет xcodebuild. На первом проходе лучше оставить между этими действиями контрольную точку, чтобы можно было проверить изменение до компиляции.

В документации Gemini CLI описаны вызов без интерактивного диалога с помощью -p и выбор формата вывода через --output-format; сверяйте синтаксис с руководством по headless-режиму, поскольку поддерживаемые параметры могут меняться. Пример ниже показывает структуру проверки, а не готовую конфигурацию для любого репозитория:

set -u

RUN_DIR="${RUN_DIR:?Укажите каталог результатов задания}"
PROMPT="${PROMPT:?Передайте ограниченное задание}"

mkdir -p "$RUN_DIR"

set +e
gemini -p "$PROMPT" --output-format json \
  >"$RUN_DIR/agent.stdout.json" \
  2>"$RUN_DIR/agent.stderr.log"
agent_status=$?
set -e

printf '%s\n' "$agent_status" >"$RUN_DIR/agent.exit-status"

if [ "$agent_status" -ne 0 ]; then
  echo "Gemini CLI завершился с ошибкой; сборка не запускается"
  exit "$agent_status"
fi

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

Для первой пробы дополнительно сохраните:

• текст запроса или его безопасную копию без секретов;
• commit до запуска и git diff после него;
• время начала и окончания задания, заданные CI;
• путь к рабочей копии и каталог результатов;
• статус процесса Gemini CLI и причину пропуска следующих шагов.

Как ограничить автоматическую задачу, если некому подтвердить действия вручную? Настройте допустимые операции и область доступа до запуска. Не считайте отсутствие интерактивного подтверждения разрешением выполнять любые команды: режим без диалога должен работать с заранее заданными границами, а не подменять процедуру принятия риска.

Проверьте действующие механизмы и правила по документации Gemini CLI о policy engine. Затем отдельно проверьте, как в вашей конфигурации устроена изоляция, используя официальное описание sandbox. Наличие настройки sandbox не доказывает, что весь процесс безопасен: важны реальные каталоги, разрешённые команды, сетевой доступ и учётная запись, от имени которой работает узел.

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

4. Проверка Xcode: как отделить сборку от вывода Agent?

Вынесите действия Xcode в явный скрипт, которым управляет CI-оркестратор. В нём укажите проект или workspace, схему и подходящее назначение сборки из конфигурации проекта. Не подставляйте эти параметры из свободного ответа Gemini CLI: их следует задавать как проверенные значения для задания.

Для сборки используйте соответствующую команду xcodebuild и сохраняйте её вывод вместе с кодом завершения. Для тестов запускайте отдельный шаг с параметром test, а результат сохраняйте в bundle, заданный через -resultBundlePath. Параметр назначения (-destination) зависит от проекта и доступной среды исполнения; его нужно проверять для конкретной схемы, а не копировать универсальное значение из примера.

Условный фрагмент:

set -u

: "${PROJECT_OR_WORKSPACE:?Нужен путь проекта или workspace}"
: "${SCHEME:?Нужно имя схемы}"
: "${DESTINATION:?Нужно назначение сборки}"
: "${RUN_DIR:?Нужен каталог результатов}"

mkdir -p "$RUN_DIR"

set +e
xcodebuild \
  -project "$PROJECT_OR_WORKSPACE" \
  -scheme "$SCHEME" \
  -destination "$DESTINATION" \
  build \
  >"$RUN_DIR/xcodebuild-build.log" 2>&1
build_status=$?
set -e

printf '%s\n' "$build_status" >"$RUN_DIR/build.exit-status"
test "$build_status" -eq 0

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

Для тестового запуска создайте отдельный путь bundle результатов, который не конфликтует с уже существующим результатом задания:

xcodebuild \
  -project "$PROJECT_OR_WORKSPACE" \
  -scheme "$SCHEME" \
  -destination "$DESTINATION" \
  -resultBundlePath "$RUN_DIR/tests.xcresult" \
  test \
  >"$RUN_DIR/xcodebuild-test.log" 2>&1

Проверьте, что каталог результатов действительно появился и его можно сохранить как артефакт задания. Не объявляйте тесты успешными только потому, что команда завершилась или Gemini CLI написал о предполагаемом успехе. Apple отдельно описывает запуск тестов и интерпретацию результатов в руководстве по тестированию Xcode. Следуйте этим правилам для разбора тестового результата, а не заменяйте его пересказом Agent.

Минимальная цепочка доказательств должна включать четыре различимых элемента:

• текстовый ответ CLI и его код завершения;
• сохранённый diff относительно исходного commit;
• лог xcodebuild и его статус;
• тестовый результат Xcode, если запускались тесты.

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

5. Перед подключением к CI: ограничение доступа Agent

Сделайте отдельную учётную запись для процесса и выделите ей только рабочую область проекта и необходимые каталоги результатов. Разрешённые команды должны соответствовать задаче: если Agent требуется анализировать код, не предоставляйте ему возможность управлять публикацией или менять системные настройки. Если в CI используются независимые шаги для Gemini CLI и Xcode, не передавайте одному процессу полномочия другого.

Проверьте конфигурацию по каждому типу доступа:

• Файлы: чтение только нужной части репозитория; запись — в рабочую копию, где изменения можно проверить и отклонить.
• Команды: перечень допустимых инструментов, правила для неизвестных команд и поведение при запросе подтверждения.
• Сеть: доступ только к тем ресурсам, без которых конкретная задача не выполняется; не открывайте произвольное соединение по умолчанию.
• Credentials: минимальные полномочия и отдельное хранение секретов; значения не помещаются в текст запроса или журналы.
• Подпись и публикация: сертификаты и ключи выпуска не следует по умолчанию открывать Agent. Выпуск оставляйте отдельному контролируемому процессу.

Посмотрите, какие решения о вызове инструментов может применять policy engine, и не полагайтесь на само название режима или параметра: поведение зависит от текущей конфигурации и версии. Аналогично sandbox нужно проверить практическим тестом на доступ к файлам вне рабочей области. Если тест не подтверждает ожидаемую границу, считайте изоляцию неподтверждённой.

Что проверять, если автоматический запуск не может ждать человека? Определите отказ по умолчанию. Неоднозначная команда, недоступная авторизация или отсутствующий результат проверки должны останавливать задание; переход к следующему шагу разрешайте только при выполнении явных условий. Сохраните сведения, по которым после инцидента можно установить, какой процесс читал или менял файлы.

Для GitHub Actions сохраняйте секреты в механизме CI, а не в репозитории, команде запуска или файле, доступном Agent. Сам факт использования GitHub Actions не гарантирует изоляцию Mac-узла: отдельно контролируйте пользователя, рабочую директорию, очистку после задания и доступ к соседним проектам. Если узел обслуживает несколько потоков работы, исключите одновременную запись в одну и ту же рабочую копию и повторное использование результатов предыдущего задания.

6. Приёмка: условия пробного и рабочего запуска

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

Используйте чек-лист перед переводом задания в регулярную цепочку:

• [ ] Зафиксированы commit, схема, назначение и состояние зависимостей.
• [ ] Gemini CLI запускается предусмотренным неинтерактивным способом, его вывод и ошибки сохранены раздельно.
• [ ] Изменения Agent видны в diff и ограничены ожидаемой областью.
• [ ] Сборка запускается отдельным скриптом, а не подтверждается ответом Agent.
• [ ] Тестовый результат Xcode сохранён и доступен для последующей проверки.
• [ ] Ошибка авторизации, CLI, сборки или тестов приводит к остановке, а не к ложному успеху.
• [ ] Учётная запись, разрешённые каталоги и команды соответствуют минимально необходимым правам.
• [ ] После перезапуска узла восстанавливаются требуемые инструменты и способ авторизации; секреты не оказываются в артефактах.
• [ ] Повторный запуск оставляет достаточно данных, чтобы сопоставить изменения, статусы и результаты.

Принимайте решение по наблюдаемым доказательствам:

• Продолжайте пробный запуск, если права ещё не проверены, восстановление после перезапуска не испытано или артефакты неполны.
• Оставьте двойной процесс, если сборка стабильна, но изменения Agent требуют обязательного ревью: сначала проверка человеком, затем Xcode.
• Рассматривайте включение в рабочий CI, только если тот же сценарий воспроизводимо выдаёт понятный diff, независимый статус xcodebuild, доступный тестовый результат и корректное поведение при ошибке.

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

Если вам нужен временный изолированный узел для проверки Gemini CLI и Xcode CI, аренда Mac у KVMFLUX может дать более удобный путь, чем покупка отдельного компьютера ради короткого пилота. Это разумно, если вы предварительно подтвердили нужный инструментальный набор и требования к постоянной работе; для длительной неизменной нагрузки или обязательного физического оборудования сначала сравните аренду с собственным Mac. Решение о включении Agent в основной CI принимайте только после повторного теста с ограниченными правами и проверяемыми результатами.