Docs menu

Package managers

How Bundler works on Primcloud: Gemfile.lock enforcement, private gem sources via credentials, and the environment applied during bundle install.

On this page

Ruby has exactly one package manager on Primcloud: Bundler. Every gem you declare in a Gemfile and resolve into Gemfile.lock gets installed by Bundler during the build. There's no second package-manager surface to choose between: a Gemfile and Gemfile.lock at the repo root are both required, and they're the only inputs the build reads.

Supported package managers#

Bundler. Version resolved from Gemfile.lock's BUNDLED WITH line:

Gemfile.lock
BUNDLED WITH
   2.5.23

Without that line, you get a default Bundler version. Pinning it means your local bundle and Primcloud's bundle behave identically, which is recommended.

Gemfile.lock is required. Detection fails without it; see Ruby on Primcloud → Detection. Bundler produces the lockfile the first time you run bundle install locally; commit it alongside your Gemfile.

Install behavior#

Every deploy runs bundle install with these settings:

Variable Value Effect
BUNDLE_FROZEN 1 The install fails if Gemfile.lock doesn't match Gemfile.
BUNDLE_WITHOUT development:test Skips the development and test groups.

Afterward, bundle clean removes gems that are no longer in your lockfile.

Two settings are commonly changed with secrets:

  • BUNDLE_WITHOUT to exclude different groups, like development:test:doc.
  • BUNDLE_JOBS to download gems in parallel. Bundler's default is 1.

Private packages and registries#

Private gem sources are supported through Bundler's env-var credential mechanism. Bundler reads credentials for a source from an environment variable whose name is derived from the source's hostname.

Example. For https://gems.contribsys.com:

Gemfile
source "https://rubygems.org"

source "https://gems.contribsys.com/" do
  gem "sidekiq-pro"
end

Then under Settings → Secrets, set:

BUNDLE_GEMS__CONTRIBSYS__COM=username:password

The naming convention: prefix BUNDLE_, then the hostname in uppercase with every . replaced by a double underscore. A few examples:

Source URL Variable
https://gems.contribsys.com BUNDLE_GEMS__CONTRIBSYS__COM
https://gem.fury.io BUNDLE_GEM__FURY__IO
https://packagecloud.io BUNDLE_PACKAGECLOUD__IO

Bundler resolves the credential at restore time and injects it into the outbound request.

Verify locally with:

Terminal
BUNDLE_GEMS__CONTRIBSYS__COM=username:password bundle install

If that command works, the same value set on the environment will work on Primcloud.

Lockfiles#

Gemfile.lock is required. The build refuses to start without it. Bundler runs in deployment/frozen mode, which means:

  • The lockfile is treated as authoritative. bundle install will not modify it during a build.
  • If the lockfile disagrees with the current Gemfile (e.g., a gem was added to Gemfile but bundle install wasn't re-run locally), the build fails with a "The Gemfile's dependencies are satisfied, but the lockfile is out of date" or similar Bundler error.

The fix in both cases is the same: run bundle install locally, commit the updated Gemfile.lock, and push.

When you want to loosen this. There's no supported way to opt out of frozen mode for a Primcloud build. Bundler's deployment posture is the safer default and matches how Ruby apps behave in production everywhere else. If you're mid-migration and need to relax it temporarily, regenerate the lockfile locally and commit the result. That's the intended workflow.

Lockfile hygiene. Two common lockfile mistakes cause build failures:

  • Not committing Gemfile.lock. Detection fails outright.
  • Bumping a gem in Gemfile without running bundle install. Frozen mode rejects the resulting mismatch.

Both are caught locally the moment you try to run bundle install on the same tree, so they don't need to be diagnosed against a Primcloud build log. Reproduce with bundle install --frozen on your machine.