Руководство по настройке сборок команды

Подключите runner — следуйте этому руководству

Весь Mac mini на Apple Silicon M4 работает только для задач вашей команды. Сначала проверьте экземпляр и подключение, затем зарегистрируйте runner и закрепите инструментарий Xcode. Разбирайте проблемы по этапам, не перезапуская весь конвейер.

Арендовать узел сборки Мои экземпляры

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

От заказа до подключения

Четыре контрольные точки для настройки узла

Обычно проверка занимает около 4 минут — от подтверждения оплаты до получения и проверки учётных данных для подключения. Указанное время ориентировочное: оно не включает подтверждение платёжным шлюзом, повторные сетевые попытки, установку зависимостей и регистрацию runner. Ориентируйтесь на данные в панели управления.

Проверьте подтверждённый заказ
Около 30 секунд

Убедитесь в панели управления, что заказ оплачен, а модель, срок и узел соответствуют покупке. Merge M4 S оснащён 16GB RAM / 256GB SSD, Merge M4 L — 24GB RAM / 512GB SSD. Обе модели работают на Apple Silicon M4.

Застряли на этом шаге? Сначала проверьте статус счёта. Если страница ещё не обновилась, не платите повторно. Сохраните номер заказа и сверьте запись об оплате в разделе счетов на этой странице.
Проверьте назначение физического узла
Около 2 минут

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

Застряли на этом шаге? Запишите ID экземпляра, номер заказа и текущий статус, затем создайте обращение через панель управления. Не считайте, что учётные данные экземпляра уже созданы, только потому что счёт оплачен.
Получите учётные данные для подключения
Около 1 минуты

В сведениях об экземпляре найдите адрес SSH, порт, имя пользователя и данные для подключения по VNC. Используйте значения из соответствующих полей. Не угадывайте порт по умолчанию и не используйте адрес или пароль от старого экземпляра.

Застряли на этом шаге? Убедитесь, что заказ принадлежит аккаунту, в который вы вошли, и что открыт нужный экземпляр. В обращении укажите только ID экземпляра и название отсутствующего поля — не отправляйте пароль целиком.
04
Проверьте удалённое подключение
Около 30 секунд
SSH подходит для сборок в командной строке, регистрации runner и синхронизации файлов; VNC — для графического интерфейса Xcode, симуляторов и интерактивной настройки. Используйте macOS как через графический интерфейс, так и из командной строки — эти способы дополняют друг друга.
```
ssh -p "$SSH_PORT" "$SSH_USER@$SSH_HOST"
uname -m
sw_vers
```
При первом подключении проверьте отпечаток хоста. После успешного входа убедитесь, что архитектура указана как arm64. При тайм-ауте проверьте адрес, порт и локальную сеть; при ошибке аутентификации — имя пользователя и учётные данные. Не отключайте проверку подлинности хоста, чтобы обойти предупреждение о несовпадении отпечатка.

В клиенте VNC используйте соответствующие поля из сведений об экземпляре, а не порт SSH. Если подключение установлено, но изображение обновляется медленно, уменьшите разрешение. Автоматические сборки можно продолжать запускать по SSH.

Проверить экземпляр и учётные данные Инструкция по удалённому подключению

Используйте существующую CI команды

Направьте задачи на этот M4

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

GitHub Actions

Добавьте self-hosted runner в настройках репозитория или организации и выберите пакет для macOS и ARM64. Распакуйте его, выполните в каталоге runner команду настройки от платформы, затем запустите процесс.

./config.sh \
  --url "$RUNNER_URL" \
  --token "$RUNNER_TOKEN" \
  --labels macos-m4
./run.sh

Укажите в рабочем процессе runs-on: [self-hosted, macOS, ARM64, macos-m4]и убедитесь, что метка совпадает с указанной при регистрации. Метка направляет задачи на нужный узел, но сама по себе не изолирует задачи друг от друга.

Проверка: платформа показывает статус «В сети», а команда uname -m в тестовой задаче выводит arm64. Если runner должен работать постоянно, настройте службу по инструкции к установочному пакету и запускайте её от имени того же пользователя, который выполняет сборки.

Рекомендуемая метка: macos-m4

GitLab Runner

Создайте runner в проекте или группе и получите токен аутентификации для используемой версии. Установите версию для ARM64 и зарегистрируйте runner, выбрав shell executor, чтобы задачи выполнялись в среде macOS от имени пользователя сборки.

gitlab-runner register
gitlab-runner verify
gitlab-runner run

Назначьте runner метку macos-m4 в настройках платформы и укажите такое же значение в поле tags . При интерактивной регистрации введите адрес и токен, предоставленные платформой. Не сохраняйте токен в репозитории.

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

Способ выполнения: shell

Jenkins agent

Создайте выделенный узел, укажите удалённый рабочий каталог и метку macos-m4 . Установите совместимую версию Java по инструкции контроллера, скачайте предоставленный им файл agent и используйте сгенерированные параметры запуска.

java -jar agent.jar \
  -url "$JENKINS_URL" \
  -secret "$AGENT_SECRET" \
  -name "$AGENT_NAME" \
  -webSocket \
  -workDir "$AGENT_WORKDIR"

Укажите в конвейере agent { label 'macos-m4' }. Пользователь сборки должен иметь права на запись в рабочий каталог. Версия Java должна соответствовать требованиям контроллера: недостаточно проверить, что Java запускается в локальном терминале.

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

Сначала проверьте одну задачу

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

Закрепите воспроизводимую среду

Используйте одну версию Xcode локально и в CI

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

Перед переключением запишите версии

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

sw_vers
xcode-select -p
xcodebuild -version
xcrun --find swift

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

sudo xcode-select --switch \
  /Applications/Xcode.app/Contents/Developer
xcodebuild -version

Выбирайте версию для каждой задачи, скачивайте под нужный проект

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

export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
xcodebuild -version
xcrun simctl list runtimes
xcrun simctl list devices available
df -h

Загрузите среду выполнения симулятора в настройках Xcode с учётом требований проекта. Среды выполнения, данные симуляторов и DerivedData занимают место на диске. Перед установкой проверьте свободное пространство и оставьте только версии, которыми действительно пользуется команда.

Работающие команды ещё не означают, что установлены все зависимости проекта. От имени того же пользователя проверьте Ruby, CocoaPods, менеджер пакетов и lock-файлы проекта. Подтверждайте запросы при первой установке в интерактивной среде.

Перед первой сборкой проверьте три пункта в среде выполнения runner
Что проверить	Команда или расположение	Условие успешной проверки
Путь к инструментарию	`xcode-select -p` и переменные среды задачи	Указан требуемый проектом Xcode, версия соответствует ожиданиям
Пользователь запуска	`whoami`и`printf '%s\n' "$HOME"`	Пользователь сборки, владелец домашнего каталога и владелец связки ключей совпадают
Рабочая область и диск	`pwd`и`df -h`	В рабочую область можно записывать, для зависимостей, временных файлов и архивов достаточно места

Говорите с командой на одном языке

Восемь терминов — восемь чётких различий

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

Физический узел: Устройство Mac mini, на котором работают macOS и задачи сборки. Данные для подключения в сведениях об экземпляре относятся к арендованному вами узлу.
Выделенный: Вся машина назначается одному клиенту: CPU не распределяется между клиентами. Команда по-прежнему должна самостоятельно управлять параллельным выполнением задач.
Не виртуальная машина: Вы получаете среду на выделенном физическом Mac, а не виртуальный экземпляр на общем хосте.
VNC: Способ удалённо просматривать графический интерфейс macOS и управлять им. Подходит для Xcode, симуляторов и интерактивной настройки.
SSH: Зашифрованное подключение к командной строке для запуска сборок, управления процессами и передачи файлов с помощью соответствующих инструментов.
self-hosted runner: Исполнитель CI, который команда регистрирует и администрирует на собственном узле. Он получает задачи от CI-платформы и выполняет их.
Apple Silicon: Архитектура чипов Apple в Mac. Обе модели этой услуги работают на M4. При выборе зависимостей и установочного пакета runner проверьте поддержку arm64.
Объединение через Thunderbolt 5: Дополнительная услуга с оплатой за каждую машину. Она не объединяет CPU и память нескольких машин в один узел — рабочую нагрузку по-прежнему нужно распределять самостоятельно.

Сохраните журналы, затем меняйте среду

Восстановите сборку, определив уровень ошибки

Сохраните команду с ошибкой, код возврата и первую содержательную ошибку, затем меняйте только одну настройку за раз. Не переключайте Xcode, не удаляйте кэш и не регистрируйте runner заново одновременно — иначе будет сложно понять, что именно помогло.

Не удаётся подписать: сначала проверьте пользователя и связку ключей

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

whoami
security list-keychains -d user
security find-identity -v -p codesigning

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

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

Проблема с кэшем: очистите только для одного проекта

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

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

xcodebuild \
  -workspace "$WORKSPACE" \
  -scheme "$SCHEME" \
  -derivedDataPath "$PROJECT_DERIVED_DATA" \
  clean build

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

Не хватает места на диске: проверьте кэш, среды выполнения и артефакты

Сначала проверьте свободное место, затем выясните, сколько занимают DerivedData, архивы и данные симуляторов. Не удаляйте рекурсивно весь домашний каталог и не очищайте артефакты во время загрузки архива.

df -h
du -sh "$HOME/Library/Developer/Xcode/DerivedData"
du -sh "$HOME/Library/Developer/Xcode/Archives"
du -sh "$HOME/Library/Developer/CoreSimulator"

Остановите связанные задачи, удалите кэш проектов, который больше не используется, и удалите ненужные среды выполнения в Xcode. Архивы с резервной копией обрабатывайте согласно правилам хранения команды. Отдельно создайте резервные копии проекта, материалов для подписи и артефактов выпуска.

Если в долгосрочной перспективе нужно больше места, при оформлении заказа можно добавить SSD на +1TB или +2TB. Увеличение хранилища не добавляет оперативную память. Сначала убедитесь, что узкое место — диск, а не параллельные задачи.

Runner не в сети: проверьте подключение, процесс и доступ по очереди

Сначала по SSH убедитесь, что узел доступен, затем проверьте процесс runner и журналы. Если узел в сети, а CI-платформа показывает runner отключённым, выясните, не завершился ли процесс, доступна ли сеть до контроллера CI и не изменились ли токен или разрешения узла.

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

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

Если используется несколько групп узлов или пулов, назначьте им различимые метки, например macos-m4-build и macos-m4-release, чтобы задачи выпуска направлялись только на узлы с настроенной для них средой подписи.

Сначала сверьте платёж, затем повторяйте попытку

Сопоставьте платёж с заказом

Оплата доступна за день, неделю, месяц или квартал; расчёты ведутся в долларах США (USD). Принимаются только USDT-TRC20 и карты Visa / Mastercard / Amex через Stripe. Доступный платёжный шлюз определяется ответом серверного интерфейса.

USDT-TRC20 отправлен, заказ всё ещё ожидает подтверждения

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

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

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

Оплата картой не завершена: проверьте проверку и ответ банка

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

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

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

Перед продлением проверьте экземпляр, период и дату окончания

Откройте в панели управления подписку или счёт, связанный с нужным экземпляром. Перед оплатой сверьте ID экземпляра, дату окончания и оплачиваемый период. Новый заказ и продление существующего экземпляра — разные операции; не ориентируйтесь только на название модели.

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

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

Укажите данные, которые помогут воспроизвести проблему

Передайте поддержке данные о сбое

Если проблема с существующим экземпляром, создайте обращение через панель управления. Укажите ID экземпляра, время и часовой пояс, шаги, на которых произошёл сбой, ожидаемый результат и журнал без чувствительных данных. Для запуска нескольких узлов или планирования пула runner опишите задачу на странице контактов либо напишите на support@vpsmerge.com.

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

Создать обращение в панели управления Подготовить запрос команды