Recommend ruby/setup-ruby's bundler-cache: true option

eregon · eregon · commit 1bfe3accb30c · 2021-01-28T12:52:25.000+01:00
Manually caching gems has many issues: * Not working if there is no Gemfile.lock but only a Gemfile * Not having the OS version in the key, which might cause binary incompatibility with system libraries of different ABI version. * Not taking the Ruby version in account. * Not taking the Ruby ABI version of development builds into accounts, which cannot be done with a key, but needs the commit hash. * Using restore-keys would grow the cache over time and have extra gems in the cache. * Those reasons are summarized in https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby#caching-bundle-install-manually
diff --git a/examples.md b/examples.md
@@ -468,21 +468,18 @@ Replace `~/.local/share/renv` with the correct `path` if not using Ubuntu.
 
 ## Ruby - Bundler
 
-```yaml
-- uses: actions/cache@v2
-  with:
-    path: vendor/bundle
-    key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
-    restore-keys: |
-      ${{ runner.os }}-gems-
-```
-When dependencies are installed later in the workflow, we must specify the same path for the bundler.
+Caching gems with Bundler correctly is not trivial and just using `actions/cache`
+is [not enough](https://github.com/ruby/setup-ruby#caching-bundle-install-manually).
+
+Instead, it is recommended to use `ruby/setup-ruby`'s
+[`bundler-cache: true` option](https://github.com/ruby/setup-ruby#caching-bundle-install-automatically)
+whenever possible:
 
 ```yaml
-- name: Bundle install
-  run: |
-    bundle config path vendor/bundle
-    bundle install --jobs 4 --retry 3
+- uses: ruby/setup-ruby@v1
+  with:
+    ruby-version: ...
+    bundler-cache: true
 ```
 
 ## Rust - Cargo
