Our iPhone builds run in the cloud, because we develop on Windows. The first working pipeline signed the app automatically and it worked, until it did not. Every run quietly created one more certificate in the developer account, and one day the builds started failing with a missing private key. This is what was happening and the setup that replaced it.
The symptom: certificates piling up
With cloud-managed signing during the archive step, the build asks the App Store Connect API for what it needs. In our case that meant a new Apple Development certificate with the note Created via API on every single build. They add up fast. The account has a limit on how many certificates of a type it can hold, which we hit at around eleven.
Then the second failure appeared: the archive step complained that the private key was not installed. A certificate without the matching private key on the machine is useless, and a fresh build machine never has the key of a certificate that an earlier machine created.
The tempting shortcut that fails later
The obvious idea is to archive without signing and sign when exporting. The archive succeeds, the export even produces a package, and the upload is rejected by App Store Connect with an invalid signature error, number 90035. The reason is that the frameworks embedded in the app stay unsigned when the archive was built with code signing switched off. Signing only the outer app is not enough, every embedded framework needs its own signature.
So there is no shortcut here. The archive has to be signed properly, with a certificate whose private key is present on the build machine.
The stable setup: one distribution key you keep
The fix is to stop letting every build invent its own identity. You create one distribution certificate, keep its private key safe outside the cloud service, and give the build the same key every time. The build then asks the API for the certificate and the provisioning profile, and the API returns the same certificate it already has for that key instead of minting a new one.
In our pipeline the private key is stored base64 encoded in a secret variable group, next to the App Store Connect API key and its two identifiers. During the build it is decoded to a file and checked with openssl, so a damaged secret fails in the first minute and not at the end of a long build.
The steps, in order
- Rebuild the API key file as a clean PEM: secrets often arrive with their line breaks mangled, so strip the header and footer, whitespace and literal backslash-n sequences, then wrap the body at 64 characters and verify it with openssl.
- Set the build number in the project and in the Info.plist, and print it again from the finished package before uploading.
- Decode the distribution private key from the secret and check it with openssl.
- Initialize the keychain on the build machine.
- Fetch the signing files for the bundle id with the create flag, type iOS App Store. The tool reuses the certificate that belongs to your key.
- Add the certificates to the keychain, then apply the provisioning profiles to the Xcode project.
- Build the signed ipa from the project and scheme, then publish it to TestFlight.
Saving minutes
Build minutes on a macOS machine are limited on a free plan, and every failed signing run burns some of them. Two habits help. First, start the signing workflow only by hand, so a push does not spend minutes. Second, keep a separate simulator workflow that builds without signing and never talks to Apple. It finds ordinary compile errors quickly and for free in terms of certificates.
We also run a script on Windows before any cloud build that checks the project for the mistakes we already paid for once. A rule that costs one second beats a build that costs ten minutes.
What to take away
- Automatic cloud signing is fine for a first experiment, but it creates a new certificate per run.
- An unsigned archive signed at export leaves frameworks unsigned and fails upload validation.
- Create one distribution certificate, keep its private key backed up, and pass it to every build as a secret.
- Validate secrets early in the build, and print the version numbers from the final package.
FAQ
Why did the builds fail with a missing private key?
Each run created a new certificate on a new machine, and the private key of a certificate exists only on the machine that created it.
Can I archive without signing and sign later?
Not reliably. The embedded frameworks stay unsigned and App Store Connect rejects the upload with an invalid signature error.
Where should the distribution private key live?
In a secure backup you control, and in the CI service as a secret variable, never in the repository.
Do I need a Mac to set this up?
No. The certificate request and the key can be created on any machine, and the cloud build does the rest.
Top comments (0)