Images
Every Tuist Runners job starts in a fresh virtual machine booted from a runner image. Your profile chooses the image: the platform, the Xcode version on macOS, and the Ubuntu release on Linux. The VM is discarded when the job ends, so anything a job installs is gone for the next one.
The images follow GitHub-hosted runners where it matters to workflows: the same user, home and workspace paths, ImageOS, passwordless sudo, and the tools most iOS, macOS and Linux workflows expect. They're intentionally smaller than GitHub's, so the differences are listed for each platform below.
Choosing an image#
- Xcode, Apple SDKs or simulators: a macOS profile pinned to the Xcode version your project builds with.
- Docker, Android builds and emulators, or other Linux tooling: a Linux profile on Ubuntu 24.04.
- A dependency that doesn't support Ubuntu 24.04 yet: a Linux profile on Ubuntu 22.04.
On macOS you pick the Xcode, not the image: each Xcode version is its own image, and a profile pinned to 26.4.1 always runs on the image built with Xcode 26.4.1. To run two Xcode versions, create a profile for each.
macOS#
macOS runners are Apple silicon (arm64) virtual machines running macOS 26 Tahoe. A runner's name includes the exact macOS version, for example tuist-macos-26.6-xcode-27.0-8vcpu-24gb-…, and appears in the job's Set up job step.
Xcode#
Each image contains exactly one Xcode, which is selected with xcode-select, so xcodebuild and xcrun use it without a setup step. This is the main difference from GitHub-hosted images, which ship several Xcode versions to switch between at job time. Available versions:
-
27.3-beta -
27.2(default) -
27.1 -
27.0 -
26.6 -
26.5 -
26.4.1 -
26.3 -
26.1.1 -
26.0.1 -
Path. Xcode is at
/Applications/Xcode_<version>.app. For a version with a patch component,/Applications/Xcode_<major>.<minor>.apppoints at the same bundle, soXcode_26.4.appresolves toXcode_26.4.1.app. Workflows that hardcode a GitHub-style path or callxcode-select -swith it keep working. -
Simulators. The iOS, tvOS, watchOS and visionOS simulator runtimes that ship with that Xcode are downloaded into the image, so the first
xcodebuild testdoesn't have to fetch them. -
Metal toolchain. Since Xcode 26, the Metal compiler isn't bundled with Xcode and has to be downloaded separately. Every image includes the Metal toolchain matching its Xcode, installed for the user jobs run as, so
xcrun metaland projects with.metalsources build without runningxcodebuild -downloadComponent MetalToolchain. -
Betas. Beta profiles (for example
27.3-beta) track the latest beta of that release. When Apple ships a new beta, the image is rebuilt and the profile moves to it without a change on your side.
Preinstalled software#
- Apple tooling: Xcode (one per image), simulator runtimes, Metal toolchain,
xcodes,xcbeautify - Swift and iOS tooling: SwiftLint, SwiftFormat, SwiftGen, LicensePlist, Mint, Carthage, CocoaPods, fastlane
- Devices:
libimobiledevice,ideviceinstaller,ios-deploy - Languages and runtimes: Ruby through
rbenv(2.7 and the two latest 3.x releases, the newest as default) with Bundler, Node.js 24 with npm, Yarn and pnpm - Package and version managers: Homebrew, mise
- Version control: Git, Git LFS, Git Credential Manager, GitHub CLI (
gh) - Utilities:
jq,yq,curl,wget,zip/unzip, CMake, GCC, AWS CLI - CI agents: GitHub Actions runner, Buildkite agent, Bitrise agent and CLI, GitLab job executor
- Other: Rosetta 2,
safaridriverenabled
Tool versions come from Homebrew when the image is built, and images are rebuilt regularly. To see the exact version on a runner, print it in a step, for example swiftlint version or xcodebuild -version.
Environment#
- User and paths. Jobs run as
runner, with home/Users/runnerand workspace/Users/runner/work, the same paths as GitHub-hosted runners, so actions that hardcode them work. sudo. Passwordless. The VM belongs to your job alone.- Homebrew. The prefix (
/opt/homebrew) is owned byrunner, sobrew install <formula>works withoutsudo.HOMEBREW_NO_AUTO_UPDATEis set. - Shell. Steps run in a login shell, so Homebrew,
rbenvand Node.js are onPATH.LANGisen_US.UTF-8. ImageOSismacos26, as on GitHub-hosted runners, for setup actions that pick prebuilt binaries by it.- Certificates. Apple's WWDR (G3) and Developer ID (G2) intermediate certificates are in the system trust store for signing and notarization.
- Privacy permissions. Two macOS privacy approvals are granted in advance, as on GitHub-hosted images: scripting Finder through Apple Events, which
create-dmgandosascriptneed, and the iOS Simulator's access to the microphone, which apps recording audio in UI tests need. Permissions inside a simulator, such assimctl privacy, remain your job's responsibility. - Disk. Each job starts with at least 100 GB of free disk space.
Not included#
- The Tuist CLI. Install it in the job, for example with mise, so your project controls the version.
- Other Xcode versions. Use a profile per Xcode version instead of
xcode-select. - Docker. macOS runners have no Docker daemon. Use a Linux profile; see Docker.
- Toolchains GitHub bundles on macOS that iOS builds rarely need, such as Java, the Android SDK, .NET, Rust, Python versions or browsers. Install them in a step with Homebrew, mise or a setup action.
Linux#
Linux runners are x86_64 (amd64) virtual machines on Ubuntu 24.04 or Ubuntu 22.04, chosen by the profile. See Profiles for how to pick a release.
Preinstalled software#
- Build toolchain:
build-essential(GCC, G++, make), autoconf, automake, libtool,pkg-config, CMake, Ninja, m4, bison, flex, gettext - Development headers: OpenSSL, libffi, zlib, bzip2, readline, SQLite, ncurses, libxml2, libxslt, libyaml, libcurl, uuid
- Python: Python 3 with
pipandvenv(the Ubuntu release's version) - Containers: Docker CLI with Buildx and Compose; the daemon runs alongside the job (see Docker)
- Kubernetes:
kubectl, Helm - Android: Android SDK at
/usr/local/lib/android/sdkwith command-line tools, platform-tools, and every platform and build-tools release from API 34 up, licenses accepted - Version control: Git, Git LFS, OpenSSH client, GitHub CLI (
gh) - Database clients: PostgreSQL, MariaDB, Redis (
redis-cli), SQLite - Archives:
tar,zip/unzip,xz,bzip2,p7zip,zstd - Utilities:
curl,wget,jq, ripgrep,fd,tree,less,vim, HTTPie,netcat,dig,ip,ping,file - CI agents: GitHub Actions runner, Buildkite agent, Bitrise agent and CLI, GitLab job executor
Environment#
- User and paths. Jobs run as
runner(UID 1000) with home/home/runner, in thedockergroup, with passwordlesssudo. ImageOSisubuntu24orubuntu22, matching GitHub-hosted runners.- Android.
ANDROID_HOMEandANDROID_SDK_ROOTpoint at the SDK. The emulator isn't preinstalled; see Android emulators. - Locale.
LANGandLC_ALLareC.UTF-8, andDEBIAN_FRONTENDisnoninteractive, sosudo apt-get installdoesn't prompt.
Not included#
The Linux image covers the build basics rather than every language toolchain GitHub preinstalls. Install what your job needs with the usual setup actions (actions/setup-java, actions/setup-node, actions/setup-go, ruby/setup-ruby), with mise, or with apt-get:
- Language runtimes such as Java, Node.js, Go, Ruby, .NET and Rust.
- The Android NDK. Install the version you need with
"$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" "ndk;<version>".ANDROID_NDK_HOMEis left unset so that a build fails clearly instead of pointing at an NDK that isn't there. - Browsers and cloud CLIs other than
kubectl, Helm andgh.
To keep a toolchain between jobs instead of installing it every time, put it on a cache volume.
Image updates#
Images are rebuilt when Apple ships a new Xcode or beta, when the CI agents are updated, and when we change the images themselves. A job always runs on a complete, tested image: new images roll out to the fleet gradually and never change while a job runs.
If a tool your workflow relies on is missing, contact us or ask in the community Slack.