GitHub's November 2026 macOS 14 Runner Retirement Explained: What to Switch To

Your macOS builds start failing for no reason you can see in the code. The cause is the macOS 14 runner retirement: GitHub is removing the machine image your workflow asks for.

Picture a common setup. A small team ships an iOS app, and its CI (continuous integration, the robot that builds and tests every push) runs on GitHub Actions. The person who wrote the workflow left, and nobody has opened it in a year. The setup is made up, but the failure is real.

The workflow says runs-on: macos-14 and selects Xcode 15.4. On a brownout evening its macOS jobs fail, though nothing in the app changed. The machine it asked for was switched off on purpose.

From 2 November 2026 that failure becomes permanent. Any job still asking for a macOS 14 label is ended with an error. This guide shows how to find every such label, pick the right replacement and prove the new build works.

You need six words: workflow, job, runner, runner image, label and brownout. Each one gets a plain meaning and an example from the iOS pipeline.

• Workflow: a YAML file in the folder .github/workflows that tells GitHub Actions what to run. YAML is a plain-text format of keys and values. Example: ios.yml.
• Job: one group of steps inside a workflow that runs on one machine. Example: the build job that compiles the app.
• Runner: the machine that runs a job. GitHub-hosted runners are fresh virtual machines that GitHub starts for each job and throws away after.
• Runner image: the disk snapshot a runner starts from, with the operating system and tools such as Xcode already installed. GitHub updates each image every week.
• Label: the name after runs-on that picks an image and machine size. Example: macos-14 picks the macOS 14 image on an Apple-chip (arm64) machine.
• Brownout: a planned window where GitHub makes jobs on a retiring label fail on purpose, so people notice before the real switch-off.

Two more words appear later. Xcode is Apple's tool for building iOS and macOS apps, and each image carries a fixed set of Xcode versions. Arm64 means Apple's own chips, while x64 means older Intel chips.

It is GitHub removing the macOS 14 (Sonoma) runner images from GitHub Actions on 2 November 2026. Three labels are affected: macos-14, macos-14-large and macos-14-xlarge.

This follows a published policy, not a one-off decision. The runner-images README says GitHub supports at most two GA (generally available) images and one beta image of each system at a time. When a newer macOS image reaches GA, the oldest label starts its deprecation.

The README describes the process in order: an announcement with a date, scheduled brownouts as the date nears, and then removal. macOS 14 has followed exactly that path, as the diagram shows.

During each brownout, jobs on the three labels fail. Two smaller warnings sit beside that. The changelog says GitHub may reduce macOS 14 capacity before retirement, and the issue warns of longer queue times during peak hours.

When are the brownouts in Indian time?

Each brownout runs from 19:30 IST to 05:30 IST the next morning. GitHub publishes the windows in UTC, the world reference time, and IST (Indian Standard Time) is UTC plus 5 hours 30 minutes. That is exactly when many teams in India push their evening work.

Neither the changelog nor the issue gives a time of day for the removal on 2 November. Assume the labels can stop working from 00:00 UTC on 2 November, which is 05:30 IST. If a brownout is still ahead when you read this, merge your fix before it starts, and a green run during it proves the fix. After 30 October, your branch test is the only proof.

For most pipelines the answer is macos-15. It is the closest image to macOS 14 that is still supported, and it runs on the same kind of Apple-chip machine. If your workflow only says runs-on: macos-14, that is your answer, and you can skip to the chart below.

The bigger labels need care. Larger runners are bigger machines with more CPUs and memory, picked with a -large or -xlarge suffix. The suffixes do not mean the same chip: in GitHub's docs, -large is Intel and -xlarge is Apple. Larger runners also need a GitHub Team or Enterprise Cloud plan and a payment method on file.

If you only need a small Intel machine, the standard labels macos-15-intel and macos-26-intel give you 4 Intel CPUs and 14 GB of memory. You do not need a paid larger runner just to stay on Intel.

A pinned label such as macos-15 always means the same macOS version until GitHub retires it. A floating label such as macos-latest is moved by GitHub to newer versions over time.

Think of a train. A pinned label is like booking one numbered train: same route, same timings, until the railway cancels it. The macos-latest label is like asking for the next fast train to Mumbai, which can be a different train next month.

Here is how the picture maps. The train number is the version in the label. The cancellation notice is the retirement announcement. The next fast train is whatever image GitHub marks as latest GA at the time. Where the picture breaks: even a pinned image changes a little every week, because GitHub updates its tools.

The README sets two promises for floating labels. GitHub announces a move of a -latest label in advance, and the move rolls out over one to two months. During that rollout, some jobs on the same label can land on the old image and some on the new one.

That is why a release build should be pinned. You want the same macOS and the same Xcode on Monday and on Friday. A floating label still has a use, covered later: a nightly job that warns you early about the next version.

Run one text search from the top folder of your repository. It works on macOS, Linux and Git Bash on Windows, and it prints the file, the line number and the line for every match.

grep -rni "macos-14" .github/workflows

The -r searches every file in the folder, -n prints line numbers, and -i ignores letter case, so macOS-14 is found too. We ran it with GNU grep 3.11 on four sample workflows: the iOS app, an Electron app, a Flutter app and one that had already moved.

It found four lines, but one was only a comment saying a job had already moved.

It also missed one job. That job builds its label from a matrix, a list of values GitHub loops over to run the same job several times. The label is written as macos-${{ matrix.ver }}, and GitHub fills in 14 when the job runs. The text macos-14 never appears in the file.

So after the search, read every runs-on line that contains ${{ by eye. For one repository that is enough. Engineers who look after many repositories get a stricter scanner in the second half of this guide.

Because each image ships its own set of Xcode versions, and the sets barely overlap. A job that names an Xcode path that is not on the new image fails at that step.

The table comes from the image READMEs in the runner-images repository, read on 26 October 2026. A simulator runtime is the installed copy of iOS that tests run on, inside a pretend iPhone. Images update weekly, so check the README again on the day you switch.

So the guess resolves like this: that job quietly gets Xcode 16.4, and no iOS 17 simulator is installed. A job that selects Xcode_15.4.app fails even earlier, because that folder does not exist. Three things follow from the table:

• If your workflow never selects Xcode, it silently moves from Xcode 15.4 to 16.4 on macos-15. That is a real compiler upgrade, so expect new warnings and maybe errors.
• If it selects /Applications/Xcode_15.4.app, change it to an installed version such as Xcode_16.4.app or Xcode_26.3.app.
• If your tests name an iOS 17 runtime or an older device such as iPhone 15, neither is installed on macos-15. Use one the README lists, such as iPhone 16 on iOS 18.6.

Which Xcode do App Store uploads need?

Xcode 26 or later. Apple's Upcoming Requirements page says that since 28 April 2026, apps uploaded to App Store Connect must be built with Xcode 26 or later, using a version 26 SDK.

The macos-15 image already has Xcode 26.0.1 to 26.3, so you do not need macOS 26 for this. A job that uploads to TestFlight or the App Store can select /Applications/Xcode_26.3.app on the same macos-15 label.

For the iOS pipeline in our setup, that means two edits on a branch. The label becomes macos-15. The Xcode path becomes Xcode_16.4.app for the build-and-test job, or Xcode_26.3.app for any job that uploads.

Run the changed workflow once on a branch and read two places: the Set up job log and a check step you add. Both show which image and Xcode really ran.

1. 1

   Create a branch

   Make a branch such as move-off-macos-14 so the main branch stays green while you test.

2. 2

   Change the label and Xcode path

   Replace macos-14 with macos-15 in runs-on. Change any Xcode_15.x path to an installed version, as in the last section.

3. 3

   Add a check step

   Add the step from the workflow below that prints the macOS version and the Xcode version.

4. 4

   Push and open the run

   Push the branch, open the Actions tab and open the job. The README says the image version is in the Set up job step log.

5. 5

   Compare with the expected output

   Check the printed versions against the expected output below. Then run your full build and tests on the branch before merging.

6. 6

   Search again

   Run the grep search again. It should print nothing except comments you wrote on purpose.

name: iOS build
on: [push]
jobs:
  build:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v7
      - run: sudo xcode-select -s /Applications/Xcode_16.4.app
      - run: |
          sw_vers -productVersion
          xcodebuild -version

Each line does one thing. The checkout step copies your code onto the runner with actions/checkout@v7. Older versions such as v4 were built for Node 20, the JavaScript engine some actions run on. GitHub removed Node 20 from its runners on 23 September 2026.

The xcode-select command picks which installed Xcode the job uses, and sudo runs it with admin rights.

The sw_vers command prints the macOS version, and xcodebuild -version prints the Xcode version. This file passed actionlint 1.7.12, a checker for workflow files, with no errors. We could not run it on a Mac, so the expected output comes from the macOS 15 README of 26 October 2026.

15.7.9
Xcode 16.4
Build version 16F6

The first line is the macOS version. Any 15.x number is correct, because the image updates weekly and the third part changes. The next two lines must show Xcode 16.4, or the select step did not work.

Use a small script instead of grep. It reads every .yml and .yaml file in .github/workflows, ignores letter case and comments, and also flags Xcode 15 paths and runs-on lines built from expressions.

An expression is anything inside ${{ }}, which GitHub fills in when the job runs. The script needs only Python 3, with no extra packages.

import re
import sys
from pathlib import Path

# Replacement labels from GitHub's 1 October 2026 changelog and issue 13518
SUGGEST = {
    "macos-14": "macos-15 (or macos-26)",
    "macos-14-large": "macos-15-large (Intel)",
    "macos-14-xlarge": "macos-15-xlarge (or macos-26-xlarge)",
}
OLD = re.compile(r"\bmacos-14(?:-large|-xlarge)?\b", re.IGNORECASE)
XCODE15 = re.compile(r"Xcode_15|xcode-version:\s*['\"]?15", re.IGNORECASE)
DYNAMIC = re.compile(r"(runs-on:.*|macos-)\$\{\{", re.IGNORECASE)


def strip_comment(line):
    # A YAML comment starts at a # outside quotes, after a space or at the start
    quote = None
    for i, ch in enumerate(line):
        if ch in "'\"":
            quote = None if quote == ch else (quote or ch)
        elif ch == "#" and quote is None and (i == 0 or line[i - 1] in " \t"):
            return line[:i]
    return line


root = Path(sys.argv[1] if len(sys.argv) > 1 else ".")
files = sorted((root / ".github" / "workflows").glob("*.y*ml"))
found = 0
for f in files:
    for n, line in enumerate(f.read_text(encoding="utf-8").splitlines(), 1):
        code = strip_comment(line)
        for label in OLD.findall(code):
            found += 1
            print(f"{f.name}:{n}: {label} -> try {SUGGEST[label.lower()]}")
        if XCODE15.search(code):
            found += 1
            print(f"{f.name}:{n}: Xcode 15 is not on the macOS 15 or 26 images")
        if DYNAMIC.search(code):
            print(f"{f.name}:{n}: label built from an expression, check by hand")
        if "macos-latest" in code.lower():
            print(f"{f.name}:{n}: macos-latest floats (macOS 26 as of Oct 2026)")
print(f"Scanned {len(files)} files, problems found: {found}")
sys.exit(1 if found else 0)

Save it as find_macos14.py and run python3 find_macos14.py from the repository folder, or pass the folder as an argument. On our four samples, with Python 3.13.17, it printed this:

electron.yaml:9: macos-14 -> try macos-15 (or macos-26)
electron.yaml:9: macos-14-large -> try macos-15-large (Intel)
electron.yaml:10: label built from an expression, check by hand
flutter.yml:5: macos-14-xlarge -> try macos-15-xlarge (or macos-26-xlarge)
flutter.yml:12: label built from an expression, check by hand
flutter.yml:16: macos-latest floats (macOS 26 as of Oct 2026)
ios.yml:5: macos-14 -> try macos-15 (or macos-26)
ios.yml:8: Xcode 15 is not on the macOS 15 or 26 images
Scanned 4 files, problems found: 5

It exits with code 1 when it finds a problem and 0 otherwise, so it can run as a CI step that blocks new macos-14 labels. Expression lines are only printed, so they do not change the exit code.

We also changed only the label in ios.yml and ran it again. It still reported the Xcode 15 path and exited with 1, which is the half-fixed job that grep would pass.

Actionlint keeps its own list of GitHub runner labels. Its 1.7.10 release removed the macOS 13 labels after GitHub had dropped them. So do not expect a warning before 2 November.

The script has limits. It reads one line at a time, so a runs-on label on the next line, or a setup input like xcode: ^15.4, is not flagged. An apostrophe in an unquoted line can confuse its comment check. It also counts macos-14 written anywhere on a line, such as in a run command.

Use macos-15-large if you need a larger Intel machine, or macos-15-intel for a standard one. Moving macos-14-large to macos-15-xlarge changes the chip from Intel to Apple, which is a different build.

This matters most for desktop apps, such as Electron apps, that ship separate Intel and Apple-chip downloads. Some teams build the Intel version on an Intel runner on purpose. Check what your build steps assume before you change the chip.

A quick way to check is to add the command uname -m to your check step. On an Apple-chip Mac it prints arm64, and on an Intel Mac it prints x86_64.

Plan for Intel to end. A GitHub changelog from 19 September 2025 says GitHub will stop supporting Intel on macOS after the macOS 15 image retires in Fall (autumn) 2027. The README also lists macOS 26 Intel labels today. The 2025 notice suggests those end too when macOS 15 retires, but no newer notice confirms it.

Pin macos-15 for builds you ship, run one nightly job on macos-latest as an early warning, and watch GitHub's announcements. That gives you a stable release build and months of notice.

The trade-off is simple. Pinning means you choose when to upgrade, but you must act when GitHub retires the label, as you are doing now. Floating means fewer edits, but your build can change under you during a one to two month rollout.

Expect to repeat this. By the README's policy, the oldest GA label starts deprecation once a newer macOS image reaches GA. As of 26 October 2026, there is no announcement issue for macos-15. The only date we found is the Fall 2027 line in the 2025 changelog.

• Watch the Announcement label in the actions/runner-images repository, where issue 13518 was posted about ten months before removal.
• Keep the scanner as a CI step, and add a pattern for macos-15 when its notice arrives.
• Write the Xcode version into the workflow, so the next person sees what the build depends on.
• Use Xcode 26 for any job that uploads to App Store Connect, even on macos-15.

Treat it as a dependency lifecycle question: a platform you depend on removes a version, with a public schedule. Interviewers want to hear how you find the impact, choose a target and roll out safely.

1. 1

   Name the dependency

   The build depends on a runner image picked by a label. The image bundles the OS and the toolchain, so changing it changes Xcode too.

2. 2

   Read the schedule

   Announcement in January 2026, deprecation from July, brownouts in October, removal on 2 November 2026. Brownouts are deliberate failures meant to surface hidden users.

3. 3

   Find every user

   Scan all repositories, including reusable workflows and labels built from expressions. A text search alone misses some and reports false alarms.

4. 4

   Pick the target

   Pin macos-15 to keep the operating-system change small and keep the chip the same. Use its Xcode 26 for App Store uploads, which Apple has required since April 2026.

5. 5

   Roll out and verify

   Change one pipeline on a branch, print the OS and Xcode versions, run full tests, then merge. Add the scanner as a CI guard.

6. 6

   Prevent the next surprise

   Add a nightly job on macos-latest, follow the announcements, and record the toolchain version in the workflow.