Apple Release Ops

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:

    methodapp-store-connect   
    destinationupload          
    manageAppVersionAndBuildNumber
    signingStyleautomatic

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  --keychain-profile ci-profile  # on failure

Sign with Developer ID Application cert, hardened runtime on (--options runtime), before submitting. Mac App Store builds skip notarization (App Review covers it).

TestFlight strategy

• Internal groups (up to 100 ASC users, 30 devices each): no Beta App Review, builds appear

in minutes. Enable "automatic distribution" on the group so every upload reaches the team. This is your smoke-test tier — every CI build goes here.

• External groups (up to 10,000 testers, email or public link): first build of each version

needs Beta App Review (usually `.

1. Decide: fix-forward build (same version train, bump build number, expedited review) vs.

server-side kill-switch/remote-config disable of the offending feature. Prefer the kill-switch you shipped in advance.

1. If the bad version must stop spreading and no fix is ready: Remove from Sale, understanding

existing users keep the app.

References

Read the matching file before deep work — they carry the exact commands and current specs:

• references/ci-recipes.md — GitHub Actions pipeline (keychain setup, ASC key auth, SPM

caching, macOS runner realities), Xcode Cloud decision guide, fastlane equivalents.

• references/signing-troubleshooting.md — decision tree for every classic signing error,

codesign/security forensics, CI keychain pathologies.

• references/store-presence.md — metadata field limits, 2026 screenshot specs, privacy label

upkeep, phased release + review windows, replying to reviews via API, crash/metric triage.

Companions & orchestration

Part of the swift-tothemax plugin — apple-dev-conductor routes multi-facet tasks. Siblings: app-review-max is the gate before every submission this skill uploads; apple-legal-max supplies the privacy/label inputs entered in App Store Connect. Ecosystem companions (delegate if installed): xcode-build-fixer and its siblings for build failures and build-time optimization; asc-metadata-sync and the rudrankriyam ASC CLI suite for scripted metadata/localization ops; xcode-project-setup (firebase) when Firebase is in play. Command syntax here is verified against Xcode 26.6 — prefer it over older companion invocations.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dev869
• Source: Dev869/swift-tothemax
• License: MIT

Install and usage instructions live in the source repository linked above.