GitHub Actions ruby/setup-ruby bundler-cache Fails to Restore Gems

ruby/setup-ruby with bundler-cache: true runs bundle install and caches the gems. It fails when there is no committed Gemfile.lock to key the cache on, or when the underlying gem fetch errors.

What this error means

The setup-ruby step fails during dependency installation, complaining about a missing lockfile or a gem that could not be fetched. With bundler-cache enabled, setup-ruby owns the bundle install, so the failure surfaces there.

Actions log

Error: bundler-cache requires a Gemfile.lock to be checked in
# or
Could not reach https://rubygems.org/ (transient fetch error)

Common causes

No committed Gemfile.lock

bundler-cache keys the cache on Gemfile.lock. If the lockfile is gitignored or absent, setup-ruby has nothing stable to cache against and errors.

Transient gem index/network fetch failure

bundle install pulls gems over the network. A brief rubygems.org or source outage makes the install step fail even though the configuration is correct.

How to fix it

Commit the lockfile and enable the cache

.github/workflows/ci.yml

- uses: ruby/setup-ruby@v1
  with:
    ruby-version: '3.3'
    bundler-cache: true   # needs a committed Gemfile.lock

Re-run transient fetch failures

A failed gem fetch from a source blip is an infrastructure issue, not a config bug. Re-running on a healthy runner usually succeeds once the index is reachable again.

How to prevent it

Commit Gemfile.lock so bundler-cache has a stable cache key.
Keep ruby/setup-ruby on v1 (it tracks rolling fixes).
Retry transient gem-source fetch failures rather than disabling the cache.