GitHub Actions Xcode 27 Runner: YAML and Migration Checklist

GitHub Actions now supports an Xcode 27 runner image in public preview. For a GitHub-hosted Apple Silicon job, change runs-on to xcode-27; use xcode-27-xlarge when that larger runner is available to you. The image is ARM64-only, is not supported on Intel runners, and may contain different tool versions from earlier macOS images.

Copy-paste Xcode 27 GitHub Actions workflow

Start with this small validation job before changing a production signing or release workflow:

name: Xcode 27 validation

on:
  workflow_dispatch:
  pull_request:

jobs:
  validate:
    runs-on: xcode-27
    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Show runner and Xcode details
        run: |
          uname -m
          xcodebuild -version
          swift --version

      - name: Build and test Swift package
        run: swift test

Remove the swift test step if the repository is not a Swift package. For an Xcode project or workspace, replace it with the project’s existing xcodebuild command rather than guessing its scheme, destination or signing configuration.

Xcode 27 runner labels

Workflow label	Use	Important constraint
xcode-27	Standard GitHub-hosted Xcode 27 image	ARM64 only; public preview
xcode-27-xlarge	Larger Xcode 27 runner	ARM64 only; availability can depend on your GitHub setup

GitHub’s announcement lists both labels. It also says the image does not support Intel runners, so do not treat this as a drop-in x86 migration.

Safe migration checklist

1. Create a separate validation job. Keep the current release job unchanged until Xcode 27 passes.
2. Pin the new label. Use xcode-27, not a general macos-latest label, when the purpose is Xcode 27 compatibility testing.
3. Print tool versions. Record xcodebuild -version, swift --version and uname -m in the log.
4. Check the installed image. Compare required tools and versions against the GitHub Actions runner-images repository.
5. Test dependencies on ARM64. Review binary frameworks, command-line tools, build scripts and package plugins that may assume Intel architecture.
6. Run build and unit tests first. Then add UI tests, archives, signing and uploads one stage at a time.
7. Inspect available simulators. Run xcrun simctl list devices available before hard-coding a simulator destination.
8. Keep signing material in GitHub secrets. Do not place certificates, profiles or passwords in workflow YAML.
9. Retain a rollback path. Keep the previous runner label in the release workflow until the preview image is stable for your project.

Test an Xcode project or workspace

First list the schemes and available destinations:

      - name: Inspect project and simulators
        run: |
          xcodebuild -list -project YourApp.xcodeproj
          xcrun simctl list devices available

Then adapt your existing test command. The placeholders below are intentional because scheme and simulator names are project-specific:

xcodebuild test \
  -workspace YourApp.xcworkspace \
  -scheme "YOUR_SCHEME" \
  -destination "platform=iOS Simulator,name=YOUR_AVAILABLE_SIMULATOR" \
  CODE_SIGNING_ALLOWED=NO

CODE_SIGNING_ALLOWED=NO can be useful for a simulator-only validation job, but it is not a substitute for testing the real signing and archive process used by your release pipeline.

What changed in GitHub’s macOS image model?

Alongside the preview, GitHub announced a new support model: macOS runner images are based on a major Xcode version rather than the underlying operating-system version, with one major Xcode version supported per image. The practical benefit is a clearer relationship between the workflow label and the toolchain the job is intended to use.

This does not mean every old workflow will behave identically. GitHub explicitly warns that the Xcode 27 image includes different tools and tool versions than earlier images. A successful compile is therefore only the first check; dependency tooling, simulators, scripts, test behavior and signing should also be verified.

ARM64 compatibility checks

Add a temporary diagnostic step if a job worked on an Intel runner but fails on the Xcode 27 image:

      - name: ARM64 compatibility diagnostics
        run: |
          echo "Architecture: $(uname -m)"
          file "path/to/your/binary" || true
          which ruby || true
          which python3 || true
          which node || true

Replace the sample binary path with a real vendored executable or framework. A failure can come from an Intel-only binary, a changed preinstalled tool version, a simulator assumption or a build script that uses an architecture-specific path.

Code signing reminder

GitHub’s signing documentation recommends storing the signing certificate, certificate password, provisioning profile and temporary keychain password as GitHub secrets. GitHub-hosted runner virtual machines are destroyed after a job, but secrets should still be scoped carefully and never printed to logs. Follow the official Apple certificate installation guide when adding a signed archive job.

Common migration problems

The job says no runner matches xcode-27

Confirm the label is typed exactly and check GitHub’s current announcement and runner-image status. The feature is a public preview, and the -xlarge option may not be provisioned the same way as the standard hosted runner in every account setup.

A dependency fails only on Xcode 27

Check whether it distributes an Intel-only executable or binary framework. Also compare its supported Swift/Xcode versions and inspect the exact versions installed on the runner image.

The requested simulator is missing

Do not assume the new image has the same simulator set as an older image. Print xcrun simctl list devices available, then choose a destination that actually exists.

The app builds but signing fails

Keep unsigned validation separate from release signing. Recheck the certificate, provisioning profile, bundle identifier, entitlements and secret names against the existing working release job.

FAQ

Is the GitHub Actions Xcode 27 image generally available?

No. GitHub announced it as a public preview on July 16, 2026.

What is the GitHub Actions runner label for Xcode 27?

Use xcode-27 for the standard image or xcode-27-xlarge for the listed larger option.

Does the Xcode 27 runner support Intel?

No. GitHub says the image is available only on ARM64 macOS runners and is not supported on Intel runners.

Should I immediately replace my production runner?

A safer approach is to add a parallel validation job, compare its results, and migrate the release workflow only after builds, tests, dependencies and signing all pass.

Sources

• GitHub Changelog: Xcode 27 runner image now in public preview
• GitHub Actions runner-images repository
• GitHub Docs: Installing an Apple certificate on macOS runners

Last checked: July 16, 2026. Preview labels, installed software and availability can change; verify GitHub’s live documentation before modifying a production pipeline.