daily-notification-plugin/docs/IOS_CODE_SIGNING.md

iOS Code Signing Guide

Author: Matthew Raymer
Date: 2025-11-12
Status: Active

Overview

iOS apps require code signing to run on devices or simulators. This guide explains how to handle signing for different scenarios.

Signing Scenarios

1. Simulator Builds (Development)

For simulator builds, signing can be disabled:

xcodebuild -workspace App.xcworkspace \
    -scheme App \
    -sdk iphonesimulator \
    -destination 'platform=iOS Simulator,name=iPhone 15' \
    CODE_SIGN_IDENTITY="" \
    CODE_SIGNING_REQUIRED=NO \
    CODE_SIGNING_ALLOWED=NO \
    clean build

Why this works:

• Simulator doesn't require valid code signatures
• Faster builds (no signing overhead)
• No need for Apple Developer account

2. Device Builds (Development)

For physical devices, you need proper signing:

Option A: Automatic Signing (Recommended)

1. Open Xcode project:

   open App.xcworkspace
   

2. Configure in Xcode:

   • Select project in navigator
   • Select target "App"
   • Go to "Signing & Capabilities" tab
   • Check "Automatically manage signing"
   • Select your Team (Apple Developer account)
   • Xcode will create provisioning profile automatically

3. Build from command line:

   xcodebuild -workspace App.xcworkspace \
       -scheme App \
       -sdk iphoneos \
       -configuration Debug \
       -destination 'generic/platform=iOS' \
       DEVELOPMENT_TEAM="YOUR_TEAM_ID" \
       CODE_SIGN_STYLE=Automatic \
       clean build
   

Option B: Manual Signing

1. Get your Team ID:

   # List available teams
   security find-identity -v -p codesigning
   

2. Create provisioning profile (via Apple Developer Portal or Xcode)

3. Build with explicit signing:

   xcodebuild -workspace App.xcworkspace \
       -scheme App \
       -sdk iphoneos \
       -configuration Debug \
       -destination 'generic/platform=iOS' \
       DEVELOPMENT_TEAM="YOUR_TEAM_ID" \
       CODE_SIGN_STYLE=Manual \
       PROVISIONING_PROFILE_SPECIFIER="Your Profile Name" \
       CODE_SIGN_IDENTITY="iPhone Developer" \
       clean build
   

3. Command-Line Build Scripts

Update build scripts to handle both scenarios:

#!/bin/bash

# Detect if building for simulator or device
SDK="${1:-iphonesimulator}"
DESTINATION="${2:-'platform=iOS Simulator,name=iPhone 15'}"

if [ "$SDK" = "iphonesimulator" ]; then
    # Simulator: Disable signing
    xcodebuild -workspace App.xcworkspace \
        -scheme App \
        -sdk "$SDK" \
        -destination "$DESTINATION" \
        CODE_SIGN_IDENTITY="" \
        CODE_SIGNING_REQUIRED=NO \
        CODE_SIGNING_ALLOWED=NO \
        clean build
else
    # Device: Use automatic signing
    xcodebuild -workspace App.xcworkspace \
        -scheme App \
        -sdk "$SDK" \
        -configuration Debug \
        -destination 'generic/platform=iOS' \
        CODE_SIGN_STYLE=Automatic \
        DEVELOPMENT_TEAM="${DEVELOPMENT_TEAM:-}" \
        clean build
fi

Common Signing Issues

Issue 1: "No signing certificate found"

Solution:

# Check available certificates
security find-identity -v -p codesigning

# If none found, create one in Xcode:
# Xcode > Preferences > Accounts > Select Team > Download Manual Profiles

Issue 2: "Provisioning profile not found"

Solution:

# List provisioning profiles
ls ~/Library/MobileDevice/Provisioning\ Profiles/

# Or use automatic signing (recommended)
# Xcode will create profiles automatically

Issue 3: "Code signing is required for product type"

Solution:

• For simulator: Add CODE_SIGNING_REQUIRED=NO
• For device: Configure signing in Xcode or provide DEVELOPMENT_TEAM

Issue 4: "Bundle identifier conflicts"

Solution:

• Change bundle identifier in Info.plist:

  <key>CFBundleIdentifier</key>
  <string>com.yourcompany.yourapp</string>
  

• Or use unique identifier for test apps

Project Configuration

Automatic Signing (Recommended)

In Xcode project settings (project.pbxproj or Xcode UI):

CODE_SIGN_STYLE = Automatic;
DEVELOPMENT_TEAM = YOUR_TEAM_ID;

Manual Signing

CODE_SIGN_STYLE = Manual;
CODE_SIGN_IDENTITY = "iPhone Developer";
PROVISIONING_PROFILE_SPECIFIER = "Your Profile Name";

Environment Variables

Set these for command-line builds:

# For device builds
export DEVELOPMENT_TEAM="YOUR_TEAM_ID"
export CODE_SIGN_STYLE="Automatic"

# For simulator builds (optional)
export CODE_SIGNING_REQUIRED="NO"
export CODE_SIGNING_ALLOWED="NO"

Quick Reference

Simulator Build (No Signing)

xcodebuild ... \
    CODE_SIGN_IDENTITY="" \
    CODE_SIGNING_REQUIRED=NO \
    CODE_SIGNING_ALLOWED=NO

Device Build (Automatic Signing)

xcodebuild ... \
    CODE_SIGN_STYLE=Automatic \
    DEVELOPMENT_TEAM="YOUR_TEAM_ID"

Device Build (Manual Signing)

xcodebuild ... \
    CODE_SIGN_STYLE=Manual \
    CODE_SIGN_IDENTITY="iPhone Developer" \
    PROVISIONING_PROFILE_SPECIFIER="Profile Name"

Testing Signing Configuration

Test if signing works:

# Check code signature
codesign -dv --verbose=4 /path/to/App.app

# Verify signature
codesign --verify --verbose /path/to/App.app

# Check entitlements
codesign -d --entitlements - /path/to/App.app

Troubleshooting

Check Current Signing Status

# In Xcode project directory
xcodebuild -showBuildSettings -workspace App.xcworkspace -scheme App | grep CODE_SIGN

Clean Derived Data

# Sometimes signing issues are cached
rm -rf ~/Library/Developer/Xcode/DerivedData

Reset Signing in Xcode

1. Open project in Xcode
2. Select target
3. Signing & Capabilities tab
4. Uncheck "Automatically manage signing"
5. Re-check "Automatically manage signing"
6. Select team again

Best Practices

1. Use Automatic Signing for development (easiest)
2. Disable signing for simulator builds (faster)
3. Use unique bundle IDs for test apps
4. Keep certificates updated in Keychain
5. Use environment variables for team IDs in CI/CD

References

• Apple Code Signing Guide
• Xcode Signing Documentation
• Capacitor iOS Setup