README.md

Slackistrano

Send notifications to Slack about Capistrano deployments.

NOTE: This README documents version >=3.1.0. You can read about 3.0.1 here.

Requirements

• Capistrano >= 3.5.0
• Ruby >= 2.0
• A Slack account

Installation

1. Add this line to your application's Gemfile:

   gem 'slackistrano'

2. Execute:

   $ bundle
   

3. Require the library in your application's Capfile:

   require 'slackistrano/capistrano'

Configuration

You have two options to notify a channel in Slack when you deploy:

1. Using Incoming WebHooks integration, offering more options but requires one of the five free integrations. This option provides more messaging flexibility.
2. Using Slackbot, which will not use one of the five free integrations.

Incoming Webhook

1. Configure your Slack's Incoming Webhook.

2. Add the following to config/deploy.rb:

   set :slackistrano, {
     channel: '#your-channel',
     webhook: 'your-incoming-webhook-url'
   }

Slackbot

1. Configure your Slack's Slackbot (not Bot).

2. Add the following to config/deploy.rb:

   set :slackistrano, {
     channel: '#your-channel',
     team: 'your-team-name',
     token: 'your-token'
   }

Test your Configuration

Test your setup by running the following command. This will post each stage's message to Slack in turn.

$ cap production slack:deploy:test

Usage

Deploy your application like normal and you should see messages in the channel you specified.

Customizing the Messaging

You can customize the messaging posted to Slack by providing your own messaging class and overriding several methods. Here is one example:

module Slackistrano
  class CustomMessaging < Messaging::Base

    # Send failed message to #ops. Send all other messages to default channels.
    # The #ops channel must exist prior.
    def channels_for(action)
      if action == :failed
        "#ops"
      else
        super
      end
    end

    # Suppress updating message.
    def payload_for_updating
      nil
    end

    # Suppress reverting message.
    def payload_for_reverting
      nil
    end

    # Fancy updated message.
    # See https://api.slack.com/docs/message-attachments
    def payload_for_updated
      {
        attachments: [{
          color: 'good',
          title: 'Integrations Application Deployed :boom::bangbang:',
          fields: [{
            title: 'Environment',
            value: stage,
            short: true
          }, {
            title: 'Branch',
            value: branch,
            short: true
          }, {
            title: 'Deployer',
            value: deployer,
            short: true
          }, {
            title: 'Time',
            value: elapsed_time,
            short: true
          }],
          fallback: super[:text]
        }]
      }
    end

    # Default reverted message.  Alternatively simply do not redefine this
    # method.
    def payload_for_reverted
      super
    end

    # Slightly tweaked failed message.
    # See https://api.slack.com/docs/message-formatting
    def payload_for_failed
      payload = super
      payload[:text] = "OMG :fire: #{payload[:text]}"
      payload
    end

    # Override the deployer helper to pull the full name from the password file.
    # See https://github.com/phallstrom/slackistrano/blob/master/lib/slackistrano/messaging/helpers.rb
    def deployer
      Etc.getpwnam(ENV['USER']).gecos
    end
  end
end

The output would look like this:

To set this up:

1. Add the above class to your app, for example lib/custom_messaging.rb.

2. Require the library after the requiring of Slackistrano in your application's Capfile.

   require_relative 'lib/custom_messaging'

3. Update the slackistrano configuration in config/deploy.rb and add the klass option.

   set :slackistrano, {
     klass: Slackistrano::CustomMessaging,
     channel: '#your-channel',
     webhook: 'your-incoming-webhook-url'
   }

4. If you come up with something that you think others would enjoy submit it as an issue along with a screenshot of the output from cap production slack:deploy:test and I'll add it to the Wiki.

Disabling posting to Slack

You can disable deployment notifications to a specific stage by setting the :slackistrano configuration variable to false instead of actual settings.

set :slackistrano, false

TODO

• Notify about incorrect configuration settings.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request