Skip to content
RunnerHub

Golden Images

Overview

Section titled “Overview”

RunnerHub jobs run on ephemeral clones of golden images—pre-built macOS VMs with all development tools pre-installed. You select an image by Xcode version via the environment.xcode field in your pipeline YAML.

Each image is a complete, reproducible snapshot of macOS plus Xcode, Android SDK, Java, Ruby, Node.js, and dozens of build tools. The image is cloned for each job, so no state persists across runs—every job starts clean.

Selecting an Image

Section titled “Selecting an Image”

In your pipeline YAML, set environment.xcode to the desired Xcode version:

jobs:
  build:
    environment:
      xcode: "16.4"  # Uses runnerhub-xcode-16.4
    steps:
      - name: Build
        run: xcodebuild build

Available Images

Section titled “Available Images”

RunnerHub currently publishes four golden images:

Image NameXcodemacOSNode.jsRubyJDK (default)Status
runnerhub-xcode-16.316.315.4223.3.617 (also 21, 11)Stable
runnerhub-xcode-16.416.415.5223.3.1117 (also 21, 11)Stable
runnerhub-xcode-26.426.426.3243.4.921 (also 17, 25, 11)Stable
runnerhub-xcode-26.5-beta26.5 beta26.3244.0.221 (also 17, 25, 11)Beta (weekly rebuild)

Image Details

Section titled “Image Details”

runnerhub-xcode-16.3

Section titled “runnerhub-xcode-16.3”

macOS 15.4 Sequoia + Xcode 16.3

  • Node.js: 22 (via node@22 Homebrew formula)
  • Ruby: 3.3.6 (via rbenv)
  • Java: JDK 17 (default), 21, 11 available
  • Extra simulator runtimes: iOS 18.5 (pre-downloaded at image-build time; iOS 18.4 is the runtime bundled with Xcode 16.3)
  • Android SDK:
    • Platforms: android-28 to android-36
    • Build-tools: 28.0.3, 29.0.2, 30.0.3, 33.0.2, 33.0.3, 34.0.0, 35.0.0, 35.0.1, 36.0.0
    • NDK: 25.1.8937393
    • CMake: 3.22.1, 3.18.1, 3.10.2
  • Pre-installed tools: See Installed Software

Source: golden-images/configs/runnerhub-xcode-16.3.env

runnerhub-xcode-16.4

Section titled “runnerhub-xcode-16.4”

macOS 15.5 Sequoia + Xcode 16.4

  • Node.js: 22 (via node@22 Homebrew formula)
  • Ruby: 3.3.11 (via rbenv)
  • Java: JDK 17 (default), 21, 11 available
  • Extra simulator runtimes: iOS 18.5, iOS 18.6 (pre-downloaded at image-build time)
  • Android SDK:
    • Platforms: android-28 to android-37
    • Build-tools: 28.0.3, 29.0.2, 30.0.3, 33.0.2, 33.0.3, 34.0.0, 35.0.0, 35.0.1, 36.0.0, 36.1.0, 37.0.0
    • NDK: 29.0.13113456, 25.1.8937393
    • CMake: 3.22.1, 3.18.1
  • Pre-installed tools: See Installed Software

Source: golden-images/configs/runnerhub-xcode-16.4.env

runnerhub-xcode-26.4

Section titled “runnerhub-xcode-26.4”

macOS 26.3 Tahoe + Xcode 26.4

  • Node.js: 24 (via node@24 Homebrew formula)
  • Ruby: 3.4.9 (via rbenv)
  • Java: JDK 21 (default), 17, 25, 11 available
  • Extra simulator runtimes: iOS 26.2, iOS 26.5 (pre-downloaded at image-build time)
  • Android SDK:
    • Platforms: android-28 to android-37
    • Build-tools: 28.0.3, 29.0.2, 30.0.3, 33.0.2, 33.0.3, 34.0.0, 35.0.0, 35.0.1, 36.0.0, 36.1.0, 37.0.0
    • NDK: 29.0.14206865, 28.2.13676358, 27.3.13750724, 25.1.8937393
    • CMake: 3.22.1, 3.18.1
  • Pre-installed tools: See Installed Software

Source: golden-images/configs/runnerhub-xcode-26.4.env

runnerhub-xcode-26.5-beta

Section titled “runnerhub-xcode-26.5-beta”

macOS 26.3 Tahoe + Xcode 26.5 beta

  • Node.js: 24 (via node@24 Homebrew formula)
  • Ruby: 4.0.2 (via rbenv)
  • Java: JDK 21 (default), 17, 25, 11 available
  • Extra simulator runtimes: iOS 26.2, iOS 26.4 (pre-downloaded at image-build time)
  • Android SDK:
    • Platforms: android-28 to android-37 (preview)
    • Build-tools: 28.0.3, 29.0.2, 30.0.3, 33.0.2, 33.0.3, 34.0.0, 35.0.0, 35.0.1, 36.0.0, 36.1.0, 37.0.0
    • NDK: 29.0.14206865, 28.2.13676358, 27.3.13750724, 25.1.8937393
    • CMake: 3.22.1, 3.18.1
  • Pre-installed tools: See Installed Software

This image is rebuilt weekly to track the latest Xcode 26.5 beta seed. Tool versions may change between builds.

Source: golden-images/configs/runnerhub-xcode-26.5-beta.env

Common Homebrew Packages

Section titled “Common Homebrew Packages”

All four images include the following Homebrew packages:

Formulae: swiftlint, swiftformat, swiftgen, xcbeautify, xcodes, xcodegen, mint, carthage, cmake, ninja, wget, imagemagick, jq, yq, gh, git-lfs, unxip, rbenv, ruby-build, gradle, maven, kotlin, ktlint, python3

Casks: android-commandlinetools, google-cloud-cli

Global npm packages: yarn, firebase-tools

Ruby gems: bundler, cocoapods, fastlane, xcpretty

Pre-Installed Simulator Runtimes

Section titled “Pre-Installed Simulator Runtimes”

Each image pre-downloads extra iOS simulator runtimes at image-build time via xcodebuild -downloadPlatform, so simulators beyond the single runtime bundled with Xcode are available immediately without an at-build-time download.

ImageBundled runtimeExtra runtimes
runnerhub-xcode-16.3iOS 18.4iOS 18.5
runnerhub-xcode-16.4iOS 18.5iOS 18.6
runnerhub-xcode-26.4iOS 26.4iOS 26.2, iOS 26.5
runnerhub-xcode-26.5-betaiOS 26.5iOS 26.2, iOS 26.4

To verify available runtimes inside a job:

Terminal window
xcrun simctl list runtimes

Per-Image Node.js and Ruby Activation

Section titled “Per-Image Node.js and Ruby Activation”

Node.js

Section titled “Node.js”

Set environment.node in your YAML to activate a specific Node.js version:

jobs:
  build:
    environment:
      xcode: "16.4"
      node: "22.11.0"  # Must match a version available on that image
    steps:
      - name: Verify
        run: node --version

The agent uses nodenv to activate the requested version before running steps.

Ruby

Section titled “Ruby”

Add a .ruby-version file to your repository root:

3.3.11

The agent auto-activates it via rbenv on each job (.zshenv sources eval "$(rbenv init - zsh)").

Flutter SDK

Section titled “Flutter SDK”

Flutter SDK is installed on demand by FVM based on your environment.flutter setting:

jobs:
  build:
    environment:
      xcode: "26.4"
      flutter: "3.19.0"  # FVM will install this version
    steps:
      - name: Build
        run: flutter build ios

FVM is pre-installed on all images and configures PATH at job start. Once the Flutter SDK is installed, use flutter and dart directly (no fvm prefix needed). See Flutter documentation.

Migrating from Xcode 16 to Xcode 26

Section titled “Migrating from Xcode 16 to Xcode 26”

The jump from a runnerhub-xcode-16.x image to a runnerhub-xcode-26.x image is a major OS upgrade (macOS 15 Sequoia → macOS 26 Tahoe). Several breaking changes can affect pipelines:

OpenSSL 1.1 → 3.x ABI break. macOS 26 ships OpenSSL 3.x; macOS 15 shipped 1.1.1w. Builds that link against the system OpenSSL (some Ruby gems, native CocoaPods, custom Node addons) commonly break. If a pod or gem fails to load on 26.x, force a clean rebuild: bundle pristine, pod deintegrate && pod install.

Ruby 3.3 → 3.4/4.0. The 26.4 image defaults to Ruby 3.4.9 (vs 3.3.11 on 16.4); 26.5-beta runs the Ruby 4.0.x preview. Gems with native extensions need rebuilding on the new image; re-run bundle install in a fresh build before relying on a restored gem cache.

Default JDK 17 → 21. The 26.x images now default to JDK 21, matching GitHub’s macos-26 runners. Pipelines that require JDK 17 should set JAVA_HOME explicitly — JDK 17 is still installed alongside 21:

Terminal window
export JAVA_HOME=$(/usr/libexec/java_home -v 17)

Node.js 22 → 24. The 26.x images use node@24; the 16.x images stay on node@22. Lock engines.node in package.json if you need a specific major.

Xcode toolchain (Clang). Clang/LLVM jumps from 17 (Xcode 16.x) to 21 (Xcode 26.x). Code relying on specific clang diagnostics or deprecated-warning suppression may surface new findings.

Image Refresh and Updates

Section titled “Image Refresh and Updates”

Golden images are static snapshots—they do not auto-update. When new tool versions are released:

  1. The engineering team evaluates the update
  2. A new image config is created (e.g., runnerhub-xcode-16.5.env)
  3. A fresh VM is provisioned, Xcode is installed, and setup.sh is run
  4. The image is tested and published as runnerhub-xcode-16.5

Beta images (like 26.5-beta) are rebuilt weekly to track the latest Xcode beta seed.

Troubleshooting

Section titled “Troubleshooting”

Q: I set environment.xcode: "16.2" but it didn’t work. A: Version 16.2 is not published. Use 16.3 or 16.4 instead.

Q: How do I request a new golden image? A: Contact support with the Xcode version and any special tool requirements.

Q: Can I use an older image indefinitely? A: Yes, but note that security patches and tool updates stop when we stop maintaining an image. We recommend upgrading to the latest stable image.

Q: What happens to images when Xcode is deprecated? A: We keep them available but mark them as deprecated. You should migrate to a newer image before deprecation.