Xcode build and export

Use this skill when you need to build an app from source and prepare it for App Store Connect. Prefer asc xcode archive and asc xcode export over raw xcodebuild recipes when they fit the project.

Preconditions

• Xcode and command line tools are installed.
• Signing identity and provisioning profiles are available, or automatic signing is enabled.
• App Store Connect auth is configured when upload or build lookup is needed.

Manage version and build numbers

asc xcode version view
asc xcode version edit --version "1.3.0" --build-number "42"
asc xcode version bump --type build
asc xcode version bump --type patch

Use --project-dir "./MyApp" when not running from the project root. Use --project "./MyApp/App.xcodeproj" when the directory contains multiple projects. Use --target "App" for deterministic reads in multi-target projects.

To avoid low build-number rejects, resolve a remote-safe build number first:

asc builds next-build-number --app "APP_ID" --version "1.2.3" --platform IOS --output json
asc xcode version edit --build-number "NEXT_BUILD"

Preferred iOS/tvOS/visionOS build flow

1. Archive with asc

asc xcode archive \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --configuration Release \
  --clean \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --xcodebuild-flag=-destination \
  --xcodebuild-flag=generic/platform=iOS \
  --output json

Use --project "App.xcodeproj" instead of --workspace for project-only apps.

2. Export with asc

asc xcode export \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --export-options "ExportOptions.plist" \
  --ipa-path ".asc/artifacts/App.ipa" \
  --xcodebuild-flag=-allowProvisioningUpdates \
  --output json

If ExportOptions.plist uses direct App Store Connect upload, add --wait to poll for build discovery and processing:

asc xcode export \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --export-options "UploadExportOptions.plist" \
  --ipa-path ".asc/artifacts/App.ipa" \
  --wait \
  --output json

3. Upload or publish

Upload an exported IPA:

asc builds upload --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --wait

Distribute to TestFlight:

asc publish testflight --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --group "GROUP_ID" --wait

Publish to the App Store:

asc publish appstore --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --version "1.2.3" --wait
asc publish appstore --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --version "1.2.3" --wait --submit --confirm

macOS App Store flow

Archive with the helper:

asc xcode archive \
  --project "MacApp.xcodeproj" \
  --scheme "MacApp" \
  --configuration Release \
  --clean \
  --archive-path ".asc/artifacts/MacApp.xcarchive" \
  --xcodebuild-flag=-destination \
  --xcodebuild-flag=generic/platform=macOS \
  --output json

If your macOS export produces a .pkg, use Xcode export with your ExportOptions.plist, then upload the package:

xcodebuild -exportArchive \
  -archivePath ".asc/artifacts/MacApp.xcarchive" \
  -exportPath ".asc/artifacts/MacAppExport" \
  -exportOptionsPlist "ExportOptions.plist" \
  -allowProvisioningUpdates

asc builds upload \
  --app "APP_ID" \
  --pkg ".asc/artifacts/MacAppExport/MacApp.pkg" \
  --version "1.0.0" \
  --build-number "123" \
  --wait

For .pkg uploads, --version and --build-number are required because they are not auto-extracted like IPA metadata.

Raw xcodebuild fallback

Use raw xcodebuild only when asc xcode archive/export --help does not cover a project-specific option. Prefer passing extra arguments through --xcodebuild-flag first.

xcodebuild -showBuildSettings -scheme "App"

Troubleshooting

No profiles for bundle ID during export

• Add --xcodebuild-flag=-allowProvisioningUpdates to asc xcode export.
• Verify the Apple ID is logged into Xcode.
• Verify profiles with the asc-signing-setup skill.

CFBundleVersion too low

asc builds next-build-number --app "APP_ID" --version "1.2.3" --platform IOS
asc xcode version edit --build-number "NEXT_BUILD"

Then rebuild and upload again.

Build rejected for missing macOS icon

macOS requires ICNS icons with all required sizes. Fix the asset catalog, rebuild, then export/upload again.

Notes

• Prefer asc xcode archive and asc xcode export for deterministic local artifacts.
• Use --overwrite only when replacing existing local artifacts intentionally.
• Use --wait on upload/publish paths when the next step depends on processed builds.
• For submission readiness, use asc-submission-health.