Resolving "Path /Applications/Xcode-X.X.app doesn't exist" errors

Why Does this Error Occur?

A previously working Xcode build pipeline may start failing

Our Xcode patch policy states that we retain the latest patch version of each Xcode major.minor version we support. Once a new patch version has been released, we will deprecate the previous patch version and redirect all requests to the new patch.

If your Fastlane configuration is relying on a hard-coded Xcode path, you may find that when a new patch version is realised that this will start to fail as the Xcode app path contains the version number of Xcode.

Example:

You use the Xcode 12.1.0 image and specify /Applications/Xcode-12.1.app in one of your Fastlane actions.

We release Xcode 12.1.1 and redirect requests for 12.1.0 to this new image. Therefore the new Xcode app path is /Applications/Xcode-12.1.1.app and your job will fail on Path '/Applications/Xcode-12.1.app' doesn't exist

Best Practises for Avoiding Hard Coded Paths

In each image, we always symlink Xcode to a generic path. For example:

/Applications/Xcode-12.1.app -> /Applications/Xcode.app

The generic path remains consistent across all images, regardless of the Xcode version, and should be used for CircleCI jobs where possible.

We can also utilise a variable and CI environment test to avoid the use of a hard-coded path when running on CircleCI specifically. For example:

# fastlane/Fastfile

xcodePath = "/Applications/Xcode-12.1.app"

platform :iOS do
  before_all do
    setup_circle_ci
    if is_ci
      xcodePath = "/Applications/Xcode.app"
    end
  end
  ...
end

The above sets a variable, xcodePath, where we store the required path to Xcode. By using if is_ciwe can check whether the job is running on CircleCI and set the generic Xcode path if this is true. This allows you to continue using a hardcoded path when dealing with a local environment, if required, whilst using the generic symlinked path on CircleCI which helps prevent breaking changes between Xcode version changes.