What’s this?

Integrity is the angel watching over your shoulder while you code. As soon as you push your commits, it builds, runs your tests, and makes sure everything works fine.

It then reports the build status using various notifiers back to your team so everyone’s on the same page, and if there’s a problem, you can get it fixed right away.

Read more about Continuous Integration on Wikipedia.

Live demo

See how integrity works for yourself on our own install, watching Integrity itself and the various notifiers.

Installation and deployment

It’s ridiculously easy. All you need is to have ruby and rubygems installed on your server, and then run the built-in installer and follow the instructions.

$ gem install integrity
$ integrity install /home/www-data/integrity

This will create a couple files on your server, mainly config.yml and config.ru.

The installer provides special configuration files for Thin and Passenger.

Passenger

$ integrity install --passenger ~www-data/integrity
$ cd ~www-data/integrity

Then, tell Passenger to start your app: $ touch tmp/restart.txt

Thin

Install Thin if necessary:
```
 $ gem install thin
```

Run the installer:

 $ integrity install --thin ~www-data/integrity
 $ cd ~www-data/integrity`

Tweak thin.yml to your need if necessary.
Then, to start the Thin server, just do this:
```
 $ thin -C thin.yml -R config.ru start
```

Heroku

Install the Heroku gem if necessary.
```
 $ gem install heroku
```

Run the installer, passing it the --heroku option.

 $ integrity install --heroku ~www-data/integrity
 $ cd ~www-data/integrity

Git-ify it.

 $ git init
 $ git add .
 $ git commit -am "Initial import"

Heroku-ify it.
```
 $ heroku create
```

Edit the :base_uri option in integrity-config.rb. It should now look something like this:

 require "rubygems"
 gem "integrity"
 require "integrity"

 Integrity.config = {
   :base_uri         => 'http://mydomain.tld' # Edited this!
   :database_uri     => ENV["DATABASE_URL"],
   :export_directory => File.dirname(__FILE__) + "/tmp",
   :log              => File.dirname(__FILE__) + "/log/integrity.log",
   # Uncomment to setup a password
   # :use_basic_auth   => true,
   # :admin_username   => "admin",
   # :admin_password   => "foobar"
 }

 Integrity.new

Get it up and running on Heroku.

 $ git push heroku master
 $ heroku rake db:migrate

You may also want to install, say, the integrity-email gem. Simply list it on its own line in the .gems manifest:

    integrity --version 0.1.9.3
    integrity-email # Add that line

(You’ll want to go edit integrity-config.rb to require it, as well.)

Configure a web proxy

nginx

http {
  upstream builder-integrityapp-com {
    server 127.0.0.1:8910;
    server 127.0.0.1:8911;
  }

  server {
    server_name builder.integrityapp.com;
    location / {
      proxy_pass http://builder-integrityapp-com;
    }
  }
}

Apache acting as reverse proxy to a cluster of thin instances

<VirtualHost *>
  <Proxy>
    Order deny,allow
    Allow from all
  </Proxy>

  RedirectMatch ^/integrity$ /integrity/
  ProxyRequests Off
  ProxyPass /integrity/ http://localhost:8910/
  ProxyHTMLURLMap http://localhost:8910 /integrity

  <Location /integrity>
    ProxyPassReverse /
    SetOutputFilter proxy-html
    ProxyHTMLURLMap / /integrity/
    ProxyHTMLURLMap /integrity/ /integrity
  </Location>
</VirtualHost>

If you run Integrity behind Passenger, or other deployment strategy, drop us a line at info@integrityapp.com and let us know what config worked for you so we can include it here :-)

Configuration

This step should be pretty pretty stepforward. You only need to touch one file:

/path/to/integrity/config.yml

All options are explained in the file. In case you want to see them anyway, you can see the source file on GitHub.

Notifiers

After a build is finished, you want to know the status immediately. Integrity gives you a modular notification’s system for this.

With Integrity, you can receive your notifications in a few different ways. Currently, we maintain three notifiers:

There are other available notifiers as well, but we do not maintain them, which mean they might not work.

NOTE: If you wrote a notifier for something else, let us know at info@integrityapp.com and we’ll add you here :)

Setting up your notifier

Also a piece of cake. For example, for email notifications:

$ gem install integrity-email

And then edit the config.ru file in your Integrity install directory:

require "rubygems"
require "integrity"

# You need to add the following line:
require "integrity/notifier/email"

Finally, restart Integrity. That’s it. Now you can browse to http://ci.example.org/my-project/edit and configure your notifier.

NOTE: Due to recent changes in Integrity’s internals, notifiers now needs to be registered. However, all notifiers haven’t been updated yet, so you might have to do it yourself into the config.ru file:

require "rubygems"
require "integrity"
require "integrity/notifier/email"

Integrity::Notifier.register(Integrity::Notifier::Email)

FAQ

But does it work with <insert tech here>?

Short answer: Yeah!

Slightly longer answer: as long as your build process can be run from an unix-y environment and it returns a zero status code for success and non-zero for failure, then integrity works for you.

How to use Integrity with a local repository?

Set the project URI’s to point to the .git directory of the repository: /home/sr/code/integrity/.git

How do I use git submodules with Integrity?

Use this as your build command: git submodule update --init && rake test It’ll fetch and update the submodules everytime the project is build.

How to handle database.yml and similar unversioned files?

Integrity is dumb. it takes a repository URL and a command to run in a working copy of the former. It then reports success or failure depending on the exit status of the command.

While this is very simplistic, it allows for great flexibility: you can use whatever you want as the build command.

So, to handle database.yml, you can either use a build command like this:

cp config/database.sample.yml config/database.yml && rake test

Or use a Rake task. Example:

namespace :test do
  task :write_test_db_config do
    file = File.join(Rails.root, "config", "database.yml")
    File.open(file), "w") { |config|
      config << "...."
    }
  end
end

How do I use metric_fu ?

Basically, it’s the same as for database.yml. See our Rakefile for an example.

Support / Development

You can get in touch via IRC at #integrity on freenode. If no one happens to be around the IRC channel, you can ask in our Google Group.

If you find a bug, or want to give us a feature request, drop by our Lighthouse tracker.

If you want to check out the code, you can do so at our GitHub project

Integrity

the easy and fun automated continuous integration server