Symptom: GitHub Actions jobs stop receiving a macOS-14 Runner, or start on a replacement image and fail later in the pipeline.
Fastest fix: Update the retired label to a currently supported Runner that matches your project’s architecture, then validate Xcode, tests, artifacts, and signing separately. GitHub Actions macOS-14 retirement CI troubleshooting is not complete just because the job starts again.
For IT leaders: You need to identify which iOS/macOS workflows are affected and who owns each repair.
For platform engineers: You need to isolate runner assignment, architecture, and toolchain failures.
For release owners: You need evidence that tests, signing, and publication work before reopening a release gate.
Last updated November 15, 2026. Retirement status checked against GitHub’s macOS-14 Runner retirement announcement and the current GitHub-hosted Runner image inventory.
SECTION 01What the macOS-14 retirement changes—and what it does not
GitHub’s announcement marks the macOS-14 hosted Runner image as retired. It names the affected labels as macos-14, macos-14-large, and macos-14-xlarge. Check the announcement and current Runner inventory before editing workflows: available labels and image contents can change, so do not treat an old migration note or a label copied from another repository as proof that a Runner is still available.
Retirement explains why a workflow that requests an affected label may no longer be assigned a Runner. It does not, by itself, explain every later failure. A job can be assigned successfully and then fail because its binaries require a different architecture, its Xcode selection changed, a test expectation depends on the old image, or a signing credential is missing.
Use the job’s first failing step to classify the incident. A job that never starts points toward label, scheduling, or policy checks. A job that starts and fails during setup, compilation, testing, archiving, or upload needs evidence from that stage. GitHub’s workflow troubleshooting guide is a useful companion for separating workflow configuration errors from environment failures.
| Option | Best fit | Key checks | Main trade-off |
|---|---|---|---|
| Supported GitHub-hosted macOS Runner | The project can use an available image and its architecture, tools, and network access meet the workflow’s needs | Confirm the exact runs-on label, actual architecture, Xcode/SDK selection, and required tools |
Less host maintenance for your team, but the image and its contents are managed outside your repository |
| Self-hosted Mac Runner | A verified workflow requirement cannot be met by the hosted options, such as a required host condition or controlled network access | Confirm host ownership, patching, runner registration, credentials, capacity, and recovery responsibility | More control over the host environment, with ongoing operations and security work assigned to your team |
| Remote Mac host | You need access to a Mac host for a defined workload and are evaluating a managed host instead of operating hardware directly | Validate the real workload, access method, environment controls, delivery terms, and service details against current documentation | Avoids treating a label change as a fix, but suitability depends on the service’s documented capabilities and your operational requirements |
The table is a routing aid, not a claim that one option is universally better. Do not decide to self-host because a single job failed on a new image. First establish whether the failure is repeatable and tied to a requirement that the hosted environment cannot satisfy.
SECTION 021. No Runner picks up the job: verify label and scheduling
Failure signal: The job remains queued, reports that no matching Runner is available, or stops being assigned after the workflow still requests a macOS-14 label.
Start with the workflow definition for the failed job, including reusable workflows and any matrix that supplies runs-on. Search the repository for all affected labels, not only the workflow file named in the first error. A shared workflow, composite action, or generated matrix may still pass a retired label to the job.
Then compare the requested label with the retirement notice and the current hosted Runner inventory. The retirement announcement identifies macos-14, macos-14-large, and macos-14-xlarge as affected. Do not assume that changing the string to a nearby label is sufficient: verify that the replacement is currently listed and suitable for the workload.
If the label is valid, continue with scheduling checks instead of repeatedly editing runs-on. Review the job’s runner assignment details, repository and organization policies, required labels, and any workflow constraints. For self-hosted jobs, also confirm that an eligible Runner is online and has every label the job requests. GitHub’s Runner image inventory is the source for hosted image availability; use the self-hosted Runner workflow documentation if the job is intended for your own host.
Evidence to retain: the workflow revision, resolved runs-on value, job queue or assignment details, and the current official label listing. That record lets you distinguish a stale workflow reference from a broader scheduling or policy problem.
Do not diagnose a retired label from a screenshot alone. Capture the workflow revision and the resolved job configuration; a reusable workflow or matrix can hide the actual label.
SECTION 032. The replacement Runner starts, but architecture-bound dependencies fail
Failure signal: The job is assigned, but dependency installation or compilation fails with an executable-format error, a missing binary, an incompatible package, or a tool that cannot run on the selected host.
Record the Runner architecture from inside the job and preserve the dependency installation output. GitHub exposes Runner context values such as operating system and architecture; use the official Runner context reference to select the relevant values. Logging the value from the actual job is more reliable than inferring architecture from the runs-on string.
Next, inspect the first failing dependency rather than changing several build settings at once. Check whether your lockfile installs a prebuilt binary, whether a script downloads an architecture-specific tool, and whether internal packages publish builds for the replacement architecture. Compare the dependency logs with a successful run, if one is available, and use the same commit when testing a proposed fix.
A label change selects an environment; it does not rewrite dependencies or migrate binaries. If an old job depended on Intel-only tooling, establish whether that tool has a compatible build or whether the workflow has to run on a host with the required architecture. Do not call this an Xcode failure until the dependency and architecture evidence supports that diagnosis.
Evidence to retain: the Runner architecture value, dependency versions, installation logs, and the exact step that first fails. If the same dependency fails before Xcode runs, changing Xcode selection is unlikely to resolve the underlying issue.
SECTION 043. Xcode or SDK drift looks like an application regression
Failure signal: The job runs and dependencies install, but compilation, simulator setup, or a script that calls Xcode fails after the image change.
Do not use the workflow label as proof of which Xcode is active. At the point where the job begins, log the selected developer directory, Xcode version, SDK version, and simulator runtime relevant to the failing step. Compare those values with GitHub’s macOS-15 Runner image software inventory if macOS-15 is the candidate image. Recheck the inventory when investigating: image contents can be updated.
Also inspect the workflow for implicit tool selection. A job may use whichever Xcode is selected by the image unless the workflow sets the developer directory itself. Search for xcode-select, scripts that assume a fixed path, and build settings that name a specific SDK. Apple’s Command Line Tools documentation helps distinguish command-line tool installation and selection from the full Xcode environment.
Run the failing command on the same commit with the toolchain values recorded in the log. If the compile command changes behavior only when the active Xcode or SDK changes, treat that as toolchain drift first. If those values match a known-good run, inspect source changes and build configuration instead.
Evidence to retain: the commit SHA, active developer directory, Xcode and SDK versions, simulator runtime where relevant, and the first failing compiler or test command. This gives you a reproducible comparison instead of a guess based on image names.
SECTION 054. Compilation passes, but tests or artifact checks fail
Failure signal: The build completes, but unit tests, simulator tests, archive validation, or downstream artifact checks fail.
Treat each stage as a separate gate. A successful compile proves only that the relevant target compiled; it does not prove that the test suite ran, that the archive is usable, or that a release artifact passed downstream validation.
First, locate the earliest failing stage
Run or inspect the pipeline in this order:
- Dependency resolution and environment setup.
- Compilation of the intended app or framework targets.
- Unit tests.
- Simulator tests, if the workflow uses them.
- Archive creation and artifact inspection.
- Downstream upload or release acceptance.
For each stage, capture the exit status and relevant log. If tests fail, record which test target and simulator runtime were selected. If archive validation fails, inspect the archive’s identity and contents rather than relying on the build command’s success message.
Compare the workflow’s environment variables and scripts with the new Runner. Look for assumptions about temporary paths, available tools, simulator names, locale, or default Xcode selection. Change one assumption at a time, then rerun the same commit. This makes it possible to attribute a repaired test to a specific change instead of accumulating unrelated edits.
A practical scenario: the replacement Runner receives the job, the application compiles, and a simulator test fails before the archive step. That is evidence against a queueing problem and points to the test environment or test behavior. If the tests pass but archive inspection fails, keep the investigation at the artifact gate; do not label the whole pipeline “fixed” because compilation passed.
Evidence to retain: logs for each gate, test results, archive validation output, and the artifact produced from the tested commit. Store them together so the release owner can verify that the repaired run produced the expected output.
SECTION 065. Signing or publication fails: check credentials independently
Failure signal: Compilation, tests, or archiving succeeds, but code signing, export, upload, or release publication fails.
A Runner image change can expose environment assumptions, but it does not prove that the image retirement caused a signing failure. Check the signing chain independently:
- Confirm that the workflow receives the expected secret or credential reference.
- Verify that the signing identity and provisioning profile are available to the job.
- Check Keychain creation, unlock, import, and cleanup steps in the job log.
- Confirm that the profile and identity match the bundle identifier and intended distribution method.
- Inspect upload or publication responses separately from local archive creation.
Review when credentials are installed and which job can access them. A successful archive on a non-release job does not prove that the production signing or publishing job has the same permissions. Likewise, a signing step that runs successfully does not prove that the uploaded artifact was accepted.
Use a controlled release test or a safe validation path that exercises the same credential scope and signing configuration. Keep the commit, archive identity, signing output, and publication result together. If the replacement environment cannot access a required credential or network resource, record the exact boundary and compare supported alternatives; do not broaden secret access simply to make the run green.
The release gate should reopen only when the intended workflow has demonstrated compilation, required tests, signing, and the relevant publication checks. A green build is one piece of evidence, not an end-to-end release acceptance.
SECTION 076. When does a self-hosted or remote Mac make sense?
A self-hosted or remote Mac becomes a serious option when a reproducible workflow requirement cannot be met by the currently supported hosted Runners. Examples include a required architecture, a tool unavailable in the hosted image, a network boundary, or a signing setup that your team cannot safely use on the available hosted environment. These are conditions to verify, not automatic reasons to move.
Before deciding, write down the requirement and the evidence that proves it:
- What exact job and commit demonstrate the limitation?
- Which architecture, tool, network route, or credential boundary is required?
- Does the current hosted Runner inventory show a suitable alternative?
- Can you isolate the workload and restrict who can alter or access its credentials?
- Who owns host updates, Runner health, capacity, and incident recovery?
GitHub’s self-hosted Runner workflow guide explains how a workflow can target self-hosted Runners. That choice also transfers host operations to your team, so include maintenance, access control, and recovery ownership in the decision. Do not present self-hosting as a GitHub requirement; it is an option when your evidence shows a hosted constraint.
If you are comparing a managed Mac host with operating a machine yourself, verify current service details directly rather than assuming a particular configuration, region, access method, recovery time, or lease term. MACNOX publishes its available Mac options and pricing; check the page for the details it actually discloses, then test a representative workflow before relying on the host for release work.
SECTION 08FAQ
Why is a GitHub Actions job still queued after macOS-14 retirement?
Check the resolved runs-on label in the failed job, including values passed through reusable workflows or a matrix. The retirement notice lists macos-14, macos-14-large, and macos-14-xlarge as affected. If the workflow no longer requests one of them, inspect scheduling eligibility and organization policies before concluding that the new label is invalid.
What should I inspect when an iOS build fails after switching to macOS-15?
Start with the actual Runner architecture and dependency installation logs, then record the active Xcode and SDK. A switch to macOS-15 does not automatically make architecture-specific tools compatible or preserve the old toolchain selection. Rerun the same commit and identify the earliest failing stage before editing build settings, dependencies, and test configuration together.
How do I confirm which Xcode a GitHub Actions macOS Runner used?
Log the active developer directory and Xcode version from inside the job, then record the SDK and simulator runtime used by the relevant step. Compare those values with the current official image inventory. The workflow’s runs-on label identifies a Runner image family, not necessarily the exact Xcode selection your build command used.
When should we move to a self-hosted Mac Runner?
Move only when a real workflow demonstrates a requirement that the supported hosted options cannot meet, such as a necessary architecture, network route, or host condition. Then assign owners for patching, Runner registration, credential isolation, capacity, and recovery. If the issue is only a stale label or an unverified Xcode assumption, fix and retest that first.
Is macOS-26 Runner automatically the right replacement?
No. Treat macOS-26 as a candidate only if the current GitHub Runner inventory lists the label and its architecture and tools satisfy your project. Verify it with the same workflow and commit you use to assess other options. Do not infer availability, tool versions, or compatibility from the label alone; the current image documentation is the authoritative check.
If your current path is to keep moving labels until a job turns green, you still lack proof that the team can build, test, sign, and publish reliably. Hosted Runners avoid operating a Mac host, but may not meet a verified architecture, toolchain, network, or credential requirement. A self-managed Mac offers more control, but makes your team responsible for host maintenance, Runner health, and recovery.
If the evidence shows that your workflow needs a controllable macOS host, compare the real workload against MACNOX’s published options and terms rather than assuming a particular setup. You can review the available Mac rental options, then validate the access and operating requirements against the information shown before moving a release job.
SECTION 09FAQ
Why does a GitHub Actions job stay queued after macOS-14 retirement?
Check the workflow’s `runs-on` value and the job’s runner assignment details before changing anything else. GitHub’s retirement notice lists `macos-14`, `macos-14-large`, and `macos-14-xlarge` as affected labels. If the job still requests one of them, update it to a currently supported label that meets your project’s requirements. If it already uses a valid label, investigate capacity, organization policies, and workflow constraints.
What should I check when an iOS build fails after changing from macOS-14 to macOS-15?
First separate runner selection from build compatibility. Record the actual runner architecture and installed tools, then check whether dependencies include architecture-specific binaries or scripts. Next, verify the selected Xcode and SDK, and rerun the failing build on the same commit. A new image does not automatically migrate Intel-only dependencies or preserve the old toolchain selection.
Where can I verify the Xcode version on a GitHub Actions macOS Runner?
Use the job log, not the workflow label alone. Print the selected developer directory and Xcode version from inside the job, and record the SDK and simulator runtime used by the failing step. Compare those results with GitHub’s current runner image software inventory. Keep the evidence with the commit SHA so you can distinguish image changes from application changes.
When should a team move from hosted runners to a self-hosted Mac Runner?
Consider a self-hosted Mac only after a real workflow shows that a required architecture, tool, network route, device connection, or signing boundary cannot be met by the current hosted options. Then account for host provisioning, patching, runner updates, credential isolation, capacity, and recovery ownership. A different label alone is not evidence that you need to operate your own host.