Code Signing Troubleshooting

Common Code Signing Issues

No Signing Credentials Configured

Symptom: Your build fails in the codesign step. The surrounding log lines mention missing signing certificates or profiles.

Cause:

API key not set up at workspace level
App signing configuration not set
Missing Apple credential selection for automatic mode

Solution:

Go to Workspace Settings > Apple Signing
Verify API key is configured:
- Issuer ID is entered
- Key ID is entered
- Team ID is entered
- Private key (.p8) is pasted
Click Save if you’ve made changes
Go to App Settings > Code Signing
Verify app configuration:
- Bundle Identifier is entered
- Signing Type is selected
- Apple Credential is selected (for automatic mode)
Click Save if you’ve made changes

If you’re on the Free plan, note that automatic code signing requires PAYG or higher. Manual mode signing is available on all plans.

Certificate Expired or Invalid

Symptom: Your build fails during the codesign step. Log lines mention certificate validation failures.

Cause:

Your Apple Distribution certificate has expired
Certificate was revoked in Apple Developer account
Certificate is malformed or corrupted

Solution:

For auto-generated certificates:

RunnerHub will automatically create a replacement certificate on the next build
No action needed

For manually uploaded P12 certificates:

Go to App Settings > Code Signing
Check the certificate expiry date
If expired:
- Export a new P12 from Keychain Access with a strong password
- Upload the new P12 to RunnerHub

Bundle ID Registration Issues

Symptom: Your build fails with the provisioning profile creation step. Log lines mention bundle ID lookup failures.

Cause:

Bundle ID in App Settings is not registered in Apple Developer
Bundle ID has a typo
API key lacks permissions to check bundle IDs

Solution:

Missing bundle IDs are auto-registered in your Apple account. If you see failures here, the issue is usually insufficient API key permissions:

Verify API key role in App Store Connect:
- Go to Users and Access > Keys
- Your key should have Developer or App Manager access
- If not, revoke it and create a new key with proper permissions
In RunnerHub App Settings > Code Signing:
- Verify bundle ID matches your Xcode project exactly (case-sensitive)
- Save changes and re-run the build
If you continue to see failures, manually register the bundle ID in Apple Developer:
- Go to App Store Connect
- Click Certificates, Identifiers & Profiles > Identifiers
- Click + to register a new identifier if needed
- Verify bundle ID matches your RunnerHub configuration exactly

Bundle ID Mismatch Between Build and Configuration

Symptom: Your build fails during xcodebuild. Log lines mention bundle ID validation failures or mismatches.

Cause:

Bundle ID in App Settings doesn’t match your Xcode project
Typo in either RunnerHub or Xcode configuration

Solution:

Open your Xcode project
Select the target
Go to Build Settings > Product Bundle Identifier
Copy the bundle ID from Xcode
In RunnerHub App Settings > Code Signing, paste the bundle ID exactly
Ensure it matches with no extra spaces
Save and re-run the build

Provisioning Profile Creation Failures

Symptom: Your build fails during the provisioning profile creation step. Log lines mention profile lookup or creation errors.

Cause:

Bundle ID is not registered in Apple account
API key doesn’t have permission to create profiles
Team ID mismatch

Solution:

Verify API key permissions:
- The API key must have Developer or App Manager role in Apple Developer
- Go to Users and Access > Keys in App Store Connect and check the key’s access level
- If it has insufficient permissions, revoke and create a new key with proper access
Verify bundle ID is registered:
- In App Store Connect, go to Certificates, Identifiers & Profiles > Identifiers
- Verify your bundle ID is listed (or create a new one if missing)
Verify Team ID matches:
- In RunnerHub Workspace Settings > Apple Signing, check the Team ID field
- In App Store Connect, go to Account > Membership and verify the Team ID
- Update RunnerHub if they don’t match
Re-enter the API key in RunnerHub:
- Go to Workspace Settings > Apple Signing
- Click Remove API Key and Add API Key again with the correct credentials

Signing Type Mismatch

Symptom: Your build fails during xcodebuild. Log lines mention profile or signing type mismatches.

Cause:

Signing type in App Settings doesn’t match your deployment target
Built a development build but trying to submit to App Store
Profile doesn’t match the selected signing type

Solution:

Determine which signing type you need:
- development: Testing on devices, TestFlight testing
- adhoc: Ad-hoc distribution to specific devices
- appstore: App Store submission (use this for TestFlight)
- developer-id: macOS distribution outside the App Store
In RunnerHub App Settings > Code Signing, select the correct signing type
Save and run the build again

P12 Certificate Upload Issues

Symptom: Your upload fails with a validation error. Error text mentions P12 parsing or password issues.

Cause:

P12 password is incorrect
P12 file is corrupted or invalid
(Workspace mode only) Certificate doesn’t exist in your Apple account

Solution:

Verify the P12 password is correct:
- Try uploading the P12 again and double-check the password you enter
- Passwords are case-sensitive
If you don’t remember the password:
- Export a new P12 from Keychain Access with a new password
- Upload the new P12 to RunnerHub
Verify the P12 file is valid:
- Open the P12 file in Keychain Access on your Mac to confirm it’s readable
- If it doesn’t open, the file may be corrupted
- Export a fresh P12 from your certificate
(Workspace mode only) Verify certificate exists in Apple account:
- If using workspace-level automatic mode, the P12 certificate must be registered in your Apple Developer account
- Go to App Store Connect > Certificates, Identifiers & Profiles > Certificates
- Verify the certificate is listed and not revoked

Team ID Mismatch

Symptom: Your build fails during signing. Log lines mention team ID validation errors.

Cause:

API key’s team ID doesn’t match the team ID in your signing configuration
You’re using an API key from a different Apple team
Typo in the Team ID field

Solution:

Verify your Team ID in Apple Developer:
- Go to App Store Connect
- Click Account in the top right
- Click Membership
- Copy your Team ID
In RunnerHub Workspace Settings > Apple Signing:
- Verify the Team ID field matches your Apple Team ID exactly
- Update if necessary and save
If using an API key from a different team:
- Revoke the old API key in Apple Developer
- Create a new API key for your correct team
- Update RunnerHub with the new key credentials

Plan/Tier Restrictions

Symptom: Your build fails with a 403 error. Error text mentions plan or subscription requirements.

Cause:

You’re on the Free plan trying to use automatic code signing
Your workspace doesn’t have access to the required feature

Solution:

Automatic code signing is available on PAYG, Pro, and Business plans. If you’re on the Free plan:

Go to Billing
Click Upgrade Plan
Select your desired plan (PAYG or higher)
Complete payment

Free plan users can still use manual code signing by uploading P12 certificates and provisioning profiles directly on each app.

Debugging Steps

If you encounter a code signing error:

Check the job logs
- Go to the failed job in the dashboard
- Scroll through the logs for the failure message
- Note which step failed (certificate import, profile creation, xcodebuild, etc.)
Verify workspace configuration
- Go to Workspace Settings > Apple Signing
- Ensure API key is fully configured (all fields filled)
- Click Save to refresh
Verify app configuration
- Go to App Settings > Code Signing
- Ensure bundle ID matches your Xcode project exactly
- Ensure signing type is appropriate for your use case
- Ensure Apple Credential is selected (for automatic mode)
- Click Save to refresh
Check Apple Developer account
- Verify bundle ID is registered
- Verify API key is not revoked
- Verify certificate is not expired (if manually uploaded)
- Verify API key has Developer or App Manager access
Re-run the job
- After making changes, run the job again
- Some issues require a fresh build to resolve

Getting Help

If the issue persists:

Check your job logs in the RunnerHub dashboard
Verify all configuration steps in API Key Setup and Per-App Signing
Confirm your plan includes code signing (automatic requires PAYG+; manual is Free+)
Verify your Apple credentials are current and valid
Contact RunnerHub support with your job logs