CocoaPods Trunk : qu'est-ce que c'est, publication de bibliothèques via Trunk

Qu'est-ce que CocoaPods Trunk ?

CocoaPods Trunk est une infrastructure serveur lancée en 2015 pour la publication centralisée des bibliothèques pod. Avant Trunk, chaque pod était distribué via un dépôt Git : le développeur devait créer un dépôt public, ajouter un fichier podspec et envoyer une Pull Request au dépôt central CocoaPods/Specs. Cette approche nécessitait une modération manuelle et créait des délais lors de la publication des mises à jour.

Trunk a résolu ces problèmes en fournissant une API unifiée pour publier, mettre à jour et gérer les pods. Le service comprend quatre composants clés :

• Authentification — inscription avec confirmation par e-mail et gestion des jetons de session. Chaque développeur reçoit un jeton unique lié à son compte et à ses appareils.
• Validation — vérification automatique du podspec avant publication, incluant l'analyse syntaxique, le linting des dépendances et la vérification de compatibilité des plateformes.
• Hébergement — stockage des métadonnées et versions des pods sur les serveurs CocoaPods. Le code source reste dans le dépôt Git du développeur, tandis que Trunk ne stocke que les fichiers podspec et les liens.
• Gestion d'accès — possibilité d'ajouter et de supprimer des propriétaires de pods, de transférer les droits de publication, de marquer les pods comme obsolètes.

L'architecture de Trunk est basée sur Ruby on Rails avec une base de données PostgreSQL. Le service utilise une API HTTP au format JSON pour toutes les opérations, et le client CLI pod trunk fait partie de la distribution CocoaPods, installé avec la gemme principale cocoapods.

À ce jour, plus de 100 000 pods ont été publiés via Trunk, avec un total de téléchargements dépassant les 50 milliards. Le service traite des milliers de demandes de publication et de mise à jour chaque jour, provenant de développeurs du monde entier.

Inscription et authentification

Avant de publier un pod, vous devez vous inscrire sur Trunk. Le processus consiste en une seule étape — la commande pod trunk register :

pod trunk register your@email.com 'Your Name' --description='MacBook Pro, développement iOS'

Après l'exécution de la commande, un lien de confirmation est envoyé à l'e-mail indiqué. En cliquant sur le lien, le compte est activé et un jeton de session est créé, stocké dans le trousseau système (Keychain sur macOS, gnome-keyring ou équivalent sur Linux). Le jeton est automatiquement utilisé pour toutes les opérations pod trunk ultérieures.

Le paramètre --description est facultatif mais recommandé — il aide à identifier la session lors de l'affichage des sessions actives via pod trunk me. Si vous travaillez depuis plusieurs machines (poste de travail, serveur CI), la description permet de distinguer une session d'une autre.

Pour vérifier l'état de l'authentification, utilisez la commande :

pod trunk me

La sortie affiche l'e-mail, le nom, la liste de vos pods (si vous en avez déjà publié) et les sessions actives. Exemple de résultat :

  - 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, développement iOS

Sur les serveurs CI (GitHub Actions, GitLab CI, Jenkins), l'authentification se fait via un jeton passé par la variable d'environnement COCOAPODS_TRUNK_TOKEN. Le jeton peut être obtenu avec la commande :

pod trunk me --token-only

Ce jeton est stocké dans la configuration CI comme variable secrète, et utilisé à l'étape de publication sans nouvelle inscription. Exemple pour GitHub Actions :

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

Important : le jeton donne un accès complet à la gestion des pods liés au compte. Ne le publiez jamais dans des dépôts publics et ne le partagez pas avec des tiers. En cas de compromission, le jeton peut être révoqué via pod trunk remove-session ou en supprimant toutes les sessions via le panneau de contrôle du site CocoaPods.

Préparation du podspec

Le fichier podspec (.podspec ou .podspec.json) est le manifeste de la bibliothèque contenant les métadonnées, les dépendances, les informations sur les plateformes et le code source. Trunk utilise ce fichier pour la validation et l'enregistrement du pod. Un podspec minimal pour la publication ressemble à ceci :

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Brève description de la bibliothèque'
  s.description  = 'Description détaillée avec explication des fonctionnalités'
  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

Champs clés du podspec :

• name — nom du pod, doit être unique dans le registre Trunk. Les noms sont enregistrés selon le principe « premier arrivé, premier servi » — si le nom est pris, la publication sera refusée.
• version — version sémantique au format MAJOR.MINOR.PATCH. Trunk n'accepte pas la republication d'une même version — il faut incrémenter le numéro.
• source — lien vers le dépôt Git et tag. Trunk ne stocke pas le code source, donc le dépôt doit être accessible pour clonage.
• platform — plateforme cible (iOS, macOS, tvOS, watchOS) et version minimale du SDK.
• license — type de licence. Il est recommandé de spécifier MIT, Apache-2.0, BSD ou une autre licence open source.

Avant la publication, vérifiez la validité du podspec avec le linter :

pod lib lint MyLibrary.podspec

Le linter vérifie la syntaxe, les champs obligatoires, l'exactitude des chemins de fichiers et la résolubilité des dépendances. Si des sources privées sont utilisées lors du linting, le flag --sources est ajouté. Pour ignorer le téléchargement réseau (vérification locale uniquement), le flag --local-only est utilisé.

Publication via pod trunk push

La commande principale pour publier un pod est pod trunk push. Elle envoie le fichier podspec au serveur Trunk, où il subit une validation complète et est enregistré dans le registre public. Syntaxe :

pod trunk push MyLibrary.podspec

Le flag --allow-warnings autorise la publication en présence d'avertissements. Par défaut, tout avertissement bloque la publication. Si votre bibliothèque a des avertissements connus qui n'affectent pas la fonctionnalité, vous pouvez utiliser ce flag. Important : les erreurs bloquent toujours la publication, indépendamment des flags.

Le flag --synchronous rend la requête synchrone — le terminal attend la fin de la validation côté serveur. Par défaut, la commande reprend la main immédiatement après l'envoi, et le serveur traite la publication de manière asynchrone. Le mode synchrone est utile en CI/CD lorsque l'étape suivante du pipeline dépend du succès de la publication.

Le flag --skip-import-validation ignore la vérification de l'import de la bibliothèque dans un projet de test. Cela accélère la publication mais ne garantit pas que la bibliothèque compile réellement. Utilisez ce flag uniquement si vous êtes sûr de la validité de la compilation.

Exemple de publication avec des options typiques :

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

Après une publication réussie, Trunk retourne un JSON avec les détails :

  Congrats

  MyLibrary (0.1.0) successfully published

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

La bibliothèque devient disponible pour installation via Podfile dans tout projet iOS ou macOS. Normalement, l'index de recherche CocoaPods est mis à jour en quelques minutes, mais dans de rares cas, l'indexation peut prendre jusqu'à une heure.

Limitation importante : une version de pod publiée ne peut pas être supprimée. Cela évite de casser les projets qui utilisent déjà cette version. Si la publication était erronée, vous pouvez publier la version suivante avec la correction, mais le retour en arrière est impossible. L'exception est pod trunk delete, disponible uniquement pour le personnel de CocoaPods et utilisé dans des cas extrêmes (violation de licence, code malveillant).

Gestion des versions et de l'accès

CocoaPods Trunk fournit plusieurs commandes pour administrer les pods publiés :

Ajouter des propriétaires

Pour transférer les droits de publication d'un pod à un autre développeur, utilisez la commande :

pod trunk add-owner MyLibrary developer@email.com

Après exécution, le nouveau propriétaire obtient un accès complet à la gestion du pod : publication de nouvelles versions, ajout et suppression d'autres propriétaires, marquage du pod comme obsolète. Tout utilisateur enregistré de Trunk peut être propriétaire — l'inscription préalable est obligatoire.

Supprimer des propriétaires

Si un développeur a quitté le projet ou ne doit plus avoir accès au pod :

pod trunk remove-owner MyLibrary developer@email.com

Seul un propriétaire actuel peut supprimer un propriétaire. On ne peut pas supprimer le dernier propriétaire d'un pod — il faut d'abord en ajouter un nouveau. Cela évite qu'un pod devienne sans propriétaire et soit abandonné.

Marquer un pod comme obsolète

Si la bibliothèque n'est plus maintenue, vous pouvez la marquer comme obsolète (deprecated). Cela ne supprime pas le pod du registre, mais ajoute un avertissement aux utilisateurs lors de l'installation :

pod trunk deprecate MyLibrary

Optionnellement, vous pouvez spécifier un pod de remplacement :

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

Lors de l'installation d'un pod obsolète, CocoaPods affiche un avertissement dans le terminal et recommande de passer au remplacement spécifié. C'est la manière correcte de mettre fin au support d'une bibliothèque sans casser les compilations de projets existants.

Consulter les informations du pod

Les informations du pod sont disponibles via la commande pod trunk info :

pod trunk info MyLibrary

La commande affiche toutes les versions du pod, les dates de publication, la liste des propriétaires et le statut (actif/obsolète). Pour voir les détails d'une version spécifique, utilisez pod spec cat MyLibrary 0.1.0.

Erreurs et solutions

Lorsqu'ils travaillent avec Trunk, les développeurs rencontrent souvent des erreurs typiques. Passons en revue les plus courantes :

Erreur d'authentification

Symptôme : [!] Authentication failed. You need to register a session first.
Cause : Jeton de session manquant ou expiré. Les jetons ont une durée de validité limitée (30 jours sans activité par défaut).
Solution : Réexécutez pod trunk register your@email.com 'Your Name'. Si vous utilisez CI, vérifiez que la variable d'environnement COCOAPODS_TRUNK_TOKEN est à jour et générez un nouveau jeton si nécessaire.

Conflit de versions

Symptôme : [!] You have already pushed version 0.1.0 for MyLibrary.
Cause : Tentative de republication d'une version existante. Trunk ne permet pas d'écraser les versions.
Solution : Incrémentez la version dans le podspec conformément au versionnement sémantique. Si vous avez fait une erreur dans le podspec, publiez la version suivante avec la correction.

Erreur de validation du podspec

Symptôme : [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Cause : Chemin incorrect vers les fichiers sources dans le champ source_files.
Solution : Vérifiez les chemins dans le podspec, exécutez pod lib lint localement jusqu'à résolution de toutes les erreurs, puis répétez la publication. Utilisez des motifs glob : Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Délai d'attente dépassé

Symptôme : [!] Connection to trunk.cocoapods.org failed. Timeout.
Cause : Problèmes réseau ou indisponibilité temporaire du serveur Trunk.
Solution : Vérifiez la disponibilité du serveur : curl -I https://trunk.cocoapods.org. Si le serveur répond, répétez la commande dans quelques minutes. Votre IP peut être bloquée — essayez depuis une autre connexion ou via un VPN.

Absence d'accès au pod

Symptôme : [!] You do not have permission to push to MyLibrary.
Cause : Vous n'êtes pas le propriétaire du pod. Cela se produit si quelqu'un a déjà enregistré un pod avec ce nom.
Solution : Contactez le propriétaire actuel du pod (identifiez-le via pod trunk info MyLibrary) et demandez-lui de vous ajouter via pod trunk add-owner. Si le nom du pod est pris, envisagez un nom alternatif.