# ios-cicd-distributor

> 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.

- Author: eovidiu
- Repository: eovidiu/agents-skills
- Version: 20260204225927
- Stars: 2
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/eovidiu/agents-skills
- Web: https://mule.run/skillshub/@@eovidiu/agents-skills~ios-cicd-distributor:20260204225927

---

---
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?

| Distribution | Certificate | Profile Type |
|---|---|---|
| Development / testing | Apple Development | Development |
| TestFlight / App Store | Apple Distribution | App Store |
| Ad Hoc | Apple Distribution | Ad Hoc |
| Enterprise / In-House | iOS Distribution (In-House) | In-House |

## End-to-End Workflows

### Development to TestFlight

```bash
# 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.

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

### Ad Hoc Distribution

```bash
# 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):
   - App Store Connect --> Users and Access --> Integrations --> App Store Connect API
   - Download the .p8 key file (only downloadable once)
5. **Copy templates** into your project:
   - `assets/templates/ExportOptions-AppStore.plist`
6. **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**:
   - `assets/templates/github-actions-ios-release.yml`
5. **Set up CI keychain**:
   ```bash
   bash scripts/setup-signing-ci.sh
   ```

**Reference**: `references/ci-cd-automation.md`

## Key Differences from macOS

| | iOS | macOS |
|---|---|---|
| Provisioning profiles | Required for all distribution | Only for App Store |
| Notarization | Not applicable (Apple re-signs) | Required for direct distribution |
| Ad Hoc distribution | Yes (100 devices/family/year) | No equivalent |
| TestFlight | Primary beta channel | Available but less common |
| Enterprise distribution | Yes (In-House) | Developer ID + MDM |
| Device registration | Required for Ad Hoc | Not required |
| Hardened runtime | Not applicable | Required for notarization |

## Quick Reference: Verification Commands

| What | Command |
|---|---|
| List signing identities | `security find-identity -v -p codesigning` |
| List installed profiles | `ls ~/Library/MobileDevice/Provisioning\ Profiles/` |
| Decode a profile | `security cms -D -i profile.mobileprovision` |
| Check profile expiry | `security cms -D -i profile.mobileprovision \| grep ExpirationDate -A1` |
| Verify app signature | `codesign --verify --verbose=4 MyApp.app` |
| Show entitlements | `codesign --display --entitlements :- MyApp.app` |
| Upload IPA | `xcrun altool --upload-app -f MyApp.ipa -t ios --apiKey KEY --apiIssuer ISSUER` |
| Validate IPA | `xcrun altool --validate-app -f MyApp.ipa -t ios --apiKey KEY --apiIssuer ISSUER` |
| Check profile devices | `security cms -D -i profile.mobileprovision \| grep -A100 ProvisionedDevices` |

## 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.**