This action downloads a prebuilt ruby and adds it to the PATH
.
It is very efficient and takes about 5 seconds to download, extract and add the given Ruby to the PATH
.
No extra packages need to be installed.
Compared to actions/setup-ruby, this actions supports many more versions and features.
This action currently supports these versions of MRI, JRuby and TruffleRuby:
Interpreter | Versions |
---|---|
ruby |
1.9.3, 2.0.0, 2.1.9, 2.2, all versions from 2.3.0 until 3.2.0-preview1, head, debug, mingw, mswin |
jruby |
9.1.17.0 - 9.3.6.0, head |
truffleruby |
19.3.0 - 22.1.0, head |
truffleruby+graalvm |
21.2.0 - 22.1.0, head |
ruby-debug
is the same as ruby-head
but with assertions enabled (-DRUBY_DEBUG=1
).
On Windows, mingw
and mswin
are ruby-head
builds using the MSYS2/MinGW and the MSVC toolchains respectively.
Preview and RC versions of Ruby might be available too on Ubuntu and macOS (not on Windows).
However, it is recommended to test against ruby-head
rather than previews,
as it provides more useful feedback for the Ruby core team and for upcoming changes.
Only versions published by RubyInstaller are available on Windows. Due to that, 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.
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 these GitHub-hosted runners virtual environments. Virtual environments not listed below are unsupported.
Operating System | Recommended | Other Supported Versions |
---|---|---|
Ubuntu | ubuntu-latest (= ubuntu-20.04 ) |
ubuntu-18.04 , ubuntu-22.04 (beta, only ruby: 3.1 - head ) |
macOS | macos-latest (= macos-11 ) |
macos-10.15 , macos-12 (beta) |
Windows | windows-latest (= windows-2022 ) |
windows-2019 |
On ubuntu-22.04
(beta), only ruby: 3.1 - head
are supported, due to Ubuntu 22.04 only supporting OpenSSL 3.
The prebuilt releases are generated by ruby-builder
and on Windows by RubyInstaller2.
mingw
and mswin
builds are generated by ruby-loco.
ruby-head
is generated by ruby-dev-builder,
jruby-head
is generated by jruby-dev-builder,
truffleruby-head
is generated by truffleruby-dev-builder
and truffleruby+graalvm
is generated by graalvm-ce-dev-builds.
The full list of available Ruby versions can be seen in ruby-builder-versions.json
for Ubuntu and macOS and in windows-versions.json for Windows.
name: My workflow
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: ruby/setup-ruby@v1
with:
ruby-version: '3.0' # Not needed with a .ruby-version file
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
- run: bundle exec rake
This matrix tests all stable releases and head
versions of MRI, JRuby and TruffleRuby on Ubuntu and macOS.
name: My workflow
on: [push, pull_request]
jobs:
test:
strategy:
fail-fast: false
matrix:
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', head, jruby, jruby-head, truffleruby, truffleruby-head]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v3
- uses: ruby/setup-ruby@v1
with:
ruby-version: ${{ matrix.ruby }}
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
- run: bundle exec rake
name: My workflow
on: [push, pull_request]
jobs:
test:
strategy:
fail-fast: false
matrix:
gemfile: [ rails5, rails6 ]
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@v3
- uses: ruby/setup-ruby@v1
with:
ruby-version: '3.0'
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
- run: bundle exec rake
See the GitHub Actions documentation for more details about the workflow syntax and the condition and expression syntax.
ruby-2.6.5
and truffleruby-19.3.0
'2.6'
, automatically using the latest release matching that version (2.6.10
)'2.6.5'
, assumes MRI for the enginetruffleruby
, 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
fileruby-version
input is not specified, .ruby-version
is tried first, followed by .tool-versions
The working-directory
input can be set to resolve .ruby-version
, .tool-versions
and Gemfile.lock
if they are not at the root of the repository, see action.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 by
setting the rubygems
input.
See action.yml for more details about the rubygems
input.
If you're running into ArgumentError: wrong number of arguments (given 4, expected 1)
errors with a stacktrace including Psych and RubyGems entries, you
should be able to fix them by setting rubygems: 3.0.0
or higher.
By default, if there is a Gemfile.lock
file (or $BUNDLE_GEMFILE.lock
or gems.locked
) with a BUNDLED WITH
section,
that version of Bundler will be installed and used.
Otherwise, the latest compatible Bundler version is installed (Bundler 2 on Ruby >= 2.4, Bundler 1 on Ruby < 2.4).
This behavior can be customized, see action.yml for more details about the bundler
input.
bundle install
automaticallyThis action provides a way to automatically run bundle install
and cache the result:
- uses: ruby/setup-ruby@v1
with:
bundler-cache: true
Note that any step doing bundle install
(for the root Gemfile
) or gem install bundler
can be removed with bundler-cache: true
.
This caching speeds up installing gems significantly and avoids too many requests to RubyGems.org.
It needs a Gemfile
(or $BUNDLE_GEMFILE
or gems.rb
) under the working-directory
.
If there is a Gemfile.lock
(or $BUNDLE_GEMFILE.lock
or gems.locked
), bundle config --local deployment true
is used.
To use a Gemfile
which is not at the root or has a different name, set BUNDLE_GEMFILE
in the env
at the job level
as shown in the example.
When using bundler-cache: true
you might notice there is no good place to run bundle config ...
commands.
These can be replaced by BUNDLE_*
environment variables, which are also faster.
They should be set in the env
at the job level as shown in the example.
To find the correct the environment variable name, see the Bundler docs or look at .bundle/config
after running bundle 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 use bundle config --local path $PWD/vendor/bundle
.
Therefore, the Bundler path
should not be changed in your workflow for the cache to work (no bundle config path
).
When there is no lockfile, one is generated with bundle lock
, which is the same as bundle install
would do first before actually fetching any gem.
In other words, it works exactly like bundle 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 system
at 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 the cache-version
option to any value other than 0
(or change it to a new unique value
if you have already used it before.)
- uses: ruby/setup-ruby@v1
with:
bundler-cache: true
cache-version: 1
bundle install
manuallyIt is also possible to cache gems manually, but this is not recommended because it is verbose and very difficult to do correctly.
There are many concerns which means using actions/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 for ruby-head
, etc).
So, please use bundler-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.
bundler:
input and ensuring there is no BUNDLED WITH 1.x.y
in a checked-in Gemfile.lock
.PATH
contains multiple compiler toolchains. Use where.exe
to debug which tool is used.Path
, similar to what RubyInstaller2 does.Path
.It is highly recommended to use ruby/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 and it 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 moving v1
branch.
This follows the recommendations of GitHub Actions.
This action might work with self-hosted runners if the virtual environment is very similar to the ones used by GitHub runners. Notably:
ImageOS
on the runner to the corresponding value on GitHub-hosted runners (e.g. ubuntu18
/macos1015
/win19
). This is necessary to detect the operating system and version.libyaml-0
and libgmp
installed/opt/hostedtoolcache
on Linux, /Users/runner/hostedtoolcache
on macOS,
C:/hostedtoolcache/windows
on Windows) must be writable by the runner
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 the runner
user.In other cases, please use a system Ruby or install Ruby manually instead.
On a self-hosted runner you need to define the ImageOs
as an evironment variable on the host, you can do this in the ~/actions-runner/.env
file (See #230).
This action used to be at eregon/use-ruby-action
and was moved to the ruby
organization.
Please update if you are using eregon/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.