The same commit passes on your Mac and fails on GitHub Actions. Before changing Swift code or clearing every cache, find the first point where the two builds diverge. Compare the runner image, the active Xcode installation and the exact command before deciding whether the fix belongs in the workflow or the project.
This guide is for teams running iOS builds or tests on a macOS runner. Start with the five-minute comparison below, then follow the branch that matches the first useful error in your CI log.
Start with the last green run
Open the last successful run and the first failed run side by side. Record the commit, workflow name and failing step. On a GitHub-hosted runner, expand the setup log and look for the image name and version. In your workflow, find the job’s runs-on setting. These are two different clues: the label selects the runner, while the setup log tells you what the job actually received.
A major-version macOS label can help avoid a move to a different operating system family. GitHub still updates the software within supported images. If identical code behaved differently on two days, compare the image and selected Xcode before assuming the rerun was a flake.
Capture the environment before the failing command
Add a temporary diagnostic step immediately before your existing build or test step. Run the same commands on the Mac where the build works. If your build step overrides DEVELOPER_DIR, apply that same override when collecting the diagnostic output.
sw_vers
uname -m
xcode-select -p
xcodebuild -version
xcodebuild -showsdks
xcrun simctl list devices available
Compare the output in this order:
Xcode and SDK: Compare the Xcode version and the SDKs available to it. If the expected SDK is absent, move to a runner that provides the required Xcode or change the selected installation.
Architecture: If a tool fails with an architecture error, compare uname -m and check whether the failing dependency provides a build for that architecture.
Simulator: Compare the requested device and iOS version with the available devices on the runner. A runtime installed on your laptop tells you nothing about the runner’s inventory.
Use the first real error to choose the next check
The compiler or SDK is different
Imagine a Swift package builds locally but CI reports an unsupported language feature. If the job is using an older Xcode, check the installed software list for that exact runner image. When the required version is present, set DEVELOPER_DIR for the build step to that Xcode app’s Contents/Developer directory. Use the actual path listed for the image. Run xcodebuild -version inside that same step before starting the build.
If the required version is missing, choose an image that supplies it or agree on a new version for the team. Rerun the same commit with only that change. That gives you a cleaner result than upgrading dependencies and the runner in one commit.
Xcode says no destination matches
First list available devices with simctl. Then run xcodebuild -showdestinations -scheme YourScheme using the same workspace or project argument as CI. The first command tells you what is installed. The second tells you what the scheme can use.
For example, a device might appear in the available list while the workflow requests an iOS version that is absent. Update the destination to a supported runtime, or choose an image with the runtime the tests need. Avoid hard-coding a simulator UUID from your laptop into a hosted workflow.
The scheme is missing or only the archive fails
If the scheme is missing, run xcodebuild -list against the exact project or workspace from a clean checkout. Check that the scheme is shared and committed. Also compare whether CI opens the workspace while your local command uses the project, or vice versa.
If simulator tests pass but a device archive fails, look at the first signing message and check the archive configuration, signing identity and provisioning profile. Avoid printing signing material or secrets while collecting logs. A simulator build and a signed archive exercise different parts of the pipeline.
If the toolchain already matches
Run the CI command from a fresh local checkout with the same scheme, configuration, destination and dependency inputs. Building from the Xcode toolbar can hide differences in the command CI actually runs. A clean checkout helps expose files you have locally that were never committed.
If that command works locally, inspect the failing step for an assumption about the runner. Check the working directory, generated files and whether dependencies resolve without a cache. Treat a cache miss as a diagnostic experiment. If the build only works with a warm cache, identify the missing setup step before restoring the cache.
Confirm the fix on the same commit
Rerun the original failing commit with one change. Confirm the log shows the intended Xcode and destination, and check that the step that originally failed actually ran and passed. Keep the small environment printout in CI if your team relies on hosted runners. The next person investigating a failure will have something concrete to compare.
References: GitHub runner selection, GitHub runner image manifests and update policy, and Apple’s Xcode component guide.