/apple-release-ops

name: apple-release-ops
description: >-
  The mechanics of shipping Apple apps. Use for ANY code signing error ("no signing certificate",
  "provisioning profile doesn't include...", "revoked certificate"), provisioning profiles,
  certificates, entitlements, capabilities, TestFlight (groups, expiry, feedback), App Store
  Connect, uploading builds, xcodebuild archive/-exportArchive, exportOptionsPlist, altool/
  notarytool/Transporter, fastlane (match/gym/pilot/deliver), Xcode Cloud, CI/CD for iOS/macOS
  (GitHub Actions, keychains on runners), version and build numbers (agvtool,
  CURRENT_PROJECT_VERSION, MARKETING_VERSION), phased release and halting a rollout, app metadata
  and screenshots, App Store Connect API keys/webhooks, crash reports and crash spikes, and macOS
  notarization/stapling. Trigger on any release, distribution, or signing task — even a single
  cryptic Xcode signing error. NOT for App Review rejection strategy (use app-review-max) or
  privacy policies/legal (use apple-legal-max).

Apple Release Ops

You own the pipeline: signed binary → TestFlight → App Store → monitored release. As of July 2026: Xcode 26.6 (Swift 6.3, iOS 26.5 SDK, requires macOS Tahoe 26.2+). Sibling skills own review strategy (`app-review-max`) and legal/compliance (`apple-legal-max`) — route there, don't improvise.

Signing, demystified

Four artifacts, four jobs. Most "signing hell" is conflating them:

| Artifact | What it is | Where it lives | |---|---|---| | **Certificate** | Your identity (public key signed by Apple + your private key) | Keychain. Private key is the part you can lose. | | **Provisioning profile** | Apple's permission slip: this cert + this app ID + these entitlements (+ these devices, for dev/ad-hoc) | `~/Library/Developer/Xcode/UserData/Provisioning Profiles/` (Xcode 16+; formerly `~/Library/MobileDevice/`) | | **Entitlements** | Key-value claims baked into the binary at sign time (`.entitlements` file) | Inside the signed binary. Inspect: `codesign -d --entitlements - MyApp.app` | | **Capability** | App Store Connect / Xcode UI switch that regenerates the app ID config and profiles | Developer portal |

Rules that resolve 90% of confusion:

• Every entitlement your binary claims MUST be allowed by the profile it ships with. Mismatch =

install/upload failure, not a build failure.

• Distribution profiles have no device list. "Device not registered" is a development/ad-hoc

problem only.

• **Cloud-managed certificates** (Xcode 13+, default with automatic signing + "Distribute App"):

Apple holds the distribution private key. Nothing to back up, nothing to expire out from under you, works with `xcodebuild -allowProvisioningUpdates`. Prefer them unless your CI can't authenticate to Apple.

**Decision: automatic vs manual signing.**

• Solo dev / small team, Xcode or Xcode Cloud builds → **automatic** + cloud-managed certs. Done.
• Self-hosted CI, multiple apps sharing certs, or extensions with exotic entitlements →

**manual** with profiles checked into a secrets store, or fastlane `match` (git/S3-backed, encrypted). Never both: mixed automatic/manual across targets is the #1 source of phantom errors.

• Wrong: fixing CI signing by exporting your personal dev certificate.

Right: a dedicated distribution cert (or cloud signing via App Store Connect API key) that no laptop depends on.

Deep debugging: `references/signing-troubleshooting.md`.

The canonical CLI release path

Three commands. Everything else (fastlane, Xcode Cloud) is a wrapper around these.

# 1. Archive (build once, distribute many)
xcodebuild archive \
  -project MyApp.xcodeproj -scheme MyApp \
  -destination 'generic/platform=iOS' \
  -archivePath build/MyApp.xcarchive \
  -allowProvisioningUpdates \
  -authenticationKeyID "$ASC_KEY_ID" \
  -authenticationKeyIssuerID "$ASC_ISSUER_ID" \
  -authenticationKeyPath "$PWD/AuthKey_$ASC_KEY_ID.p8"

# 2. Export + upload in one step (destination: upload does the upload for you)
xcodebuild -exportArchive \
  -archivePath build/MyApp.xcarchive \
  -exportOptionsPlist ExportOptions.plist \
  -exportPath build/export \
  -allowProvisioningUpdates \
  -authenticationKeyID "$ASC_KEY_ID" \
  -authenticationKeyIssuerID "$ASC_ISSUER_ID" \
  -authenticationKeyPath "$PWD/AuthKey_$ASC_KEY_ID.p8"

`ExportOptions.plist` — the method name changed; `app-store` is deprecated:

<dict>
    <key>method</key><string>app-store-connect</string>   <!-- NOT "app-store" -->
    <key>destination</key><string>upload</string>          <!-- or "export" for an .ipa -->
    <key>manageAppVersionAndBuildNumber</key><true/>
    <key>signingStyle</key><string>automatic</string>
</dict>

**Uploading a pre-built .ipa/.pkg** (if you exported instead of uploading):

• `altool` upload is **deprecated**. Do not write new automation on it.
• Use Transporter CLI (`xcrun iTMSTransporter` or Transporter.app) with the same ASC API JWT, or
• Use the **Build Upload API** (App Store Connect API, WWDC25+): create a `buildUploads`

resource, PUT the asset parts, commit — pure REST, works from any language/runner, structured error messages. Prefer this for new tooling.

**Auth everywhere with an App Store Connect API key** (Users and Access → Integrations → Team Keys, role App Manager). One `.p8` powers xcodebuild, notarytool, fastlane, and raw API calls. Never use Apple ID + app-specific passwords in new CI — 2FA prompts will break it.

**macOS outside the App Store — notarize or Gatekeeper blocks you:**

xcrun notarytool store-credentials ci-profile \
  --key AuthKey_XXX.p8 --key-id "$ASC_KEY_ID" --issuer "$ASC_ISSUER_ID"
xcrun notarytool submit MyApp.dmg --keychain-profile ci-profile --wait
xcrun stapler staple MyApp.dmg          # staple the ticket for offline validation
xcrun notarytool log <submission-id> --keychain-profile ci-profile  # on failure

Sign with Developer ID Application cert, hardened runtime on (`--options runtime`), before submittin