Tuesday, August 9, 2011

Get Your Ruby Project on Travis and Have a Martini in 15 Minutes

Almost overnight, every Ruby project out there seem to be moving to Travis. Travis is a dead-simple, community-owned build system. I'm usually too lazy to put all my projects on automated build. Travis took away my excuses by getting me from zero to the first build in a matter of minutes.

Here are step-by-step instructions to get your project on Travis and have a delicious Martini Cocktail in about 15 minutes. Please note that preparing the Martini will take about 5 minutes, so the Travis part should take just 10 minutes of your life.

Check That Your Project Has What It Takes (2 minutes)

Your project needs three prerequisites to get on Travis:
  1. It's a Ruby project on GitHub.
  2. It uses Bundler to manage its gems. (Actually, that’s not strictly necessary, but it will make it easier to set up Travis.)
  3. You can run the project's tests with a single command. A Rake task is typical, but other commands (like, say, bundle exec rspec spec) are also fine.
Ultimately, you should be able to test your project on a new machine by just doing a bundle install followed by the test command. If your setup is more complicated, then you'll need extra work to put the project on Travis. It's probably a good idea to make your project very easy to setup, whether or not you want to use Travis.

I’ll assume that your project meets the three prerequisites, and that you can run your test with bundle exec rake test.

Create a Travis Configuration File (3 minutes)

Commit a new file named .travis.yml in your project root. Here is what mine looks like:

All the entries have sensible defaults, so your configuration could be even simpler. For example, if you skip the script property, then Travis will try bundle exec rake, or just rake if you're not using Bundler. You can find more details on the Travis configuration page.

Activate Your Project on Travis (2 minutes)

Go to http://travis-ci.org and sign in with your GitHub account. Grant Travis read/write access to your GitHub. You should see your private Travis build token on your profile page:

You don't really need to care about the token now - but while you’re on the profile page, flip the switch for the project that you want to build with Travis.

Run Your First Build (3 minutes)

Push to your git repository (make sure that you committed the .travis.yml file), then go to the Travis home page and sit back as Travis adds your project to its build queue, installs the bundle and runs the tests. When the build is done, check your email to find a little love message from Travis - and congratulations for getting it green (or red)!

If You're Curious...

Why did Travis require write access to your GitHub account? That's because Travis automagically configures GitHub to be notified when you push to the project. Go check it if you like: on your project's admin page on GitHub, follow Service Hooks, and click on the Travis hook. The configuration should look like this:

If you click Test Hook, Travis should schedule a build right now.

Prepare the Martini (5 minutes)

Fill a frozen cocktail glass with cold gin, add a touch of vermouth and stir. Garnish with an olive.

(If you’re in a hurry, you can merge this step with the previous one, thus sparing 3 minutes and keeping yourself busy as Travis is building your project.)

Drink the Martini (extra quality time)

I don’t think you need my help here. Just find good company and enjoy. Drink responsibly!