Managing iOS code signing in CI is best handled through fastlane match, which stores certificates and provisioning profiles encrypted in a private repository or cloud storage bucket and syncs them to each CI runner automatically, replacing the fragile approach of manually exporting and copying certificate and profile files between machines. Match generates and maintains one shared certificate and profile set across your team and CI environment rather than each developer generating their own, which is what Apple's provisioning model expects but rarely gets in practice without a shared tool, and it distinguishes between development, ad hoc, App Store, and enterprise distribution profiles automatically. CI-specific setup requires a dedicated CI-only Apple account or, preferably, App Store Connect API keys instead of a full account login, storing match's encryption passphrase as a CI secret rather than in the repository, and running match in read-only mode during CI builds so the pipeline only fetches certificates. For simulator-only XCUITest runs, code signing is largely irrelevant since simulator builds sign automatically, so this setup mainly matters for testing on physical devices or archiving for TestFlight. Nanobase AI, an NVIDIA Inception Program member, configures fastlane match and CI secret management as part of the pipelines its Mobile Test Lab integrates with.
Code signing mostly matters for physical devices, not simulator tests
Simulator builds sign automatically, so code signing setup is largely irrelevant for XCUITest runs against the iOS Simulator. It becomes necessary the moment testing extends to physical devices or archiving a build for TestFlight distribution, which is when a manually managed set of certificates and profiles across a team and CI environment starts breaking in ways that are hard to diagnose from the error message alone. Most iOS CI signing failures trace back to a certificate or profile mismatch that fastlane match's centralized, encrypted storage model is specifically designed to prevent.
Common CI signing failures and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| "No matching provisioning profile found" | Profile does not include the CI runner's signing identity | Re-run match in the correct environment (development, ad hoc, App Store) |
| Certificate expired mid-build | Certificate rotation not synced to CI | Run match to fetch the current certificate before the build stage |
| "Multiple valid certificates found" | Local and CI-generated certificates coexist | Consolidate to a single team-shared certificate via match |
| Match decryption fails in CI | Encryption passphrase not set or incorrect as a CI secret | Verify the passphrase is stored correctly as a CI secret, not in the repository |
| Match tries to create new certificates in CI | Match not run in read-only mode | Set match to readonly mode for CI builds |
Nearly every entry in this table traces back to the same root cause: a certificate or profile that exists in one place but not the one CI is actually looking in.
Setup checklist for a clean CI signing pipeline
- Store certificates and provisioning profiles encrypted in a private repository or cloud storage bucket managed by fastlane match, rather than manually exporting files between machines.
- Create a dedicated CI-only Apple account, or preferably use App Store Connect API keys instead of a full account login, avoiding two-factor prompts that block automated runs.
- Store match's encryption passphrase and API key credentials as CI secrets, never committed to the repository.
- Run match in read-only mode during CI builds so the pipeline only fetches existing certificates rather than generating new ones on every run.
- Verify signing works end to end with a test build before wiring it into the full pipeline, since debugging signing issues inside a larger pipeline run is slower than isolating it first.
Following this checklist in order matters, since skipping the isolated verification step means any signing issue surfaces inside a longer, harder-to-debug pipeline run instead.
Why a shared certificate model matters
Match generates and maintains one shared certificate and profile set across the team and CI environment rather than each developer generating their own, which is what Apple's provisioning model expects but rarely gets in practice without a shared tool managing it. This distinguishes automatically between development, ad hoc, App Store, and enterprise distribution profiles, removing a common source of manual error. A single, centrally managed certificate set is what actually prevents the "works on my machine" version of a signing failure.
Frequently asked questions
Do simulator-only XCUITest runs need code signing configured?
No, simulator builds sign automatically without a distribution certificate or provisioning profile, so code signing setup only becomes necessary once testing extends to physical devices or TestFlight archiving.
Why use App Store Connect API keys instead of a CI Apple account login?
API keys avoid two-factor authentication prompts that block unattended automated runs, and full account credentials carry more risk if leaked, since API keys can be scoped and revoked independently of a real account.
What does running match in read-only mode actually prevent?
It prevents the CI pipeline from generating new certificates or profiles during a build, which would otherwise risk exceeding Apple's certificate limits or creating inconsistent signing identities across different CI runs.
How does this fit with running XCUITest on GitHub Actions?
Code signing setup is one piece of a broader CI configuration; see running XCUITest on GitHub Actions for the rest of that pipeline setup.
How Nanobase AI helps
Nanobase AI, an accepted member of the NVIDIA Inception Program, configures fastlane match and CI secret management as part of the pipelines its Mobile Test Lab integrates with, resolving the signing failures above before they block a release pipeline. Signing is set up once, centrally, so individual engineers stop hitting profile and certificate errors on their own machines. This pairs with our running iOS UI tests without a Mac guidance for teams without dedicated Mac CI hardware.
Ready to discuss your project? Contact Nanobase AI or email hello@bumu.tech.