name: ios-cicd-distributor
description: iOS app code signing, provisioning, and distribution expert. Guides developers through certificate and provisioning profile management, TestFlight distribution, App Store submission, Ad Hoc builds, and CI/CD automation with GitHub Actions, Xcode Cloud, and Fastlane. Use when preparing an iOS app for release, debugging signing or provisioning errors, setting up TestFlight pipelines, or troubleshooting distribution failures.

iOS Signing, Provisioning & Distribution

Overview

Code signing and distribution are the most error-prone part of shipping iOS apps. Unlike macOS (which uses notarization for direct distribution), iOS relies entirely on provisioning profiles that bind certificates, App IDs, entitlements, and device lists into a single trust package. A mismatch in any component produces cryptic errors that waste hours.

This skill provides battle-tested workflows, scripts, and templates that eliminate guesswork.

Use this skill when preparing an iOS app for release, debugging signing or provisioning errors, setting up CI/CD pipelines, choosing distribution channels, or managing TestFlight and App Store submissions.

Core Workflow

Every iOS app distribution follows this pipeline:

Build --> Archive --> Export IPA --> Upload --> Review --> Distribute

The export step is where signing happens. The ExportOptions plist controls which certificate, profile, and method are used.

Decision Trees

How Should I Distribute?

Is this for internal testing by your team (up to 100 people)?
+-- YES --> TestFlight Internal
|          No review, available immediately after processing
|          Reference: references/distribution-channels.md
+-- NO |

Is this for external beta testers (up to 10,000)?
+-- YES --> TestFlight External
|          Requires beta app review (usually 24-48 hours first time)
|          Reference: references/distribution-channels.md
+-- NO |

Is this for a limited set of known devices (QA, client demo)?
+-- YES --> Ad Hoc Distribution
|          Max 100 devices per device family per year, registered UDIDs
|          Reference: references/distribution-channels.md
+-- NO |

Is this for all employees in your organization?
+-- YES --> Enterprise / In-House
|          Requires Apple Enterprise Program ($299/year), MDM recommended
|          Reference: references/distribution-channels.md
+-- NO --> App Store
           Full review, unlimited public distribution
           Reference: references/distribution-channels.md

Signing Error Diagnosis

Error contains "No profiles matching"?
+-- YES --> Profile not installed or bundle ID mismatch
|          Reference: references/troubleshooting.md

Error contains "No signing certificate found"?
+-- YES --> Certificate missing from keychain or expired
|          Reference: references/troubleshooting.md

Error contains "doesn't include the entitlement"?
+-- YES --> Capability not enabled in App ID on Developer Portal
|          Reference: references/troubleshooting.md

Error contains "Signing requires a development team"?
+-- YES --> Missing DEVELOPMENT_TEAM build setting
|          Reference: references/troubleshooting.md

Error contains "ITMS-90168" or "invalid binary"?
+-- YES --> Architecture or signing format issue
|          Reference: references/troubleshooting.md

What Certificate Do I Need?

End-to-End Workflows

Development to TestFlight

# 0. Verify signing identity exists
security find-identity -v -p codesigning

# 1. Archive
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp \
  -configuration Release \
  -archivePath build/MyApp.xcarchive \
  -destination 'generic/platform=iOS' \
  archive

# 2. Export IPA for App Store / TestFlight
xcodebuild -exportArchive \
  -archivePath build/MyApp.xcarchive \
  -exportPath build/export \
  -exportOptionsPlist ExportOptions-AppStore.plist

# 3. Upload to TestFlight
xcrun altool --upload-app \
  -f build/export/MyApp.ipa \
  -t ios \
  --apiKey "$API_KEY_ID" \
  --apiIssuer "$API_ISSUER"

# 4. Wait for TestFlight processing (5-30 minutes typically)
# Then distribute to testers in App Store Connect

Template: assets/templates/ExportOptions-AppStore.plist
Script: scripts/build-and-archive.sh + scripts/upload-testflight.sh

Development to App Store

The IPA for App Store is identical to the TestFlight IPA. Upload it the same way, then submit the build for App Store review in App Store Connect.

# Same archive + export as TestFlight
# Then in App Store Connect: select the build, fill metadata, submit for review

Ad Hoc Distribution

# 1. Register device UDIDs in Developer Portal
# 2. Generate Ad Hoc provisioning profile including those UDIDs
# 3. Archive
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp \
  -configuration Release \
  -archivePath build/MyApp.xcarchive \
  -destination 'generic/platform=iOS' \
  archive

# 4. Export with Ad Hoc method
xcodebuild -exportArchive \
  -archivePath build/MyApp.xcarchive \
  -exportPath build/export \
  -exportOptionsPlist ExportOptions-AdHoc.plist

# 5. Distribute the .ipa file directly (email, web, MDM)

Template: assets/templates/ExportOptions-AdHoc.plist

Quick Start

First-Time Setup

1. Get certificates from Apple Developer Portal (Certificates, Identifiers & Profiles)
2. Create App ID with required capabilities
3. Generate provisioning profiles for your distribution method
4. Create App Store Connect API key (for CI uploads):
5. App Store Connect --> Users and Access --> Integrations --> App Store Connect API
6. Download the .p8 key file (only downloadable once)
7. Copy templates into your project:
8. assets/templates/ExportOptions-AppStore.plist
9. Use the automation scripts:
   bash bash scripts/build-and-archive.sh bash scripts/upload-testflight.sh build/export/MyApp.ipa

CI/CD Setup

1. Export your .p12 certificate and encode as base64
2. Download provisioning profile and encode as base64
3. Create App Store Connect API key
4. Copy the GitHub Actions template:
5. assets/templates/github-actions-ios-release.yml
6. Set up CI keychain:
   bash bash scripts/setup-signing-ci.sh

Reference: references/ci-cd-automation.md

Key Differences from macOS

Quick Reference: Verification Commands

Resources

references/

Comprehensive documentation loaded as needed:

• code-signing.md - Certificates, provisioning profiles, entitlements, automatic vs manual signing
• distribution-channels.md - TestFlight, App Store, Ad Hoc, Enterprise comparison
• ci-cd-automation.md - GitHub Actions, Xcode Cloud, Fastlane pipelines
• troubleshooting.md - Common signing errors with diagnosis and fixes

scripts/

Ready-to-use automation:

• build-and-archive.sh - Archive iOS app and export IPA
• upload-testflight.sh - Upload IPA to TestFlight via App Store Connect API
• setup-signing-ci.sh - CI keychain creation, cert import, profile installation

assets/templates/

Copy-paste templates:

• ExportOptions-AppStore.plist - Export for App Store / TestFlight
• ExportOptions-AdHoc.plist - Export for Ad Hoc distribution
• ExportOptions-Development.plist - Export for development builds
• Entitlements-iOS.entitlements - Common iOS entitlements template
• github-actions-ios-release.yml - Complete CI pipeline for iOS
• Fastfile-ios.rb - Fastlane Fastfile for iOS

When to Use This Skill

Trigger this skill when:
- Preparing an iOS app for first release
- Setting up code signing certificates and provisioning profiles
- Debugging signing or provisioning profile errors
- Creating CI/CD pipelines for TestFlight or App Store
- Choosing between TestFlight, Ad Hoc, App Store, or Enterprise distribution
- Setting up Fastlane match for team signing
- Troubleshooting TestFlight upload or processing failures
- Managing device registrations for Ad Hoc distribution
- Configuring entitlements and App ID capabilities

Summary

Shipping iOS apps requires getting signing and provisioning right. A single mismatch between certificate, profile, entitlements, or bundle ID produces cryptic errors.

This skill eliminates guesswork:
- Decision trees tell you which distribution path to take
- Scripts automate the error-prone archive, export, and upload steps
- Templates give you correct ExportOptions and entitlements starting points
- Troubleshooting guides diagnose what went wrong

Build it. Sign it. Ship it.