iOS Code Signing Explained: Certificates, Profiles and Keys

Most first-time iOS releases do not fail because of the code. They fail at the signing step, with an error message that names a certificate, a profile or an entitlement and assumes you already know how those relate. This guide explains each piece, how they connect, and how to diagnose the errors you are most likely to see in Xcode or a CI pipeline.

The five building blocks, defined

Think of code signing as a chain of trust. Every link has to be present and has to point at the next one.

• Signing certificate: an identity issued by Apple to your developer account. In practice there are two you care about: Apple Development (for running builds on test devices) and Apple Distribution (for TestFlight and App Store builds). The certificate is public; what makes it useful is the matching private key, which lives in the keychain of the Mac that created the certificate request.
• App ID / bundle identifier: the reverse-DNS name of your app, such as com.example.notes. It is registered in your developer account and carries the list of enabled capabilities (push notifications, Sign in with Apple, App Groups, associated domains and so on).
• Entitlements: the capabilities your binary claims at runtime. They are declared in an .entitlements file in the Xcode project and must be a subset of what the App ID allows.
• Provisioning profile: a signed file from Apple that bundles an App ID, one or more certificates, the allowed entitlements and, for development and ad hoc profiles, a list of device UDIDs. It is the document that says "this certificate may sign this app with these capabilities".
• Keys (.p8 files): separate from certificates. An App Store Connect API key lets tools like Fastlane, Xcode Cloud or a CI runner upload builds and manage profiles without a personal Apple ID login. An APNs authentication key is used by your server to send push notifications. Neither signs your app binary.

How the pieces fit together at build time

1. Xcode (or xcodebuild) reads the bundle identifier and the entitlements file of your target.
2. It looks for a provisioning profile whose App ID matches the bundle identifier and whose entitlements cover the ones in your file.
3. It checks that the profile includes a certificate for which the private key is available in the current keychain.
4. It signs every executable part of the app (the main binary, frameworks and app extensions) with that identity and embeds the profile.
5. When you upload, App Store Connect validates the signature, the profile type and the entitlements again before the build reaches processing.

Each app extension (widgets, notification service extension, share extension) has its own bundle identifier and needs its own matching profile. Forgetting this is one of the most frequent reasons a build signs fine locally but fails during export or upload.

Profile types and when each is used

For a normal App Store release you only need one Apple Distribution certificate per team and one App Store profile per bundle identifier.

Automatic vs. manual signing vs. a shared signing repository

There are three common ways to manage all of this, and the right one depends mostly on how many machines build your app.

• Xcode automatic signing: Xcode creates and renews certificates and profiles for you. Ideal for a solo developer on one Mac. It becomes fragile when several people or a CI server each create their own certificates, because you end up with multiple identities and profiles that silently replace each other.
• Manual signing: you create certificates and profiles in the developer portal, download them and select them explicitly in the target settings. Predictable, but someone has to remember renewals and distribute the private key securely.
• Shared signing repository (for example Fastlane match): one encrypted store (a private Git repo or a cloud bucket) holds the certificates, private keys and profiles. Every developer machine and CI runner pulls the same identity read-only. This is the most robust option for teams and for pipelines where coding agents push code but should never touch signing material.

If you use Xcode Cloud or Expo's EAS Build, those services can manage signing credentials for you. Check their current documentation for how credentials are stored and who on your team can access them.

Error messages and what they usually mean

A hygiene checklist for teams

• Enroll as an organization so certificates belong to the company, not to an individual. Our guide to the Apple Developer account for companies covers roles and access.
• Keep exactly one active Apple Distribution certificate and document who can revoke it. Revoking does not remove live apps from the App Store, but it breaks every profile and pipeline that depends on it.
• Put renewal dates for certificates and profiles in a shared calendar. Both expire, typically after a year.
• Store private keys and .p8 files only in a secrets manager or an encrypted signing repository, never in the app repository and never in prompts or chat logs with an AI assistant.
• Use an App Store Connect API key with the narrowest role that still allows uploads for CI.
• Write the signing setup into your project README so the next person (or agent) does not reinvent it. The same applies to the pipeline itself; see CI/CD for AI-generated mobile apps and the Fastlane setup for Claude Code projects.

When to hand signing off

Signing is a one-time setup with recurring maintenance, and it is unforgiving: a wrong profile type or a missing extension profile costs a full build-and-upload cycle each time. If you would rather spend that time on the product, appsubmitter.io sets up signing and CI/CD inside your own Apple and Google developer accounts and handles the submission, so the certificates stay yours. Either way, run through the App Store submission checklist before your first upload; signing is only one of the gates.

Apple's own reference for all of the above is the Apple Developer Documentation and the Certificates, Identifiers & Profiles section of your developer account.