CocoaPods Trunk: qué es, publicación de bibliotecas mediante Trunk

¿Qué es CocoaPods Trunk?

CocoaPods Trunk es una infraestructura de servidor lanzada en 2015 para la publicación centralizada de bibliotecas pod. Antes de Trunk, cada pod se distribuía a través de un repositorio Git: el desarrollador debía crear un repositorio público, añadir un archivo podspec y enviar un Pull Request al repositorio central CocoaPods/Specs. Este enfoque requería moderación manual y generaba retrasos al publicar actualizaciones.

Trunk resolvió estos problemas proporcionando una API unificada para publicar, actualizar y gestionar pods. El servicio incluye cuatro componentes clave:

• Autenticación — registro con confirmación por correo electrónico y gestión de tokens de sesión. Cada desarrollador obtiene un token único vinculado a su cuenta y dispositivos.
• Validación — verificación automática del podspec antes de la publicación, incluyendo análisis sintáctico, linting de dependencias y comprobación de compatibilidad de plataformas.
• Alojamiento — almacenamiento de metadatos y versiones de pods en los servidores de CocoaPods. El código fuente permanece en el repositorio Git del desarrollador, mientras que Trunk solo guarda los archivos podspec y enlaces.
• Gestión de acceso — posibilidad de añadir y eliminar propietarios de pods, transferir derechos de publicación, marcar pods como obsoletos.

La arquitectura de Trunk está basada en Ruby on Rails con base de datos PostgreSQL. El servicio utiliza API HTTP con formato JSON para todas las operaciones, y el cliente CLI pod trunk es parte de la distribución de CocoaPods, instalado junto con la gema principal cocoapods.

Hasta la fecha, se han publicado más de 100 000 pods a través de Trunk, con un total de descargas que supera los 50 mil millones. El servicio procesa miles de solicitudes de publicación y actualización diariamente de desarrolladores de todo el mundo.

Registro y autenticación

Antes de publicar un pod, debe registrarse en Trunk. El proceso consiste en un solo paso: el comando pod trunk register:

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

Después de ejecutar el comando, se envía un enlace de confirmación al correo electrónico indicado. Al hacer clic en el enlace se activa la cuenta y se crea un token de sesión que se almacena en el llavero del sistema (Keychain en macOS, gnome-keyring o equivalente en Linux). El token se usa automáticamente en todas las operaciones posteriores de pod trunk.

El parámetro --description es opcional pero recomendado: ayuda a identificar la sesión al ver las sesiones activas mediante pod trunk me. Si trabaja desde varios equipos (estación de trabajo, servidor CI), la descripción permite distinguir una sesión de otra.

Para verificar el estado de la autenticación, use el comando:

pod trunk me

La salida muestra el correo electrónico, el nombre, la lista de sus pods (si ya ha publicado) y las sesiones activas. Ejemplo de resultado:

  - 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, desarrollo iOS

En servidores CI (GitHub Actions, GitLab CI, Jenkins), la autenticación se realiza mediante un token pasado a través de la variable de entorno COCOAPODS_TRUNK_TOKEN. El token se obtiene con el comando:

pod trunk me --token-only

Este token se guarda en la configuración de CI como variable secreta y se utiliza en el paso de publicación sin necesidad de registro repetido. Ejemplo para GitHub Actions:

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

Importante: el token otorga acceso completo a la gestión de los pods vinculados a la cuenta. Nunca lo publique en repositorios públicos ni lo comparta con terceros. Si se ve comprometido, el token se puede revocar mediante pod trunk remove-session o eliminando todas las sesiones a través del panel de control del sitio web de CocoaPods.

Preparación del podspec

El archivo podspec (.podspec o .podspec.json) es el manifiesto de la biblioteca que contiene metadatos, dependencias, información sobre plataformas y código fuente. Trunk utiliza este archivo para la validación y el registro del pod. Un podspec mínimo para publicar tiene este aspecto:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Breve descripción de la biblioteca'
  s.description  = 'Descripción detallada con explicación de las características'
  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

Campos clave del podspec:

• name — nombre del pod, debe ser único en el registro de Trunk. Los nombres se registran por orden de llegada: si el nombre está ocupado, la publicación será rechazada.
• version — versión semántica en formato MAJOR.MINOR.PATCH. Trunk no acepta la republicación de la misma versión: debe incrementar el número.
• source — enlace al repositorio Git y etiqueta. Trunk no almacena el código fuente, por lo que el repositorio debe estar disponible para clonación.
• platform — plataforma objetivo (iOS, macOS, tvOS, watchOS) y versión mínima del SDK.
• license — tipo de licencia. Se recomienda especificar MIT, Apache-2.0, BSD u otra licencia de código abierto.

Antes de publicar, verifique la corrección del podspec con el linter:

pod lib lint MyLibrary.podspec

El linter comprueba la sintaxis, los campos obligatorios, la corrección de las rutas a los archivos y la resolubilidad de las dependencias. Si durante el linting se utilizan fuentes privadas, se añade el flag --sources. Para omitir la descarga de red (solo comprobación local), se usa el flag --local-only.

Publicación mediante pod trunk push

El comando principal para publicar un pod es pod trunk push. Envía el archivo podspec al servidor Trunk, donde se somete a una validación completa y se registra en el registro público. Sintaxis:

pod trunk push MyLibrary.podspec

El flag --allow-warnings permite la publicación en presencia de advertencias. Por defecto, cualquier advertencia bloquea la publicación. Si la biblioteca tiene advertencias conocidas que no afectan la funcionalidad, puede usar este flag. Importante: los errores siempre bloquean la publicación, independientemente de los flags.

El flag --synchronous hace que la solicitud sea síncrona: el terminal espera a que se complete la validación en el servidor. Por defecto, el comando devuelve el control inmediatamente después del envío, y el servidor procesa la publicación de forma asíncrona. El modo síncrono es útil en CI/CD cuando el siguiente paso del pipeline depende del éxito de la publicación.

El flag --skip-import-validation omite la comprobación de importación de la biblioteca en un proyecto de prueba. Esto acelera la publicación pero no garantiza que la biblioteca realmente compile. Use este flag solo si está seguro de la corrección de la compilación.

Ejemplo de publicación con opciones típicas:

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

Después de una publicación exitosa, Trunk devuelve un JSON con los detalles:

  Congrats

  MyLibrary (0.1.0) successfully published

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

La biblioteca está disponible para su instalación mediante Podfile en cualquier proyecto de iOS o macOS. Normalmente, los datos en el índice de búsqueda de CocoaPods se actualizan en unos minutos, pero en casos excepcionales la indexación puede tardar hasta una hora.

Limitación importante: una versión de pod publicada no se puede eliminar. Esto se hace para evitar romper proyectos que ya usan esa versión. Si la publicación fue errónea, puede publicar la siguiente versión con la corrección, pero la reversión es imposible. La excepción es pod trunk delete, disponible solo para el personal de CocoaPods y se aplica en casos extremos (violación de licencia, código malicioso).

Gestión de versiones y acceso

CocoaPods Trunk proporciona varios comandos para administrar los pods publicados:

Añadir propietarios

Para transferir los derechos de publicación de un pod a otro desarrollador, use el comando:

pod trunk add-owner MyLibrary developer@email.com

Tras la ejecución, el nuevo propietario obtiene acceso completo a la gestión del pod: publicación de nuevas versiones, añadir y eliminar otros propietarios, marcar el pod como obsoleto. Puede ser propietario cualquier usuario registrado de Trunk; el registro previo es obligatorio.

Eliminar propietarios

Si un desarrollador ha abandonado el proyecto o ya no debe tener acceso al pod:

pod trunk remove-owner MyLibrary developer@email.com

Solo un propietario actual puede eliminar a otro propietario. No se puede eliminar al último propietario de un pod: primero debe añadir uno nuevo. Esto evita que un pod se quede sin propietario y se convierta en abandonado.

Marcar un pod como obsoleto

Si la biblioteca ya no tiene soporte, puede marcarla como obsoleta (deprecated). Esto no elimina el pod del registro, pero añade una advertencia a los usuarios durante la instalación:

pod trunk deprecate MyLibrary

Opcionalmente, puede especificar un pod de reemplazo:

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

Al instalar un pod obsoleto, CocoaPods muestra una advertencia en el terminal y recomienda cambiar al reemplazo especificado. Esta es la forma correcta de finalizar el soporte de una biblioteca sin romper las compilaciones de proyectos existentes.

Ver información del pod

La información del pod está disponible mediante el comando pod trunk info:

pod trunk info MyLibrary

El comando muestra todas las versiones del pod, fechas de publicación, lista de propietarios y estado (activo/obsoleto). Para ver los detalles de una versión específica, use pod spec cat MyLibrary 0.1.0.

Errores y soluciones

Al trabajar con Trunk, los desarrolladores se encuentran a menudo con errores típicos. Veamos los más comunes:

Error de autenticación

Síntoma: [!] Authentication failed. You need to register a session first.
Causa: Token de sesión ausente o caducado. Los tokens tienen un período de validez limitado (30 días sin actividad por defecto).
Solución: Vuelva a ejecutar pod trunk register your@email.com 'Your Name'. Si usa CI, verifique que la variable de entorno COCOAPODS_TRUNK_TOKEN esté actualizada y genere un nuevo token si es necesario.

Conflicto de versiones

Síntoma: [!] You have already pushed version 0.1.0 for MyLibrary.
Causa: Intento de republicación de una versión existente. Trunk no permite sobrescribir versiones.
Solución: Incremente la versión en el podspec según el versionado semántico. Si se equivocó en el podspec, publique la siguiente versión con la corrección.

Error de validación del podspec

Síntoma: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Causa: Ruta incorrecta a los archivos fuente en el campo source_files.
Solución: Verifique las rutas en el podspec, ejecute pod lib lint localmente hasta resolver todos los errores, luego repita la publicación. Use patrones glob: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Tiempo de espera agotado

Síntoma: [!] Connection to trunk.cocoapods.org failed. Timeout.
Causa: Problemas de red o indisponibilidad temporal del servidor Trunk.
Solución: Verifique la disponibilidad del servidor: curl -I https://trunk.cocoapods.org. Si el servidor responde, repita el comando en unos minutos. Es posible que su IP esté bloqueada; intente desde otra conexión o mediante VPN.

Falta de acceso al pod

Síntoma: [!] You do not have permission to push to MyLibrary.
Causa: No es propietario del pod. Esto ocurre si alguien ya registró un pod con ese nombre.
Solución: Póngase en contacto con el propietario actual del pod (puede averiguarlo mediante pod trunk info MyLibrary) y solicite que le añada mediante pod trunk add-owner. Si el nombre del pod está ocupado, considere un nombre alternativo.