Building a Ruby Project
What This Guide Covers #
Language versions and other build-environment specific information are in our reference pages:
Specifying Ruby versions and implementations #
The Ruby environment on Travis CI uses RVM to provide many Ruby implementations, versions and even patch levels.
To specify them, use the
rvm: key in your
language: ruby rvm: - 2.5 - 2.6 - jruby - truffleruby
Note that the
rvm:key is only available in Ruby Build Environments, not in other images containing a ruby implementation.
As we upgrade both RVM and Rubies, aliases like
jruby point to
different exact versions and patch levels.
If the ruby version is not specified by the
rvm key, Travis CI uses the
version specified in the
.ruby-version file in the root of the repository if
one is available.
If you’re using macOS or Trusty environments, you can also use
Rubinius. To test with Rubinius, add
.travis.yml, where X.Y.Z specifies a Rubinius release listed on
language: ruby dist: trusty rvm: - rbx-3
To test with TruffleRuby, simply add
truffleruby-VERSION to your
language: ruby rvm: - truffleruby # latest release # or - truffleruby-19.2.0 # specific version
JRuby: C extensions are not supported #
Please note that C extensions are not supported in JRuby on Travis CI. The reason for doing so is to bring it to developers attention that their project may have dependencies that should not be used on JRuby in production. Using C extensions on JRuby is technically possible but is not a good idea performance and stability-wise and we believe continuous integration services like Travis CI should highlight it.
So if you want to run CI against JRuby, please check that your Gemfile takes JRuby into account. Most popular C extensions these days also have Java implementations (json gem, nokogiri, eventmachine, bson gem) or Java alternatives (like JDBC-based drivers for MySQL, PostgreSQL and so on).
Default Build Script #
On Ruby projects the default build script is
rake to the
group of your Gemfile.
Build Config Reference #
Dependency Management #
Travis CI uses Bundler to install your Ruby project’s dependencies if there is a Gemfile in the project’s root directory, or if there is a Gemfile specified in the build matrix:
bundle install --jobs=3 --retry=3
If a Gemfile.lock exists in your project’s root directory, we add the
If you want to use a different means of handling your Ruby project’s
dependencies, you can override the
install: gem install rails
By default, gems are installed into vendor/bundle in your project’s root directory.
Bundler 2.0 #
On January 3rd 2019 the Bundler team released Bundler 2.0 which requires Ruby 2.3+. A subsequent 2.0.1 release lowered the required RubyGems version to 2.5.0, which is available by default on Ruby 2.3+.
Therefore, there is no need to update RubyGems for Bundler 2.
TravisCI uses Bundler 1 by default.
Gemfile.lock has a
BUNDLED WITH 1.x section (or no such section),
the default behavior should be enough and require no changes.
If you find your builds are failing due to “bundler not installed” errors or want to use Bundler 2.0, try one of the following solutions:
If you’re using Ruby 2.3 or higher, and you wish to upgrade to Bundler 2.0, use the following in your
before_install: - gem install bundler
If you’re using a version of Ruby lower than 2.6 and want to use Bundler 2.x, make sure to upgrade to a newer version of RubyGems. On the default version of RubyGems shipped with older versions of Ruby, the Bundler version in
Gemfile.lockmust match exactly the version being used, or it will error. It’s fixed in more recent RubyGems releases.
before_install: - yes | gem update --system --force - gem install bundler
It’s necessary to pipe
gem update --systemcommand because of a separate issue involving older versions of RubyGems shipping with a bad binstub, which prompts interactive confirmation from the user.
If you are using Ruby 2.3.x but wish to explicitly stay on Bundler 1.x (e.g., for dependency reasons such as Rails 4.2.x), write:
before_install: - gem uninstall -v '>= 2' -i $(rvm gemdir)@global -ax bundler || true - gem install bundler -v '< 2'
gem uninstallcommand above removes any Bundler 2.x installed in RVM’s “global” gemset during the Ruby installation by RVM, which would be selected as the default
bundlecommand. We ignore the failure from that command, because the failure most likely means that there was no matching Bundler version to uninstall.
Your build configuration may require a combination of these workarounds.
Caching Bundler #
Bundler installation can take a while, slowing down your build. You can tell Travis CI to cache the installed bundle.
On your first build, we warm the cache. On the second one, we’ll pull in the
bundle install only take seconds to run.
Speeding up your build by excluding non-essential dependencies #
Lots of project include libraries like
in their default set of gems.
This slows down the installation process quite a lot, and commonly, those libraries aren’t needed when running your tests. This also includes libraries that compile native code, slowing down the installation and overall test times even more.
On top of that, libraries that implicitly pull in
linecache19, are bound to fail when Travis CI upgrades Ruby versions and
The same is true for gems that you only need in production, like Unicorn, the New Relic library, and the like.
You can speed up your installation process by moving these libraries to a
separate section in your Gemfile, e.g.
group :production do gem 'unicorn' gem 'newrelic_rpm' end
Adjust your Bundler arguments to explicitly exclude this group:
bundler_args: --without production
Enjoy a faster build, which is also less prone to compilation problems.
Custom Bundler arguments and Gemfile locations #
The default Gemfile location is the
Gemfile in the root of your project.
To specify a custom Gemfile name or location:
If you specify the location of your Gemfile in this way, the build will fail if the file is not found.
You can pass extra arguments
Testing against multiple versions of dependencies #
Many projects need to be tested against multiple versions of Rack, EventMachine, HAML, Sinatra, Ruby on Rails,etc.
To test against multiple versions of dependencies:
- Create a directory in your project’s repository root where you will keep
gemfiles, such as
- Add one or more gemfiles to it.
- Set the
gemfilekey in your
Thoughtbot’s Paperclip is tested against multiple ActiveRecord versions:
gemfile: - gemfiles/rails2.gemfile - gemfiles/rails3.gemfile - gemfiles/rails3_1.gemfile
An alternative to this is to use environment variables and make your test runner use them. For example, Sinatra is tested against multiple Tilt and Rack versions:
env: - "rack=1.3.4" - "rack=master" - "tilt=1.3.3" - "tilt=master"
ChefSpec is tested against multiple Chef versions:
env: - CHEF_VERSION=14.3.37 - CHEF_VERSION=13.10.0 - CHEF_VERSION=12.22.5
The same technique is often applied to test against multiple databases, templating engines, hosted service providers and so on.
$BUNDLE_GEMFILE environment variable #
gemfile is defined and a Gemfile file exists in the repository,
we define the environment variable
uses to resolve dependencies.
If you need to work with multiple Gemfiles within a single job, override
$BUNDLE_GEMFILE by passing the
bundle install --gemfile=my_gemfile
JRuby: Testing against multiple JDKs #
Test projects against multiple JDKs, by using the
jdk key in your
jdk: - oraclejdk7 - openjdk7 - oraclejdk8
Each JDK you test against will create permutations with all other configurations, so to avoid running tests for, say, CRuby 1.9.3 multiple times you need to add some matrix excludes (described in our Build Configuration guide):
language: ruby rvm: - 1.9.2 - jruby-18mode - jruby-19mode - jruby-head jdk: - openjdk6 - openjdk7 - oraclejdk7 jobs: exclude: - rvm: 1.9.2 jdk: openjdk6 - rvm: 1.9.2 jdk: openjdk7 - rvm: 1.9.2 jdk: oraclejdk7
For example, see travis-support.
Using Java 10 and Up #
For testing with OpenJDK and OracleJDK 10 and up, see Java documentation.
Upgrading RubyGems #
The RubyGems version installed on Travis CI’s Ruby environment depends on what’s installed by the newest Bundler/RubyGems combination, and is kept as up-to-date as possible.
Should you require the latest version of RubyGems, you can add the following to
before_install: - gem update --system - gem --version
To downgrade to a specific version of RubyGems:
before_install: - gem update --system 2.1.11 - gem --version
Note that this will impact your overall test time, as additional network downloads and installations are required.