Что делать, если Xcode Cloud не загружает частные зависимости? Руководство по устранению неполадок 2026

Симптом → самое быстрое действие: если сборка Xcode Cloud не получает частные зависимости, сначала определите по отчёту, где именно возникает сбой — при доступе к репозиторию, разрешении пакетов или выполнении скрипта. Затем исправляйте только соответствующую ветку; сам факт использования частных пакетов не требует немедленно переносить CI.

Эта последовательность подходит инженерам, которые поддерживают рабочие процессы Xcode Cloud и внутренние Swift Package или Git-подмодули.
Руководители платформенной инженерии смогут проверить несколько репозиториев и настройки зависимостей.
IT-специалисты смогут оценить собственный Mac только тогда, когда выявлены конкретные требования к сети или инструментам, не покрываемые рабочим процессом.

Начните с этапа, на котором остановилась сборка

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

Для диагностики полезно разделять сборку на четыре наблюдаемых этапа:

• Получение исходного кода. Xcode Cloud клонирует проект, подмодули и необходимые репозитории. Ошибка здесь направляет проверку к подключению хранилища и авторизации.
• Разрешение зависимостей. Рабочая среда обрабатывает Swift Package и другие зависимости проекта. Ищите сообщения о недоступном пакете, URL источника, версии или файле фиксации.
• Подготовка и выполнение скриптов. Сценарии могут загружать файлы, подготавливать инструменты или обращаться к внутренним ресурсам. Проверьте строку команды, контекст выполнения и код выхода.
• Сборка средствами Xcode. Если предыдущие этапы завершились, а ошибка появилась уже во время сборки, причиной может быть конфигурация проекта или сам код, а не доступ к репозиторию.

В документации разработчика описаны ситуации, когда недоступность частных зависимостей или нужных сторонних инструментов может привести к неудачной сборке. Это объясняет возможную причину, но не доказывает, что именно она вызвала конкретный сбой. Сверяйте вывод с описанием подготовки зависимостей для Xcode Cloud и справочником по рабочим процессам, а причину подтверждайте повторяемым запуском после одного целевого изменения.

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

Xcode Cloud не загружает частные зависимости: проверьте область авторизации

Доступ к основному проекту не означает автоматически, что доступны все ресурсы, на которые он ссылается. Отдельную авторизацию могут потребовать Swift Package в частном репозитории, Git-подмодуль и репозиторий, к которому обращается скрипт. Установите соответствие между URL из конфигурации и местом хранения каждой зависимости.

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

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

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

Это не универсальный порядок управления корпоративными учётными записями: здесь проверяется только доступ рабочей среды к конкретному репозиторию. Подробные общие инструкции по правам пользователей не заменят проверку URL и состояния подключения самого ресурса.

Разрешение пакетов должно совпадать с зафиксированным состоянием проекта

Когда клонирование проходит, но сборка останавливается на Swift Package, проверьте Package.resolved до принудительного обновления зависимостей. Этот файл помогает зафиксировать выбранное состояние пакетов; если он отсутствует, не попал в ожидаемую ветку или хранится не там, где его ожидает проект, CI может разрешить зависимости не так, как команда проверила их локально.

Проведите проверку в таком порядке:

• Определите, в какой части проекта Xcode ожидает файл фиксации, и сравните это место с фактическим расположением Package.resolved.
• Проверьте, включён ли файл в нужный коммит и ветку, используемые рабочим процессом. Сравните содержимое коммита с текущей локальной копией проекта.
• Убедитесь, что файл относится к актуальной конфигурации проекта, а не к старой рабочей области или прежнему расположению пакетов.
• Посмотрите сообщение разрешения зависимостей в отчёте и сопоставьте указанный пакет с URL и состоянием версии, зафиксированными в проекте.
• После исправления пути или коммита повторите сборку без дополнительных обновлений, чтобы проверить только изменение фиксации.

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

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

Сторонние инструменты и скрипты требуют явной подготовки

Для CocoaPods, Carthage и других используемых проектом инструментов выясните, как именно рабочая среда получает нужные компоненты. Не полагайтесь на то, что программа уже установлена или что на конкретной машине сохранились файлы и настройки, которых нет в чистой среде сборки. Зафиксируйте способ установки, источник зависимостей и связанные lock-файлы в конфигурации проекта или подготовительном сценарии.

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

Для каждого сценария проверьте:

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

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

Сеть, переменные окружения и секреты проверяются по фактическим обращениям

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

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

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

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

Контрольный список перед повторным запуском

Используйте список как журнал изменений: отмечайте выполненные проверки и меняйте одну группу настроек за раз.

• [ ] В отчёте найден последний успешный этап и зафиксировано место, где появился первый относящийся к проблеме сбой.
• [ ] Для основного проекта, частного Swift Package, Git-подмодуля и запросов из скриптов записаны фактические адреса репозиториев.
• [ ] Проверено подключение каждого нужного сервиса или экземпляра, а не только основного репозитория приложения.
• [ ] Если отчёт предлагает предоставить доступ, авторизация выполнена для ожидаемого репозитория; результат проверен повторным запуском.
• [ ] Путь, коммит и состояние Package.resolved сопоставлены с проектом и веткой, которые собирает CI.
• [ ] Установка сторонних инструментов и наличие lock-файлов подтверждены для чистой среды сборки.
• [ ] Имена, пути, точки выполнения и коды выхода скриптов сверены с конфигурацией проекта.
• [ ] Внутренние URL, сетевые настройки и нужные переменные проверены без вывода секретов в журнал.
• [ ] После изменения повторён тест, который проверяет именно исправленную ветку, а не несколько независимых гипотез одновременно.

Если ошибки исчезают после подключения репозитория, изменения Package.resolved или подготовки инструмента, продолжайте использовать Xcode Cloud и зафиксируйте результат в документации рабочего процесса. Не переносите CI только потому, что проект использует закрытые зависимости: сначала подтвердите конкретное ограничение и воспроизводимость отказа.

Когда рассматривать собственную среду Mac

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

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

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

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

Часто задаваемые вопросы