Moving Old GitHub Actions Workflows Off Retired macOS Runners

name: iOS Build

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: macos-14

    steps:
      - name: Checkout source
        uses: actions/checkout@v4

      - name: Build application
        run: swift build

grep -RInE 'macos-14(-large|-xlarge)?' .github/workflows

uname -m

xcodebuild -version

Some dependencies may require updates to support a newer operating system or processor architecture.

Updating the GitHub Actions Workflow

After selecting a replacement runner, update the runs-on property.

For example, if your application supports macOS 26 and Apple Silicon, the updated workflow could look like this:

name: iOS Build

on:
  push:
    branches:
      - main

  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: macos-26

    steps:
      - name: Checkout source
        uses: actions/checkout@v4

      - name: Check environment
        run: |
          sw_vers
          uname -m
          xcodebuild -version
          swift --version

      - name: Build application
        run: swift build

      - name: Run tests
        run: swift test

The main change is:

runs-on: macos-26

The additional commands display the operating system, processor architecture, Xcode version, and Swift version.

If your project still requires macOS 15, you can use:

runs-on: macos-15

For a project that requires an Intel environment, use an appropriate Intel runner label:

runs-on: macos-26-intel

The example uses Swift Package Manager. If you are working with an Xcode application project, use the appropriate xcodebuild commands for your project scheme and simulator destination.

Testing the Updated Workflow

Changing the runner label is only the first part of the migration. You should run the complete build and test process before merging the changes.

Verify the runner environment

Add a step to display the environment information:

- name: Verify environment
  run: |
    sw_vers
    uname -m
    xcodebuild -version
    swift --version

This helps identify unexpected differences between runner images.

Check available simulators

iOS applications often depend on simulator versions for automated testing.

Use the following command to list available simulators:

xcrun simctl list devices available

If your workflow uses a specific simulator, confirm that the device and runtime are installed.

For example:

xcodebuild test \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 17'

The simulator name is only an example. Use a destination available on the selected runner.

Build and test the application

Run the same commands used in your existing CI pipeline.

For an Xcode project, this might include:

xcodebuild build \
  -scheme MyApp \
  -destination 'generic/platform=iOS'

You should also run unit tests and any UI tests included in your project.

Check the generated build artifacts before considering the migration complete.

Supporting Intel and Apple Silicon With a Build Matrix

Some teams maintain libraries or applications that need to work on both Intel and Apple Silicon environments.

GitHub Actions provides a matrix strategy for running the same workflow on multiple runners.

name: Cross Architecture Build

on:
  push:
    branches:
      - main

jobs:
  build:
    strategy:
      matrix:
        runner:
          - macos-26
          - macos-26-intel

    runs-on: ${{ matrix.runner }}

    steps:
      - name: Checkout source
        uses: actions/checkout@v4

      - name: Check architecture
        run: uname -m

      - name: Build
        run: swift build

      - name: Test
        run: swift test

GitHub creates a separate job for each runner in the matrix.

This approach is useful when developing SDKs, reusable frameworks, or applications that support multiple processor architectures.

However, it is not necessary for every project. Running multiple jobs increases build time and can increase GitHub Actions usage. Use a matrix when testing across architectures is part of your application requirements.

Common Migration Problems

A runner migration can expose issues that were not visible in the previous environment.

Problem	What to check
Build fails after migration	Check Xcode and Swift versions
Framework cannot be linked	Verify supported processor architectures
Simulator tests fail	Check installed simulator runtimes
Build script cannot find a tool	Verify tool installation and paths
Dependency installation fails	Check package compatibility
Workflow starts but tests fail	Review the complete build and test logs

One mistake is replacing a specific runner label with macos-latest without testing the application.

The macos-latest label points to the latest supported macOS image. Its underlying environment can change as GitHub updates its runner images.

For predictable builds, use a specific supported macOS label when your project depends on a known environment.

Best Practices for Future Runner Updates

Runner retirement should be part of regular CI/CD maintenance.

A few practices can make future migrations easier:

• Keep a list of runner labels used across your repositories.
• Review GitHub Actions runner image announcements.
• Test new runner images before changing production workflows.
• Record the macOS, Xcode, Swift, and architecture versions used by important builds.
• Document tools that your build scripts require.
• Keep dependencies updated.
• Avoid relying on undocumented tools installed on hosted runners.
• Update shared reusable workflows when changing runner configurations.

These practices help development teams identify upcoming changes before they affect application builds.

Summary

GitHub's macOS 14 runner retirement affects workflows that use macos-14, macos-14-large, and macos-14-xlarge.

To migrate, first search your repositories for the retired labels. Then select a supported replacement based on your Xcode requirements, processor architecture, simulator availability, and third-party dependencies.

Update the runs-on property and test the complete build and test process. For projects supporting both Intel and Apple Silicon, consider using a GitHub Actions matrix.

Keeping runner configurations documented and reviewing GitHub's runner image announcements can help prevent unexpected CI/CD failures during future migrations.