setup-ruby

The ruby-version input supports several formats to specify which Ruby implementation and version to use:

• Engine-version: e.g., ruby-2.6.5 or truffleruby-19.3.0.
• Short version: e.g., '2.6', which automatically uses the latest release matching that version (e.g., 2.6.10).
• Version only: e.g., '2.6.5', which assumes the MRI implementation.
• Engine only: e.g., ruby or truffleruby, which uses the latest stable release of that implementation.
• Automatic detection: If ruby-version is not provided, the action searches for .ruby-version, .tool-versions, or mise.toml files in the repository.

# Examples of different syntax styles
ruby-version: 'ruby-2.6.5'
ruby-version: '2.6'
ruby-version: '2.6.5'
ruby-version: 'ruby'

Use ruby/setup-ruby@v1 to download a prebuilt Ruby version and add it to the PATH. This action is efficient, typically taking about 5 seconds to set up. It is recommended to use the @v1 tag rather than pinning to a specific commit to ensure newer Ruby versions remain available.

- uses: ruby/setup-ruby@v1
  with:
    ruby-version: '4.0'

To use setup-ruby on self-hosted runners, the runner image must closely match GitHub-hosted runners. Ensure the following requirements are met:

• OS & Libraries: Use the same operating system/version, the same version of libssl, and ensure libyaml-0 and libgmp are installed.
• Permissions: The following directories must be writable by the runner user:
  • /opt/hostedtoolcache (Linux)
  • /Users/runner/hostedtoolcache (macOS)
  • C:/hostedtoolcache/windows (Windows)
  • /home/runner (Linux)
• Custom Rubies: If you have custom-built Rubies in your self-hosted toolcache, set the self-hosted: input to true.

If these conditions aren't met, you may need to manually install Ruby in the runner toolcache or use a system package/Docker image instead.

It is highly recommended to use the moving v1 tag to ensure you receive automatic bug fixes, new Ruby versions, and new features.

If you pin to a specific version (e.g., v1.2.3) or a commit SHA, you will not receive automatic updates and must manually update the action when it stops working.

uses: ruby/setup-ruby@v1

Setting bundler-cache: true automatically runs bundle install and caches the installed gems. This significantly speeds up workflows and reduces requests to RubyGems.org.

Requirements & Behavior:

• Requires a Gemfile (or $BUNDLE_GEMFILE or gems.rb) under the working-directory.
• If a lockfile exists, it uses bundle config --local deployment true.
• If no lockfile exists, it generates one using bundle lock to create a cache key.
• Important: Do not manually change the Bundler path (e.g., via bundle config path), as the action relies on bundle config --local path $PWD/vendor/bundle for caching to work.
• To bypass a corrupted cache, set cache-version to any value other than 0.

- uses: ruby/setup-ruby@v1
  with:
    ruby-version: '4.0'
    bundler-cache: true

Running CI on Windows can be challenging. Follow these guidelines to ensure a stable environment:

• Bundler Version: Use Bundler 2.2.18 or newer. To ensure this, do not set the bundler: input and ensure your Gemfile.lock does not contain BUNDLED WITH 1.x.y.
• Shell: The default shell is PowerShell, not Bash. Multi-line scripts may behave differently.
• Toolchains: The PATH contains multiple compiler toolchains. Use where.exe to debug which tool is being utilized.
• MSYS2:
  • For Ruby ≥ 2.4: MSYS2 is prepended to the Path (similar to RubyInstaller2).
  • For Ruby < 2.4: DevKit MSYS tools are installed and prepended to the Path.
• Compiling Extensions: On Windows 2022, packages required to build Ruby are included. For additional packages needed for stdlib extension gems, use setup-ruby-pkgs or MSYS2's pacman.

While the action uses ${{ github.token }} by default to avoid rate limiting, you can provide a custom token if you are using GitHub Enterprise Server (GHES) or experiencing rate limits.

- uses: ruby/setup-ruby@v1
  with:
    token: ${{ secrets.MY_GITHUB_TOKEN }}

The ruby-version input can be specified in several ways:

1. Explicit Version: A version string like 3.2.2 (sets engine to ruby) or an engine-version string like truffleruby-34.0.
2. Default: If set to 'default', the action looks for version files in the current working directory in this order:
   • .ruby-version
   • .tool-versions (extracts the ruby line)
   • mise.toml (extracts the ruby key)
3. File Paths: You can pass the filename directly (e.g., '.ruby-version').

Engine Detection Logic:

• X.Y.Z $\rightarrow$ engine: ruby, version: X.Y.Z
• engine-X.Y.Z $\rightarrow$ engine: engine, version: X.Y.Z
• engine (no dash) $\rightarrow$ engine: engine, version: (latest available)

By default, the RubyGems version bundled with the Ruby version is used. You can override this using the rubygems input. This is useful for fixing errors like ArgumentError: wrong number of arguments (given 4, expected 1) involving Psych and RubyGems by setting rubygems: 3.0.0 or higher.

- uses: ruby/setup-ruby@v1
  with:
    ruby-version: '4.0'
    rubygems: '3.0.0'