Ruby versions on Bitrise

Abstract

Ruby is pre-installed on all Bitrise stacks as several Steps require Ruby to work. You can change the active Ruby version by using a .ruby-version file or by using a Script Step.

Four official Bitrise Steps rely on Ruby to work. These are:

Third-party Steps

Third-party Steps - verified Steps and community Steps - that are not maintained by Bitrise might also use Ruby. Read more about the different Steps: Types of Steps.

Ruby is pre-installed on all our stacks. You can view the actual versions in the system reports. However, you can use a different Ruby version if that's what your app needs.

Managing Ruby versions in your builds

If you need a specific Ruby version, there are two main ways to make sure it will be installed on the virtual machine.

You can use a .ruby-version file. We recommend this method.
You can use a Script Step to override the Ruby version.

Using a .ruby-version file

The best way is to simply include the .ruby-version file in the root of your repository. The file should specify the version you need.

The Run CocoaPods Install Step looks for the .ruby-version file in the root of your repo. When you run the Step, it will install and activate the specified version. We plan to implement this feature for all Bitrise Steps that need Ruby.
Common version manager tools such as Ruby Version Manager, rbenv, or asdf can read the file and automatically activate the specified version.

Setting up a version manager locally

If you set up one of the version manager tools locally, you can have a consistent setup between your local environment and the CI environment.

Using a Script Step

An alternative solution is to add a Script Step to your Workflow to override the default Ruby version. You can declare the version you want in the RUBY_VERSION Environment Variable and then use that Env Var with either rbenv or asdf.

Best practice: using asdf

Using asdf commands is the recommended way to manually switch Ruby versions in a Script Step.

     - script:
        title: Activate correct Ruby version
        inputs:
        - content: |-
            #!/bin/bash
            set -ex
            RUBY_VERSION=3.2.2
            asdf install ruby $RUBY_VERSION
            asdf global ruby $RUBY_VERSION

Supported Ruby versions

Before changing the Ruby version, make sure that the necessary tools support the version you need.

Fastlane supports Ruby 3 which means the Deploy to App Store Connect with Deliver and the fastlane Steps definitely support Ruby 3.
The recent versions of CocoaPods support Ruby 3. However, older legacy gems in your Gemfile or pods in your Podfile might not be compatible. Generally, we recommend always updating gems and pods to the latest version, and testing a Ruby version change in a local environment first.

In this section:

app