Last updated October 08, 2025

Bundler can be configured locally by using the command bundle config, which can either set global options or local options in a .bundle/config file. We recommend that you do not check this .bundle/config file into your source control as it contains local paths that can vary from system to system. Instead, it is recommended that you use environment variables to configure Bundler on Heroku.

Environment variable behavior

Most settings that you want to pass as arguments to bundle install can be set via an environment variable. For example, instead of bundle install --without development:test:ci, you can configure Bundler using a BUNDLE_ prefix environment variable. For the --without flag, this would be:

$ heroku config:set BUNDLE_WITHOUT=development:test:ci

Gem source username and password

For gem sources that are password-protected, you can set a username and password using a specially crafted environment variable. For example, if you are trying to connect to a secure gem server on contribsys.com, you previously would have added this to your Gemfile:

gem "mygem", source: "https://#{ ENV['CONTRIBSYS_USERNAME_PASSWORD'] }@gems.contribsys.com"

Now, instead, you can declare your source without a username and password:

gem "mygem", source: "https://gems.contribsys.com"

Then, in your config, you can set the username and password:

$ heroku config:set BUNDLE_GEMS__CONTRIBSYS__COM=<username>:<password>

You will have to set the environment variable based on the domain name of the source you want. Periods are not valid in environment variables, so you can use a double underscore __ to indicate a period.

You can verify your environment variable formatting by running bundle config locally and using that environment variable:

$ env BUNDLE_GEMS__CONTRIBSYS__COM=<username>:<password> bundle config

gems.contribsys.com
Set via BUNDLE_GEMS__CONTRIBSYS__COM: "<username>:<password>"

You’ll need to replace username and password with your actual values. Don’t forget to put a colon between the two. Other common example:

• To access https://gem.fury.io use the Bundler environment variable BUNDLE_GEM__FURY__IO.
• To access https://packagecloud.io use the Bundler environment variable BUNDLE_PACKAGECLOUD__IO.

To verify that this is working, you can install the protected gems locally. First, uninstall the gem locally. For example, if you are using Sidekiq in your Gemfile:

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

You’ll need to remove your already installed gem from your local machine:

$ gem uninstall sidekiq-pro

Then verify the re-install works correctly:

$ BUNDLE_GEMS__CONTRIBSYS__COM=<username>:<password> bundle install

If that fails locally then it will also fail on Heroku.

If you are getting an error message while deploying to Heroku:

Authentication is required for https://gems.contribsys.com/.
Please supply credentials for this source.

Verify that the installation works locally using the above steps.

Gem build configuration settings

Some gems that have native extensions may need additional flags provided directly to the gem at install time.

For example, the mysql gem needs to know where to find the configuration options. If you were to gem install this on a system, you would have to run a command with the --with-mysql-config flag like this:

$ gem install mysql -- --with-mysql-config=<path/to/mysql_config>

Bundler supports passing these flags through build settings. The key is build.<name-of-gem>. For MySQL, it would be build.mysql. The environment variable version would be BUNDLE_BUILD__MYSQL. You could set this value on Heroku using:

$ heroku config:set BUNDLE_BUILD__MYSQL=<path/to/mysql_config>

As with gem source, you can check your environment variable formatting using bundle config locally:

$ env BUNDLE_BUILD__MYSQL="--with-mysql-config=<path/to/mysql_config>" bundle config
# ...

build.mysql
Set via BUNDLE_BUILD__MYSQL: "--with-mysql-config=<path/to/mysql_config>"