|
1 | | -# setup-ruby |
| 1 | +<div align="center"> |
| 2 | + <img src="https://buildjet.com/buildjet-for-github-actions-logo2.svg" height="38"> |
| 3 | +</div> |
2 | 4 |
|
3 | | -This action downloads a prebuilt ruby and adds it to the `PATH`. |
| 5 | +--- |
4 | 6 |
|
5 | | -It is very efficient and takes about 5 seconds to download, extract and add the given Ruby to the `PATH`. |
6 | | -No extra packages need to be installed. |
| 7 | +This is a fork by [BuildJet for GitHub Actions](https://buildjet.com/for-github-actions). |
| 8 | +It is **fully compatible with the official setup-ruby action**, simply replace `ruby/setup-ruby` with `buildjet/setup-ruby`. |
| 9 | +Under the hood we simply switch the underlying caching package to our fully compatible `buildjet/cache`. No other changes have been made to this package. |
7 | 10 |
|
8 | | -**Important:** Prefer `ruby/setup-ruby@v1`. |
9 | | -If you pin to a commit or release, only the Ruby versions available at the time of the commit |
10 | | -will be available, and you will need to update it to use newer Ruby versions, see [Versioning](#versioning). |
11 | | - |
12 | | -### Supported Versions |
13 | | - |
14 | | -This action currently supports these versions of MRI, JRuby and TruffleRuby: |
15 | | - |
16 | | -| Interpreter | Versions | |
17 | | -| ----------- | -------- | |
18 | | -| `ruby` | 1.9.3, 2.0.0, 2.1.9, 2.2, all versions from 2.3.0 until 3.4.0-preview1, head, debug, mingw, mswin, ucrt | |
19 | | -| `jruby` | 9.1.17.0 - 9.4.7.0, head | |
20 | | -| `truffleruby` | 19.3.0 - 24.0.1, head | |
21 | | -| `truffleruby+graalvm` | 21.2.0 - 24.0.1, head | |
22 | | - |
23 | | -`ruby-debug` is the same as `ruby-head` but with assertions enabled (`-DRUBY_DEBUG=1`). |
24 | | - |
25 | | -Regarding Windows ruby master builds, `mingw` is a MSYS2/MinGW build, `head` & `ucrt` are MSYS2/UCRT64 |
26 | | -builds, and `mswin` is a MSVC/VS 2022 build. |
27 | | - |
28 | | -Preview and RC versions of Ruby might be available too on Ubuntu and macOS (not on Windows). |
29 | | -However, it is recommended to test against `ruby-head` rather than previews, |
30 | | -as it provides more useful feedback for the Ruby core team and for upcoming changes. |
31 | | - |
32 | | -Only release versions published by [RubyInstaller](https://rubyinstaller.org/downloads/archives/) |
33 | | -are available on Windows. Due to that, Ruby 2.2 resolves to 2.2.6 on Windows and 2.2.10 |
34 | | -on other platforms. Ruby 2.3 on Windows only has builds for 2.3.0, 2.3.1 and 2.3.3. |
35 | | - |
36 | | -Note that Ruby ≤ 2.4 and the OpenSSL version it needs (1.0.2) are both end-of-life, |
37 | | -which means Ruby ≤ 2.4 is unmaintained and considered insecure. |
38 | | - |
39 | | -### Supported Platforms |
40 | | - |
41 | | -The action works on these [GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources) images. Runner images not listed below are not supported yet. `$OS-latest` just alias to one of these images. |
42 | | - |
43 | | -| Operating System | Supported | |
44 | | -| ---------------- | --------- | |
45 | | -| Ubuntu | `ubuntu-20.04`, `ubuntu-22.04`, `ubuntu-24.04` | |
46 | | -| macOS | `macos-11`, `macos-12`, `macos-13`, `macos-14` | |
47 | | -| Windows | `windows-2019`, `windows-2022` | |
48 | | - |
49 | | -The prebuilt releases are generated by [ruby-builder](https://github.com/ruby/ruby-builder) |
50 | | -and on Windows by [RubyInstaller2](https://github.com/oneclick/rubyinstaller2). |
51 | | -The `mingw`, `ucrt` and `mswin` builds are generated by [ruby-loco](https://github.com/MSP-Greg/ruby-loco). |
52 | | -`ruby-head` is generated by [ruby-dev-builder](https://github.com/ruby/ruby-dev-builder), |
53 | | -`jruby-head` is generated by [jruby-dev-builder](https://github.com/ruby/jruby-dev-builder), |
54 | | -`truffleruby-head` is generated by [truffleruby-dev-builder](https://github.com/ruby/truffleruby-dev-builder) |
55 | | -and `truffleruby+graalvm` is generated by [graalvm-ce-dev-builds](https://github.com/graalvm/graalvm-ce-dev-builds). |
56 | | -The full list of available Ruby versions can be seen in [ruby-builder-versions.json](ruby-builder-versions.json) |
57 | | -for Ubuntu and macOS and in [windows-versions.json](windows-versions.json) for Windows. |
58 | | - |
59 | | -## Usage |
60 | | - |
61 | | -### Single Job |
62 | | - |
63 | | -```yaml |
64 | | -name: My workflow |
65 | | -on: [push, pull_request] |
66 | | -jobs: |
67 | | - test: |
68 | | - runs-on: ubuntu-latest |
69 | | - steps: |
70 | | - - uses: actions/checkout@v4 |
71 | | - - uses: ruby/setup-ruby@v1 |
72 | | - with: |
73 | | - ruby-version: '3.3' # Not needed with a .ruby-version file |
74 | | - bundler-cache: true # runs 'bundle install' and caches installed gems automatically |
75 | | - - run: bundle exec rake |
76 | | -``` |
77 | | -
|
78 | | -### Matrix of Ruby Versions |
79 | | -
|
80 | | -This matrix tests all stable releases and `head` versions of MRI, JRuby and TruffleRuby on Ubuntu and macOS. |
81 | | - |
82 | | -```yaml |
83 | | -name: My workflow |
84 | | -on: [push, pull_request] |
85 | | -jobs: |
86 | | - test: |
87 | | - strategy: |
88 | | - fail-fast: false |
89 | | - matrix: |
90 | | - os: [ubuntu-latest, macos-latest] |
91 | | - # Due to https://github.com/actions/runner/issues/849, we have to use quotes for '3.0' |
92 | | - ruby: ['2.7', '3.0', '3.1', '3.2', '3.3', head, jruby, jruby-head, truffleruby, truffleruby-head] |
93 | | - runs-on: ${{ matrix.os }} |
94 | | - steps: |
95 | | - - uses: actions/checkout@v4 |
96 | | - - uses: ruby/setup-ruby@v1 |
97 | | - with: |
98 | | - ruby-version: ${{ matrix.ruby }} |
99 | | - bundler-cache: true # runs 'bundle install' and caches installed gems automatically |
100 | | - - run: bundle exec rake |
101 | | -``` |
102 | | - |
103 | | -### Matrix of Gemfiles |
104 | | - |
105 | | -```yaml |
106 | | -name: My workflow |
107 | | -on: [push, pull_request] |
108 | | -jobs: |
109 | | - test: |
110 | | - strategy: |
111 | | - fail-fast: false |
112 | | - matrix: |
113 | | - gemfile: [ rails5, rails6 ] |
114 | | - runs-on: ubuntu-latest |
115 | | - env: # $BUNDLE_GEMFILE must be set at the job level, so it is set for all steps |
116 | | - BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/${{ matrix.gemfile }}.gemfile |
117 | | - steps: |
118 | | - - uses: actions/checkout@v4 |
119 | | - - uses: ruby/setup-ruby@v1 |
120 | | - with: |
121 | | - ruby-version: '3.3' |
122 | | - bundler-cache: true # runs 'bundle install' and caches installed gems automatically |
123 | | - - run: bundle exec rake |
124 | | -``` |
125 | | - |
126 | | -See the GitHub Actions documentation for more details about the |
127 | | -[workflow syntax](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions) |
128 | | -and the [condition and expression syntax](https://help.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions). |
129 | | - |
130 | | -### Supported Version Syntax |
131 | | - |
132 | | -* engine-version like `ruby-2.6.5` and `truffleruby-19.3.0` |
133 | | -* short version like `'2.6'`, automatically using the latest release matching that version (`2.6.10`) |
134 | | -* version only like `'2.6.5'`, assumes MRI for the engine |
135 | | -* engine only like `ruby` and `truffleruby`, uses the latest stable release of that implementation |
136 | | -* `.ruby-version` reads from the project's `.ruby-version` file |
137 | | -* `.tool-versions` reads from the project's `.tool-versions` file |
138 | | -* If the `ruby-version` input is not specified, `.ruby-version` is tried first, followed by `.tool-versions` |
139 | | - |
140 | | -### Working Directory |
141 | | - |
142 | | -The `working-directory` input can be set to resolve `.ruby-version`, `.tool-versions` and `Gemfile.lock` |
143 | | -if they are not at the root of the repository, see [action.yml](action.yml) for details. |
144 | | - |
145 | | -### RubyGems |
146 | | - |
147 | | -By default, the default RubyGems version that comes with each Ruby is used. |
148 | | -However, users can optionally customize the RubyGems version that they want by |
149 | | -setting the `rubygems` input. |
150 | | - |
151 | | -See [action.yml](action.yml) for more details about the `rubygems` input. |
152 | | - |
153 | | -If you're running into `ArgumentError: wrong number of arguments (given 4, |
154 | | -expected 1)` errors with a stacktrace including Psych and RubyGems entries, you |
155 | | -should be able to fix them by setting `rubygems: 3.0.0` or higher. |
156 | | - |
157 | | -### Bundler |
158 | | - |
159 | | -By default, Bundler is installed as follows: |
160 | | - |
161 | | -* If there is a `Gemfile.lock` file (or `$BUNDLE_GEMFILE.lock` or `gems.locked`) with a `BUNDLED WITH` section, |
162 | | - that version of Bundler will be installed and used. |
163 | | -* If the Ruby ships with Bundler 2.2+ (as a default gem), that version is used. |
164 | | -* Otherwise, the latest compatible Bundler version is installed (Bundler 2 on Ruby >= 2.3, Bundler 1 on Ruby < 2.3). |
165 | | - |
166 | | -This behavior can be customized, see [action.yml](action.yml) for more details about the `bundler` input. |
167 | | - |
168 | | -### Caching `bundle install` automatically |
169 | | - |
170 | | -This action provides a way to automatically run `bundle install` and cache the result: |
171 | | -```yaml |
172 | | - - uses: ruby/setup-ruby@v1 |
173 | | - with: |
174 | | - bundler-cache: true |
175 | | -``` |
176 | | - |
177 | | -Note that any step doing `bundle install` (for the root `Gemfile`) or `gem install bundler` can be removed with `bundler-cache: true`. |
178 | | - |
179 | | -This caching speeds up installing gems significantly and avoids too many requests to RubyGems.org. |
180 | | -It needs a `Gemfile` (or `$BUNDLE_GEMFILE` or `gems.rb`) under the [`working-directory`](#working-directory). |
181 | | -If there is a `Gemfile.lock` (or `$BUNDLE_GEMFILE.lock` or `gems.locked`), `bundle config --local deployment true` is used. |
182 | | - |
183 | | -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 |
184 | | -as shown in the [example](#matrix-of-gemfiles). |
185 | | - |
186 | | -#### bundle config |
187 | | - |
188 | | -When using `bundler-cache: true` you might notice there is no good place to run `bundle config ...` commands. |
189 | | -These can be replaced by `BUNDLE_*` environment variables, which are also faster. |
190 | | -They should be set in the `env` at the job level as shown in the [example](#matrix-of-gemfiles). |
191 | | -To find the correct the environment variable name, see the [Bundler docs](https://bundler.io/man/bundle-config.1.html) or look at `.bundle/config` after running `bundle config --local KEY VALUE` locally. |
192 | | -You might need to `"`-quote the environment variable name in YAML if it has unusual characters like `/`. |
193 | | - |
194 | | -To perform caching, this action will use `bundle config --local path $PWD/vendor/bundle`. |
195 | | -Therefore, the Bundler `path` should not be changed in your workflow for the cache to work (no `bundle config path`). |
196 | | - |
197 | | -#### How it Works |
198 | | - |
199 | | -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. |
200 | | -In other words, it works exactly like `bundle install`. |
201 | | -The hash of the generated lockfile is then used for caching, which is the only correct approach. |
202 | | - |
203 | | -#### Dealing with a corrupted cache |
204 | | - |
205 | | -In some rare scenarios (like using gems with C extensions whose functionality depends on libraries found on the system |
206 | | -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. |
207 | | -In order to achieve this, set the `cache-version` option to any value other than `0` (or change it to a new unique value |
208 | | -if you have already used it before.) |
209 | | - |
210 | | -```yaml |
211 | | - - uses: ruby/setup-ruby@v1 |
212 | | - with: |
213 | | - bundler-cache: true |
214 | | - cache-version: 1 |
215 | | -``` |
216 | | - |
217 | | -#### Caching `bundle install` manually |
218 | | - |
219 | | -It is also possible to cache gems manually, but this is not recommended because it is verbose and *very difficult* to do correctly. |
220 | | -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). |
221 | | -So, please use `bundler-cache: true` instead and report any issue. |
222 | | - |
223 | | -## Windows |
224 | | - |
225 | | -Note that running CI on Windows can be quite challenging if you are not very familiar with Windows. |
226 | | -It is recommended to first get your build working on Ubuntu and macOS before trying Windows. |
227 | | - |
228 | | -* Use Bundler 2.2.18+ on Windows (older versions have [bugs](https://github.com/ruby/setup-ruby/issues/209#issuecomment-889064123)) by not setting the `bundler:` input and ensuring there is no `BUNDLED WITH 1.x.y` in a checked-in `Gemfile.lock`. |
229 | | -* The default shell on Windows is not Bash but [PowerShell](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#using-a-specific-shell). |
230 | | - This can lead issues such as multi-line scripts [not working as expected](https://github.com/ruby/setup-ruby/issues/13). |
231 | | -* The `PATH` contains [multiple compiler toolchains](https://github.com/ruby/setup-ruby/issues/19). Use `where.exe` to debug which tool is used. |
232 | | -* For Ruby ≥ 2.4, MSYS2 is prepended to the `Path`, similar to what RubyInstaller2 does. |
233 | | -* For Ruby < 2.4, the DevKit MSYS tools are installed and prepended to the `Path`. |
234 | | -* Use JRuby 9.2.20+ on Windows (older versions have [bugs](https://github.com/ruby/setup-ruby/issues/18#issuecomment-889072695)). |
235 | | -* JRuby on Windows has multiple issues ([jruby/jruby#7106](https://github.com/jruby/jruby/issues/7106), [jruby/jruby#7182](https://github.com/jruby/jruby/issues/7182)). |
236 | | - |
237 | | -## Versioning |
238 | | - |
239 | | -It is highly recommended to use `ruby/setup-ruby@v1` for the version of this action. |
240 | | -This will provide the best experience by automatically getting bug fixes, new Ruby versions and new features. |
241 | | - |
242 | | -If you instead choose a specific version (v1.2.3) or a commit sha, there will be no automatic bug fixes and |
243 | | -it will be your responsibility to update every time the action no longer works. |
244 | | -Make sure to always use the latest release before reporting an issue on GitHub. |
245 | | - |
246 | | -This action follows semantic versioning with a moving `v1` branch. |
247 | | -This follows the [recommendations](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) of GitHub Actions. |
248 | | - |
249 | | -## Using self-hosted runners |
250 | | - |
251 | | -This action might work with [self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) |
252 | | -if the [Runner Image](https://github.com/actions/runner-images) is very similar to the ones used by GitHub runners. Notably: |
253 | | - |
254 | | -* Make sure to use the same operating system and version. |
255 | | -* Make sure to use the same version of libssl. |
256 | | -* Make sure that the operating system has `libyaml-0` and [`libgmp`](https://stackoverflow.com/questions/26555902/ruby-v-dyld-library-not-loaded-usr-local-lib-libgmp-10-dylib) installed |
257 | | -* The default tool cache directory (`/opt/hostedtoolcache` on Linux, `/Users/runner/hostedtoolcache` on macOS, |
258 | | - `C:/hostedtoolcache/windows` on Windows) must be writable by the `runner` user. |
259 | | - This is necessary since the Ruby builds embed the install path when built and cannot be moved around. |
260 | | -* `/home/runner` must be writable by the `runner` user. |
261 | | - |
262 | | -In other cases, you will need to install Ruby in the runner tool cache as shown by the action when it detects that case |
263 | | -(run it so it will show you where to install Ruby). |
264 | | -You could of course also not use this action and e.g. use Ruby from a system package or use a Docker image instead. |
265 | | - |
266 | | -See also the [`self-hosted:` input](action.yml). |
267 | | -You can set it to `true` if you want to use custom-built Rubies in your self-hosted toolcache instead of prebuild Rubies. |
268 | | - |
269 | | -## History |
270 | | - |
271 | | -This action used to be at `eregon/use-ruby-action` and was moved to the `ruby` organization. |
272 | | -Please [update](https://github.com/ruby/setup-ruby/releases/tag/v1.13.0) if you are using `eregon/use-ruby-action`. |
273 | | - |
274 | | -## Credits |
275 | | - |
276 | | -The current maintainer of this action is @eregon. |
277 | | -Most of the Windows logic is based on work by MSP-Greg. |
278 | | -Many thanks to MSP-Greg and Lars Kanis for the help with Ruby Installer. |
| 11 | +For help migrating to BuildJet's setup-ruby, please visit our [migration guide](https://buildjet.com/for-github-actions/docs/guides/migrating-to-buildjet-cache). |
| 12 | +For detailed usage instructions, please visit the [official `ruby/setup-ruby` repository](https://github.com/ruby/setup-ruby). |
0 commit comments