Can I use a custom version of CocoaPods for iOS jobs?

Overview

Learn how to control which CocoaPods version runs in your CircleCI iOS builds. This guide shows you how to match your local CocoaPods setup with your CI environment using a Gemfile. Using the same CocoaPods version locally and in CI helps avoid unexpected build failures.

What is CocoaPods?

CocoaPods is a dependency manager for Swift and Objective-C projects. It helps you manage third-party libraries in your iOS apps. Different CocoaPods versions can behave differently, so keeping versions consistent prevents build issues.

Prerequisites

Before you start, make sure you have:

An iOS project configured on CircleCI
Local access to your project repository
Basic knowledge of Ruby gems and Bundler

Instructions

Step 1: Create a Gemfile

In your iOS project's root directory, create a new file called Gemfile (no file extension). Add the following content:

source 'https://rubygems.org'
gem 'cocoapods','=1.3.0'

Important: Replace 1.3.0 with your desired CocoaPods version. Use the exact version (with =) to ensure consistent builds.

Step 2: Install Dependencies Locally

Run these commands in your project directory:

bundle install

This creates a Gemfile.lock file that locks in the exact gem versions.

Step 3: Commit Both Files

Add both files to your repository:

git add Gemfile Gemfile.lock
git commit -m "Add Gemfile for CocoaPods version control"
git push

Step 4: Update Your CircleCI Configuration

Add caching and bundle commands to your .circleci/config.yml:

steps:
  - restore_cache:
      key: 1-gems-{{checksum "Gemfile.lock"}}
  - run: bundle check || bundle install --path vendor/bundle --clean
  - save_cache:
      key: 1-gems-{{checksum "Gemfile.lock"}}
      paths:
        -vendor/bundle
  - run: bundle exec pod install

Key Point: Always use bundle exec before CocoaPods commands to use your specified version.

Outcome

After completing these steps:

Your local and CI environments will use the same CocoaPods version
Builds become more predictable and reproducible
You can easily upgrade CocoaPods by updating your Gemfile

Additional Notes

Caching: The configuration above caches your gems to speed up builds
Bundle exec: Always prefix pod commands with bundle exec in CI
Version updates: To change CocoaPods versions, update your Gemfile and run bundle install

Additional Resources

CircleCI iOS Testing Documentation - Complete guide to iOS testing on CircleCI
CocoaPods Gemfile Guide - Official CocoaPods documentation on using Gemfiles
Bundler Documentation - Learn more about Ruby dependency management