Code Signing

Overview

Code signing proves that your app and its extensions come from a trusted source (you) and haven’t been tampered with. Every target in your app—main app, widgets, App Clips, extensions—requires its own code signature.

How Code Signing Works

Each target needs:

Certificate - Identifies you as the developer (shared across all targets)
Provisioning Profile - Links your app ID, certificate, and device IDs
Entitlements - Permissions the target needs

┌─────────────────┐
│   Main App      │ → Certificate + Profile + Entitlements
├─────────────────┤
│   Widget        │ → Certificate + Profile + Entitlements
├─────────────────┤
│   App Clip      │ → Certificate + Profile + Entitlements
├─────────────────┤
│   Share Ext.    │ → Certificate + Profile + Entitlements
└─────────────────┘

Automatic Code Signing (Xcode)

First-Time Setup

Open Xcode:
```
xed ios
```
Select each target in the project navigator
Go to Signing & Capabilities tab
Check “Automatically manage signing”
Select your Team from the dropdown

Xcode will automatically create provisioning profiles and register App IDs for all targets.

Development Team ID

Set your Apple Team ID in app.json:

{
  "expo": {
    "ios": {
      "appleTeamId": "TEAM123456",
      "bundleIdentifier": "com.example.app"
    }
  }
}

Find your Team ID:

In Xcode: Signing & Capabilities → Team dropdown shows ID in parentheses
Apple Developer Portal: Membership page → Team ID

If appleTeamId is missing, builds may fail with code signing errors. The plugin warns you but continues:

// From config-plugin.ts:32-36
if (!appleTeamId) {
  warnOnce(
    chalk`{yellow [bacons/apple-targets]} Expo config is missing required {cyan ios.appleTeamId} property. iOS builds may fail until this is corrected.`,
  );
}

EAS Build (Automatic)

EAS Build handles code signing automatically for all targets.

How It Works

Syncs entitlements - The plugin exports entitlements via withEASTargets:

// From with-widget.ts:356-360
config = withEASTargets(config, {
  targetName: productName,
  bundleIdentifier: bundleId,
  entitlements: entitlementsJson,
});

Creates App IDs - EAS registers all bundle identifiers
Generates profiles - Creates provisioning profiles for each target
Downloads certificates - Uses your distribution certificate
Signs all targets - Applies signatures during build

EAS Setup

# Install EAS CLI
npm install -g eas-cli

# Login
eas login

# Configure project
eas build:configure

Your eas.json:

{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "ios": {
        "simulator": true
      }
    },
    "preview": {
      "distribution": "internal",
      "ios": {
        "simulator": false
      }
    },
    "production": {
      "ios": {
        "buildConfiguration": "Release"
      }
    }
  }
}

Running a Build

# Development build (for testing)
eas build --platform ios --profile development

# Production build (for App Store)
eas build --platform ios --profile production

EAS automatically:

Detects all targets from your config
Creates provisioning profiles
Signs each target
Embeds targets in the app bundle

The first build takes longer as EAS registers App IDs and creates profiles. Subsequent builds reuse credentials.

Manual Code Signing

For custom CI/CD or advanced setups.

1. Register App IDs

For each target, register an App ID in Apple Developer Portal:

Main App:  com.example.app
Widget:    com.example.app.widget
App Clip:  com.example.app.clip
Share:     com.example.app.share

2. Configure Capabilities

For each App ID, enable required capabilities:

App Groups - For data sharing
Associated Domains - For App Clips and universal links
Push Notifications - For remote notifications
Sign in with Apple - For authentication
Etc.

3. Create Provisioning Profiles

For each target:

Go to Provisioning Profiles
Click + to create new profile
Select profile type:
- Development - For local testing
- Ad Hoc - For TestFlight internal testing
- App Store - For App Store distribution
Select the App ID
Select your certificate
Select devices (Development/Ad Hoc only)
Download and install

4. Install Profiles

Double-click .mobileprovision files or:

cp *.mobileprovision ~/Library/MobileDevice/Provisioning\ Profiles/

5. Configure Xcode

For each target:

Select target in Xcode
Signing & Capabilities tab
Uncheck “Automatically manage signing”
Select provisioning profile from dropdown

Build Settings

The plugin automatically configures code signing build settings:

// From with-xcode-changes.ts:113-127
function applyDevelopmentTeamIdToTargets() {
  const devTeamId =
    props.teamId ||
    project.rootObject.props.targets
      .map((target) => target.getDefaultBuildSetting("DEVELOPMENT_TEAM"))
      .find(Boolean);

  project.rootObject.props.targets.forEach((target) => {
    if (devTeamId) {
      target.setBuildSetting("DEVELOPMENT_TEAM", devTeamId);
    }
  });
}

Key build settings:

DEVELOPMENT_TEAM - Your Team ID
CODE_SIGN_STYLE - Automatic or Manual
CODE_SIGN_ENTITLEMENTS - Path to entitlements file
PRODUCT_BUNDLE_IDENTIFIER - Bundle ID
PROVISIONING_PROFILE_SPECIFIER - Profile name (manual signing)

App Clip Signing

App Clips have additional requirements:

1. Parent Application Identifier

Automatically set by the plugin:

<key>com.apple.developer.parent-application-identifiers</key>
<array>
    <string>$(AppIdentifierPrefix)com.example.app</string>
</array>

2. Associated Domains

Required for launching from websites:

// targets/clip/expo-target.config.js
module.exports = {
  type: "clip",
  entitlements: {
    "com.apple.developer.associated-domains": [
      "appclips:example.com",
    ],
  },
};

3. AASA File

Publish an Apple App Site Association file at:

https://example.com/.well-known/apple-app-site-association

{
  "appclips": {
    "apps": ["TEAM123456.com.example.app.clip"]
  }
}

App Clip code signing is not fully automated. You may need to manually configure profiles in Xcode on first build.

Troubleshooting

Common Issues

Code signing error: No profile found

Solution:

Open Xcode Signing tab
Enable “Automatically manage signing”
Select your Team
Xcode will create profiles
Re-run your build

Entitlements don't match provisioning profile

Solution:

Check entitlements in expo-target.config.js
Verify capabilities are enabled for App ID in Developer Portal
Regenerate provisioning profile
Download and install new profile

App Groups not in provisioning profile

Solution:

Go to App ID in Developer Portal
Enable “App Groups” capability
Configure App Group ID (matches entitlements)
Regenerate provisioning profile
Download and install

Multiple targets with same bundle ID

Solution:

Each target needs a unique bundle ID
Use dot notation: .widget, .clip, .share
Or specify absolute: com.example.widget
Re-run npx expo prebuild --clean

EAS Build fails with provisioning error

Solution:

Check appleTeamId in app.json
Verify bundle IDs are unique
Check entitlements are valid
Try deleting credentials: eas credentials
Run build again (will recreate credentials)

Debug Commands

# List provisioning profiles
security find-identity -v -p codesigning

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

# View profile details
security cms -D -i profile.mobileprovision

# Check code signature
codesign -dv --verbose=4 YourApp.app

# Verify embedded profiles
codesign -d --entitlements - YourApp.app

CI/CD Integration

GitHub Actions

name: Build

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      
      - name: Install dependencies
        run: npm install
      
      - name: EAS Build
        run: |
          npm install -g eas-cli
          eas build --platform ios --non-interactive --no-wait
        env:
          EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}

Fastlane

lane :build do
  # Run prebuild
  sh("npx expo prebuild -p ios --clean")
  
  # Match provisioning
  match(
    type: "appstore",
    app_identifier: [
      "com.example.app",
      "com.example.app.widget",
      "com.example.app.clip",
    ]
  )
  
  # Build
  gym(
    workspace: "ios/YourApp.xcworkspace",
    scheme: "YourApp",
    export_method: "app-store"
  )
end

Best Practices

Use EAS Build - Simplest and most reliable
Set appleTeamId - Required for consistent builds
Enable automatic signing - For local development
Use unique bundle IDs - Never reuse across targets
Enable capabilities - Match entitlements in Developer Portal
Test profiles - Build locally before CI/CD
Document setup - Team members need same Team ID access

Get Started

Core Concepts

Guides

Advanced

Overview

How Code Signing Works

Automatic Code Signing (Xcode)

First-Time Setup

Development Team ID

EAS Build (Automatic)

How It Works

EAS Setup

Running a Build

Manual Code Signing

1. Register App IDs

2. Configure Capabilities

3. Create Provisioning Profiles

4. Install Profiles

5. Configure Xcode

Build Settings

App Clip Signing

1. Parent Application Identifier

2. Associated Domains

3. AASA File

Troubleshooting

Common Issues

Debug Commands

CI/CD Integration

GitHub Actions

Fastlane

Best Practices

Next Steps

Development workflow

EAS Build

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Overview

​How Code Signing Works

​Automatic Code Signing (Xcode)

​First-Time Setup

​Development Team ID

​EAS Build (Automatic)

​How It Works

​EAS Setup

​Running a Build

​Manual Code Signing

​1. Register App IDs

​2. Configure Capabilities

​3. Create Provisioning Profiles

​4. Install Profiles

​5. Configure Xcode

​Build Settings

​App Clip Signing

​1. Parent Application Identifier

​2. Associated Domains

​3. AASA File

​Troubleshooting

​Common Issues

​Debug Commands

​CI/CD Integration

​GitHub Actions

​Fastlane

​Best Practices

​Next Steps

Development workflow

EAS Build

Build docs developers (and LLMs) love

Overview

How Code Signing Works

Automatic Code Signing (Xcode)

First-Time Setup

Development Team ID

EAS Build (Automatic)

How It Works

EAS Setup

Running a Build

Manual Code Signing

1. Register App IDs

2. Configure Capabilities

3. Create Provisioning Profiles

4. Install Profiles

5. Configure Xcode

Build Settings

App Clip Signing

1. Parent Application Identifier

2. Associated Domains

3. AASA File

Troubleshooting

Common Issues

Debug Commands

CI/CD Integration

GitHub Actions

Fastlane

Best Practices

Next Steps