Guides

Native iOS & macOS

Last updated 14 September 2026

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

ToolVersion
macOS26.6.2
Xcode27.2, already selected as the active developer directory
Swift6.4.2
SimulatorsiOS, watchOS, tvOS and visionOS 27.2 runtimes; iPhone 17, 17e, 18 Pro, 18 Pro Max, Air and Duo
CocoaPods1.17.0
Ruby4.0.7 via rbenv, so gem install works without sudo
Homebrew7.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
Use -workspace MyApp.xcworkspace instead of -project if you use CocoaPods or Swift packages that Xcode resolved into a workspace. Passing -project to a Pods-based app is the single most common first failure, and the error Xcode gives for it (“module not found”) does not mention the workspace at all.

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
Note the || true after xcodebuild test. Without it a failing test ends the build immediately and the conversion never runs — so you get a red build with no test report, which tells you less than either one alone. The report itself turns the build red once it is parsed.

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:

Next: code signing & TestFlight, or the full configuration reference.


Something here wrong or missing? Tell us — we read every message, and documentation fixes go out the same day.