Most of us get notified about lots of little events on our projects: Commits, build failures (and fixed builds), and runtime exceptions, for example. But deployment is where the rubber meets the road on web development projects. Deployment to staging means new functionality to try out and test, and of course deployment to production is even more important.

CapGun is a gem we use to send email notifications whenever we deploy one of our projects. It works with Capistrano and uses ActionMailer to let every interested party know when a deployment happens.

Here's how to work with CapGun in a Rails project. Add this to config/environment.rb:

  config.gem 'relevance-cap_gun', 
             :source => "http://gems.github.com/", 
             :lib => "cap_gun"

Then install and unpack the gem:

  $ rake gems:install
  $ rake gems:unpack

Finally, edit your deployment script (usually config/deploy.rb) and add this:

  require File.join(RAILS_ROOT,
                    Dir["vendor/gems/relevance-cap_gun-*/lib"].last,
                    'cap_gun')
  
  set :cap_gun_action_mailer_config, {
    :address => "smtp.gmail.com",
    :port => 587,
    :user_name => "grey-goo@example.com", # deploy bot email address
    :password => "outtacontrol",  # deploy bot email password
    :authentication => :plain 
  }

  set :cap_gun_email_envelope, {
    :recipients => %w[fooproj-devs@example.com fooproj-mgr@example.com], 
    :from => "Foo Project Deployment Bot <grey-goo@example.com>"
  }

  after "deploy:restart", "cap_gun:email"

We usually use GMail as our MTA for this purpose, and CapGun includes support for secure, authenticated email connections so that you can do the same. It's best to create a special-purpose, throwaway email account just for things like this; that way there's little risk in putting the email password in the project deployment script. (But there's also nothing stopping you from reading it from another file that's not checked into source control, just like you would do with your production database passwords. The deploy.rb file is just Ruby code, after all. And if the source is going to be in a public repository, you should definitely do that.)

The deployment email has a brief summary at the top (in fact, the subject often tells you all you need to know). But there are useful details in the body. Here's an example of what you might see from the configuration above:

From: Foo Project Deployment Bot <grey-goo@example.com>
To: fooproj-devs@example.com, fooproj-mgr@example.com
Date: Tue, 15 Sep 2009 17:27:57 -0400
Subject: [DEPLOY] fooproj deployed to production

fooproj was deployed to production by george at September 15th, 2009 5:27 PM EDT.

Nerd details
============
Release: /var/apps/fooproj/releases/20090915212721
Release Time: September 15th, 2009 5:27 PM EDT
Release Revision: 69246739f2a1cbcef5ca76f1842c21849db7778a

Previous Release: /var/apps/fooproj/releases/20090915194707
Previous Release Time: September 15th, 2009 3:47 PM EDT
Previous Release Revision: 9ceb19b1777470d1d5133f433fdd5d1873c7a4c0

Repository: git@github.com:foocorp/fooproj.git
Deploy path: /var/apps/fooproj
Domain: fooproj.example.com
Branch: main

Commits since last release
====================
d37a15c:who put a blink tag in here?
f1b603e:Added favicon

Setting up CapGun only takes a few minutes, and you'll love the increased visibility into your team's deployments. (And even if you're a team of one, you'll appreciate having the emails as a record of your deployments.) Try it out, and let us know what you think!