CocoaPods 101: Creating your first CocoaPod & Private Repository


Doing a tech talk has been something I’ve wanted to do and get into for a while, and Greg Spiers who heads up NSManchester finally let me break my silence and do my first talk at December 2017’s meet up.

I’d recently done an internal company blog post about setting up a Private CocoaPods repository, so I thought that would be a good place to start, but during the talk I realised that not everyone (especially some junior iOS dev’s) are fully aware of CocoaPods and what they have to offer.

This is basically a more in-depth post around my talk at NSManchester, hopefully covering some of the areas I take for granted being a more experienced iOS dev.

What is (are) CocoaPods?

CocoaPods is a dependency manager written in Ruby for Objective-C & Swift projects (and can actually be used for any other languages that use the Objective-C runtime.

The CocoaPods “specs" repository has over 40k available public libraries.

Some of the most popular CocoaPod libraries you may be familiar with are:


CocoaPods homepage can be found at

So…. what is a CocoaPod?

A CocoaPod (Pod) is ‘said’ library, typically a popular packaged or OpenSource framework (see examples above) created and maintained by a third party.

Alternatively it could be a simple wrapper or group of really useful extensions/categories..

Where does a Pod live?

A Pod lives it it’s own repository, away from the primary CocoaPods “specs" repository. CocoaPods only host the specs file that simply points to your repository.

Tell me more about “Specs"...

The master CocoaPods repository lives at and hosts the collection of specs file that belong to all of the CocoaPods out there.

We’ll go through the specs file in more detail later, but in a nutshell, this is just a config file which contains all the information about your Pod and more importantly where it lives (i.e. link to your repo).

Install, Setup & Using CocoaPods

So you’re doing your next major iOS project and you’ve come across this cool library on GitHub you want to use. Usually you’re presented with two choices “Manual installation" or “CocoaPods" (there is sometimes a third but I’m not really going to touch on that today)

On this occasion you’ve opted for CocoaPods installation, so where to begin...

First, start by installing CocoaPods on your Mac, simply open Terminal and type the following:

$ sudo gem install cocoapods

Once complete your ready to setup your Xcode project to use CocoaPods
Back in Terminal, simply navigate to the root of your Xcode’s project folder and type:

bash">$ pod init

This will create your Podfile in your Xcode’s project directory that we’ll use to add details about the Pods we want to use in our project. Initially this will create a template Podfile with some boilerplate code to get you started, but for those more experienced you can simply create an empty pod file.

bash">$touch Podfile

Next we’ll run the Pod Installation on our project, now this might initially seem a bit wrong as we’ve yet to define any Pods we want to use in our Podfile, but this will basically setup our current *.xcproject to use CocoaPods (and in turn will generate a *.workspace file for us to use.

To accomplish this, simple type the following in terminal:

bash">$ pod install

Once complete, you’ll need to close your current Xcode project (if open) and re-open with the newly generated *.workspace file.
If your unfamiliar with working with *.workspace’s in Xcode see the following link:

Now once your workspace is open, search for the ‘Podfile’ and select it.

You should see something like the below:

The following file format is Ruby and it is here where you tell your app what CocoaPods you would like to use.
There are lots of configuration options available in here, but for the sake of this article - we’ll just go through some of the basics.

Notice the following function like syntax
target 'NSManchester-CocoaPods101' do


Inside here is where we’ll declare the Pod we want to use, the “target" declaration lets us specify what Pods we want to use with what targets with out app.

So let’s add a Pod in there.

Cool, all done there - now lets install that Pod into our project.

Back to terminal, simply type the following:

bash">$ pod install

All going well you should see something like this…

Notice the “Installing RxSwift (4.0.0)" - this means that the RxSwift library has been downloaded and is ready to use in your project - check it out…

Couple of places to pay attention to here:

  1. The RxSwift folder under Pods > Pods
  2. "import RxSwift" declaration
  3. Access to the RxSwift library in my ViewController (line 9)

And that’s it, you’re away using CocoaPods, how easy was that!

Couple of things to remember

When you initially install CocoaPods to your Mac, part of the process is basically cloning their “specs" repo to your machine, if you take a look here:

You’ll see all the specs from when you first installed CocoaPods, if someone published a new CocoaPod then you’ll need to update this.

Easiest way to go about this, simply run the following:

pod update

Instead of:

pod install

This will do a pull from the master specs repo and then in turn update / install any new CocoaPods you have.

In addition if you have multiple Pods in your Podfile, you can easily target the a specific Pod to update by simply running:

pod update RxSwift

Creating your first CocoaPod

So you have a cool little library or neat little wrapper for an existing API that you want to share it with the world. Or just simply have easy access to it across multiple projects as/when you need it. Then creating your first CocoaPod is a great place to start.

First lets generate our template project by simply entering the following into terminal:

pod lib create MyFirstCocoaPod

All going well you’ll see the following:

Answer the following questions as you see fit, for this post - I’ll be doing it in Swift, here are my choices:

Basically, I’ve opted to include a test application with my CocoaPod (very wise if you are sharing with the community), I’ve opted out of any testing frameworks as this goes a little beyond the scope of this article.

For those familiar with Quick as a BDD testing tool, might feel the benefit of including this in their CocoaPods, for more information on Quick as a testing tool and Quick’s integration into CocoaPods check out the following link:

Once complete, your template project will be generated and should open in Xcode automatically

Coding your Pod

Next, lets take a look at the project structure, Your core project “MyFirstCocoaPod" (or whatever you call yours) is basically your Example app which will use your Pod to in order to demonstrate its use.

The actual code for your Pod will live in the “Pods" workspace under a group called “Development Pods"

See below for the expanded tree and take note off the highlighted areas:

Focus your attention on the “ReplaceMe.swift" file - here is where your code for your POD is going to live.

Now, I’m not going to walk through actually build a working Pod, but here you simply drop in your code that you want as part of your Library / Wrapper etc….

Next, it’s time to build your simple test project - nothing too fancy (try something visual if you can, people like “seeing" something working), but something that shows a good use for your Pod, but most importantly, let it show how to use all of your Pods features.

Building your Example application

Now once you’ve added your Pod code (replaced the “ReplaceMe.swift" with your fancy code) you’ll want to be able use it in your test example application.
You’ll notice that you files you've just replaced live in the “Pods" project within your Workspace, and your example application lives in the "MyFirstCocoaPod" project so the best way to test your Pod is by installing it in your test application.

But wait a minute, our Pod has not been uploaded to the master specs repo yet, fear not - simply take a look at your Podfile and you’ll see the following:

pod 'MyFirstCocoaPod', :path => '../'

Notice the :path => '../‘ this basically tells your Pod that it’s local to the to Pods project and look there to install rather than the master specs repo.

Go ahead and perform a
pod update
then head over to your example application, you should now be able to
@import MyFirstCocoaPod
and use the Pod in the application.

Next Steps - Three important files

Next we are going to taker a look at the following 3 files

  1. Specs file
  2. ReadMe
  3. LicenceFile

Specs file

Scroll back a few paragraphs and you’ll hear me talk about the ‘Specs’ file, basically the specs file is what CocoaPods uses to understand / read & install your Pod. It’s your ‘Specs’ file that lives in the Cocoapods master repository

There’s a lot that go into your Specs file, such a dependancies required for your Pod, but for there sake of this primer we’ll just go through the basics of what you need in order to get your Pod out there.

First of all, lets start out by “linting" your specs file, CocoaPods gives us to option to lint our Specs file to see if all is okay prior to pushing out our Pod.

For those just starting out and may be unfamiliar with the term “linting" see the following link

Simply run the following:
pod lib lint MyFirstCocoaPod.podspec
All going well, you should get the following warnings:

In a nutshell,

  1. Your Summary is rubbish
  2. CocoaPods can’t validate your repo URL (because you haven’t created it yet)
  3. I’m running Swift 4 on my machine (so we can ignore this one - it’s fine!)

So lets take a look at your Specs file:

Here we can configure your Pod with all the required details (and some more). As above, the file is already templated out with pre-filed content for you to simply just update.

We’ll quickly cover the basics that you need in order to get going, alternatively but the file is full of comments pointing you in the right direction for anything you need to know.

Here is a good starting point, take particular note of the “s.version" number as we’ll need this later when pushing you build to master specs repo. = 'MyFirstCocoaPod'
s.version = '0.1.0'
s.summary = 'A short description of MyFirstCocoaPod.’

Next take a look at the following. As per the comments in the file - any lines starting with # are optional

s.description = <<-DESC
TODO: Add long description of the pod here.
s.homepage = ''
# s.screenshots = '', ''
s.license = { :type => 'MIT', :file => 'LICENSE' } = { 'Chris Barker' => ‘' }
s.source = { :git => '', :tag => s.version.to_s }
# s.social_media_url = '’

One of the most important ones is “s.source" this is the repo where your CocoaPod is going to live.

Create a public repo, either GitHub or BitBucket will do fine and grab your URL (pointless doing this as a Private repo as we’ll be pushing this to the master Specs repo and we’ll want everyone to have access).

“s.version" is another important one to have set at this point, basically this is the version number of the Pod and we’ll be tagging your remote repository with this number later (as this all helps with the CocoaPods magic!!)

Now once your all happy and have populated your specs file with all the details of your Pod, it's time to lint again!

pod lib lint MyFirstCocoaPod.podspec

This time you should see something more like the below:

If you get any other errors, then simply follow the advisory fixes accordingly.

ReadMe file

This your is basic ReadMe file which will contain all the information about your Pod, everything from how to use it, how to install it and what it does.

Include references / kudos to others who may have influenced this Pod and anything else you see fit

Licence file

Basic licence information, by default CocoaPods generates a MIT licence file, but you can choose your own (don’t forget to correctly reference it in “s.licence" section of your Specs file.

Prepping your Pod’s remote repo

It’s official, your ready to commit your first Pod, but first it need to commit to your remote repository (remember only your 'specs file’ lives in the CocoaPods master specs repo). Commit your code via command line (for a simpler life) by doing the below.

git add .
git commit -m “Initial Commit"
git remote add origin
git push -u origin master

The majority of contributors seem to prefer GitHub, but you can use BitBucket or any other offerings that may be out there.

Tag your build

Once you’ve done your first commit your almost ready to go, you now just need to tag and push to your remote repository, important, you must tag the build with the version number that you put in
s.version/pre> (remember we mentioned this earlier above).

git tag 0.1.0
git push origin 0.1.0

Make rocket go!

We’re all set, it’s time to push the button… well, commit our specs file to the "master specs repo"

Just for fun (and good practice), lets give our specs once final lint..

pod lib lint NSManchesterPod.podspec

And then push!

pod trunk push NSManchesterPod.podspec

Quick roundup

Can you feel it……. can you feel that warm fuzzy feeling inside, yep you’ve official contributed to the dev community - go check and you’ll see your name in shining lights.

Joking a side I’m not going to lie it’s a great feeling, but just remember to be as open minded about your contribution as you were open about sharing it.
Offer support for those who may need it, listen to the community and allow contributions where you see fit, endeavour (although not always possible) to keep your Pod up to date.

But CocoaPods is not always all about sharing your love of coding with the community, it is after all a dependancy manager, so lets take a look at our options for hosting our own private specs repository.

Private specs repository & why?

This is the part that really triggered the post and indeed my talk I did at NSManchester, as an iOS developer you may be familiar with the phrase “ohh, there’s a Pod for that". Let's say you hear on the grapevine about a new library / framework doing the rounds or even your client sends you their API you need to integrate in your application, there’s a good chance it’s in a Pod - but what happens if your client wants to keep their API private or have “some" form of control over the API and it’s updates, is CocoPods still an option….?

Sure, they can simply host this on a private specs repository which only you (and other clients) have specifc access too, lets have a look below at some of the other potential reason why we may choose to host our own "private specs repo"

Code sharing (my story)
This has to be the main reason I created my first private specs repo. Working for a mobile app agency was how I first learned my trade as an iOS developer.
We simultaneously worked on a lot of cool projects for various clients during any given time so we often wrote snippets of logic that we would reuse from project to project. If it was small enough, we’d post it to a Slack channel, sometimes we’d even put it on an internal blog post, but usually we’d fire up a version of the project that we had last worked on and simply copy and paste - job done!

For the most part this was acceptable, but as the company grew and people started to make changes to various codebases, things started to evolve (in a good way).
However one day I really needed to do some heaving lifting on NSThreading and by chance we had a great little Objective-C NSThreading category that we used through pretty much all of our projects. Cool, so Open Xcode, copy, paste - done!

But there was a bug….. only really identifiable when we really stretching the use of this cool little extension, but it was there and this particular app could potentially cause this issue to raise it’s ugly head, it needed fixing.

It was a quick fix, 1 line of code I seem to remember, but it was needed and now I felt I had to tell the world about it (or at least the guys in the team), so a Slack message went out.

2 mins later I got a response “yeah I noticed & fixed that few weeks ago….", followed by another one….. “yeah I made some other changes to that too code…."

Hmm… question was who was using who’s code…. I just grabbed the last project I was working on which I knew had it in and took it from there, but my branch was old and admittedly I'd not touched that project for about 8 months. Were the other guys in sync with each other, were they even aware of each others changes - something needs to be done here.

For me this was a perfect situation to bring in a private specs repo to store and maintain this code in source control. Truthfully, it could have been a public Pod as it was nothing special - but we used it an awful lot and I felt that giving it a home in it’s own private specs repo allowed it to keeps it’s place within all our projects.

Code sharing (other benefits)
You don’t necessarily have to be an agency working on multiple apps to take advantage of anything mentioned above. You could simply be a team of 10-15 devs working on one product which in-turn could have multiple projects, workspaces and version control for specific libraries created in house (possibly by another part of your team who works away from the core app) could certainly see the advantages of working this way.

Code Control with access Control
Using all the features that CocoaPods has to offer - another benefit for creating a private repo is sharing your work externally. You may want to share / control versioning of a project that your working on with a client or a remote team members working on another product within your company, but at the same time keeping it locked down and in control as much as possible. With this approach you can simply grant them access to your repository & specs repository and away they go, full benefits of CocodPods without the need for sharing it to the world.

Using a private repo

Could not be more simpler.. let’s say you’ve got a sister company in Barcelona which you’ve already got access to their GitHub / Bitbucket account. They have a specs repo that points to their Pods sat within the same private repo.

Lets take a look at our Podfile on how we achieve this.

It really is as simple as above, just add the “source" line pointing to the private specs repo, add in your private Pod and run
pod update

CocoaPods (given that you have correct permissions) will pull the private specs repo locally, it will then search the specs files (including the local CocoaPods master specs repo) for your Pod, once found (again, credential permitting) will pull and install.

And your'e done for using private pods, but the next burning question is, how do we create one….

Creating a Private Specs Repository

Again much like using a private specs repo, creating it is very simple indeed, first you need a place for it to live, if you’ve already followed the above and created your first CocoaPod, why not let it live in the same account - makes sense right!

So simply create a new public repo and give it a unique name (or just call is ’specs’ like most people do) but like the the following

Now we tell CocoaPods that we’ve created a private repo and we tell it its name and where it lives, we’ll call this one “ChrisBarkersPrivateRepo" because it sounds ace!

pod repo add ChrisBarkersPrivateRepo

As you can see, very similar to the
pod repo add
we did back when pushing our first Pod to the master specs repo, only difference is we’ve added our specs repo's name and our git URL.

Once thats done, we can now push our Pod (well, it’s spec file) to our private repo

pod repo push ChrisBarkersPrivateRepo NSManchesterPod.podspec

With any luck, its all just worked out fine…. Go check you specs repo and you should see your first push along with the specs file you just pushed your Private Pod and it’s specs repo is now ready to use.


So we’ve taken a look at CocoaPods and how to use them, we’ve gone through how to setup and create your own Pod and we’ve taken a look at how we can share our Pod either publicly or through our own private repo.

All in all CocoaPods is a great dependancy manager with more to offer than I cover in this blog post. But as usual, when presenting my talk at NSManchester, it's often the discussions that the talks spark that really get you thinking.

Truthfully, I expected most people in the room to have already created their own (or a company) Pod, but was surprised to hear that not people has ventured down that route, with even some people saying they don’t really use CocoaPods. This started the conversation “why & when would you choose not use a CocoaPods".

In my honesty, when I joined a mobile app agency as an iOS developer, pretty much every project had a public CocoaPod in it, weather it be a Facebook SDK or some cool tool that a guy down the road wrote, CocoaPods where widely used.

But after much discussion, it seemed that one of the main concerns people were having was simply “code ownership". Who owns the code - is it the person who submitted the Pod - so is it up to them to update it to Swift 5 or 6 when you need to upgrade your project, you’ve got the source code in your repo now - do you or another member of your team maintain it - is the code safe, does it adhere to your coding standards and security policies - who’s responsibility is it to check this…..

With companies such as Parse deciding to call it a day, buy and Ice Cream Van and take off into the sunset, something that was once handled by someone else is now in your backlog and regardless how big or small it is there's going to be some impact somewhere down the line….