Как настроить корпоративный прокси Swift Package Manager? Руководство по Mac CI 2026

Корпоративный прокси для Swift Package Manager нужно настраивать не одной переменной HTTP_PROXY, а по карте потоков: исходный Git, Swift Package Registry, бинарные артефакты и сервисы Apple требуют раздельной проверки. На этой неделе сначала зафиксируйте реальную CI-учётную запись и чистую сетевую трассу, затем настройте Git, сертификаты и исключения; узел, который не удаётся надёжно включить в корпоративную политику, перенесите в отдельный пул удалённых Mac.

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

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

Мы начинаем не с добавления сертификата, а с карты зависимости:

• Исходный Git — репозитории, откуда Swift Package Manager получает исходный код. Для HTTPS важны Git-конфигурация, прокси и доверие к сертификату. Для SSH дополнительно проверяются ~/.ssh/config, ключ и доступность соответствующего канала.
• Swift Package Registry — отдельный путь публикации и получения пакетов. Для него нужно проверить адрес Registry, формат авторизации и правила, описанные в официальной документации Swift Package Registry.
• Бинарные Target и артефакты — загрузки, которые могут идти не тем же клиентом, что исходный Git. Успешное клонирование репозитория не подтверждает доступность бинарного содержимого.
• Сервисы Apple — обновления, компоненты Xcode и другие обращения экосистемы Apple. Для них нельзя автоматически применять правила внутреннего Git или Registry: требования к корпоративной сети и HTTPS-перехвату необходимо сверять с документацией Apple по сетевым требованиям обновлений.

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

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

Зафиксируйте:

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

Здесь важно не смешивать пять разных областей:

1. системный прокси macOS;
2. переменные HTTP_PROXY, HTTPS_PROXY и NO_PROXY;
3. настройки Git;
4. настройки SSH;
5. доверие к центру сертификации и секреты в Keychain.

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

Для Git сверяйте область действия и параметры прокси с официальным описанием Git FAQ и документацией Git по конфигурации HTTP и TLS. В рабочей документации команды достаточно минимальных проверок: какой конфигурационный файл читается, какой URL применяется и какой сертификат предъявляет конечная точка. Не переносите на общий узел личный прокси-токен, личный Keychain или полный профиль администратора.

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

• HTTPS Git через корпоративный прокси;
• SSH Git через разрешённый канал;
• Swift Package Registry с его способом авторизации;
• получение бинарного артефакта;
• обращение к сервису Apple.

Это не пять вариантов одной и той же команды. Успешный HTTPS-клон не подтверждает работоспособность SSH, а доступный Registry не подтверждает загрузку бинарного Target. Такой разбор позволяет связать ошибку с конкретным клиентом, сертификатом или правилом сети, а не расширять разрешения на весь узел.

Если сценарий сборки должен использовать системную конфигурацию Git, это нужно проверить именно в реальном процессе xcodebuild, а не только в интерактивной оболочке. Apple описывает сборку Swift-пакетов и приложений в CI в официальном руководстве по непрерывной интеграции. Практический критерий — процесс CI видит нужный Git, читает ожидаемую конфигурацию и разрешает зависимость из чистого каталога.

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

После сетевой проверки нужно исключить ситуацию, когда каждый запуск заново выбирает версии зависимостей. Файл Package.resolved должен находиться под контролем процесса разработки и поставляться в CI в соответствии с политикой репозитория. В материалах Apple о сборке пакетов в CI проверяется именно связка разрешения зависимостей и автоматизированной сборки, а не только доступ к одному URL.

Порядок действий такой:

1. Подготовьте чистую рабочую область без локального кэша, сохранённых незакоммиченных изменений и пользовательских настроек.
2. Передайте ей тот же commit, который будет использовать производственная задача.
3. Убедитесь, что Package.resolved находится там, где его ожидает проект.
4. Запустите разрешение зависимостей под сервисной учётной записью.
5. Зафиксируйте, какой поток был использован для каждого пакета.
6. Выполните xcodebuild с теми же параметрами, что и в реальном CI.
7. Сохраните журнал, в котором отдельно видны сетевое разрешение, загрузка, компиляция и тесты.

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

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

• какой целевой адрес разрешился и через какой маршрут;
• какую цепочку сертификатов видит фактический процесс;
• на каком этапе появляется отказ — прокси, TLS или приложение.

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

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

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

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

• получение исходного commit;
• разрешение Swift-зависимостей;
• загрузка требуемых бинарных компонентов;
• сборка через xcodebuild;
• запуск тестов;
• создание ожидаемого артефакта;
• сохранение журнала и признаков использованных потоков.

Приёмка должна разделять четыре результата:

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

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

• [ ] Зафиксирован фактический сервисный аккаунт CI и его домашний каталог.
• [ ] Составлена карта потоков для Git, Registry, бинарных артефактов и сервисов Apple.
• [ ] Для каждого потока указаны инструмент, маршрут, аутентификация и владелец политики.
• [ ] Отдельно проверены системный прокси macOS, переменные окружения, Git и SSH.
• [ ] Конфигурация Git подтверждена из процесса, который запускает реальную сборку.
• [ ] Внутренний центр сертификации установлен корпоративным способом, а не через отключение TLS-проверки.
• [ ] Apple-сервисы вынесены в отдельные правила HTTPS-перехвата и сетевого доступа.
• [ ] Package.resolved и поведение автоматического разрешения согласованы с политикой проекта.
• [ ] Чистая рабочая область успешно прошла разрешение, сборку, тесты и создание артефакта.
• [ ] Проверены перезапуск службы, повторная авторизация и ротация секретов.
• [ ] Документировано, что происходит при недоступности прокси.
• [ ] Производственные задачи отделены от экспериментальных до завершения серой эксплуатации.

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

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

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

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

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

Альтернативный вариант — проверить изолированный удалённый Mac по той же карте потоков. Такой узел не следует считать подходящим только из-за наличия macOS: сначала подтверждаются корпоративный Git, внутренний Registry, сертификаты, сервисная учётная запись и восстановление без ручного входа. Если все эти условия проходят, аренда JEXCLOUD позволяет начать с отдельного узла для пилота, не закупая оборудование до подтверждения сетевой совместимости. Доступные варианты размещения можно сопоставить на странице удалённых Mac JEXCLOUD для корпоративной проверки.

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