xcodebuild: Build, Test, and Archive iOS in CI
xcodebuild drives Xcode from the command line: build, test, and archive actions against a scheme and a destination simulator or device.
xcodebuild is the backbone of iOS CI. The recurring pain points are choosing a destination that exists on the runner and pointing it at the .xcworkspace (not .xcodeproj) when CocoaPods is involved.
What it does
xcodebuild runs Xcode build actions non-interactively. You give it a -workspace or -project, a -scheme, and a -destination (a simulator or device), plus an action: build, test, archive, or clean. It streams the raw build log, which xcbeautify or xcpretty can format.
Common usage
xcodebuild -workspace App.xcworkspace -scheme App \
-destination 'platform=iOS Simulator,name=iPhone 15' \
clean build
xcodebuild test -workspace App.xcworkspace -scheme App \
-destination 'platform=iOS Simulator,name=iPhone 15,OS=17.5'
xcodebuild -scheme App -archivePath build/App.xcarchive archiveOptions
| Flag / action | What it does |
|---|---|
| -workspace / -project | The workspace (Pods) or bare project |
| -scheme <name> | Scheme to build/test |
| -destination <spec> | Simulator or device to target |
| build / test / archive / clean | The build action |
| -configuration <Debug|Release> | Build configuration |
| -derivedDataPath <dir> | Where to write DerivedData |
| CODE_SIGNING_ALLOWED=NO | Skip signing for a compile-only CI check |
In CI
Pick a -destination that exists on the runner image; list available ones with xcrun simctl list devices available or xcodebuild -showdestinations. Use the .xcworkspace after pod install, not the .xcodeproj. Pipe through xcbeautify for readable logs while keeping the raw log as an artifact.
Common errors in CI
"Unable to find a destination matching the provided destination specifier" means the named simulator/OS is not installed; adjust to an available device. "xcodebuild: error: The workspace ... does not contain a scheme named ..." means a wrong -scheme or the scheme is not shared. "Code signing is required for product type ... requires a development team" needs a team or CODE_SIGNING_ALLOWED=NO. "xcode-select: error: tool xcodebuild requires Xcode" means the CLT-only path is active; run xcode-select -s.