Using Custom Ruby Versions in Xcode Cloud
This page has been translated by machine translation. View original
Xcode Cloud is a convenient CI/CD service, but there's an issue with the Ruby version pre-installed in the build environment. Specifically, it uses Ruby 2.6 series, which has compatibility differences with the Ruby 3 series commonly used today.
Recently, I adopted Arkana for handling confidential information in iOS apps. Arkana is a gem that generates obfuscated Swift code from .env files or environment variables, allowing app secrets to be handled separately from code. In this article, I introduced how I used Arkana v1.4.0 because Xcode Cloud runs Ruby 2.6.
To use the latest version of Arkana, Ruby version 2.7.0 or higher is required.
While Apple may update the Ruby in their runner environment in the future, developers currently need to handle this issue themselves. This article explains how to use any Ruby version in Xcode Cloud using the ci_post_clone.sh script.
Installing Custom Ruby in Xcode Cloud
Xcode Cloud has a mechanism called ci_post_clone.sh that allows running custom scripts after repository checkout. We can use this to install and configure a newer Ruby.
- Create a
ci_scriptsdirectory in the project root - Place
ci_post_clone.shinside it - Grant execution permission with
chmod +x ci_scripts/ci_post_clone.shand commit to Git
Xcode Cloud executes this script immediately after cloning the repository.
Upgrading to Ruby 3.x (e.g., 3.2.1) makes it easier to adapt to additional gems in the future. Here's an example script to install Ruby 3.2.1 in ci_post_clone.sh:
#!/bin/zsh
set -euo pipefail
cd "$CI_PRIMARY_REPOSITORY_PATH"
# Install Bundler in user space to avoid write permission errors
export GEM_HOME="$HOME/.gem"
# Install rbenv
brew install rbenv ruby-build
eval "$(rbenv init -)"
# Install required Ruby version (e.g., 3.2.1)
rbenv install 3.2.1
rbenv global 3.2.1
# Check which Ruby is being used
echo "🔎 Ruby executable: $(which ruby)"
echo "🔎 Ruby: $(ruby -v)"
echo "🔎 RubyGems: $(gem --version)"
# Install Bundler (match version with BUNDLED WITH in Gemfile.lock)
BUNDLER_VERSION="2.4.22"
gem install bundler -v "$BUNDLER_VERSION" --no-document --quiet
bundle install --quiet
# Generate ArkanaKeys package
bundle exec ruby -e "puts '🔎 Arkana version: ' + Gem.loaded_specs['arkana'].version.to_s"
bundle exec arkana
The build log after executing ci_post_clone.sh confirms that Ruby 3.2.1 is being used:
Impact on Build Time
The biggest drawback of installing a custom Ruby is increased build time. Since Xcode Cloud runners are ephemeral environments, the installation process occurs every time without caching.
Depending on project dependencies, build times typically increase by about 4-6 minutes. In my project, a normal 15-minute build extended to about 20 minutes and 30 seconds. With Xcode Cloud's free plan limited to 25 hours per month, this overhead should be considered (reducing possible builds from 100 to 70 per month).
Summary
- It's possible to install custom Ruby versions in Xcode Cloud
- For time-billed CI/CD services, increased build times directly impact costs
Due to the build time increase, I decided to continue using Arkana 1.4.0 for now. If Arkana were distributed as a Homebrew Formula, the time loss in CI would be eliminated. Issue #44 has been filed for this, but unfortunately, it's stalled due to dependency issues. I'll continue monitoring the situation.
Related Articles
I've covered how to build existing iOS apps with Xcode Cloud in the following article:
