name: cocoapods-publishing-workflow description: Use when publishing CocoaPods libraries to CocoaPods Trunk. Covers pod trunk registration, podspec validation, version management, and publishing best practices for successful library distribution. allowed-tools:

Read
Write
Edit
Bash
Grep
Glob

CocoaPods - Publishing Workflow

Complete guide to publishing your CocoaPods library to the official CocoaPods Trunk.

Publishing Overview

Process Steps

Register with CocoaPods Trunk (one-time)
Prepare your podspec
Validate locally (pod lib lint)
Validate for publishing (pod spec lint)
Tag version in git
Push to Trunk (pod trunk push)

Trunk Registration

Register Email (One-Time)

# Register your email
pod trunk register email@example.com 'Your Name'

# Verify email (check inbox for verification link)
# Click link in email to activate account

Check Registration

# Verify registration
pod trunk me

# Sample output:
# - Name:     Your Name
# - Email:    email@example.com
# - Since:    January 1st, 2024
# - Pods:     None

Podspec Preparation

Version Management

Pod::Spec.new do |spec|
  # Semantic versioning: MAJOR.MINOR.PATCH
  spec.version = '1.0.0'

  # Must match git tag
  spec.source = {
    :git => 'https://github.com/username/MyLibrary.git',
    :tag => spec.version.to_s
  }
end

Required Metadata

Pod::Spec.new do |spec|
  # Identity (required)
  spec.name         = 'MyLibrary'
  spec.version      = '1.0.0'

  # Description (required)
  spec.summary      = 'Brief one-line description'
  spec.description  = 'Longer description with more details about what the library does'

  # Links (required)
  spec.homepage     = 'https://github.com/username/MyLibrary'
  spec.source       = { :git => 'https://github.com/username/MyLibrary.git', :tag => spec.version.to_s }

  # License (required)
  spec.license      = { :type => 'MIT', :file => 'LICENSE' }

  # Authors (required)
  spec.authors      = { 'Your Name' => 'email@example.com' }

  # Platform (required)
  spec.ios.deployment_target = '13.0'
end

Local Validation

Quick Validation

# Fast validation (skips build)
pod lib lint --quick

# Check for common issues without full build

Full Validation

# Complete validation with build
pod lib lint

# With Swift version
pod lib lint --swift-version=5.9

# Verbose output
pod lib lint --verbose

Handle Warnings

# Allow warnings (not recommended for new pods)
pod lib lint --allow-warnings

# Better: Fix warnings
pod lib lint
# Address each warning individually

Publishing Validation

Spec Lint

# Validate podspec for publishing
pod spec lint

# Validates against remote repository
# Simulates real-world installation

Pre-Publishing Checklist

Git Tagging

Create Tag

# Stage all changes
git add .

# Commit changes
git commit -m "Release version 1.0.0"

# Create tag matching podspec version
git tag 1.0.0

# Push to remote with tags
git push origin main --tags

Tag Format

# Semantic versioning
git tag 1.0.0      # MAJOR.MINOR.PATCH
git tag 1.0.0-beta.1  # Pre-release
git tag 1.0.0-rc.1    # Release candidate

# Must match spec.version in podspec

Publishing to Trunk

Push Pod

# Push to CocoaPods Trunk
pod trunk push MyLibrary.podspec

# With specific Swift version
pod trunk push MyLibrary.podspec --swift-version=5.9

# Allow warnings (not recommended)
pod trunk push MyLibrary.podspec --allow-warnings

Successful Publish Output

Validating podspec
 -> MyLibrary (1.0.0)

Updating spec repo `trunk`
 -> MyLibrary (1.0.0)

--------------------------------------------------------------------------------
 🎉  Congrats

 🚀  MyLibrary (1.0.0) successfully published
 📅  January 1st, 2024
 🌎  https://cocoapods.org/pods/MyLibrary
 👍  Tell your friends!
--------------------------------------------------------------------------------

Version Updates

Patch Release (Bug Fixes)

# In podspec
spec.version = '1.0.1'  # Was 1.0.0

# Git workflow
git add .
git commit -m "Fix: Resolve crash in background mode"
git tag 1.0.1
git push origin main --tags
pod trunk push MyLibrary.podspec

Minor Release (New Features)

# In podspec
spec.version = '1.1.0'  # Was 1.0.1

# Git workflow
git add .
git commit -m "Add: Support for custom themes"
git tag 1.1.0
git push origin main --tags
pod trunk push MyLibrary.podspec

Major Release (Breaking Changes)

# In podspec
spec.version = '2.0.0'  # Was 1.1.0

# Git workflow
git add .
git commit -m "BREAKING: Refactor API for modern Swift"
git tag 2.0.0
git push origin main --tags
pod trunk push MyLibrary.podspec

Managing Multiple Pods

List Your Pods

# View all your published pods
pod trunk me

# Shows:
# - Pods:
#   - MyLibrary
#   - MyOtherLibrary

Add Contributors

# Add team member to pod
pod trunk add-owner MyLibrary email@example.com

# Remove contributor
pod trunk remove-owner MyLibrary email@example.com

Deprecation

Deprecate Old Version

# Deprecate specific version
pod trunk deprecate MyLibrary --version=1.0.0

# Deprecate entire pod
pod trunk deprecate MyLibrary

Deprecation with Replacement

# In podspec
spec.deprecated = true
spec.deprecated_in_favor_of = 'NewAwesomeLibrary'

Common Issues

Issue: Tag Doesn't Match

ERROR | [MyLibrary] The repo has no tag for version 1.0.0

Solution:

# Create and push tag
git tag 1.0.0
git push origin --tags

Issue: Validation Fails

ERROR | [MyLibrary] xcodebuild: Returned an unsuccessful exit code

Solution:

# Run detailed validation
pod lib lint --verbose

# Fix errors shown in output
# Re-validate until clean

Issue: Missing License

ERROR | [MyLibrary] Missing required attribute `license`

Solution:

# Add to podspec
spec.license = { :type => 'MIT', :file => 'LICENSE' }

# Create LICENSE file in repo root

Best Practices

Pre-Publish Testing

# 1. Test in example app
cd Example
pod install
# Run app, verify functionality

# 2. Test in real project
# Create test project, add pod from local path
pod 'MyLibrary', :path => '../MyLibrary'

# 3. Validate
pod lib lint
pod spec lint

Version Numbering

# Follow semantic versioning strictly
spec.version = '1.0.0'  # Initial release
spec.version = '1.0.1'  # Bug fix
spec.version = '1.1.0'  # New feature
spec.version = '2.0.0'  # Breaking change

CHANGELOG

# Changelog

## [1.1.0] - 2024-01-15
### Added
- Custom theme support
- Dark mode compatibility

### Fixed
- Memory leak in background processing

## [1.0.0] - 2024-01-01
- Initial release

README

# MyLibrary

Brief description of library.

## Installation

\`\`\`ruby
pod 'MyLibrary', '~> 1.0'
\`\`\`

## Usage

\`\`\`swift
import MyLibrary

let library = MyLibrary()
library.doSomething()
\`\`\`

## Requirements

- iOS 13.0+
- Swift 5.7+

## License

MyLibrary is available under the MIT license.

Anti-Patterns

Don't

❌ Publish without testing

pod trunk push --skip-tests  # Risky

❌ Use --allow-warnings for initial release

pod trunk push --allow-warnings  # Fix warnings instead

❌ Forget to tag git

# Missing git tag - publish will fail
pod trunk push

❌ Skip version bump

# Still version 1.0.0 after changes - confusing
spec.version = '1.0.0'

Do

✅ Test thoroughly before publishing

pod lib lint
pod spec lint
# Test in real project

✅ Fix all warnings

pod lib lint
# Address warnings

✅ Always tag git

git tag 1.0.0
git push --tags

✅ Bump version for every release

spec.version = '1.0.1'  # Incremented

Complete Publishing Example

# 1. Prepare podspec
vim MyLibrary.podspec
# Update version to 1.0.0

# 2. Update CHANGELOG
vim CHANGELOG.md
# Document changes

# 3. Commit and tag
git add .
git commit -m "Release 1.0.0: Initial public release"
git tag 1.0.0
git push origin main --tags

# 4. Validate locally
pod lib lint

# 5. Validate for publishing
pod spec lint

# 6. Publish
pod trunk push MyLibrary.podspec

# 7. Verify
pod search MyLibrary
# Should show your new pod

Related Skills

cocoapods-podspec-fundamentals
cocoapods-subspecs-organization
cocoapods-test-specs
cocoapods-privacy-manifests