Swift Package Manager: не удаётся загрузить приватную зависимость? Исправление CI для предприятий 2026

Не удаляйте кэш и не выдавайте общий ключ доступа, если приватная зависимость Swift Package Manager не загружается в CI: сначала зафиксируйте Package.resolved, затем проверьте фактическую учётную запись CI и только после этого исследуйте кэш. Для каждого доверенного домена используйте отдельную read-only SSH-идентичность, а узел разрешения зависимостей отделяйте от узла производственной подписи, если на общем Mac нельзя разделить аккаунты, рабочие каталоги и секреты.

Эта схема подходит руководителям, которые сопровождают iOS/macOS-проекты с приватными пакетами и разбирают ситуацию «у разработчика работает, в CI — ошибка». Она также нужна платформенным инженерам, управляющим Jenkins, GitHub Actions, GitLab или собственными Mac Agent, а также специалистам по безопасности и IT, проверяющим доступ к репозиториям, ключам подписи и удалённым Mac.

SECTION 01 Сначала определите границу сбоя: что проверять в первый час

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

Apple отдельно описывает сборку Swift-пакетов и приложений с ними в непрерывной интеграции, включая необходимость управляемого разрешения зависимостей и работу CI-пользователя с приватными репозиториями. Сверяйте корпоративный процесс с официальным руководством Apple по Swift Package Manager в CI, а не с результатом интерактивного запуска от имени администратора.

Временная шкала диагностики

Первые 15 минут — зафиксировать исходные условия. Сохраните commit, путь к проекту или workspace, команду запуска, имя macOS-пользователя, URL неудачного endpoint и код завершения. Не заменяйте реального сервисного пользователя локальным запуском из Terminal: это уже другой контекст HOME, SSH-конфигурации и доступа к Keychain.

Следующие 30 минут — разделить четыре фазы.

Фаза проверки	Что сохранять в журнале	Что это исключает
Разрешение версий	commit, `Package.resolved`, сообщение Swift Package Manager	самопроизвольное изменение графа зависимостей
Git-соединение	hostname, способ доступа, результат SSH-проверки	неправильный URL, `known_hosts`, ключ или права
Загрузка бинарного пакета	endpoint, тип артефакта, ответ сервера	ошибочное предположение, что проблема только в Git
Компиляция	команда `xcodebuild`, target, полный exit status	смешение ошибки скачивания и ошибки исходного кода

К концу первого часа — передать владельцу компонента таблицу фактов. В ней должны быть команда воспроизведения, выполняющий аккаунт, конкретный endpoint и exit status. Без этих четырёх полей команда приложения, владелец компонента и CI-платформа будут повторять разные тесты и давать несовместимые выводы.

Сервис Swift Package Manager использует описание зависимостей из Package.swift, а зафиксированное состояние разрешения хранится в Package.resolved. Для понимания роли самого объявления зависимости полезно свериться с документацией Apple о Package.Dependency.

SECTION 02 Почему локальная машина загружает пакет, а CI — нет?

Наиболее частая причина — не «нестабильная сеть», а несовпадение контекста исполнения. Разработчик может иметь SSH-ключ в личном ~/.ssh, уже принятый host key, сохранённые учётные данные или разрешение на чтение нескольких репозиториев. Сервисный аккаунт CI видит другой HOME, другой known_hosts, другой ssh-agent и может не иметь доступа даже к тому же URL.

Ответственность приложения: зафиксировать граф зависимостей

Команда приложения должна проверить, что Package.resolved находится в ожидаемом проектом или workspace месте и добавлен в систему контроля версий. Сам файл не заменяет корректные права доступа, но не позволяет производственному CI молча получить иной набор версий.

Для автоматического обновления зависимостей и воспроизводимой сборки нужны разные рабочие процессы:

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

Документация Swift Package Manager описывает разрешение версий и обновление графа; используйте официальное описание разрешения версий, чтобы согласовать поведение команды приложения с политикой релизной ветки.

Критерий передачи в CI-команду: тот же commit должен пройти минимальную задачу разрешения в чистом workspace, но под реальным сервисным аккаунтом. Если ошибка появляется только после смены пользователя, причина находится в доступе или окружении, а не в состоянии рабочей копии разработчика.

Ответственность владельца приватного компонента: проверить не только верхний уровень

Проверьте весь граф:

прямые зависимости приложения;
транзитивные пакеты;
приватные репозитории, вызываемые бинарными Target;
отдельные endpoints для исходников, бинарных архивов и package registry;
старые URL после переименования или переноса репозитория.

Верхнеуровневый Package.swift может выглядеть корректно, пока транзитивный пакет обращается к другому домену или использует устаревший адрес. Сведения о добавлении зависимостей и допустимых формах объявления сверяйте с документацией Swift Package Manager о зависимостях.

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

Важное ограничение: успешный git clone из административного Terminal доказывает только доступ администратора. Он не доказывает, что xcodebuild увидит тот же ключ, тот же HOME и ту же конфигурацию SSH.

SECTION 03 Как проверить SSH-контекст реального CI-пользователя?

Первый шаг: воспроизвести запуск от имени сервиса

Выполняйте проверку на том Mac, где действительно запускается xcodebuild, и под тем же macOS-аккаунтом. Зафиксируйте:

whoami
printf '%s\n' "$HOME"
ssh -G git.example.invalid
git config --show-origin --list

Вместо git.example.invalid подставьте фактический hostname приватного Git-сервера. Команды нужны не для диагностики «вообще», а для сравнения с интерактивной машиной разработчика. Если сервис запускается через Jenkins, GitHub Actions, GitLab Runner или другой агент, проверяйте окружение внутри задания, а не в отдельной SSH-сессии.

Второй шаг: проверить минимальный доступ без публикации секрета

Используйте тест, который подтверждает личность и доступ, но не выводит приватный ключ:

ssh -T git@git.example.invalid
git ls-remote git@git.example.invalid:team/private-package.git

Замените путь на реальный read-only репозиторий. В журнале оставляйте hostname, статус и текст ошибки, но не содержимое ключа, токены и секретные переменные. Если ssh -T проходит, а git ls-remote завершается отказом, проверяйте авторизацию на уровне конкретного репозитория, а не только регистрацию ключа на сервере.

Третий шаг: проверить локальную конфигурацию SSH

CI-команда должна отдельно подтвердить:

что HOME указывает на каталог сервисного аккаунта;
что known_hosts доступен без интерактивного подтверждения;
что конфигурация SSH выбирает нужный alias и ключ;
что права на файл ключа не позволяют другим локальным пользователям читать его;
что ssh-agent действительно существует в момент запуска;
что системная Git-конфигурация, proxy и URL rewrite применяются именно к этому процессу.

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

Если проект использует package registry, SSH-тест к Git не будет достаточным доказательством. Официальное описание использования package registry в Swift Package Manager помогает отделить registry-аутентификацию от доступа к Git-репозиторию.

Четвёртый шаг: проверить именно `xcodebuild`

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

xcodebuild \
  -workspace App.xcworkspace \
  -scheme App \
  -resolvePackageDependencies

Пути, имя workspace и scheme замените на значения конкретного проекта. Не считайте успешный git ls-remote достаточным: xcodebuild может использовать иной SCM Provider, другой каталог проекта или другую рабочую среду. Если платформа задаёт системную Git-конфигурацию или URL mapping, это должно быть описано в конфигурации задания и проверено после перезапуска агента.

Пятый шаг: повторить проверку после перезапуска

После исправления выполните три независимых теста:

разрешение зависимостей;
минимальную компиляцию без публикации;
повторный запуск после перезагрузки или повторного запуска агента.

Последний тест выявляет решения, которые работают только благодаря временному ssh-agent, интерактивному подтверждению host key или остаточному окружению. В отчёте укажите commit, аккаунт, workspace, endpoint и exit status каждого теста.

SECTION 04 Как разделить кэш, учётные данные и производственную подпись?

Что делать с кэшем Swift Package Manager

Кэш следует рассматривать как ускоритель, а не как источник истины. Если сборка проходит только на старом узле, сначала выполните успешное разрешение с зафиксированным Package.resolved, затем повторите его в чистом workspace. Полное удаление кэша до сохранения журнала может уничтожить единственное доказательство того, что узел использовал устаревший или частично загруженный объект.

Используйте такую последовательность:

сохранить логи и идентификатор commit;
проверить Package.resolved;
проверить доступ сервисного аккаунта;
повторить разрешение в текущем workspace;
выполнить чистую проверку на новом или очищенном узле;
только после этого определить политику сохранения кэша.

Если чистая проверка ломается, но повторная с кэшем проходит, передавайте вопрос владельцу компонента и платформенной команде вместе с endpoint и статусом, а не называйте это «случайной ошибкой сети».

Почему общий ключ опаснее отдельной настройки

Ключ для чтения приватного исходного кода нельзя объединять с Apple signing key, release API credential или общим администраторским аккаунтом. Для каждого доверенного домена задайте собственную read-only идентичность, ограничьте разрешения на уровне нужных репозиториев и сохраняйте записи создания, ротации и отзыва.

Внешние pull request и непроверенные ветки не должны автоматически получать доступ к производственным приватным пакетам и signing-узлу. Безопасная граница обычно требует как минимум раздельных сервисных аккаунтов, отдельных рабочих каталогов и независимого ввода секретов. Если общий Mac не позволяет надёжно реализовать эти границы, его нельзя использовать для всех задач только ради экономии узлов.

Официальные документы Swift Package Manager также описывают registry и конфигурацию публикации; описание registry-модели полезно при проектировании отдельного доверенного контура для пакетов, которые не должны загружаться из обычного Git-контекста.

SECTION 05 Кто принимает решение о восстановлении и разделении узлов?

Используйте следующий список условий, а не общее правило «добавим ещё один Mac»:

Если Package.resolved зафиксирован, сервисный аккаунт имеет read-only доступ, workspace очищается между задачами, а signing secrets не доступны задаче разрешения, выбирайте текущий узел и оформляйте повторяемую проверку после перезапуска.
Если разрешение зависимостей и подпись используют один аккаунт или один каталог секретов, переходите на раздельные контуры до расширения нагрузки.
Если приватные пакеты принадлежат нескольким доверенным доменам и им нужны разные ключи, создавайте отдельные SSH-профили и минимальные права, а не общий ключ для всей команды.
Если ошибка исчезает только после восстановления старого кэша, откладывайте увеличение ёмкости и сначала проводите чистую проверку.
Если внешний PR должен собираться, но не должен видеть приватные пакеты или production signing, выбирайте непроизводственный Mac Agent с отдельной политикой доступа.
Если после перезапуска агент теряет SSH-контекст, исправляйте доставку конфигурации и секретов; не компенсируйте дефект ручным входом администратора.

Приёмка нового или удалённого Mac

Для нового узла оформите milestone-план: доставка среды, создание сервисного аккаунта, ввод SSH-конфигурации, проверка Package.resolved, первая чистая компиляция, перезапуск и повторная проверка. Каждый этап должен иметь ответственного, commit, журнал и условие передачи следующей команде.

Удалённый Mac удобен для такого теста только при фактическом разделении аккаунтов, ключей и workspace. До заказа проверьте, как вы получите доступ через справочный центр VPSNIX, кто отвечает за переинициализацию узла и как фиксируется замена машины. Это организационная часть CI, а не замена SSH-диагностике.

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

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

На практике локальная машина разработчика в этой ситуации неудобна по трём причинам: её SSH-контекст персонален, кэш скрывает воспроизводимость, а доступ к signing assets трудно отделить от повседневной работы. Общий физический Mac дешевле лишь до тех пор, пока не возникает конфликт аккаунтов, ручное восстановление после сбоя или необходимость срочно заменить узел. Если вам нужен временный изолированный контур для чистой проверки после исправления Package.resolved и сервисного доступа, удалённый Mac VPSNIX может дать более управляемую точку эксперимента; для постоянной тяжёлой нагрузки, физического оборудования и строгого контроля площадки сначала сравните аренду с собственной инфраструктурой.

Итоговый порядок для приватных зависимостей Swift Package Manager в CI остаётся неизменным: зафиксируйте граф, воспроизведите ошибку под реальным аккаунтом, проверьте все endpoints, отделите зависимости от подписи и только затем принимайте решение о кэше или новом узле.