Guides

Code signing & TestFlight

Last updated 6 November 2026

How to get a signed .ipa out of a build, and what we do — and deliberately do not do — with your Apple credentials.

01The one rule that matters

A build never writes anything to your Apple Developer account. We do not pass -allowProvisioningUpdates, we do not let Xcode “fix” signing automatically, and we do not register devices or create certificates on your behalf.

This is not caution for its own sake. Automatic signing creates a new certificate whose private key lives on the machine that made it — and our machines are destroyed after every build. Left on, it would quietly fill your account with dead certificates until you hit Apple's limit and your own laptop could no longer sign anything.

So: you create the certificate and the profile once, the way you already do, and we use them. Nothing more.

02Finding your way around Apple’s website

Everything in this guide happens on two Apple sites that look similar but are not the same. Getting lost between them is normal — neither file you need is on the page you land on after signing in. This section is the map.

developer.apple.com Sign in Account Certificates, Identifiers & Profiles this hop is easy to miss Certificates Profiles appstoreconnect.apple.com Sign in Users and Access Integrations Keys → download .p8 The .p8 downloads once. Apple will not show it again — keep the file.

Green boxes are the two pages you actually need.

Which account do I sign in with?

The Apple ID that owns your Apple Developer Program membership — the one the $99/year fee is paid with. On a company team it must have the Admin or App Manager role; a member without one of those cannot create certificates. A free Apple ID cannot issue a distribution certificate at all. Both sites below use the same Apple ID. If you belong to more than one team, set the team selector at the top right before looking for anything — every list is per team and looks empty on the wrong one.

Site 1 — developer.apple.com (certificates and profiles)

  1. Go to developer.apple.com and click Account in the top-right corner.
  2. In the left sidebar open Certificates, Identifiers & Profiles. This is the hop people miss — certificates are not on the account landing page.
  3. Click Certificates. The table is your certificate list; count the rows of type Apple Distribution. Apple caps distribution certificates per team (three at the time of writing), and at the cap the create button simply stops offering Apple Distribution with no explanation.
  4. For provisioning profiles, click Profiles in the same sidebar, click the row for your profile, then Download at the top right of the detail panel. The file ends in .mobileprovision.

Before you revoke anything. Revoking a distribution certificate does not remove apps already on the App Store, but it does break every build and upload that still signs with it — including ours — from the moment you revoke. Check what is using a certificate before freeing up a slot.

I am on Profiles and I do not see mine

A profile only appears once an App ID and a certificate exist for the same team, and the list is filtered by platform. Set the filter to iOS and check the team selector. If it genuinely is not there, create it: Profiles → add → App Store Connect, pick your App ID, pick the distribution certificate you just made, name it, then Download.

Site 2 — appstoreconnect.apple.com (API keys and TestFlight)

  1. Go to appstoreconnect.apple.com, click Users and Access, then the Integrations tab, then App Store Connect API in the left list.
  2. Click + next to Active. Name it MacBuildCloud, set Access to App Manager, then Generate.
  3. Three things on that page go into Secrets on your MacBuildCloud dashboard. Add one secret with Kind set to App Store Connect key, then fill in:
    • Apple’s Issuer ID (top of the page) → the Issuer ID field
    • Apple’s KEY ID (in the key’s row) → the Key ID field
    • The downloaded .p8 → the File field. Download works once only — Apple will not show that file again.
  4. TestFlight builds appear under Apps → your app → TestFlight. A new upload shows within a few minutes as Processing, then becomes installable.

03What to upload

Three kinds of credential live in Secrets on your dashboard. Each is encrypted at rest and only ever decrypted onto the machine running your build.

KindFileWhere it comes from
Certificate.p12 On a Mac: Keychain Access → export your Apple Distribution identity, with its password. On Windows or Linux: OpenSSL, see section 04 below.
Provisioning profile .mobileprovision developer.apple.com → Profiles → download
App Store Connect key .p8 App Store Connect → Users and Access → Integrations → keys. Needed only for uploading.

On a Mac, export the identity, not just the certificate: the .p12 has to contain the private key. In Keychain Access, expand the certificate and select it together with the key underneath it before exporting. A .p12 without the key imports cleanly and then fails at codesign with a message that does not mention the key at all.

No Mac? You do not need one. The next section makes the same .p12 on Windows or Linux with OpenSSL.

04Making the .p12 without a Mac

Keychain Access is not the only way to get a signing identity — it is just the way Apple documents. Everything below runs on Windows (OpenSSL ships with Git for Windows, or install it on its own) and on Linux. You never touch a Mac: your certificate is created here, used on our machines during the build, and destroyed with the machine.

1. Make a private key and a certificate request. Keep the .key file — without it the certificate Apple issues is useless.

openssl req -new -newkey rsa:2048 -nodes \
  -keyout ios_distribution.key \
  -out ios_distribution.csr \
  -subj "/emailAddress=you@example.com/CN=Your Name/C=HK"

2. Get it signed by Apple. On developer.apple.com go to Certificates → add one → Apple Distribution, upload ios_distribution.csr, and download the .cer it gives you. This is all in the browser.

3. Put the key and the certificate into one .p12. Apple hands out the certificate in DER form, so convert it first. The last command asks you to set a password twice — that is the password you give us with the file.

openssl x509 -inform DER -in distribution.cer -out distribution.pem

openssl pkcs12 -export \
  -inkey ios_distribution.key \
  -in distribution.pem \
  -out distribution.p12

Upload distribution.p12 with that password as your certificate secret. That is the whole difference: on a Mac the export button does these three steps for you.

Recent OpenSSL writes a .p12 that macOS refuses to import, and the error it gives says wrong password? even though the password is right — a trap that has cost people whole afternoons. We convert the file when you upload it, without changing a byte of the key or the certificate, so you do not have to know about it. If you see that message somewhere else, this is why.

05Pointing a build at them

signing:
  certificate: APPLE_DIST_CERT
  profile: MyApp_AppStore

The values are the secret names you chose on the Secrets page, not filenames. If a build needs more than one profile — an app with an extension, a widget, a watch app — list them all:

signing:
  certificate: APPLE_DIST_CERT
  profile: MyApp_AppStore, MyApp_Widget, MyApp_Watch
List every profile the target needs, including extensions. A missing one surfaces as Xcode's No profiles were found, which names the bundle id of the extension — easy to read past when you are looking at the app's own bundle id.

06What happens on the machine

Worth knowing, because it explains the error messages:

  1. A temporary keychain is created for this build alone, with a random password, and your certificate is imported into it. Your credentials never touch a shared or default keychain.
  2. Each profile is decoded, checked that it really is a profile, and installed under its own Apple-assigned UUID into both of the directories Xcode looks in. Naming them by UUID matters: two profiles downloaded from Apple are both called profile.mobileprovision, and one would silently overwrite the other.
  3. Your script runs.
  4. The keychain and both profile directories are deleted, and then the whole machine is destroyed.

Credentials are read from a read-only mount and are never written to the machine's own disk. They are not in the build script, so they cannot end up in your log or get swept up by an artifact glob.

07Exporting an .ipa

You need an ExportOptions.plist in your repository. It is a plain text file — write it in any editor, on any operating system. Copy this one and change the three values; if you do have a Mac, exporting once from Xcode also produces a correct one.

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
  <key>method</key>            <string>app-store-connect</string>
  <key>teamID</key>            <string>YOURTEAMID</string>
  <key>signingStyle</key>      <string>manual</string>
  <key>provisioningProfiles</key>
  <dict>
    <key>com.example.myapp</key><string>MyApp AppStore</string>
  </dict>
</dict>
</plist>

signingStyle must be manual. The value under provisioningProfiles is the profile's name as Apple shows it, which is not necessarily the secret name you chose here.

signing:
  certificate: APPLE_DIST_CERT
  profile: MyApp_AppStore

script:
  - xcodebuild \
      -workspace MyApp.xcworkspace -scheme MyApp \
      -destination "generic/platform=iOS" \
      -archivePath build/MyApp.xcarchive \
      CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY="" \
      archive
  - xcodebuild \
      -exportArchive \
      -archivePath build/MyApp.xcarchive \
      -exportOptionsPlist ExportOptions.plist \
      -exportPath build/ipa

artifacts:
  - build/ipa/*.ipa

Note the archive step is told not to sign. Signing happens in -exportArchive, from your ExportOptions and the certificate and profile we installed. Signing at archive time only works when the project itself is set up for manual signing with your team; signing at export time works for every project, which is why all our examples do it. Flutter is the same idea: flutter build ipa --no-codesign, then export.

08Uploading to TestFlight

Add your App Store Connect key to Secrets and name it in the secrets section. We put it where Apple's tools look for it and export two variables for you:

secrets:
  - ASC_KEY

signing:
  certificate: APPLE_DIST_CERT
  profile: MyApp_AppStore

script:
  - xcodebuild ... archive
  - xcodebuild -exportArchive ... -exportPath build/ipa
  - xcrun altool --upload-app -f build/ipa/MyApp.ipa -t ios \
      --apiKey "$ASC_KEY_ID" --apiIssuer "$ASC_ISSUER_ID"

Each upload needs a build number App Store Connect has not seen. Use $MBC_BUILD_NUMBER, which is different for every build: pass CURRENT_PROJECT_VERSION=$MBC_BUILD_NUMBER to the archive step (or --build-number=$MBC_BUILD_NUMBER to Flutter).

The key needs the App Manager role. A Developer-role key is accepted by App Store Connect when you create it and then rejected at upload — the failure arrives minutes later, at the end of a build, which is an expensive way to find out.

Upload puts the build in App Store Connect as Processing; Apple takes a few minutes to turn it into a TestFlight build. The first upload of any app also asks you, in the App Store Connect UI, whether it uses encryption. Nothing automated can answer that for you.

09When signing fails

MessageWhat it usually is
No signing certificate “iOS Distribution” found The .p12 has no private key, or the certificate has expired. Check the expiry date on developer.apple.com first — it is the more common of the two.
No profiles for ‘com.example.app’ were found The bundle id in the profile does not match the one in the target, or you did not list the profile for an extension. Read the bundle id in the message carefully.
Provisioning profile doesn't include signing certificate The profile was made against a different certificate. Regenerate the profile after replacing a certificate — Apple does not update it for you.
Could not read the provisioning profile Ours, not Xcode's. The uploaded file is not a .mobileprovision — often a .cer or a renamed .p12.

10If you would rather not upload a certificate at all

Then do not. Build with CODE_SIGNING_ALLOWED=NO (or flutter build ios --no-codesign) and sign on a machine you control. You get compilation, tests and artifacts from us, and your signing identity never leaves your laptop.

For many teams that is the right split, and it is what we would suggest you start with.


Something here wrong or missing? Tell us — we read every message, and documentation fixes go out the same day.