Cleaner HipChat notifications with Capistrano

Apr 26, 2014

Use more of the API features that are available.

The hipchat gem has many features that the default capistrano integration does not take advantage of. This is quick run down of how I integrated a more full featured use of the gem. This particular walk-through is for integrating with Capistano 3.

First off, in your deploy.rb file require the HipChat gem. We will also need to set a few state wide symbols that will be used throughout the cap tasks. NOTE: DO NOT require 'hipchat/capistrano'. This will cause the old capistrano integration to take over. I have found that the old capistrano hipchat integration to be flawed, mainly confusing stages that are being acted on.

# HipChat client
require 'hipchat'
set :hipchat_token,     "SuperSecretToken"
set :hipchat_room_name, "Deployments"
set :hipchat_user,      "Deploy Bot"
set :hipchat_announce,  true
set :hipchat_client,    HipChat::Client.new(fetch(:hipchat_token))

Note the :hipchat_client symbol. This will be what is used to post notifications throughout the multiple cap tasks.

Next we can add a simple ping task to test the HipChat integration.

namespace :hipchat do
  desc 'Test HipChat API connection'
  task :ping do
    fetch(:hipchat_client)[fetch(:hipchat_room_name)].send(fetch(:hipchat_user), "Test 1, 2... Test! (#{fetch(:stage)})", :notify => fetch(:hipchat_announce), :color => 'purple')
  end
end

What I like about this method is that I am able to control the Username, Message, Notification and Color with every call. Using the capistrano fetch method, I am able to call on the many different state wide variables I have setup to make the overall pattern highly repeatable.

Taking the pattern in the above example, it’s easy to place that into another cap task:

namespace :apache do
  [:start, :stop, :restart, :reload].each do | command_sym |
    desc "#{command_sym} apache services"
    task command_sym do
      on roles(:admin, :web), in: :parallel do |host|
        fetch(:hipchat_client)[fetch(:hipchat_room_name)].send(fetch(:hipchat_user), "#{command_sym}ing apache servers on #{host.hostname} (#{fetch(:stage)})", :notify => fetch(:hipchat_announce), :color => 'blue')
        sudo "/etc/rc.d/init.d/httpd #{command_sym}"
      end
    end
  end
end

I love capistrano.