CocoaPods Trunk: что это такое, публикация библиотек через Trunk

Что такое CocoaPods Trunk?

CocoaPods Trunk — это серверная инфраструктура, запущенная в 2015 году для централизованной публикации pod-библиотек. До появления Trunk каждый pod распространялся через Git-репозиторий: разработчику нужно было создать публичный репозиторий, добавить podspec-файл и отправить Pull Request в центральный репозиторий CocoaPods/Specs. Такой подход требовал ручного модераторства и создавал задержки при публикации обновлений.

Trunk решил эти проблемы, предоставив единый API для публикации, обновления и удаления подов. Сервис включает четыре ключевых компонента:

• Аутентификация — регистрация с email-подтверждением и управление сессионными токенами. Каждый разработчик получает уникальный токен, который привязывается к его аккаунту и устройствам.
• Валидация — автоматическая проверка podspec перед публикацией, включая синтаксический анализ, линтинг зависимостей и проверку совместимости платформ.
• Хостинг — хранение метаданных и версий подов на серверах CocoaPods. Исходный код по-прежнему размещается в Git-репозитории разработчика, а Trunk хранит только podspec-файлы и ссылки.
• Управление доступом — возможность добавлять и удалять владельцев пода, передавать права на публикацию, отмечать поды как устаревшие.

Архитектура Trunk построена на стеке Ruby on Rails с базой данных PostgreSQL. Сервис использует HTTP API с JSON-форматом для всех операций, а CLI-клиент pod trunk является частью дистрибутива CocoaPods и устанавливается вместе с основным гемом cocoapods.

На текущий момент через Trunk опубликовано более 100 000 подов, суммарное количество загрузок превышает 50 миллиардов. Ежедневно сервис обрабатывает тысячи запросов на публикацию и обновление библиотек от разработчиков по всему миру.

Регистрация и аутентификация

Перед публикацией пода необходимо пройти регистрацию в Trunk. Процесс состоит из одного шага — команды pod trunk register:

pod trunk register your@email.com 'Your Name' --description='MacBook Pro, разработка iOS'

После выполнения команды на указанный email приходит письмо со ссылкой для подтверждения. Переход по ссылке активирует аккаунт и создаёт сессионный токен, который сохраняется в системной связке ключей (Keychain на macOS, gnome-keyring или эквивалент на Linux). Токен автоматически используется при всех последующих операциях pod trunk.

Параметр --description необязателен, но рекомендуется — он помогает идентифицировать сессию при просмотре активных сессий через pod trunk me. Если вы работаете с нескольких машин (рабочая станция, CI-сервер), описание позволит отличить одну сессию от другой.

Для проверки статуса аутентификации используется команда:

pod trunk me

Вывод показывает email, имя, список ваших подов (если уже публиковали) и активные сессии. Пример результата:

  - Name: Your Name
  - Email: your@email.com
  - Since: 2024-03-15 10:30 UTC
  - Pods:
    - MyLibrary
    - AnotherPod
  - Sessions:
    - 2024-03-15 10:30 UTC - MacBook Pro, разработка iOS

На CI-серверах (GitHub Actions, GitLab CI, Jenkins) аутентификация выполняется через токен, переданный через переменную окружения COCOAPODS_TRUNK_TOKEN. Токен можно получить командой:

pod trunk me --token-only

Этот токен сохраняется в настройках CI как секретная переменная, и на этапе публикации указывается без повторной регистрации. Пример для GitHub Actions:

env:
  COCOAPODS_TRUNK_TOKEN: ${{ secrets.COCOAPODS_TRUNK_TOKEN }}

Важно: токен даёт полный доступ к управлению подами, привязанными к аккаунту. Никогда не публикуйте его в открытых репозиториях и не передавайте третьим лицам. При компрометации токен можно отозвать через pod trunk remove-session или удалить все сессии через панель управления на сайте CocoaPods.

Подготовка podspec

Podspec-файл (.podspec или .podspec.json) — это манифест библиотеки, содержащий метаданные, зависимости, информацию о платформах и исходном коде. Trunk использует этот файл для валидации и регистрации пода. Минимальный podspec для публикации выглядит так:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Краткое описание библиотеки'
  s.description  = 'Развёрнутое описание с пояснением возможностей'
  s.homepage     = 'https://github.com/username/MyLibrary'
  s.license      = { :type => 'MIT', :file => 'LICENSE' }
  s.author       = { 'Your Name' => 'your@email.com' }
  s.source       = { :git => 'https://github.com/username/MyLibrary.git', :tag => s.version.to_s }
  s.source_files = 'Sources/**/*.{swift,h,m}'
  s.platform     = :ios, '12.0'
  s.swift_version = '5.7'
end

Ключевые поля podspec:

• name — имя пода, должно быть уникальным в реестре Trunk. Имена регистрируются по принципу «первый занял» — если имя занято, публикация будет отклонена.
• version — семантическая версия в формате MAJOR.MINOR.PATCH. Trunk не принимает повторную публикацию той же версии — нужно увеличивать номер.
• source — ссылка на Git-репозиторий и тег. Trunk не хранит исходный код, поэтому репозиторий должен быть доступен для клонирования.
• platform — целевая платформа (iOS, macOS, tvOS, watchOS) и минимальная версия SDK.
• license — тип лицензии. Рекомендуется указывать MIT, Apache-2.0, BSD или другую открытую лицензию.

Перед публикацией podspec необходимо проверить на корректность с помощью линтера:

pod lib lint MyLibrary.podspec

Линтер проверяет синтаксис, наличие обязательных полей, корректность путей к файлам и разрешимость зависимостей. Если в процессе линтинга используются частные источники (private specs), добавляется флаг --sources. Для пропуска загрузки сети (только локальная проверка) используется флаг --local-only.

Публикация через pod trunk push

Основная команда для публикации пода — pod trunk push. Она передаёт podspec-файл на сервер Trunk, где проходит полную валидацию и регистрируется в публичном реестре. Синтаксис:

pod trunk push MyLibrary.podspec

Флаг --allow-warnings разрешает публикацию при наличии предупреждений. По умолчанию любые предупреждения (warnings) блокируют публикацию. Если библиотека имеет известные предупреждения, которые не влияют на функциональность, можно использовать этот флаг. Важно: ошибки (errors) всегда блокируют публикацию, независимо от флагов.

Флаг --synchronous делает запрос синхронным — терминал ожидает завершения валидации на сервере. По умолчанию команда возвращает управление сразу после отправки, а сервер обрабатывает публикацию асинхронно. Синхронный режим полезен в CI/CD, когда следующий шаг пайплайна зависит от успешности публикации.

Флаг --skip-import-validation пропускает проверку импорта библиотеки в тестовый проект. Это ускоряет публикацию, но не гарантирует, что библиотека действительно компилируется. Используйте этот флаг только если уверены в корректности сборки.

Пример публикации с типичными опциями:

pod trunk push MyLibrary.podspec \
  --allow-warnings \
  --synchronous \
  --skip-import-validation

После успешной публикации Trunk возвращает JSON с деталями:

  Congrats

  MyLibrary (0.1.0) successfully published

  Pod URL: https://cocoapods.org/pods/MyLibrary

Библиотека становится доступна для установки через Podfile любой iOS- или macOS-проекта. Обычно данные в поисковом индексе CocoaPods обновляются в течение нескольких минут, но в редких случаях индексация может занять до часа.

Важное ограничение: однажды опубликованную версию пода нельзя удалить. Это сделано для предотвращения поломок в проектах, которые уже используют эту версию. Если публикация прошла с ошибкой, можно опубликовать следующую версию с исправлением, но откат невозможен. Исключение — pod trunk delete, доступный только сотрудникам CocoaPods и применяется в крайних случаях (нарушение лицензии, вредоносный код).

Управление релизами и доступом

CocoaPods Trunk предоставляет несколько команд для администрирования опубликованных подов:

Добавление владельцев

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

pod trunk add-owner MyLibrary developer@email.com

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

Удаление владельцев

Если разработчик покинул проект или больше не должен иметь доступ к поду:

pod trunk remove-owner MyLibrary developer@email.com

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

Отметка пода как устаревшего

Если библиотека больше не поддерживается, её можно пометить как устаревшую (deprecated). Это не удаляет под из реестра, но добавляет предупреждение пользователям при установке:

pod trunk deprecate MyLibrary

Опционально можно указать под-замену:

pod trunk deprecate MyLibrary --in-favor-of=NewLibrary

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

Просмотр информации о поде

Информация о поде доступна через команду pod trunk info:

pod trunk info MyLibrary

Команда показывает все версии пода, даты публикации, список владельцев и статус (активен/устарел). Для просмотра деталей конкретной версии используется pod spec cat MyLibrary 0.1.0.

Ошибки и их решение

При работе с Trunk разработчики часто сталкиваются с типовыми ошибками. Рассмотрим наиболее распространённые:

Ошибка аутентификации

Симптом: [!] Authentication failed. You need to register a session first.
Причина: Отсутствует или истёк сессионный токен. Токены имеют ограниченный срок действия (по умолчанию 30 дней без активности).
Решение: Повторно выполнить pod trunk register your@email.com 'Your Name'. Если вы используете CI, проверьте актуальность переменной COCOAPODS_TRUNK_TOKEN и при необходимости сгенерируйте новый токен.

Конфликт версий

Симптом: [!] You have already pushed version 0.1.0 for MyLibrary.
Причина: Попытка повторной публикации существующей версии. Trunk не позволяет перезаписывать версии.
Решение: Увеличить версию в podspec в соответствии с семантическим версионированием. Если вы ошиблись в podspec, опубликуйте следующую версию с исправлением.

Ошибка валидации podspec

Симптом: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Причина: Неправильно указан путь к исходным файлам в поле source_files.
Решение: Проверить пути в podspec, выполнить pod lib lint локально до устранения всех ошибок, затем повторить публикацию. Используйте глоб-паттерны: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Таймаут соединения

Симптом: [!] Connection to trunk.cocoapods.org failed. Timeout.
Причина: Проблемы с сетью или временная недоступность сервера Trunk.
Решение: Проверить доступность сервера: curl -I https://trunk.cocoapods.org. Если сервер отвечает, повторить команду через несколько минут. Возможно, ваш IP заблокирован — попробуйте с другого соединения или через VPN.

Отсутствие доступа к поду

Симптом: [!] You do not have permission to push to MyLibrary.
Причина: Вы не являетесь владельцем пода. Это происходит, если кто-то уже зарегистрировал под с таким именем.
Решение: Связаться с текущим владельцем пода (узнать можно через pod trunk info MyLibrary) и попросить добавить вас через pod trunk add-owner. Если имя пода занято, рассмотрите альтернативное имя.