Xcode 27 Switches to macOS 27: 2026 CI Migration Checklist

GitHub confirmed that the xcode-27 and xcode-27-xlarge runner images began running on macOS 27 on September 10, 2026, while remaining in Public Preview (GitHub’s change notice). That makes this an Xcode 27 macOS 27 CI migration, not a normal Xcode-only upgrade.

This week, keep the existing production workflow, capture a comparable baseline, and create a fixed remote Mac node with the same Xcode version before sending release traffic to the new runner.

This checklist is for developers maintaining an xcode-27 workflow, DevOps engineers responsible for Apple-platform CI, and mobile platform owners deciding whether a preview runner is ready for production. If you only need a local Xcode setup, the migration controls below are more than you need.

Last updated September 14, 2026. Status and dates were checked against the GitHub Changelog, GitHub hosted runner documentation, the Xcode 27 image manifest, and Apple’s Xcode documentation. macOS 27’s later release status, future image changes, and the date of any General Availability transition are not assumed here.

The migration decision

The immediate production decision is not “does Xcode 27 compile?” It is “can you prove which environment changed, reproduce the result, and recover if the preview runner fails during release work?”

Keep the current production pipeline when any of these conditions apply:

• The workflow uses signing, release export, or delivery credentials that have not been tested on macOS 27.
• A minimal xcodebuild job fails before the project’s application code is involved.
• Tests, simulator startup, result-bundle parsing, or artifact verification behave differently without a documented explanation.
• The team cannot reproduce a failure on a controlled node with the same Xcode version.
• The old pipeline has no clear rollback trigger or retention period.

Move toward migration only after the new runner passes the same build, test, archive, signing, and artifact checks as the existing path. If the project passes on macOS 27 but a controlled same-Xcode, macOS 26 environment remains materially more predictable, operate both paths until the difference is understood.

Why did the xcode-27 runner move to macOS 27 without a YAML change? Because a runner label identifies an image selection, not a permanent host operating system contract. GitHub’s September 10 announcement explicitly states that the Xcode 27 runner image now runs on macOS 27 and is still Public Preview. Your YAML can remain unchanged while the image and host layer change underneath it.

Before the switch: production baseline

Treat the last successful production job as an evidence package, not just a green check mark. Save the complete workflow log, artifact metadata, and environment details before changing the runner label or Xcode selection.

Record these items from the successful run:

• The exact runner label and image version.
• The reported macOS version and kernel details.
• The Xcode version and active Developer Directory.
• CPU architecture and the architecture of important native tools.
• Dependency lock files and package-manager versions.
• Deployment Target, SDK selection, Scheme, and configuration.
• Key build settings passed to xcodebuild.
• Simulator runtime, test destination, and test result format.
• Archive, export, signing, and artifact verification output.
• Cache keys, environment variables, and any installed tools.

Use the workflow log as the primary observation and compare it with the published Xcode 27 image software list. Do not infer the actual host from the YAML label alone. The label tells you what the job requested; the log tells you what executed.

Freeze the comparison variables. Do not update dependencies, rewrite signing scripts, change the Deployment Target, and move to macOS 27 in the same commit. If all of those changes land together, a failure cannot tell you whether the cause was the project, dependency resolution, Xcode, macOS, or the runner image.

A useful migration branch changes one environmental variable first: the runner or host. Keep the source revision, lock files, Scheme, signing mode, and build commands unchanged. Only after you have a clean comparison should you test a dependency or script change.

First run: layer identification

The first job on the new runner should be diagnostic rather than a full release build. Add a temporary environment collection step that prints the operating system, image metadata, architecture, active Developer Directory, SDK information, and selected Xcode version.

Avoid printing secrets, provisioning content, certificate material, or private repository variables. The purpose is to establish the execution layer, not to create a larger security exposure.

A minimal job should then perform the smallest useful compilation for the project. Keep it separate from signing and distribution. For example, the diagnostic sequence can:

• Resolve dependencies from the existing lock files.
• Select the intended Developer Directory explicitly.
• Run a no-sign build for the relevant Scheme.
• Emit the full xcodebuild command and destination.
• Preserve the raw log and derived result data.
• Exit without modifying production credentials.

How do you distinguish an Xcode change from a macOS change? Hold Xcode constant and compare hosts. If the same Xcode build succeeds on macOS 26 but fails on macOS 27, investigate host APIs, system paths, permissions, runtimes, architecture assumptions, and installed tools. If it fails on both hosts after changing Xcode, start with the toolchain or project configuration. If the minimal build fails only on the new runner, stop production migration and retain the complete evidence.

Do not begin by deleting every cache or reinstalling every dependency. That destroys useful evidence and can hide a missing system tool, a changed path, or a broken native binary. First classify the failure as one of these:

• Project or source failure.
• Dependency resolution or binary compatibility failure.
• Xcode toolchain failure.
• macOS host or permission failure.
• Simulator or runtime failure.
• Signing or keychain failure.
• Runner image or workflow integration failure.

The GitHub-hosted runner documentation is useful for separating hosted-environment behavior from project-specific behavior. It should supplement your logs, not replace them.

First hour: scripts, dependencies, and architecture

Once the minimal build is understood, inspect the assumptions most likely to break when the host changes. The goal is not to make every script portable immediately. The goal is to identify which assumptions are unsafe on the new image.

Review shell scripts for:

• Hard-coded system directories.
• Intel-only paths such as architecture-specific package locations.
• Fixed tool paths instead of PATH or explicit discovery.
• Shell-specific syntax and default shell assumptions.
• Commands that expect interactive permissions.
• Logic that treats the macOS version as a fixed string.
• Cleanup steps that remove shared signing or simulator state.

Then inspect Homebrew-installed tools, binary plugins, command-line utilities, and native package components. Check the architecture of binaries rather than trusting package names. A package can install successfully while a later plugin or helper executable cannot run under the runner’s architecture.

Check community Actions and custom setup scripts for version or path assumptions. A workflow can fail before compilation because a setup action expects a tool location that no longer exists on the image.

Keep an isolation list for anything that is Intel-only, tied to a system path, or dependent on undocumented host behavior. Do not “repair” each item by reinstalling it during the first migration attempt. Reproduce it on a controlled node first, then decide whether to update the component, run it through an approved compatibility layer, or keep that workflow on the older host.

What should you do when an Intel-only dependency blocks the migration? Record the binary architecture, the command that invokes it, and the first failing log line. If the dependency cannot be replaced or isolated quickly, move that workflow to a fixed remote Mac comparison node while the preview runner remains outside production release traffic.

The Apple Xcode system requirements should be checked alongside the project’s Deployment Target. These are different controls. The host system required by Xcode does not automatically determine the minimum operating system your application supports.

Full build: tests, simulators, and result bundles

A successful archive is not a migration certificate. Run the validation sequence in stages so that each failure has a narrow search area.

Start with a no-sign build. This confirms that source compilation, dependency resolution, SDK selection, and basic build scripts work without involving production credentials.

Next, run unit tests on the intended destination. Capture the destination string, simulator runtime, test process output, and exit status. A test command can fail because the runtime is missing, the device cannot boot, the test target cannot launch, or the project has a toolchain issue. Those causes require different remedies.

Then validate Simulator tests and their cleanup behavior. Check whether the runtime exists on the runner, whether the test target starts, whether parallel output arrives in the expected order, and whether your scripts wait for completion instead of assuming an immediate result.

Finally, parse the .xcresult bundle with the same reporting tools used in production. Do not accept a green test command if the report generator cannot read the result bundle or if failure details disappear from the artifact.

Apple’s Xcode 27 release notes should be attached to any known workaround. A workaround without a corresponding release-note entry or reproducible log evidence should remain a migration risk, not become an undocumented permanent step.

How do you handle a build that fails after the Xcode 27 CI upgrade? Re-run the minimal no-sign build, then compare the first failing action with the old baseline. If the minimal job fails, investigate the environment before touching project code. If the minimal job passes, add dependencies, tests, simulator execution, and signing one layer at a time. This sequence prevents a release failure from being misdiagnosed as a compiler problem.

Candidate release: signing and delivery isolation

Keep preview validation separate from production signing. Use a non-production application identifier, controlled credentials, and a test keychain for the first archive and export attempt.

The signing sequence should cover:

• Keychain creation or access.
• Certificate availability.
• Provisioning profile selection.
• Archive generation.
• Export options.
• Signature verification.
• Artifact retention and transfer.
• Downstream delivery checks.

Do not let the first macOS 27 run delete certificates, rebuild the keychain, overwrite signing settings, or rotate credentials automatically. Every destructive operation needs a documented impact boundary and a recovery path.

Compare the new runner with the fixed remote Mac node using the same source revision, dependency lock files, Scheme, build parameters, and test application. Compare the archive metadata, signing verification output, result bundles, and workflow logs. A successful export on one node is not enough if the other node produces a different artifact or lacks evidence needed for incident review.

Can a Public Preview xcode-27 runner handle production release work? It can be evaluated for production readiness, but its Preview status means you should not treat it as an immutable release foundation. Keep release traffic on the existing path until the new runner has passed controlled signing, artifact verification, failure recovery, and rollback tests. The self-hosted runner documentation provides the operational model for using a controlled Apple-platform node when hosted-image drift is unacceptable.

Decision matrix: migrate, dual-track, or roll back

Use the following comparison after the first complete validation cycle. The decision should depend on repeatability and recovery, not on a single successful build.

A gradual migration means moving low-risk validation jobs first, then scheduled builds, then selected release candidates. Do not remove the old workflow until the rollback path has been exercised rather than merely documented.

Dual-track operation is appropriate when the new runner is useful for testing but the host change still affects reproducibility, signing, or incident recovery. This is especially important when the same Xcode version behaves differently across macOS versions and the difference is not yet explained.

Rollback is the correct outcome when a minimal build fails, evidence is incomplete, or the new environment changes signing state. A rollback is not a failed migration. It is a controlled result that protects the production release path.

First week: operating rules

During the first week, review consecutive jobs rather than one green run. Track whether the same source revision produces consistent build outputs, whether simulator tests remain reliable, whether the image reports unexpected software changes, and whether the team can identify the first failure from retained logs.

Define a written retention period for the old workflow. The period should be long enough to cover the next planned release cycle and any scheduled maintenance window that could expose environment drift. Because the runner remains Public Preview as of September 14, 2026, do not assume that a future image will preserve the current software list or host behavior.

Set re-evaluation triggers:

• A new Xcode 27 build or release note appears.
• GitHub changes the preview status or host operating system.
• The runner image manifest changes a required tool.
• A signing, simulator, or artifact regression appears.
• A failure occurs only on macOS 27.
• The fixed comparison node is no longer available.
• A rollback cannot be completed within the team’s release process.

For a controlled comparison, you can use a remote Mac environment from VMSPIN and reproduce the key workflow with a fixed Xcode and macOS combination. Do not assume that a remote node is automatically equivalent to a hosted runner. Verify the actual system version, Xcode path, architecture, access method, restart behavior, and credential isolation before treating it as evidence.

If your team needs a repeatable purchasing path for a temporary comparison node, review the VMSPIN Mac rental options only after defining the required operating system, Xcode version, access method, and retention period. The engineering decision should determine the environment, not the other way around.

The practical endpoint

The hosted runner is convenient, but its changing image and host layer can make a release failure harder to reproduce. A local Mac gives you physical control, yet it ties the CI node to one device, one network path, and one maintenance owner. A Linux-only build server avoids some Mac hardware overhead, but it cannot replace macOS-specific tools, Xcode, simulator execution, or Apple-platform signing.

A fixed remote Mac is a useful middle path when you need a stable comparison environment, a persistent self-hosted runner, or a temporary release safety net. It still requires you to manage access, updates, credentials, monitoring, and recovery. That trade-off is preferable to treating a Public Preview image as a permanent production contract.

For this migration, the safest next action is to preserve the existing production workflow, run the same Xcode 27 toolchain on a controlled remote Mac, and compare the macOS 26 and macOS 27 results before changing release traffic. If you need that comparison only during the migration window, renting the required Mac environment through VMSPIN can be more practical than buying a dedicated Mac that may sit idle after the runner stabilizes.