Fix "No signing certificate matching team ID" in GitHub Actions

When building an iOS app in GitHub Actions, a common issue encountered is a failure during the archive/export step. The error message "No signing certificate iOS Distribution matching team ID XXXXXXXXXX with a private key was found" indicates that there is a mismatch between the signing certificate and the one being used by the CI job. This mismatch is rarely due to a coding error but rather a discrepancy between Apple's portal and the CI job's certificate usage. To resolve this issue, follow these steps in order:

1. Verify whether the certificate was successfully imported. Check the Actions log for the "Import signing certificate" step, which prints the identities found after importing the .p12 file. If the list is empty or the identity is missing, the certificate import failed. Possible causes include truncation or corruption of the base64-encoded .p12 secret or an incorrect .p12 password. Re-export the certificate fresh to avoid debugging the existing value.

2. Confirm that the certificate and the provisioning profile match. A provisioning profile is specific to a signing certificate. If the certificate import was successful, the next common cause is that the certificate on Apple's portal was regenerated without updating the associated profile. In this case, regenerate the provisioning profile in the developer portal, download it, and update the base64 secret used in your workflow.

3. Ensure that the profile name and bundle ID match exactly. Even a typo in the profile name or bundle ID can cause the issue to persist. Both values must match character-for-character, including case and whitespace, between Apple's portal and your CI configuration. Copy the values directly from the developer portal rather than retyping them from memory. This step is crucial to catching mismatches caused by typos.

If none of these steps resolve the issue, double-check that you are using an Apple Distribution certificate instead of an Apple Development certificate. TestFlight and App Store builds require an iOS Distribution certificate, not a Development one.

This issue is more likely to occur in CI environments compared to using Xcode's GUI, as Xcode handles the matching automatically when "Automatically manage signing" is enabled. However, CI uses the certificate and profile you provide directly, making mismatch errors more noticeable as hard failures. The author encountered these issues while building a CI pipeline for Citolex, and a detailed writeup of the signing setup can be found at macless.dev.