A production build starts failing after a signing certificate changes, even though the new certificate is in the Keychain.
Fastest safe path: identify the certificate type and account constraints, update the linked provisioning profile, validate the full release path on an isolated Mac CI node, and only then move production jobs. If a private key may have leaked, treat it as an incident and revoke it promptly rather than preserving a planned overlap.
This guide is for IT administrators managing Apple Developer accounts and signing assets, platform teams maintaining iOS CI/CD, and release or security owners deciding between routine rotation and emergency response.
[ SECTION_01 ] Start with the certificate and its permitted use
Enterprise iOS CI certificate rotation begins with one question: what kind of signing asset is actually in the failing or changing path? Do not assume every certificate can be replaced in parallel or that revoking one has the same effect on every app and distribution route.
Apple distinguishes development and distribution certificate types, including Apple Development, Apple Distribution, and Developer ID. Their intended uses differ. Developer ID is for signing Mac software distributed outside the Mac App Store; it is not a substitute for an iOS app distribution certificate. Check the Apple certificate overview against the actual app and delivery route.
Cloud-managed certificates are another distinct mechanism. They are managed through Apple’s service and have a different creation and use flow from a locally generated certificate with a privately held key. The cloud-managed certificate guidance should be checked before planning a replacement; do not assume that a cloud-managed asset can be exported or rotated like a local certificate.
Keep these assets separate in the change record:
- Certificate: identifies a signing identity and has a type-specific purpose.
- Private key: the sensitive key material paired with a locally generated certificate. A certificate file alone is not a usable replacement for a missing private key.
- Provisioning Profile: connects an app’s identifier and signing configuration to permitted distribution or development conditions.
- Apple Developer account access: determines who can manage the relevant certificates and profiles.
- CI node access: determines who can use the installed identity, profile, and build environment.
Account access is not the same as Keychain access. Confirm who can create or revoke account assets using Apple’s role permissions table, then separately audit who can access the Mac CI node and its signing credentials.
[ SECTION_02 ] Build the rotation baseline before changing anything
A rotation plan should describe the current working release path, not just list certificates. Record enough evidence to identify what a successful build uses and what must change.
Start with an asset inventory for each affected application:
- App ID and distribution route.
- Certificate type, displayed status, and expiry information shown in the account.
- Whether the private key is present, where it is stored, and which operators or automation identities can access it.
- Provisioning Profile name, App ID, associated certificate, entitlements, and current file location.
- CI workflow, signing mode, Mac node, and the jobs that consume the profile.
- Publishing credentials and delivery destination, tracked separately from signing assets.
Use the Apple Developer account records and the latest successful pipeline as evidence. If the build logs do not make the selected identity and profile clear, improve that observability before rotation. Otherwise, a green build after the change may still be using cached or old assets.
Set the change owner, approver, maintenance window, application priority, and rollback condition. A practical rollback condition is an observable failure in signing, archive creation, export, or delivery—not simply a vague concern that the new certificate “looks wrong.” Decide in advance whether rollback means restoring the previous profile and signing configuration or pausing publication while the account state is repaired.
How can a team recover publishing after a certificate expires? First identify the expired certificate and the profile and pipeline that depend on it. Create or enable a valid replacement under the account’s rules, update the corresponding profile, and test the entire release path. Re-importing a certificate into Keychain alone does not repair a profile that still references a different signing identity.
[ SECTION_03 ] Prepare the replacement under account rules
Before creating a new asset, confirm whether the current certificate is still valid, whether the account permits the intended action, and whether the certificate type supports the planned transition. Certificate creation and revocation are account operations; local administrator access to a Mac does not grant the necessary Apple Developer permissions.
Review the account’s current state and the relevant Apple documentation. Do not build a runbook around an assumed certificate quota, overlap period, or guaranteed no-downtime handoff. Those details depend on certificate type and account state. If the required old and new identities cannot coexist for validation, use a controlled maintenance window and make the release pause an explicit part of the plan.
For a locally managed certificate, generate and protect the private key through the approved process. Keep its access limited to the operators and CI identities that need it. Record who generated it, how it was transferred, where it is installed, and how it will be removed from old nodes. Do not place private keys in source control, ordinary build artifacts, or broadly readable shared storage.
For a cloud-managed certificate, follow the applicable Apple workflow rather than attempting to handle it as a downloadable private-key pair. Record which account and toolchain path will use it, and test that specific path on the intended build node.
Also verify the operator’s role before the maintenance window. Apple’s role guidance identifies permissions associated with account tasks. If the designated operator cannot create, edit, or revoke the required asset, resolve that access dependency before starting the change—not during a release outage.
Treat a suspected private-key exposure differently from a routine expiry. Preserve relevant audit evidence, restrict access to affected systems, and follow the organization’s incident process. Do not keep a potentially compromised identity active merely to maintain a convenient overlap.
[ SECTION_04 ] Refresh profiles and signing configuration
Replacing a certificate does not automatically guarantee that every pipeline will use a matching profile. Check the actual profile contents and the signing mode for each affected app.
For manual signing, identify the profile tied to the app’s App ID and distribution method. If its associated certificate must change, edit or regenerate the profile as applicable, then download and install the updated file on the test node. Apple’s App Store provisioning profile instructions describe the profile’s relationship to the app and distribution signing setup. Use the profile edit and download documentation to confirm the correct update path.
For Xcode-managed signing, verify the account access available to the build environment and confirm that the selected team, bundle identifier, and signing mode match the release configuration. A profile visible in one developer’s local Xcode environment is not proof that a headless CI job can retrieve or use the same asset.
Apple documents profile changes and their consequences in its provisioning profile update guidance. Check that guidance for the profile type in use. Do not generalize one profile’s update behavior to every development or distribution path.
Does a new Apple Distribution certificate require a new Provisioning Profile? Check whether the existing profile includes the replacement certificate and remains valid for the app’s signing configuration. If it does not, update or regenerate the profile and install that version in the relevant CI environment. Replacing only the Keychain identity can leave the build signing against an outdated profile.
After updating, remove ambiguity in the node: label the new profile clearly, remove stale copies from the active search path, and confirm that the pipeline selects the intended file. Keep the old asset available only as long as the approved rollback plan requires it, and restrict access while it remains present.
[ SECTION_05 ] Validate the complete chain on an isolated Mac
Do not use the first production release as the test. Select a representative app and run it on an isolated Mac CI node or a non-production job that cannot publish over the production release.
The validation should cover the entire chain:
- The build process can find the expected certificate and profile.
- The signing identity is the new, intended identity.
- The app’s bundle identifier and entitlements match the profile.
- The archive completes and the exported app is signed as expected.
- The output reaches the intended test or delivery destination without using a production release job.
- Logs, build artifacts, and change records show which assets were used.
- The rollback configuration remains available and has not been silently overwritten.
How can a team verify a new certificate without affecting production? Use a separate node or isolated job with its own test output path and no production publishing permission. Validate certificate selection, profile matching, archive, export, and delivery. A successful compile alone is not a signing acceptance test.
Compare the signing results and logs against the baseline. Search for references to the old certificate or profile, including cached paths and scripts that select assets by name. If the node has multiple identities installed, confirm the build selected the expected one rather than relying on the fact that the new certificate appears in Keychain.
Before production cutover, require an auditable pass record: test run identifier, selected identity and profile, reviewer approval, and the rollback trigger. If any of these are missing, keep the production job on the known-good path and fix the evidence gap first.
[ SECTION_06 ] Cut production over in controlled batches
Move applications or pipelines in manageable batches. For each batch, change the profile and signing selection, run the production-equivalent build, and inspect the first delivery result before proceeding to the next group. Keep unrelated certificate or publishing changes out of the same change window; otherwise, a failure becomes harder to attribute.
Set a pause condition before the first change. Examples include a profile mismatch, unexpected old-identity selection, archive or export failure, or rejection at the delivery step. If a condition is met, stop the batch, preserve logs, and use the documented rollback path. Do not continue changing other applications while the cause is unknown.
Should the old certificate be revoked immediately after cutover? Not automatically. First confirm that the replacement is accepted, the affected production paths use it, and no approved rollback still depends on the old asset. Then decide the old certificate’s disposition according to its type, current account state, and Apple’s revocation guidance. Apple explains the certificate revocation process; its revocation permissions reference also helps distinguish who may take that action. Revocation can affect associated provisioning profiles, so check and repair dependent profiles rather than treating revocation as isolated cleanup.
For suspected exposure, use the security incident path instead of the normal rollout sequence. Restrict access, identify affected certificates and profiles, and follow the applicable urgent revocation and replacement procedure. Then repair affected profiles and validate the replacement signing path. Do not delay action on a compromised private key simply to preserve a routine cutover schedule.
[ SECTION_07 ] Rotation acceptance checklist
Use this checklist as a production gate. Each item should have an owner or recorded evidence.
- [ ] Identify the certificate type and the apps and distribution routes that depend on it.
- [ ] Record the current certificate, private-key location, profile, CI node, and last successful release path.
- [ ] Confirm account permissions for creating, editing, or revoking the required assets.
- [ ] Document the maintenance window, approver, rollback path, and batch pause conditions.
- [ ] Create or enable the replacement through the correct certificate-specific process.
- [ ] Update or regenerate each profile that needs to reference the replacement certificate.
- [ ] Install and verify the intended certificate and profile on an isolated Mac CI node.
- [ ] Test signing, archive, export, and non-production delivery; retain logs and review evidence.
- [ ] Switch production jobs in batches and inspect each initial delivery result.
- [ ] Remove or revoke old assets only after checking rollback needs, profile impact, and incident status.
[ SECTION_08 ] Choose the rotation path by operational fit
The right route depends on how the certificate is managed and whether the team can safely validate before cutover. The ratings below are qualitative fit for a release rotation, not measured performance scores.
| Signing path | Rotation fit | Main validation gate | Key caution |
|---|---|---|---|
| Locally managed Apple Distribution certificate | Strong when the team controls private-key custody and can test a replacement | Confirm the new identity and updated profile are selected by the isolated build | Do not assume every account state allows parallel use |
| Cloud-managed certificate | Conditional on the account and toolchain workflow | Validate the Apple-managed path on the actual CI node | Do not treat it as an exportable local key pair |
| Apple Development certificate | Not a production distribution replacement | Validate development signing and its intended test route | Its purpose differs from App Store distribution |
| Developer ID certificate | Not applicable to iOS app distribution | Use only for the relevant Mac app distribution route | Do not substitute it for iOS signing |
For temporary validation, an isolated remote Mac can keep test signing and release checks separate from developers’ everyday machines. That still requires explicit control of node access, Keychain contents, and publishing permissions. Teams comparing hosted capacity with dedicated hardware can review NOVAKVM remote Mac options as one input to their environment plan; it does not replace account-level controls or a tested rotation procedure.
The tradeoff is operational, not merely hardware cost. A team’s current shared workstation may create contention, inconsistent signing state, and unclear access boundaries. A generic cloud runner may not provide the macOS environment or Apple signing workflow the release requires. Buying a dedicated Mac avoids some shared-capacity concerns but leaves procurement, maintenance, and idle-capacity costs with the team. For a short pilot or temporary isolated test node, renting a Mac through NOVAKVM may be worth evaluating; compare that option with local ownership and other cloud capacity against security controls, access needs, and expected usage. The Mac mini ordering information can support that evaluation, but the release team should verify the required access and delivery details before assigning any production role.