Repository files navigation

This action downloads a prebuilt ruby and adds it to thePATH.

It is very efficient and takes about 5 seconds to download, extract and add the given Ruby to thePATH.No extra packages need to be installed.

Important: Preferruby/setup-ruby@v1.If you pin to a commit or release, only the Ruby versions available at the time of the commitwill be available, and you will need to update it to use newer Ruby versions, seeVersioning.

This action currently supports these versions of MRI, JRuby and TruffleRuby:

ruby-debug is the same asruby-head but with assertions enabled (-DRUBY_DEBUG=1).

ruby-asan is the same asruby-head but with AddressSanitizer (ASan) enabled, helpful for finding memory issues in native extensions.Native extensions are automatically compiled with AddressSanitizer when usingruby-asan.ruby-asan is currently only available onubuntu-24.04.

ruby-3.4-asan is similar toruby-asan but built from the latest stable 3.4 release tag.Likeruby-asan, it's currently only available onubuntu-24.04.

Regarding Windows ruby master builds,mingw is a MSYS2/MinGW build,head &ucrt are MSYS2/UCRT64builds, andmswin is a MSVC/VS 2022 build.

Preview and RC versions of Ruby might be available too on Ubuntu and macOS (not on Windows).However, it is recommended to test againstruby-head rather than previews,as it provides more useful feedback for the Ruby core team and for upcoming changes.

Only release versions published byRubyInstallerare available on Windows. Due to that, Ruby 2.2 resolves to 2.2.6 on Windows and 2.2.10on other platforms. Ruby 2.3 on Windows only has builds for 2.3.0, 2.3.1 and 2.3.3.

Note that Ruby ≤ 2.4 and the OpenSSL version it needs (1.0.2) are both end-of-life,which means Ruby ≤ 2.4 is unmaintained and considered insecure.

The action works on theseGitHub-hosted runners images. Runner images not listed below are not supported yet.$OS-latest just alias to one of these images.

Not all combinations of runner images and versions are supported.The list of available Ruby versions can be seen inruby-builder-versions.json for Ubuntu and macOS(although some combinations are not available, seethe full list)and inwindows-versions.json for Windows.

The prebuilt releases are generated byruby-builderand on Windows byRubyInstaller2.Themingw,ucrt andmswin builds are generated byruby-loco.ruby-head is generated byruby-dev-builder,jruby-head is generated byjruby-dev-builder,truffleruby-head andtruffleruby+graalvm-head are generated bytruffleruby-dev-builder.

name:My workflowon:[push, pull_request]jobs:test:runs-on:ubuntu-lateststeps:    -uses:actions/checkout@v4    -uses:ruby/setup-ruby@v1with:ruby-version:'3.3'# Not needed with a .ruby-version, .tool-versions or mise.tomlbundler-cache:true# runs 'bundle install' and caches installed gems automatically    -run:bundle exec rake

This matrix tests all stable releases andhead versions of MRI, JRuby and TruffleRuby on Ubuntu and macOS.

name:My workflowon:[push, pull_request]jobs:test:strategy:fail-fast:falsematrix:os:[ubuntu-latest, macos-latest]# Due to https://github.com/actions/runner/issues/849, we have to use quotes for '3.0'ruby:['2.7', '3.0', '3.1', '3.2', '3.3', head, jruby, jruby-head, truffleruby, truffleruby-head]runs-on:${{ matrix.os }}steps:    -uses:actions/checkout@v4    -uses:ruby/setup-ruby@v1with:ruby-version:${{ matrix.ruby }}bundler-cache:true# runs 'bundle install' and caches installed gems automatically    -run:bundle exec rake

name:My workflowon:[push, pull_request]jobs:test:strategy:fail-fast:falsematrix:gemfile:[ rails7, rails8 ]runs-on:ubuntu-latestenv:# $BUNDLE_GEMFILE must be set at the job level, so it is set for all stepsBUNDLE_GEMFILE:${{ github.workspace }}/gemfiles/${{ matrix.gemfile }}.gemfilesteps:      -uses:actions/checkout@v4      -uses:ruby/setup-ruby@v1with:ruby-version:'3.3'bundler-cache:true# runs 'bundle install' and caches installed gems automatically      -run:bundle exec rake

See the GitHub Actions documentation for more details about theworkflow syntaxand thecondition and expression syntax.

• engine-version likeruby-2.6.5 andtruffleruby-19.3.0
• short version like'2.6', automatically using the latest release matching that version (2.6.10)
• version only like'2.6.5', assumes MRI for the engine
• engine only likeruby andtruffleruby, uses the latest stable release of that implementation
• .ruby-version reads from the project's.ruby-version file
• .tool-versions reads from the project's.tool-versions file
• mise.toml reads from the project'smise.toml file
• If theruby-version input is not specified,.ruby-version is tried first, followed by.tool-versions, followed bymise.toml

Theworking-directory input can be set to resolve.ruby-version,.tool-versions,mise.toml andGemfile.lockif they are not at the root of the repository, seeaction.yml for details.

By default, the default RubyGems version that comes with each Ruby is used.However, users can optionally customize the RubyGems version that they want bysetting therubygems input.

Seeaction.yml for more details about therubygems input.

If you're running intoArgumentError: wrong number of arguments (given 4, expected 1) errors with a stacktrace including Psych and RubyGems entries, youshould be able to fix them by settingrubygems: 3.0.0 or higher.

By default, Bundler is installed as follows:

• If there is aGemfile.lock file (or$BUNDLE_GEMFILE.lock orgems.locked) with aBUNDLED WITH section,that version of Bundler will be installed and used.
• If the Ruby ships with Bundler 2.2+ (as a default gem), that version is used.
• Otherwise, the latest compatible Bundler version is installed (Bundler 2 on Ruby >= 2.3, Bundler 1 on Ruby < 2.3).

This behavior can be customized, seeaction.yml for more details about thebundler input.

This action provides a way to automatically runbundle install and cache the result:

    -uses:ruby/setup-ruby@v1with:bundler-cache:true

Note that any step doingbundle install (for the rootGemfile) orgem install bundler can be removed withbundler-cache: true.

This caching speeds up installing gems significantly and avoids too many requests to RubyGems.org.
It needs aGemfile (or$BUNDLE_GEMFILE orgems.rb) under theworking-directory.
If there is aGemfile.lock (or$BUNDLE_GEMFILE.lock orgems.locked),bundle config --local deployment true is used.

To use aGemfile which is not at the root or has a different name, setBUNDLE_GEMFILE in theenv at the job levelas shown in theexample.

When usingbundler-cache: true you might notice there is no good place to runbundle config ... commands.These can be replaced byBUNDLE_* environment variables, which are also faster.They should be set in theenv at the job level as shown in theexample.To find the correct the environment variable name, see theBundler docs or look at.bundle/config after runningbundle config --local KEY VALUE locally.You might need to"-quote the environment variable name in YAML if it has unusual characters like/.

To perform caching, this action will usebundle config --local path $PWD/vendor/bundle.
Therefore, the Bundlerpath should not be changed in your workflow for the cache to work (nobundle config path).

When there is no lockfile, one is generated withbundle lock, which is the same asbundle install would do first before actually fetching any gem.In other words, it works exactly likebundle install.The hash of the generated lockfile is then used for caching, which is the only correct approach.

In some rare scenarios (like using gems with C extensions whose functionality depends on libraries found on the systemat the time of the gem's build) it may be necessary to ignore contents of the cache and get and build all the gems anew.In order to achieve this, set thecache-version option to any value other than0 (or change it to a new unique valueif you have already used it before.)

    -uses:ruby/setup-ruby@v1with:bundler-cache:truecache-version:1

It is also possible to cache gems manually, but this is not recommended because it is verbose andvery difficult to do correctly.There are many concerns which means usingactions/cache is never enough for caching gems (e.g., incomplete cache key, cleaning old gems when restoring from another key, correctly hashing the lockfile if not checked in, OS versions, ABI compatibility forruby-head, etc).So, please usebundler-cache: true instead and report any issue.

Note that running CI on Windows can be quite challenging if you are not very familiar with Windows.It is recommended to first get your build working on Ubuntu and macOS before trying Windows.

• Use Bundler 2.2.18+ on Windows (older versions havebugs) by not setting thebundler: input and ensuring there is noBUNDLED WITH 1.x.y in a checked-inGemfile.lock.
• The default shell on Windows is not Bash butPowerShell.This can lead issues such as multi-line scriptsnot working as expected.
• ThePATH containsmultiple compiler toolchains. Usewhere.exe to debug which tool is used.
• For Ruby ≥ 2.4, MSYS2 is prepended to thePath, similar to what RubyInstaller2 does.
• For Ruby < 2.4, the DevKit MSYS tools are installed and prepended to thePath.
• Use JRuby 9.2.20+ on Windows (older versions havebugs).
• JRuby on Windows has multiple issues (jruby/jruby#7106,jruby/jruby#7182).
• When compiling extension code, note that the packages required to build Ruby are included when using Windows 2022, but that Windows 2019 does not include all of them, and may require installing package(s). This can be done withsetup-ruby-pkgs or via MSYS2's pacman. These packages may be required when installing or updating Ruby std-lib extension gems.

It is highly recommended to useruby/setup-ruby@v1 for the version of this action.This will provide the best experience by automatically getting bug fixes, new Ruby versions and new features.

If you instead choose a specific version (v1.2.3) or a commit sha, there will be no automatic bug fixes andit will be your responsibility to update every time the action no longer works.Make sure to always use the latest release before reporting an issue on GitHub.

This action follows semantic versioning with a movingv1 branch.This follows therecommendations of GitHub Actions.

This action might work withself-hosted runnersif theRunner Image is very similar to the ones used by GitHub runners. Notably:

• Make sure to use the same operating system and version.
• Make sure to use the same version of libssl.
• Make sure that the operating system haslibyaml-0 andlibgmp installed
• The default tool cache directory (/opt/hostedtoolcache on Linux,/Users/runner/hostedtoolcache on macOS,C:/hostedtoolcache/windows on Windows) must be writable by therunner user.This is necessary since the Ruby builds embed the install path when built and cannot be moved around.
• /home/runner must be writable by therunner user.

In other cases, you will need to install Ruby in the runner tool cache as shown by the action when it detects that case(run it so it will show you where to install Ruby).You could of course also not use this action and e.g. use Ruby from a system package or use a Docker image instead.

See also theself-hosted: input.You can set it totrue if you want to use custom-built Rubies in your self-hosted toolcache instead of prebuild Rubies.

This action used to be ateregon/use-ruby-action and was moved to theruby organization.Pleaseupdate if you are usingeregon/use-ruby-action.

The current maintainer of this action is @eregon.Most of the Windows logic is based on work by MSP-Greg.Many thanks to MSP-Greg and Lars Kanis for the help with Ruby Installer.