CocoaPods Trunk: o que é, publicação de bibliotecas via Trunk

O que é CocoaPods Trunk?

CocoaPods Trunk é uma infraestrutura de servidor lançada em 2015 para publicação centralizada de bibliotecas pod. Antes do Trunk, cada pod era distribuído por meio de um repositório Git: o desenvolvedor precisava criar um repositório público, adicionar um arquivo podspec e enviar um Pull Request ao repositório central CocoaPods/Specs. Essa abordagem exigia moderação manual e criava atrasos ao publicar atualizações.

O Trunk resolveu esses problemas fornecendo uma API unificada para publicar, atualizar e gerenciar pods. O serviço inclui quatro componentes principais:

• Autenticação — registro com confirmação por email e gerenciamento de tokens de sessão. Cada desenvolvedor recebe um token único vinculado à sua conta e dispositivos.
• Validação — verificação automática do podspec antes da publicação, incluindo análise sintática, linting de dependências e verificação de compatibilidade de plataformas.
• Hospedagem — armazenamento de metadados e versões de pods nos servidores CocoaPods. O código-fonte permanece no repositório Git do desenvolvedor, enquanto o Trunk armazena apenas arquivos podspec e links.
• Gerenciamento de acesso — capacidade de adicionar e remover proprietários de pods, transferir direitos de publicação, marcar pods como obsoletos.

A arquitetura do Trunk é baseada em Ruby on Rails com banco de dados PostgreSQL. O serviço usa API HTTP com formato JSON para todas as operações, e o cliente CLI pod trunk faz parte da distribuição CocoaPods, instalado junto com a gema principal cocoapods.

Até o momento, mais de 100.000 pods foram publicados através do Trunk, com um total de downloads superior a 50 bilhões. O serviço processa milhares de solicitações de publicação e atualização diariamente de desenvolvedores em todo o mundo.

Registro e autenticação

Antes de publicar um pod, você deve se registrar no Trunk. O processo consiste em uma única etapa — o comando pod trunk register:

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

Após executar o comando, um link de confirmação é enviado para o email especificado. Clicar no link ativa a conta e cria um token de sessão que é armazenado no chaveiro do sistema (Keychain no macOS, gnome-keyring ou equivalente no Linux). O token é usado automaticamente em todas as operações subsequentes do pod trunk.

O parâmetro --description é opcional, mas recomendado — ajuda a identificar a sessão ao visualizar sessões ativas via pod trunk me. Se você trabalha em várias máquinas (estação de trabalho, servidor CI), a descrição permite distinguir uma sessão de outra.

Para verificar o status da autenticação, use o comando:

pod trunk me

A saída mostra email, nome, lista de seus pods (se já publicou) e sessões ativas. Exemplo 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, desenvolvimento iOS

Em servidores CI (GitHub Actions, GitLab CI, Jenkins), a autenticação é feita através de um token passado pela variável de ambiente COCOAPODS_TRUNK_TOKEN. O token pode ser obtido com o comando:

pod trunk me --token-only

Este token é armazenado nas configurações do CI como uma variável secreta e usado na etapa de publicação sem necessidade de novo registro. Exemplo para GitHub Actions:

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

Importante: o token fornece acesso total ao gerenciamento dos pods vinculados à conta. Nunca o publique em repositórios públicos ou compartilhe com terceiros. Se comprometido, o token pode ser revogado via pod trunk remove-session ou excluindo todas as sessões através do painel de controle do site CocoaPods.

Preparação do podspec

O arquivo podspec (.podspec ou .podspec.json) é o manifesto da biblioteca contendo metadados, dependências, informações sobre plataformas e código-fonte. O Trunk usa este arquivo para validação e registro do pod. Um podspec mínimo para publicação se parece com isto:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Breve descrição da biblioteca'
  s.description  = 'Descrição detalhada com explicação das funcionalidades'
  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-chave do podspec:

• name — nome do pod, deve ser único no registro do Trunk. Os nomes são registrados por ordem de chegada — se o nome estiver ocupado, a publicação será rejeitada.
• version — versão semântica no formato MAJOR.MINOR.PATCH. O Trunk não aceita republicação da mesma versão — é necessário incrementar o número.
• source — link para o repositório Git e tag. O Trunk não armazena código-fonte, portanto o repositório deve estar disponível para clonagem.
• platform — plataforma alvo (iOS, macOS, tvOS, watchOS) e versão mínima do SDK.
• license — tipo de licença. Recomenda-se especificar MIT, Apache-2.0, BSD ou outra licença de código aberto.

Antes da publicação, verifique a correção do podspec com o linter:

pod lib lint MyLibrary.podspec

O linter verifica sintaxe, campos obrigatórios, correção dos caminhos de arquivos e resolubilidade das dependências. Se durante o linting forem usadas fontes privadas, adiciona-se a flag --sources. Para pular o download de rede (apenas verificação local), usa-se a flag --local-only.

Publicação via pod trunk push

O comando principal para publicar um pod é pod trunk push. Ele envia o arquivo podspec para o servidor Trunk, onde passa por validação completa e é registrado no registro público. Sintaxe:

pod trunk push MyLibrary.podspec

A flag --allow-warnings permite a publicação na presença de avisos. Por padrão, qualquer aviso bloqueia a publicação. Se sua biblioteca tiver avisos conhecidos que não afetam a funcionalidade, você pode usar esta flag. Importante: erros sempre bloqueiam a publicação, independentemente das flags.

A flag --synchronous torna a requisição síncrona — o terminal aguarda a conclusão da validação no servidor. Por padrão, o comando retorna o controle imediatamente após o envio, e o servidor processa a publicação de forma assíncrona. O modo síncrono é útil em CI/CD quando o próximo passo do pipeline depende do sucesso da publicação.

A flag --skip-import-validation pula a verificação de importação da biblioteca em um projeto de teste. Isso acelera a publicação, mas não garante que a biblioteca realmente compile. Use esta flag apenas se estiver confiante na correção da compilação.

Exemplo de publicação com opções típicas:

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

Após uma publicação bem-sucedida, o Trunk retorna um JSON com detalhes:

  Congrats

  MyLibrary (0.1.0) successfully published

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

A biblioteca fica disponível para instalação via Podfile em qualquer projeto iOS ou macOS. Normalmente, o índice de busca do CocoaPods é atualizado em poucos minutos, mas em casos raros a indexação pode levar até uma hora.

Limitação importante: uma versão de pod publicada não pode ser excluída. Isso é para evitar quebrar projetos que já usam esta versão. Se a publicação foi errônea, você pode publicar a próxima versão com a correção, mas a reversão é impossível. A exceção é pod trunk delete, disponível apenas para funcionários do CocoaPods e usado em casos extremos (violação de licença, código malicioso).

Gerenciamento de versões e acesso

O CocoaPods Trunk fornece vários comandos para administrar pods publicados:

Adicionar proprietários

Para transferir direitos de publicação de um pod para outro desenvolvedor, use o comando:

pod trunk add-owner MyLibrary developer@email.com

Após a execução, o novo proprietário obtém acesso total ao gerenciamento do pod: publicação de novas versões, adicionar e remover outros proprietários, marcar o pod como obsoleto. Qualquer usuário registrado do Trunk pode ser proprietário — o registro prévio é obrigatório.

Remover proprietários

Se um desenvolvedor deixou o projeto ou não deve mais ter acesso ao pod:

pod trunk remove-owner MyLibrary developer@email.com

Apenas um proprietário atual pode remover outro proprietário. Não é possível remover o último proprietário de um pod — primeiro é necessário adicionar um novo. Isso impede que um pod fique sem proprietário e se torne abandonado.

Marcar um pod como obsoleto

Se a biblioteca não for mais mantida, você pode marcá-la como obsoleta (deprecated). Isso não remove o pod do registro, mas adiciona um aviso aos usuários durante a instalação:

pod trunk deprecate MyLibrary

Opcionalmente, você pode especificar um pod de substituição:

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

Ao instalar um pod obsoleto, o CocoaPods exibe um aviso no terminal e recomenda mudar para a substituição especificada. Esta é a maneira correta de encerrar o suporte de uma biblioteca sem quebrar as compilações de projetos existentes.

Visualizar informações do pod

As informações do pod estão disponíveis através do comando pod trunk info:

pod trunk info MyLibrary

O comando mostra todas as versões do pod, datas de publicação, lista de proprietários e status (ativo/obsoleto). Para ver detalhes de uma versão específica, use pod spec cat MyLibrary 0.1.0.

Erros e soluções

Ao trabalhar com o Trunk, os desenvolvedores frequentemente encontram erros típicos. Vamos revisar os mais comuns:

Erro de autenticação

Sintoma: [!] Authentication failed. You need to register a session first.
Causa: Token de sessão ausente ou expirado. Os tokens têm um período de validade limitado (30 dias sem atividade por padrão).
Solução: Execute novamente pod trunk register your@email.com 'Your Name'. Se você usa CI, verifique se a variável de ambiente COCOAPODS_TRUNK_TOKEN está atualizada e gere um novo token se necessário.

Conflito de versões

Sintoma: [!] You have already pushed version 0.1.0 for MyLibrary.
Causa: Tentativa de republicação de uma versão existente. O Trunk não permite sobrescrever versões.
Solução: Incremente a versão no podspec de acordo com o versionamento semântico. Se você errou no podspec, publique a próxima versão com a correção.

Erro de validação do podspec

Sintoma: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Causa: Caminho incorreto para arquivos fonte no campo source_files.
Solução: Verifique os caminhos no podspec, execute pod lib lint localmente até resolver todos os erros, depois repita a publicação. Use padrões glob: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Tempo limite de conexão

Sintoma: [!] Connection to trunk.cocoapods.org failed. Timeout.
Causa: Problemas de rede ou indisponibilidade temporária do servidor Trunk.
Solução: Verifique a disponibilidade do servidor: curl -I https://trunk.cocoapods.org. Se o servidor responder, repita o comando em alguns minutos. Seu IP pode estar bloqueado — tente de outra conexão ou via VPN.

Falta de acesso ao pod

Sintoma: [!] You do not have permission to push to MyLibrary.
Causa: Você não é proprietário do pod. Isso acontece se alguém já registrou um pod com esse nome.
Solução: Entre em contato com o proprietário atual do pod (descubra via pod trunk info MyLibrary) e peça para ser adicionado via pod trunk add-owner. Se o nome do pod estiver ocupado, considere um nome alternativo.