Masterclass: Code signing & Provisioning profiles

The voodoo.

The dark alley.

Never works.

Do not touch “Fix issues” ever, it will ruin everything!

I can list hundred more scary quotes that various iOS developers will tell you. And for years this was actually close to the truth, as Xcode’s integrated attempts to ease the management of the profiles were less than stellar.

This is extremely complicated and convoluted part of the iOS developer life. Apple recognizes this and Xcode and iTunes Connect / Developer Portal teams have worked for years to make this work seamlessly.

So next time when you are fed up with all the nonsense and just want to burn it all – go and do just that. Seriously, make a clean start.

Step 0: nuke everything you have.

If you have existing prov. profiles, go and kill them all. You need to start fresh and clean and then let Xcode create everything for you, as you go along.

Know Your Accounts

Go to Preferences then Accounts and load up all the accounts you use. There are many options and various setups here.

iTunes Connect

Most devs think that you need to have paid iOS Dev Program account credentials to be able to manage apps, Test Flight builds and testers etc.

Not really, as iTC sports a rather sophisticated user-level system:

So you can add any AppleID here, even free ones, and have it assigned the role of App Manager which will give you all the app management stuff you need as contractor without giving you access to legal and financial parts that most clients - rightfully - don’t want to give you.

For your own apps, you will certainly have that one paid account which you also use to manage iTC and don’t need an additional account.

That covers the iTC, which handles the app metadata, Test Flight and App Store submission process.

Developer Portal

Developer portal is the place where you handle the App IDs, development and distribution certificates; setup technical details like iCloud containers, App Groups, Wallet Pass IDs and many other things that concerns you as developer but may not concern your client.

So what options are available here?

If you are indie developer, you probably have just one paid iOS dev program account, for which you are Team Agent. Agent is the most senior role, the master role. It has access to everything and can do everything.

If you are also working as consultant for a client that has a Company account for the iOS Standard Developer Program, you may have additional accounts for which you are Admin.

For development side of things, being Admin is enough. Your client (who is Team Agent) needs to send an invite to your email/AppleID related to your paid dev program and assigns you as Admin and not just as Member (which is common mistake). See this Apple Developer support page for up-to-date list of role permissions.

If you use the same account for consultancy as for your own app – something I strongly advise against – you may have a mix of Admin and Agent roles under the same account.

Calling people up to be a part of the team is only possible for dev program accounts signed up as Company. If your client only has Individual account, then he needs to give you credentials for it (essentially hand over the Team Agent access to you) or you won’t be able to work for them. There is no dancing around this.


Now, go to the Xcode, open Preferences then Accounts tab and add all the accounts you need:

Refresh each of them and make sure they are showing a clean slate (no projects, no profiles) - you nuked everything, remember?

Use default values for provisioning profiles

Now, when you setup your projects in Xcode, first stop is the Project configuration, General tab.

Select your Target, then choose proper Team: – you need to select the proper account for the Developer Portal. So it’s either one of the Team Agent or Admin accounts.

Do not use iTC App Manager account here, even though Xcode will offer it as option (Xcode lists all accounts you have added in its Preferences).

This setting configures the account that - for this project alone - Xcode will use to generate any certificates it needs, as well as create/update any provisioning profiles it may need along the way.

It will also create the required AppID which you can then pick in the iTunes Connect when you go to create a record for your new app. This is important - first create the project here in Xcode, setup proper bundle Identifier and then choose the team. Then you can go to iTC and hit Add new app button since you will have something to choose as AppID.

If Xcode shows you a progress loading indicator when you select the team, wait until it finishes whatever it is doing. What happens in background is that it takes the bundle ID then contacts Developer Portal and does the required work to setup certificates / profiles. This involves lots of back and forth between Xcode and Dev Portal, so be patient.

Then switch over to Build Settings tab and make sure you don’t have any specific stuff chosen here. Use iOS Developer as Code Signing Identity and set Provisioning Profile to Automatic.

Do not ever choose any of the specific accounts listed by Xcode. I have worked in some pretty complicated setups for various clients in last several years and never needed anything other then all Automatic.

Again – the goal is to not care about this.

Develop as usual

Now just get to development work and don’t care about anything. Turn stuff on and off in Capabilities tab, use the Fix Issue buttons when they show up etc. It will all just work.


When you are ready to submit to the iTunes Connect, first thing to do is make an xcarchive of your project. My checklist, to avoid headache, for each submission:

  1. Select Generic iOS device as target in the Scheme drop-down

  2. Click Product menu, press Option key, then choose Clean Build Folder…

  3. Then Product menu, choose Archive

  4. Wait until all is done and your Xcode Organizer window shows up

Then when you submit directly from Xcode (which is still a lottery) or export this build to upload later using Application Loader (use this if you value your sanity), a popup dialog appears:

Here you need to choose either your Team Agent or Team Admin account from Developer Portal. That’s because signing identity needs to be the account that can create certificates and profiles which are part of the Developer Portal.

What will happen in the background is that Xcode will automatically create any necessary distribution certificates and profiles for this project.

After choosing the account and continuing the process, Xcode will fetch signing credentials, sign all the stuff and show you the summary:

On this screen you will see the account and team used for the distribution certificate. If you login into Developer Portal you will see that Xcode has created what it needs to complete the process.

Exceptions and caveats

Small caveat: if you have previously used the wildcard App ID and have submitted it at some point, this would have created distribution profile for that.

If during further development you enable any of the features that require specific Bundle Identifier – say enable iCloud, PassKit, HealthKit etc – then Fix Issues for the development provisioning profile will still work. But it will not work for the distribution profile. Xcode get’s stuck at the “Signing assets” screen and will complain that it could not find signing identity / prov. profile for the chosen capabilities.

This is the only bug in the process I have experienced, with Xcode 6.4. Solution:

Easy-peasy. I did not have this happen to me for ages and certainly not with Xcode 7, because each new project I create has its own full Bundle Identifier. I do not use wildcard ones for anything, anymore.

Development profiles are checked / created every time you build during development. Every time you attach new device, it will complain that it needs to Fix Issues - just do it, it will work just fine.

Trouble is forcing Xcode to create distribution profile. It does that automatically per chosen team only when you get to actually submitting the app to the App Store, which happens in the Xcode Organizer.

But what about if you work in the Enterprise program? There is no submission there. Well, you also do Product / Archive and then in the Organizer you do the proper Export option - Xcode will then go and look for signing / provisioning profile and do its thing on the iTunes Connect backend.

Let the Force flow…

In essence - now in 2016, there are very little cases where it’s actually needed to go into Developer Portal and do anything manually.

This all, is tedious and annoying to manage by hand. Leave it to the machines.