edgeever/docs/ios-xcode-cloud.md

iOS App Store builds via Xcode Cloud

Why

Local Macs on macOS beta stamp binaries with BuildMachineOSBuild from the beta OS. App Store Connect then rejects the upload as ITMS-90111 (often worded as “Unsupported SDK or Xcode version”), even when using a release Xcode.

Policy for this repo:

Work	Where
Day-to-day coding, Simulator, device debug	Local Mac (beta OS OK)
Archive / TestFlight / App Store binary	Xcode Cloud only (manual start)

Xcode Cloud is billed as 25 compute hours per month with the Apple Developer Program. Start workflows manually so hours go only to real store submissions.

Native store target: apps/ios (SwiftUI). Expo apps/mobile is not the iOS store path.

One-time setup

Xcode / App Store Connect

1. Open the project:

   cd apps/ios
   xcodegen generate   # if needed
   open EdgeEver.xcodeproj
   

2. Xcode → Product → Xcode Cloud → Create Workflow… (or Report navigator → Cloud).
3. Product: EdgeEver (org.edgeever.mobile), repository tianma-if/edgeever.
4. When asked for the project path in a monorepo, select apps/ios/EdgeEver.xcodeproj.
5. Workflow settings (important):
   • Start condition: Manual only — do not start on every git push / PR (saves the 25h quota).
   • Actions: Archive (scheme EdgeEver, platform iOS).
   • Deployment preparation: App Store Connect / App Store eligible (or TestFlight Internal Only).
   • Xcode / macOS: latest release — not a beta toolchain.
6. Signing: project uses Automatic signing so Xcode Cloud can mint Development + Distribution profiles. First run may ask the Account Holder to confirm certificates in App Store Connect.
7. Grant GitHub access for the primary repo only. Public SPM deps (GRDB, Pow) do not need Connect.

Shared secrets (auto-upload)

In App Store Connect → EdgeEver → Xcode Cloud → Settings → Shared Environment Variables, add (secret):

Variable	Value
APP_STORE_CONNECT_API_KEY_ID	Key ID (e.g. from Users and Access → Integrations → App Store Connect API)
APP_STORE_CONNECT_API_ISSUER_ID	Issuer ID
APP_STORE_CONNECT_API_KEY_P8_BASE64	Entire .p8 file contents, base64-encoded

ci_post_xcodebuild.sh uses these to run altool after the archive so the IPA reaches ASC even if secondary Development/Ad Hoc exports fail.

Encode the key:

base64 -i AuthKey_XXXX.p8 | tr -d '\n'

Build number (source of truth)

Xcode Cloud overwrites CFBundleVersion with its managed counter:

App Store Connect → EdgeEver → Xcode Cloud → Settings → Build Number → Next build number

Rules:

1. Next Cloud number must be greater than every build already on ASC for this app.

2. Keep apps/ios/Config/Version.xcconfig → CURRENT_PROJECT_VERSION in the same ballpark (the repo stamps Cloud’s CI_BUILD_NUMBER into the archive via ci_pre_xcodebuild.sh).

3. Before a store run, from a machine with API credentials:

   cd apps/ios
   export APP_STORE_CONNECT_API_KEY_ID=...
   export APP_STORE_CONNECT_API_ISSUER_ID=...
   export APP_STORE_CONNECT_API_KEY_P8_BASE64=...   # or install AuthKey_*.p8 under ~/.appstoreconnect/private_keys/
   bash Scripts/ensure-xcode-cloud-build-number.sh
   

   Then set the ASC “next build number” UI to the printed recommended_next_cloud_build (or higher) if the UI is not already there.

What the repo provides

Path	Role
apps/ios/ci_scripts/ci_post_clone.sh	bun + XcodeGen + EditorBundle + xcodegen generate
apps/ios/ci_scripts/ci_pre_xcodebuild.sh	Stamp CI_BUILD_NUMBER; force Automatic signing
apps/ios/ci_scripts/ci_post_xcodebuild.sh	Upload App Store IPA via altool when secrets are set
apps/ios/Scripts/upload-app-store-ipa.sh	Manual upload of .ipa or Cloud app-store.zip
apps/ios/Scripts/ensure-xcode-cloud-build-number.sh	Recommend / sync next build number from ASC history
apps/ios/EdgeEver.xcodeproj/xcshareddata/xcodecloud/manifest.json	Cloud product linkage (commit this file)

Routine: ship a store binary

1. Land the code on the branch Cloud tracks (usually main).

2. Bump MARKETING_VERSION when the user-facing version changes; ensure Cloud next build number > latest ASC build (ensure-xcode-cloud-build-number.sh).

3. Start the manual Archive workflow (Xcode or ASC → Xcode Cloud → Start Build).

4. Wait for Archive. Prefer a green run; if the run is red only because Development/Ad Hoc export failed, check that ci_post_xcodebuild still uploaded the App Store IPA (or download ARCHIVE_EXPORT and run upload-app-store-ipa.sh).

5. In ASC: wait until the build is Valid, attach it to the version, Submit for Review.

   Optional (metadata already on ASC, binary already uploaded):

   cd apps/ios
   APP_STORE_VERSION=X.Y.Z APP_STORE_BUILD_NUMBER=N \
   APP_STORE_CONNECT_API_KEY_ID=... \
   APP_STORE_CONNECT_API_ISSUER_ID=... \
   APP_STORE_CONNECT_API_KEY_P8_BASE64=... \
   fastlane ios submit_review
   

Local archive (release macOS only)

cd apps/ios
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer bash Scripts/archive-app-store.sh
bash Scripts/upload-app-store-ipa.sh build/export/EdgeEver.ipa

On macOS beta, do not upload that IPA; use Xcode Cloud instead. archive-app-store.sh refuses beta hosts unless EDGE_EVER_IOS_ALLOW_BETA_HOST=1.

Troubleshooting

Symptom	Likely cause	Fix
ITMS-90111 after local upload	Host macOS is beta (BuildMachineOSBuild)	Use Xcode Cloud only for store binaries
Cloud run FAILED but ARCHIVE_EXPORT / App Store IPA exists	Development/Ad Hoc export lacks profiles	Automatic signing + Cloud managed certs; ci_post_xcodebuild still uploads App Store IPA
IPA CFBundleVersion is 1 or too low	Cloud “next build number” not advanced	ASC → Xcode Cloud → Build Number; run ensure-xcode-cloud-build-number.sh
Build never appears on ASC	Auto-upload secrets missing; or only Dev/Ad Hoc failed without App Store IPA	Set shared env secrets; or manual upload-app-store-ipa.sh
Cloud fails in post-clone on bun/xcodegen	Network / Homebrew on Cloud	Re-run; inspect ci_post_clone log
Editor blank in app	EditorBundle not built	Confirm ci_post_clone log shows bundle build
Hours running out	Workflow not Manual	Disable push/PR start conditions

Related

• apps/ios/README.md — generate / test / Fastlane submit
• apps/ios/Scripts/archive-app-store.sh — local archive
• apps/ios/ci_scripts/* — Cloud lifecycle hooks