Certificates & Provisioning Profiles

Overview

RunnerHub supports two modes for certificate and provisioning profile management:

1. Automatic — RunnerHub generates and manages certificates via the Apple App Store Connect API
2. Manual — You upload your own P12 certificate and .mobileprovision files

Both modes are fully supported. Choose the approach that fits your workflow best.

Automatic Certificate Management

When you add an API key to RunnerHub as a credential, the system:

1. Generates a Certificate Signing Request (CSR) — Creates a unique CSR on RunnerHub’s backend
2. Creates or Reuses a Certificate — Requests an Apple Distribution certificate from Apple
   • If a valid certificate already exists under your team, RunnerHub reuses it
   • If the certificate is expired or doesn’t exist, RunnerHub creates a new one
3. Stores the Certificate — Encrypts and stores the certificate private key in the RunnerHub database

Each credential maintains its own certificate(s). When you configure an app, you select which credential to use, and that credential’s certificates are used for signing.

Provisioning Profile Management

RunnerHub automatically fetches provisioning profiles during job execution:

• Profile Creation: If a profile doesn’t exist for your bundle ID and signing type, RunnerHub creates one through the Apple API
• Profile Caching: Created profiles are cached and reused across builds
• Profile Installation: Profiles are installed into the ephemeral keychain only during job execution
• Cleanup: Profiles are deleted from the ephemeral keychain after the job completes

The provisioning profile is specific to:

• Your bundle ID (e.g., com.example.myapp)
• Your signing type (development, adhoc, or appstore)
• Your team ID

Signing Types

RunnerHub supports three signing types, configurable per app:

Signing Type	Use Case	Certificate Type
development	Development and testing	Apple Development
adhoc	Ad-hoc distribution	Apple Distribution
appstore	App Store submission	Apple Distribution (default)

Configure your signing type in App Settings — see Per-App Signing.

Certificate Expiry

RunnerHub tracks certificate expiration dates:

• Before Each Build: RunnerHub validates that your certificate hasn’t expired
• Auto-Renewal: If a certificate is within 30 days of expiration, RunnerHub will create a new one
• Expired Certificate: If a certificate has expired, RunnerHub creates a replacement automatically

You don’t need to manually renew or rotate certificates.

Manual Mode - Using Your Own Certificates

In manual mode, you upload and manage your own P12 certificate(s) and provisioning profiles. You can upload multiple certificates per app — for example, a development certificate and a distribution certificate — and all will be available during your build:

Step 1: Export Your Certificate as P12

From your local machine:

1. Open Keychain Access
2. Find your Apple Distribution or Development certificate
3. Right-click and select Export
4. Choose Personal Information Exchange (.p12) format
5. Set a password (required for security)
6. Save the file

Step 2: Upload P12 Certificate(s) to RunnerHub

In the RunnerHub dashboard:

1. Go to App Settings → Code Signing
2. Select Manual as the signing mode
3. Click Upload Certificate
4. Select your .p12 file and enter the password
5. Click Upload
6. Repeat steps 3-5 for each additional certificate (e.g., development + distribution)

RunnerHub will:

• Decrypt and parse your P12 file
• Validate that the certificate exists in your Apple Developer account
• Verify the certificate matches your Team ID
• Store the certificate private key encrypted in the database

All uploaded certificates are installed into your build keychain, and xcodebuild automatically selects the correct certificate based on your provisioning profile.

Step 3: Upload Provisioning Profiles

Add provisioning profiles for your app:

1. Click Add Provisioning Profile
2. Select your .mobileprovision file
3. Click Upload
4. Repeat for each profile (development, ad-hoc, App Store, etc.)

RunnerHub validates each profile:

• ✓ Profile format is valid
• ✓ Profile is not expired
• ✓ Profile matches your Bundle ID
• ✓ Profile exists in your Apple Developer account

P12 Upload Validation

RunnerHub validates your P12 file:

• ✓ P12 format is valid and readable
• ✓ Certificate is not expired
• ✓ Certificate exists in your Apple Developer account
• ✓ Certificate matches your team ID

If validation fails, you’ll see an error message explaining what went wrong.

Managing Manually Uploaded Certificates and Profiles

When using manual mode:

• Multiple Certificates: Upload multiple certificates (development, distribution, enterprise, etc.) to your app
• Automatic Selection: All uploaded certificates are installed into the build keychain; xcodebuild automatically selects the correct one based on your provisioning profile
• Profile Selection: RunnerHub automatically selects the correct profile based on your app configuration
• Expiry Tracking: Certificate and profile expiration dates are tracked and displayed in the dashboard
• Certificate Removal: You can remove individual certificates independently; other certificates and profiles are preserved
• Profile Removal: You can remove individual profiles or all profiles
• Mode Switch: Switching from manual to automatic mode will remove all uploaded certificates and profiles

Manual Mode Best Practices

• Strong Password: Use a strong password when exporting your P12 files
• Multiple Certificates: Upload both development and distribution certificates if you use them
• Profile Types: Upload all three profile types (Development, Ad-hoc, App Store) if you use them
• Bundle ID Verification: Ensure your provisioning profiles match your app’s Bundle ID exactly
• Keep Profiles Updated: Renew and re-upload profiles before they expire
• Certificate Management: Each uploaded certificate is independent; you can remove one without affecting others
• Secure Storage: Delete local P12 copies after uploading to RunnerHub

Deleting and Regenerating Certificates

Automatic Mode

To reset certificates and profiles for a credential:

1. In Workspace Settings > Apple Signing
2. Select the credential you want to modify
3. Click Remove Certificate
4. RunnerHub will:
   • Delete the stored certificate for that credential
   • Revert to auto-generating certificates on the next build that uses this credential

Deleting a credential does not:

• Revoke the certificate on Apple’s servers
• Affect in-progress builds
• Affect provisioning profiles already installed on devices
• Affect other credentials or apps using other credentials

To delete an entire credential (and all its apps must be updated to use a different credential or have none):

1. In Workspace Settings > Apple Signing
2. Click the Delete button next to the credential name
3. Any apps using this credential will have their apple_signing_credential_id set to null

To revoke a certificate in Apple Developer:

1. Go to App Store Connect > Certificates, Identifiers & Profiles
2. Click Certificates
3. Find the certificate and click the X to revoke it

Manual Mode

To remove your uploaded certificates and profiles:

1. Go to App Settings > Code Signing
2. To remove a specific certificate: Click the X next to the certificate name; other certificates and profiles are preserved
3. To remove all certificates and profiles: Click Remove Certificate → Confirm (this clears all manual signing configuration)

You can then either:

• Upload new certificates
• Switch to Automatic mode (which will use workspace API key)

Certificate Chain & WWDR

RunnerHub automatically handles the Apple Worldwide Developer Relations (WWDR) intermediate certificate:

• Automatic Import: The WWDR certificate is imported to your build system automatically
• Trust Chain: Ensures your certificates are properly trusted by macOS
• No Manual Setup: You don’t need to install anything manually

Troubleshooting

“Certificate not found in your Apple account”

• The P12 certificate you uploaded doesn’t match your Apple account
• Re-export the correct certificate from your Apple Developer account

“Certificate expired”

• If you uploaded a P12, renew or upload a new one
• If using auto-generated certificates, RunnerHub will create a replacement automatically

“No provisioning profile found”

• Verify bundle ID is registered in your Apple Developer account
• Check that the bundle ID is correctly configured in App Settings

See Code Signing Troubleshooting for more help.