Start here, then get in touch

Transfer the .p12 to the machine over a secure channel, import it into the keychain used for builds, and confirm that it contains the matching private key. A certificate without its private key can’t sign code. Provide the import password through a CI secret; don’t put it in your repository, build script, or support ticket.

security find-identity -v -p codesigning

Run the check in the environment used by the runner. Seeing the certificate as a desktop user doesn’t mean another service user can access it. Also check that the keychain is unlocked, included in that user’s search list, and accessible to the signing process.

Use a dedicated keychain for builds and lock it according to your process when the job ends. If you need help, share only redacted identity check results and error text. Never send the .p12 file, private key, or import password.

Check four things: the Bundle ID, Team ID, export purpose, and entitlements. For apps with extensions, every Target that needs signing must have a matching configuration; a match for the main app doesn’t guarantee that the extensions are configured correctly.

Next, check that the provisioning profile is valid, includes the certificate in use, and matches the signing method selected for export. Development and distribution builds use different configurations, so don’t choose a profile based only on a similar filename.

Keep the export-stage logs and a redacted copy of ExportOptions.plist. In your support ticket, say whether the failure occurred during archive or exportArchive to narrow down the issue.

Store the .p8 file in a restricted-access directory, and provide the Key ID, Issuer ID, and file path through CI secrets. Grant only the permissions needed for uploads or automation. Don’t put the key contents directly in a lane or commit them to your repository.

An API key can be used for upload and management workflows that support this authentication method, but it can’t replace the certificate and private key required for local code signing. If a TestFlight upload fails, first determine whether the problem is local signing, API authentication, app permissions, or version information.

After rotating a key, update the runner configuration and remove old references. If you need support, share the redacted error code and the stage where it occurred—not the .p8 file.

Check access to the signing repository, the decryption password, distribution type, app identifier, and team configuration. For routine CI runs, use read-only access to fetch prepared signing assets rather than creating or modifying certificates every time.

lane :prepare_signing do
  match(
    type: "appstore",
    readonly: true,
    app_identifier: ENV.fetch("APP_IDENTIFIER"),
    team_id: ENV.fetch("TEAM_ID")
  )
end

Manage repository credentials separately from the decryption password. If fetching fails, check repository authentication. If decryption fails, check the password. If installation succeeds but signing fails, check the keychain and provisioning profile. Don’t lump all three issues together as “match isn’t working.”