In this article

Move workflows off GitHub’s macOS 14 runner labels before November 2, 2026, and validate the replacement environment rather than only changing runs-on. The important migration unit is the complete build environment: architecture, selected Xcode, dependencies and release output.

GitHub’s October 1 retirement notice names macos-14, macos-14-large and macos-14-xlarge. It also lists temporary brownouts before retirement and warns of reduced capacity. Consult that notice for the exact windows instead of treating an intermittent failure as proof of a broken application.

Find every reference, including reusable workflows#

Search workflow files, reusable workflows and generated templates. Also inspect matrix values: a job can select its runner indirectly, so searching only for runs-on: macos-14 can miss it.

For a repository you control, this read-only example finds the literal label:

sh
git grep -n 'macos-14' -- .github

Record each affected job’s purpose. A unit-test job and a signed App Store archive need different acceptance checks. If a workflow is generated by another tool, identify the supported regeneration route so your edit is not overwritten later.

Build a migration ledger#

For each job, capture these fields from its last successful run:

  • Runner label and reported machine architecture.
  • Selected Xcode and SDK, where applicable.
  • Flutter, Dart and native dependency-tool versions.
  • Whether it builds, signs, uploads or merely tests.
  • The artifact identity and checks that made the run acceptable.

Use the runner-images repository to inspect current image software. GitHub’s suggested replacement labels include ARM64 options. Check architecture-dependent tools, native binaries and caches rather than assuming your previous environment transfers unchanged.

Change the environment in a reviewable branch#

Choose a documented available label that meets the job’s requirements. Pin the tools that your workflow supports pinning; a moving latest label is convenient, but its name does not freeze installed software.

A hypothetical team might first migrate a build-only job, verify its output, then migrate the signing job. That is a risk-control sequence, not a claim about GitHub’s required procedure.

Keep dependency upgrades separate where practical. If runner, Flutter and five plugins change together, a failure becomes harder to attribute. Where an upgrade is necessary for compatibility, record it explicitly in the same ledger.

Acceptance means more than a green job#

Compare the intended build configuration and output identity. For an iOS release, check the selected toolchain, bundle identifier, version, signing/export outcome and a suitable device test. Do not upload repeatedly to a production store merely to investigate a runner change.

Compare clean and cached runs. A successful warm run can hide an omitted dependency installation; a successful clean run can still leave an incorrectly shared cache behind.

If the new environment fails, retain the error and the environment difference. Reverting a branch temporarily can help diagnosis while the old image is available, but it is not a plan after retirement.

Close the migration when the references are gone#

Repeat the repository search, check indirect matrix configuration and update owned templates. Record the replacement label and the validation run. Review the official notice again before your next release because image availability is time-sensitive.

For the wider release workflow, Meet CascadeCI explains why a successful build and public store availability are separate outcomes. This migration guide is based on documentation; it does not claim a benchmark or a migration of your repository.