Xcode Build Server

What makes a good Xcode build server

Xcode only runs on macOS, and Apple-platform builds need it. A reliable build server has four things: the right Xcode versions installed side by side, caches that survive between builds, simulator runtimes ready to go, and a scripted path from source to signed, notarized output. This page covers each one with commands you can paste.

If you have not chosen a CI system yet, start with our macOS CI/CD runner overview.

Prices in USD per month for each machine's starting configuration. More memory, storage or several machines? Ask us.

Install several Xcode versions

Most teams need the current Xcode for new work and the previous one for maintenance branches. The open-source xcodes CLI installs versions side by side. It asks for your Apple Account the first time.

brew install xcodesorg/made/xcodes aria2
xcodes install --latest
xcodes install 26.0
xcodes installed
xcodes select 26.0
sudo xcodebuild -license accept
sudo xcodebuild -runFirstLaunch

xcodes select switches the system default, like xcode-select -s. To pin a version for a single job instead, set DEVELOPER_DIR. Check the exact app path with xcodes installed.

# per job, without changing the system default
export DEVELOPER_DIR="/Applications/Xcode-26.0.0.app/Contents/Developer"
xcodebuild -version

Each Xcode plus its simulator runtimes can take tens of gigabytes, so two or three versions are a good reason to choose a 512GB plan.

Cache DerivedData and Swift packages

By default Xcode keys DerivedData by the workspace path, so when a CI checkout moves between runs the cache is missed. Give each project a stable path so incremental builds work and package checkouts are reused.

xcodebuild build \
  -scheme MyApp \
  -destination 'generic/platform=iOS Simulator' \
  -derivedDataPath "$HOME/ci-cache/DerivedData/MyApp" \
  -clonedSourcePackagesDirPath "$HOME/ci-cache/SourcePackages" \
  -skipPackagePluginValidation

• Commit Package.resolved so dependency versions are fixed.
• Clear a project's DerivedData when you change Xcode versions; mixed caches cause odd errors.
• Add a weekly clean-up job that deletes old DerivedData and archives so the disk does not fill up.

Archive and export

For release builds, archive with a generic device destination, then export with an ExportOptions.plist that sets the method (for example app-store-connect, release-testing or developer-id), team ID and signing style.

xcodebuild archive \
  -scheme MyApp -configuration Release \
  -destination 'generic/platform=iOS' \
  -archivePath build/MyApp.xcarchive

xcodebuild -exportArchive \
  -archivePath build/MyApp.xcarchive \
  -exportOptionsPlist ExportOptions.plist \
  -exportPath build/export

Signing on a headless Mac needs certificates in an unlocked keychain. Our iOS build server page covers certificates, provisioning profiles and fastlane match in detail.

Simulators

Recent Xcode versions download simulator runtimes separately. Install them once on the server so test jobs do not wait for downloads.

xcodebuild -downloadPlatform iOS
xcrun simctl list runtimes
xcrun simctl list devices available
xcrun simctl delete unavailable

Pick test destinations by name and OS, for example -destination 'platform=iOS Simulator,name=iPhone 17,OS=latest', and delete unavailable devices after Xcode upgrades.

Notarize Mac apps with notarytool

Mac apps distributed outside the Mac App Store need a Developer ID signature and notarization. notarytool replaced the old altool workflow. Store an App Store Connect API key once in the keychain, then submit and staple in your pipeline.

xcrun notarytool store-credentials "ci-notary" \
  --key AuthKey_ABC123.p8 --key-id ABC123 --issuer "$ASC_ISSUER_ID"

ditto -c -k --keepParent MyApp.app MyApp.zip
xcrun notarytool submit MyApp.zip --keychain-profile "ci-notary" --wait
xcrun stapler staple MyApp.app

See Apple's notarization documentation for the full requirements, including the hardened runtime.

Which Mac to choose

• Mac mini M6, 24GB / 512GB: our most popular plan and a good default for one or two apps and two Xcode versions.
• Mac mini M5 Pro, 24GB / 512GB: for larger codebases where clean build time matters.
• Mac Studio M5 Max, 36GB / 512GB: for big modular projects, several parallel simulators or a server shared by a larger team.

More storage is available on request. Tell us what you need. For an end-to-end walkthrough, read iOS CI/CD on a cloud Mac mini.

FAQ

Can I install beta versions of Xcode on the build server?

Yes. You have full admin access, so you can install betas alongside release versions with xcodes or by downloading them from Apple, and switch per job with DEVELOPER_DIR.

How much disk does an Xcode build server need?

Plan for each Xcode version plus its simulator runtimes to take tens of gigabytes, plus DerivedData and archives. 512GB suits most teams; more storage is available on request.

Do I need a separate Mac to notarize apps?

No. The same Xcode build server can sign, notarize and staple with notarytool as part of the build.

Is this a virtual Mac?

No. Each Hatmac machine is a dedicated physical Mac assigned to one customer.