RubyGems "Gem::FilePermissionError ... Permission denied" in CI

gem install tried to write into a system gem directory owned by root while the job runs as an unprivileged user. RubyGems refuses with a permission error rather than installing where it cannot write.

What this error means

gem install or bundle install fails with "Gem::FilePermissionError: You don't have write permissions for the /usr/lib/ruby/gems/... directory."

ERROR:  While executing gem ... (Gem::FilePermissionError)
    You don't have write permissions for the /usr/local/lib/ruby/gems/3.3.0 directory.

Common causes

Installing into a root-owned system gem path

The default GEM_HOME points at a system directory owned by root, but the CI step runs as a non-root user, so the write is denied.

A container that drops root mid-job

A step switches to an unprivileged user yet still targets the system gem directory created as root.

How to fix it

Install gems into a user-writable path

1. Set a project-local bundle path that the job user can write.
2. Run bundle install against that path.
3. Use the same path for bundle exec so gems are found.

bundle config set --local path vendor/bundle
bundle install

Point GEM_HOME at a writable directory

Direct gem installs to a user-owned location via GEM_HOME and PATH.

export GEM_HOME="$HOME/.gem"
export PATH="$GEM_HOME/bin:$PATH"
gem install bundler

How to prevent it

• Install gems into vendor/bundle or a user GEM_HOME in CI.
• Avoid writing to system gem directories as a non-root user.
• Use setup-ruby, which configures a writable gem path.

Related guides