setup-ruby: the GitHub Action that puts a prebuilt Ruby on the PATH in five seconds

What the action does and why the pinning advice comes first

setup-ruby is an action to download a prebuilt Ruby and add it to the PATH, and the README is unusually blunt about the speed. It is very efficient and takes about 5 seconds to download, extract and add the given Ruby to the PATH, and no extra packages need to be installed.

Five seconds is the number that matters for CI, and it is achieved by not building Ruby at all. The prebuilt releases are generated by ruby-builder on Linux and macOS and by RubyInstaller2 on Windows. The mingw, ucrt and mswin builds are generated by ruby-loco, and the head builds come from dedicated dev builders: ruby-dev-builder for ruby-head, jruby-dev-builder for jruby-head, and truffleruby-dev-builder for truffleruby-head and truffleruby+graalvm-head.

So the action is a download, an extract and a PATH entry, and the reason it can be that fast is that the hard work, compiling Ruby, was done ahead of time by other projects.

The advice at the top of the README is the part every user should read first. It is marked Important: prefer ruby/setup-ruby@v1. If you pin to a commit or release, only the Ruby versions available at the time of the commit will be available, and you will need to update it to use newer Ruby versions.

That is a real and non-obvious coupling. The action resolves a version string to a prebuilt artefact, and the set of available artefacts grows over time as the builders publish new ones. Pinning the action to a commit freezes your workflow against that moment's catalogue of Rubies. So the usual advice about pinning for supply chain safety, pin exactly, is inverted here, because the action's own documentation asks you not to.

The primary language is JavaScript, the licence is MIT, and the recent releases are v1.329.0 on 2026-10-12, v1.328.0 on 2026-10-09 and v1.327.0 on 2026-09-25. The repository is not archived, with the last push on 2026-10-12. The homepage points at the marketplace entry for the action and its JRuby and TruffleRuby variants.

The package.json shows a small footprint. The dependencies are the standard GitHub Actions toolchain packages, @actions/cache, @actions/core, @actions/exec, @actions/io and @actions/tool-cache, plus linux-os-info for detecting the runner's distribution and semver for version comparison. The build is ncc build index.js -o dist, so the action ships as a bundled single file in dist/, which is the standard pattern for a JavaScript action that has to run without an install step.

The version syntax, and the four ways to say which Ruby you want

The version resolution is the part of this action that has to be right, and the README gives a list of the accepted forms.

An engine and a version, like ruby-2.6.5 or truffleruby-19.3.0. A short version like '2.6', which automatically uses the latest release matching that version, for example 2.6.10. A version only like '2.6.5', which assumes MRI for the engine. An engine only like ruby or truffleruby, which uses the latest stable release of that implementation.

And then the file based forms, which are the ones most projects end up using. A .ruby-version is read from the project's .ruby-version file, a .tool-versions is read from the project's .tool-versions file, and a mise.toml is read from the project's mise.toml file. If the ruby-version input is not specified, .ruby-version is tried first, followed by .tool-versions, followed by mise.toml.

That fallback order is the useful detail, because it means a project that already declares its Ruby in any of the three common ways can add the action with no version at all and it will work. The single job example in the README says as much in a comment: ruby-version: '4.0' with the note that it is not needed with a .ruby-version, .tool-versions or mise.toml.

The working-directory input extends the same idea to a monorepo. It can be set to resolve .ruby-version, .tool-versions, mise.toml and Gemfile.lock if they are not at the root of the repository, and the README points at action.yml for the details.

The version catalogue itself is spread across several files in the repository, which is a good sign about how it is maintained. The list of available Ruby versions can be seen in ruby-builder-versions.json for Ubuntu and macOS, with a note that some combinations are not available and a link to the full list in the ruby-builder releases, and in windows-versions.json for Windows. There is also windows-toolchain-versions.json and versions-strings-for-builder.rb, which is the script that produces the version strings the builders consume.

The supported interpreter matrix is broad. For ruby, MRI, the versions are 1.9.3, 2.0.0, 2.1.9, 2.2, all versions from 2.3.0 until 4.1.0-preview1, head, debug, mingw, mswin and ucrt. For jruby, 9.1.17.0 through 10.1.2.0 and head. For truffleruby, 19.3.0 through 40.0.0 and head. And truffleruby+graalvm, 21.2.0 through 40.0.0 and head.

The long tail of old MRI versions from 1.9.3 is worth noting, because it means the action is useful for maintaining libraries that still support old rubies, which is the opposite of most CI tooling, which assumes a recent version.

The debug and asan builds, and the platform support matrix

Three of the supported version strings are not releases at all, and they are the reason this action is more than a convenience.

ruby-debug is the same as ruby-head but with assertions enabled, via -DRUBY_DEBUG=1. ruby-asan is the same as ruby-head but with AddressSanitizer enabled, which the README calls helpful for finding memory issues in native extensions. Native extensions are automatically compiled with AddressSanitizer when using ruby-asan. asan-release is similar to ruby-asan but built from the latest stable release tag.

So the action gives you a Ruby with an instrumented allocator and an instrumented compiler for native extensions, on demand, without maintaining your own build of either. For a project with C extensions, that is the difference between a memory bug that takes a week to find and one that takes an afternoon, and it is a capability that a plain language toolchain setup does not give you.

The restriction on the sanitizer builds is that ruby-asan is currently only available on ubuntu-24.04, and asan-release is likewise currently only available on ubuntu-24.04. So the debug tooling is tied to one runner image, which is worth knowing before you plan a matrix on it.

The Windows build variants are described separately. mingw is a MSYS2/MinGW build, head and ucrt are MSYS2/UCRT64 builds, and mswin is an MSVC/VS 2022 build.

The platform support table lists the GitHub-hosted runner images the action works on, with the note that runner images not listed are not supported yet, and that $OS-latest just aliases to one of these images. For Ubuntu there are ubuntu-22.04, ubuntu-24.04 and ubuntu-26.04, plus the arm variants of each, so ubuntu-22.04-arm, ubuntu-24.04-arm and ubuntu-26.04-arm. For macOS it is macos-14 and newer versions. For Windows it is windows-2022, windows-2025 and windows-11-arm.

The arm entries are the newest part of that list, and they matter because the arm64 runner images are the ones people are migrating to for cost reasons, and a Ruby action that does not support them is a blocker for that migration.

The Windows caveat is a separate and important limitation. Only release versions published by RubyInstaller are available on Windows, so Ruby 2.2 resolves to 2.2.6 on Windows and 2.2.10 on other platforms, and Ruby 2.3 on Windows only has builds for 2.3.0, 2.3.1 and 2.3.3. Preview and RC versions of Ruby might be available on Ubuntu and macOS but not on Windows, and the recommendation is to test against ruby-head rather than previews, since it provides more useful feedback for the Ruby core team and for upcoming changes.

And the security note is short and blunt: Ruby 2.4 and below, and the OpenSSL version it needs, 1.0.2, are both end-of-life, which means Ruby 2.4 and below is unmaintained and considered insecure. So the action can install those versions for compatibility testing, but you should not deploy on them.

The workflow patterns, and the bundler cache

The usage section gives three workflow patterns, and the middle one is the reason most projects adopt this action.

The single job case is the minimum:

name: My workflow
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - uses: ruby/setup-ruby@v1
      with:
        ruby-version: '4.0' # Not needed with a .ruby-version, .tool-versions or mise.toml
        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
    - run: bundle exec rake

The matrix of Ruby versions is the pattern that needs this action to exist:

name: My workflow
on: [push, pull_request]
jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
        ruby: ['3.3', '3.4', '4.0', head, jruby, jruby-head, truffleruby, truffleruby-head]
    runs-on: ${{ matrix.os }}
    steps:
    - uses: actions/checkout@v6
    - uses: ruby/setup-ruby@v1
      with:
        ruby-version: ${{ matrix.ruby }}
        bundler-cache: true
    - run: bundle exec rake

Eight Ruby configurations across two operating systems, which is sixteen jobs, each needing a different Ruby in seconds. There is no other practical way to do that, and the comment about quotes around '3.0' in the source, with a link to a GitHub Actions runner issue, is a small window into the YAML parsing quirk that makes the quotes necessary.

The third pattern is a matrix of Gemfiles rather than Rubies, which is what you want when you are testing a library against different dependency sets rather than different interpreters:

name: My workflow
on: [push, pull_request]
jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        gemfile: [ rails7, rails8 ]
    runs-on: ubuntu-latest
    env: # $BUNDLE_GEMFILE must be set at the job level, so it is set for all steps
      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/${{ matrix.gemfile }}.gemfile
    steps:
    - uses: actions/checkout@v6
    - uses: ruby/setup-ruby@v1
      with:
        ruby-version: '4.0'
        bundler-cache: true
    - run: bundle exec rake

The env comment is worth reading, because it is the kind of thing that costs an hour. $BUNDLE_GEMFILE has to be set at the job level so it applies to all the steps, and the path is absolute, built from github.workspace.

The bundler-cache: true option is the other workhorse. It runs bundle install and caches the installed gems automatically, and the action uses the @actions/cache dependency to do it. The lock file is what determines the cache key, which is why the working-directory input also resolves Gemfile.lock, since a monorepo with several lock files needs to know which one defines the cache.

The RubyGems version is configurable too. By default the default RubyGems version that comes with each Ruby is used, but you can customise it by setting the rubygems input, and the README points at the action documentation for that.

The repository layout shows how the version data is maintained. There are new-versions.rb and versions-strings-for-builder.rb as the scripts that talk to the builders, generate-test-matrix.rb and generate-windows-versions.rb for the metadata, windows.js, ruby-builder.js, rubygems.js, bundler.js, common.js and index.js as the action logic, a gemfiles/ directory, a pre-commit hook, and a yarn.lock. The Rakefile and the scripts are the release machinery, and release.js is the release script.

Editorial conclusion

setup-ruby fits any GitHub Actions workflow that needs a specific Ruby, and it is close to mandatory for a Ruby project with a version matrix, since it is the only practical way to run four MRI versions plus head plus two alternative runtimes in one CI run. It is the wrong tool outside GitHub Actions, since it is an action and not a Ruby installer, and the wrong tool if your build needs a Ruby configuration that is not in the published list. Before adopting, pin to ruby/setup-ruby@v1 rather than a commit, because a pinned commit freezes the set of available Ruby versions, and check the supported runner images, since the action only works on the images the README lists.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. ruby/setup-ruby on GitHub