Golden Images

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

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

RunnerHub currently publishes four golden images:

Image Name	Xcode	macOS	Node.js	Ruby	JDK	Status
`runnerhub-xcode-16.3`	16.3	15.4	22	3.3.6	17, 21, 11	Stable
`runnerhub-xcode-16.4`	16.4	15.5	22	3.3.6	17, 21, 11	Stable
`runnerhub-xcode-26.4`	26.4	26.3	24	3.4.7	17, 21, 11, 26	Stable
`runnerhub-xcode-26.5-beta`	26.5 beta	26.3	24	4.0.2	17, 21, 11, 26	Beta (weekly rebuild)

Image Details

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
Android SDK:
- Platforms: android-28 to android-35
- 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
- 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

macOS 15.5 Sequoia + Xcode 16.4

Node.js: 22 (via node@22 Homebrew formula)
Ruby: 3.3.6 (via rbenv)
Java: JDK 17 (default), 21, 11 available
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: 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

macOS 26.3 Tahoe + Xcode 26.4

Node.js: 24 (via node@24 Homebrew formula)
Ruby: 3.4.7 (via rbenv)
Java: JDK 17 (default), 21, 11, 26 available
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: 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

macOS 26.3 Tahoe + Xcode 26.5 beta

Node.js: 24 (via node@24 Homebrew formula)
Ruby: 4.0.2 (via rbenv)
Java: JDK 17 (default), 21, 11, 26 available
Android SDK:
- Platforms: android-28 to android-36, 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, 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

All four images include the following Homebrew packages:

Formulae: swiftlint, swiftformat, swiftgen, xcbeautify, xcodegen, mint, carthage, cmake, wget, imagemagick, jq, yq, gh, rbenv, ruby-build, gradle, ktlint, python3

Casks: android-commandlinetools, google-cloud-cli

Global npm packages: yarn, firebase-tools

Ruby gems: bundler, cocoapods, fastlane, xcpretty

Per-Image Node.js and Ruby Activation

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

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

3.3.6

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

Flutter SDK

Flutter SDK is not pre-installed. Projects must use FVM (Flutter Version Manager) at build time:

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

FVM is pre-installed on all images. Invoke Flutter as fvm flutter …, not bare flutter …. See Flutter documentation.

Image Refresh and Updates

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

The engineering team evaluates the update
A new image config is created (e.g., runnerhub-xcode-16.5.env)
A fresh VM is provisioned, Xcode is installed, and setup.sh is run
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

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.