Per-App Signing Configuration

Overview

Each app in RunnerHub requires a signing configuration:

Bundle Identifier: Your app’s unique ID (e.g., com.example.myapp)
Signing Type: How your app should be signed (development, adhoc, appstore, or developer-id for macOS outside-App-Store distribution)

These settings tell RunnerHub which certificate and provisioning profile to use for your build.

Configuring App Signing

In the RunnerHub dashboard, go to App Settings
Click the Apple Signing tab (or Signing Configuration)
Enter:
- Bundle Identifier: Your app’s bundle ID
- Signing Type: Select development, adhoc, appstore, or developer-id (macOS only)
Click Save

Signing Types

Development

Use for development builds and testing on simulators or TestFlight.

Certificate: Apple Development
Devices: Limited to development team members
Provisioning: Supports up to 100 devices per team

Ad-Hoc

Use for ad-hoc distribution to a limited set of devices.

Certificate: Apple Distribution
Devices: You specify which devices can run the app
Provisioning: Includes specific UDIDs

App Store

Use for App Store submission and production distribution.

Certificate: Apple Distribution
Devices: No device restrictions; runs on all devices that download from the App Store
Provisioning: Standard app store provisioning profile

Developer ID

Use for distributing macOS apps outside the App Store.

Certificate: Developer ID Application
Platform: macOS only (not available for iOS/iPadOS)
Distribution: Direct distribution to end users or third-party stores
Provisioning: No provisioning profile required (Developer ID signing is not provisioning-profile-based)

How Signing is Applied During Build

When your job runs, RunnerHub:

1. Fetches Your Credentials

RunnerHub securely retrieves your signing credentials for the job:

Your API key credentials
Certificate private key
Bundle ID and signing type

2. Sets Up the Ephemeral Keychain

Creates a temporary keychain for the job
Imports your certificate
Installs the provisioning profile

3. Injects Environment Variables

Your pipeline steps can access:

APPLE_TEAM_ID=ABC123D45E
DEVELOPMENT_TEAM=ABC123D45E
PROVISIONING_PROFILE=<profile-uuid>
PROVISIONING_PROFILE_SPECIFIER=<profile-name>
CODE_SIGN_IDENTITY=Apple Distribution
CODE_SIGN_STYLE=Manual
OTHER_CODE_SIGN_FLAGS=--keychain <ephemeral-keychain-path>
APP_STORE_CONNECT_API_KEY_ID=<key-id>
APP_STORE_CONNECT_API_ISSUER_ID=<issuer-id>
RH_PROVISIONING_PROFILE_NAME=<profile-name>
RH_EXPORT_OPTIONS_PLIST=/path/to/ExportOptions.plist

These variables are available to:

Xcode and xcodebuild
Fastlane and other build tools
Your custom scripts

4. Auto-Generates ExportOptions.plist

RunnerHub automatically creates an ExportOptions.plist file with the correct configuration for exporting your app. The file is created in the workspace root and exposed via the RH_EXPORT_OPTIONS_PLIST environment variable.

The generated plist includes:

method: Your signing type (app-store-connect, ad-hoc, or development)
teamID: Your Apple Team ID
signingStyle: manual (RunnerHub manages the signing)
provisioningProfiles: Bundle ID to profile UUID mapping

You can use this in your export step:

xcodebuild -exportArchive \
  -archivePath $PWD/build/MyApp.xcarchive \
  -exportPath $PWD/build \
  -exportOptionsPlist $RH_EXPORT_OPTIONS_PLIST

When is the plist generated?

Only if auto-sign is enabled and both profile and bundle ID are available
Only if no existing ExportOptions.plist exists in your repository root
Your existing plist always takes precedence

This allows you to either:

Use the auto-generated plist for convenience (recommended for simple builds)
Maintain your own custom plist for advanced configurations

5. Patches Xcode Project

RunnerHub automatically modifies your project.pbxproj to enable manual signing:

CODE_SIGN_STYLE=Manual
CODE_SIGN_IDENTITY=Apple Distribution
DEVELOPMENT_TEAM=ABC123D45E
PROVISIONING_PROFILE_SPECIFIER=<profile-name>
OTHER_CODE_SIGN_FLAGS=--keychain <ephemeral-keychain-path>

This ensures your build uses the correct credentials.

6. Your Build Uses Signing

Your build commands work unchanged:

xcodebuild archive \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -configuration Release

Xcode automatically uses the provisioning profile and signing identity from the environment and project settings.

Using with Fastlane

If you use Fastlane, signing works automatically. Fastlane respects the default keychain and environment variables:

desc "Build for App Store"
lane :build_appstore do
  build_app(
    workspace: "MyApp.xcworkspace",
    scheme: "MyApp",
    configuration: "Release",
    export_method: "app-store",
    # Fastlane uses PROVISIONING_PROFILE_SPECIFIER and CODE_SIGN_IDENTITY
    # from environment variables automatically
  )
end

You don’t need to configure Fastlane Match or match storage—RunnerHub handles it all.

Using with Flutter

For Flutter apps, RunnerHub patches the xcconfig files instead of project.pbxproj:

Modified Files:

ios/Flutter/Debug.xcconfig
ios/Flutter/Release.xcconfig
ios/Flutter/Profile.xcconfig

RunnerHub adds:

CODE_SIGN_STYLE = Manual
CODE_SIGN_IDENTITY = Apple Distribution
DEVELOPMENT_TEAM = ABC123D45E
PROVISIONING_PROFILE_SPECIFIER = <profile-name>
OTHER_CODE_SIGN_FLAGS = --keychain <ephemeral-keychain-path>

Your Flutter build then uses these settings automatically.

Bundle ID Registration

Your bundle ID must be registered in your Apple Developer account:

Go to App Store Connect
Click Certificates, Identifiers & Profiles
Click Identifiers
Verify your bundle ID is listed (or create a new one)

If your bundle ID is not registered, provisioning profile creation will fail, and your build will not be signed.

Multiple Apps, One Workspace

If you have multiple apps in one workspace, each can have its own signing configuration:

App	Bundle ID	Signing Type
MyApp	com.example.myapp	appstore
MyApp Dev	com.example.myapp.dev	development
MyApp Staging	com.example.myapp.staging	adhoc

Each app uses the same API key and certificates from the workspace, but with different bundle IDs and profiles.

Changing Bundle ID or Signing Type

To change your app’s signing configuration:

Go to App Settings > Apple Signing
Update Bundle Identifier or Signing Type
Click Save

The next build will use the new configuration. No additional setup is needed.

Troubleshooting

“Bundle ID not registered”

Verify the bundle ID in App Settings matches your Xcode project
Check that the bundle ID is registered in Apple Developer

“Signing type mismatch”

Ensure your signing type (development/adhoc/appstore) matches your deployment target
For TestFlight, use appstore; for ad-hoc distribution, use adhoc

“Certificate not found”

Verify API key is configured at workspace level
Check that the workspace has valid Apple credentials

See Code Signing Troubleshooting for more help.