Data point: GitHub’s retirement notice confirms that the macos-14, macos-14-large, and macos-14-xlarge labels were retired on November 2, 2026. If your workflow still requests one of them, do not replace it automatically with macos-latest: first match a supported label to your macOS, Xcode, and CPU requirements, then run isolated or parallel checks for builds, tests, and release delivery before switching. (GitHub’s retirement notice)

Who should read this: Apple platform teams with any of those labels in workflow files or reusable workflows should inventory affected jobs and choose a migration candidate.
CI engineers responsible for signing, testing, and releases should validate the actual pipeline, not just whether a job starts.
DevOps and platform teams can use the decision conditions below to define acceptance and rollback criteria.

Last updated November 8, 2026. Runner retirement and label details checked against GitHub’s retirement notice, hosted-runner documentation, and runner-images repository; Xcode compatibility references checked against Apple’s release notes and system requirements.

Start with label availability

The macos-14 Runner retirement affects three labels, but it does not mean every replacement label has the same operating system, processor architecture, or installed software. GitHub’s notice gives migration direction; the current GitHub-hosted runner documentation and runner-images repository are the references for currently listed labels and image contents.

The practical distinction is between a label being documented and that label meeting a project’s needs. Check the current documentation for the exact runner label, architecture, and image information before changing YAML. Then confirm what the job actually received from its run log. A familiar label is not proof that the underlying image has the same tools or behavior as the retired image.

What should replace the retired macOS 14 label? Choose a label that is currently documented and satisfies the project’s required macOS, Xcode, and architecture constraints. Consider macos-15 or macos-26 only if the current runner documentation lists the label and the project’s toolchain is compatible with its image. Do not treat macos-latest as a pin: it can move as the supported image changes.

Before editing workflows, search the repository for all three retired labels. Include reusable workflows, composite actions, matrix definitions, scripts that generate workflow YAML, and release workflows maintained in a separate repository. Review recent run records as well: a workflow may select its runner indirectly or contain a job that runs only on a release branch.

Capture the old job’s relevant baseline where available: runner label, reported architecture, Xcode version, SDK selection, dependency-resolution output, test destinations, signing approach, and produced artifact details. This gives the team a meaningful comparison target; “the new job is green” is weaker evidence than “the same commit produced the expected archive and passed the same required tests.”

Match the macOS image to the Xcode toolchain

An operating-system image change does not establish Xcode compatibility. A project may depend on a particular Xcode release, SDK, command-line tool, or build setting. Check the project’s actual requirements, then compare them with Apple’s Xcode release notes and Xcode system requirements. Treat release and beta toolchains separately; a beta’s availability is not evidence that it is suitable for a production pipeline.

Record the Xcode version selected by the workflow and the active developer directory in the run log. If the workflow uses a setup action or script to select Xcode, verify that it still selects an installed version on the candidate image. Also inspect SDK and simulator destinations. A successful invocation of xcodebuild does not prove that the intended SDK or simulator runtime was selected.

What needs checking before moving from macOS 14 to macOS 15 or macOS 26? Check the project’s supported host OS, required Xcode release, SDKs, simulator destinations, and any tools that assume a specific system version. Confirm each candidate label and its installed image contents in current GitHub documentation. Then run the project’s real build and test commands on that label. Do not infer compatibility from the label name alone.

For an Xcode CI environment, separate toolchain selection from application compatibility. The first question is whether the candidate runner can provide the required Xcode and SDK. The next is whether the app, packages, scripts, and tests work under that combination. If the required Xcode is missing, or Apple’s requirements exclude the candidate host, reject that candidate rather than masking the mismatch with a build-script change.

Verify CPU architecture and native dependencies

A workflow can start successfully and still fail later because a binary dependency or script assumes a different architecture. Review package managers, vendored frameworks, command-line utilities, build scripts, and any downloaded artifacts that contain native code. Check the runner’s reported architecture in the job itself; do not derive it from a label that may not guarantee the architecture your task requires.

For each candidate environment, validate dependency installation, compilation, and testing as separate stages. Dependency installation can fail when a package provides no compatible binary. Compilation can expose assumptions in a custom build script. Tests can reveal runtime differences that a successful compile will not catch. If the project intentionally needs Intel execution, verify that the candidate label actually provides the required architecture. If that cannot be confirmed from current runner documentation, keep the task on a verified environment or arrange a separately validated execution path.

How should Intel build tasks be handled after the macOS 14 Runner retirement? First identify whether the task truly requires Intel execution or merely contains an architecture-sensitive dependency. Check the supported runner documentation and confirm the architecture in a test job. If an eligible hosted label is documented and passes the project’s checks, route the task there. Otherwise, use an explicitly managed macOS execution environment that can meet the requirement, or defer the change until a validated option is available. Do not silently substitute Apple Silicon and assume all native dependencies are compatible.

Keep cache behavior in the test plan. A restored cache can make an incompatible environment appear healthy if the cache contains artifacts produced under different conditions. Use a deliberate cache-key boundary for the trial, compare a clean dependency install with a cache-enabled run, and review GitHub’s dependency caching guidance before changing cache scope or keys.

Choose a candidate with explicit conditions

Use these conditions to select a migration path rather than guessing from the newest label:

  • If the project requires a specific Xcode or SDK, choose only a currently documented runner image that provides it and meets Apple’s host requirements. Otherwise, keep the job on a verified environment until the toolchain requirement can be met.
  • If the task has a confirmed architecture requirement, select a documented label that provides that architecture and prove it in the run log. Otherwise, test the project’s native dependencies on the candidate before deciding that architecture no longer matters.
  • If the workflow needs stable, disposable hosted execution and has no unmet host requirement, trial a supported GitHub-hosted label. If it depends on private network access or a controlled, persistent toolchain, evaluate a self-managed macOS environment instead.
  • If the candidate passes clean builds, required tests, signing, and artifact checks on the same commit, approve a controlled switch. If any required result differs, retain the old deployment plan where possible, investigate the specific failure, and do not promote the change to release workflows.

A matrix can help compare candidates without editing the production path in place. GitHub documents job variations and matrix workflows; use that approach only where the project can safely run the same checks against each candidate. Keep release credentials and publishing steps out of exploratory jobs unless there is a specific, approved reason to test them.

A green status checks only the commands that ran. It does not prove that the intended Xcode was selected, that an archive was signed correctly, or that the artifact is ready for distribution.

Validate delivery, not just compilation

The acceptance run should use a representative commit and a controlled workflow that records enough evidence to compare old and new environments. Keep logs and artifact metadata with the migration record so reviewers can trace differences later.

Use this checklist for each candidate:

  • [ ] Confirm the job log reports the expected runner label and architecture.
  • [ ] Record the selected Xcode version, active developer directory, SDK, and simulator destination.
  • [ ] Resolve dependencies from a clean or intentionally controlled cache state.
  • [ ] Run a clean build using the project’s release-relevant configuration.
  • [ ] Run the project’s required unit, integration, and simulator tests.
  • [ ] Verify signing identity, provisioning behavior, archive creation, and export settings where the workflow uses them.
  • [ ] Inspect the delivered artifact and compare its relevant metadata with the established baseline.
  • [ ] Retain logs and artifact references for the same commit, then record a clear pass, fail, or blocked decision.

A single successful build is not full acceptance. A simulator test may depend on a runtime that is not present in the candidate image. A private package source may be reachable from one runner context but not another. A signing step may behave differently when keychain state, credentials, or access policies change. Test each of these where the project uses it, rather than assuming that a compiler success covers downstream delivery.

Use separate trial and production paths. The trial should run the meaningful validation tasks without publishing an artifact or changing a release. Once reviewers accept the evidence, change the production label in a small, traceable update. Keep the previous workflow definition or a documented rollback change ready until the new path has completed the team’s required release checks.

Check network, credentials, caches, and operations

Runner migration changes more than the compiler host. Check whether the workflow needs private package registries, internal APIs, source mirrors, or other restricted services. Review how secrets are supplied, which jobs can access them, and whether any step assumes persistent state between jobs. Do not copy credentials into a diagnostic job just to make a trial pass.

Hosted runners and self-hosted runners also have different operational responsibilities. With a hosted runner, GitHub manages the execution image, while the workflow owner still needs to validate image changes and its own credentials, dependencies, and scripts. With a self-hosted runner, the team must also account for host maintenance, access control, network exposure, cleanup, and the runner’s operational lifecycle. GitHub’s self-hosted runner documentation describes relevant networking and management considerations; use it to assign ownership rather than assuming that self-hosting removes maintenance work.

Review caching as part of the migration, not as a later performance tweak. A cache can conceal a missing dependency or preserve an artifact produced for a different toolchain. For the trial, make the cache policy explicit, ensure keys distinguish materially different environments where necessary, and compare results with a clean run. If the candidate behaves differently with and without cached state, investigate before switching release jobs.

Also avoid inferring queue times or service availability from past macOS 14 runs. The retirement notice and runner documentation establish label and image information; they are not a promise about the queue behavior of a different environment. If queue behavior matters to a release window, use the team’s own observed run records for the candidate and keep the conclusion limited to that observation.

Decide whether a remote Mac belongs in the plan

A hosted runner remains a strong fit when the workflow benefits from disposable execution, the documented image has the required toolchain and architecture, and the team wants GitHub to manage the host. A remote Mac can be a better fit when a team needs direct control of a real Mac environment, persistent access to its development tools, or a place to reproduce a macOS-specific issue outside a hosted job. It also brings responsibilities: teams must manage their own access, environment changes, credentials, and operational checks.

For workflows that need private dependencies or a consistent environment, teams can assess a remote Mac development setup as a separate validation target. It should not be treated as a drop-in replacement for every hosted job. A persistent host may retain state that a clean hosted job would not, so acceptance should include workspace cleanup and a reproducible setup process. A physical interface requirement may still call for local hardware, while a stable, high-duty workload may justify owning and operating dedicated hardware rather than renting it.

After updating the runner label and toolchain, rerun the same project commit on the target macOS environment and compare build, test, signing, and artifact evidence. If hosted images do not meet the project’s requirements, or the team needs a real Mac for investigation and repeatable validation, RUVCLOUD’s remote Mac rental is an option to evaluate; review the available rental plans against the required access and operating model before choosing it.