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

Лінтер перевіряє синтаксис, наявність обов'язкових полів, коректність шляхів до файлів та розв'язність залежностей. Якщо в процесі лінтингу використовуються приватні джерела, додається прапорець --sources. Для пропуску завантаження мережі (тільки локальна перевірка) використовується прапорець --local-only.

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

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

pod trunk push MyLibrary.podspec

Прапорець --allow-warnings дозволяє публікацію за наявності попереджень. За замовчуванням будь-які попередження блокують публікацію. Якщо бібліотека має відомі попередження, які не впливають на функціональність, можна використовувати цей прапорець. Важливо: помилки завжди блокують публікацію, незалежно від прапорців.

Прапорець --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. Якщо ім'я пода зайняте, розгляньте альтернативне ім'я.