Native iOS & macOS
Building an Xcode project or workspace — iOS, macOS, watchOS or tvOS — on a real Mac with the full toolchain already installed.
Nothing here is specific to us: these are ordinary xcodebuild invocations. If a command works on your own Mac it works here, with the one exception noted under signing.
01What is already on the machine
| Tool | Version |
|---|---|
| macOS | 26.6.2 |
| Xcode | 27.2, already selected as the active developer directory |
| Swift | 6.4.2 |
| Simulators | iOS, watchOS, tvOS and visionOS 27.2 runtimes; iPhone 17, 17e, 18 Pro, 18 Pro Max, Air and Duo |
| CocoaPods | 1.17.0 |
| Ruby | 4.0.7 via rbenv, so gem install works without sudo |
| Homebrew | 7.0.11; use it for anything else you need |
These are the versions on the default image. To stay on Xcode 26.6, add one line to your build config — see image.
You do not need a setup step for any of these. If you want to be sure what you got, make the first line of your script xcodebuild -version — it costs a second and it ends up in the log next to the failure.
02A build that does not sign
Start here. It compiles your code and proves the project is sound, without any certificates involved:
script:
- xcodebuild -version
- xcodebuild \
-project MyApp.xcodeproj \
-scheme MyApp \
-destination "generic/platform=iOS" \
-configuration Release \
CODE_SIGNING_ALLOWED=NO \
build
03With CocoaPods
script:
- pod install
- xcodebuild \
-workspace MyApp.xcworkspace \
-scheme MyApp \
-destination "generic/platform=iOS" \
CODE_SIGNING_ALLOWED=NO \
build
pod install downloads from the public CocoaPods CDN. You do not configure anything.
Commit your Podfile.lock. Without it pod install is free to resolve a different version than your laptop did, and you get a build that fails only here — the worst kind to debug.
04Swift Package Manager
Xcode resolves packages by itself. For a pure SwiftPM package with no Xcode project:
script:
- swift build -c release
- swift test
For an app whose dependencies are SwiftPM, nothing special is needed — xcodebuild resolves them as part of the build. Commit Package.resolved for the same reason you commit Podfile.lock.
05Running tests
script:
- xcodebuild \
-workspace MyApp.xcworkspace \
-scheme MyApp \
-destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
-resultBundlePath TestResults.xcresult \
test
tests:
- build/reports/*.xml
Tests need a simulator, so the destination is a platform=iOS Simulator one, not generic/platform=iOS. The first simulator boot on a fresh machine takes 30–60 seconds; that is macOS, not us.
The tests section wants JUnit XML. Xcode does not produce it natively — convert the result bundle, for example with xcresultparser:
script:
- brew install a7ex/homebrew-formulae/xcresultparser
- xcodebuild ... test || true
- mkdir -p build/reports
- xcresultparser -o junit TestResults.xcresult > build/reports/tests.xml
06Producing an .ipa
This step needs signing, so read code signing & TestFlight first and come back. The short version, once your certificate and profile are in Secrets:
signing:
certificate: APPLE_DIST_CERT
profile: MyApp_AppStore
script:
- xcodebuild \
-workspace MyApp.xcworkspace \
-scheme MyApp \
-destination "generic/platform=iOS" \
-archivePath build/MyApp.xcarchive \
CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY="" \
archive
- xcodebuild \
-exportArchive \
-archivePath build/MyApp.xcarchive \
-exportOptionsPlist ExportOptions.plist \
-exportPath build/ipa
artifacts:
- build/ipa/*.ipa
The archive is built unsigned and signed while it is exported. That works whether your project uses automatic or manual signing, and your certificate is used for exactly one step. It is how our own test app reached TestFlight.
07Building for macOS
Same machine, different destination. A macOS app builds and runs its tests natively, with no simulator to boot:
script:
- xcodebuild \
-project MyMacApp.xcodeproj \
-scheme MyMacApp \
-destination "platform=macOS" \
-configuration Release \
CODE_SIGNING_ALLOWED=NO \
build
Notarisation is not something we do for you. It needs your Apple credentials and a network call to Apple that can take minutes; if you want it, run xcrun notarytool yourself in a build step with an App Store Connect key from Secrets.
08Making builds faster
In rough order of how much they buy you:
- Build one scheme, not the whole project. Most repositories have schemes nobody needs on every commit.
- Skip signing unless the build's output is an .ipa. CODE_SIGNING_ALLOWED=NO removes a whole class of slow, brittle failures from pull-request builds.
- Use -quiet. Xcode's default output is enormous; the 20 MB log limit is real and a verbose build can hit it.
- Do not run clean. Every build already starts on a machine created seconds earlier — there is nothing to clean, and the flag only makes Xcode redo work.
Next: code signing & TestFlight, or the full configuration reference.