slackistrano 3.0.1 → 3.1.0.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d61845e7cdfae5f62970368fb7151e5c2e01a525
-  data.tar.gz: 8b29ea88f33d79f8430f185bcf3d88a6bf9f79eb
+  metadata.gz: 896df176f220863aab32aa8e816f4b466dc9a105
+  data.tar.gz: 2f80f45cf424c0490be715670ccea02117a33376
 SHA512:
-  metadata.gz: 26f4396d6d1ab40bebc9e66d26a43ad31b7d178c9444354031d5f20206b3ee34795dd9f06f331adcfa070c0e61da591888458e909d501e82a1054da0529f29da
-  data.tar.gz: 05fe08acd7d3a21495bbdabe64001a6d79ecf5e1f12360b23b564af01bb324a7a0b56ace54981e6379663cc90fd40d7b5ee3ea2b922f4d5eed1030d44615d636
+  metadata.gz: 17ca0ce1996dc7ec7b54f18d3804b949f4ff73d58a0ccae28a4124aba7d764971108296941b6d37a37eec61585a2746ae2677ea06c3867f8ee9da376cc0569a2
+  data.tar.gz: d407a73ccec54c17c2ae891480976a24ef747b93e1953417009e3fabaa8bdf28e0259b143438349b5775a77cdf172ba058eef755b1eaeb8426bf3a4ff33f69e4

data/README.md

@@ -6,181 +6,178 @@
 
 Send notifications to [Slack](https://slack.com) about [Capistrano](http://www.capistranorb.com) deployments.
 
-If you need Capistrano v2 support, check out [capistrano-slack](https://github.com/j-mcnally/capistrano-slack).
-
-## NOTE: Upgrading from 1.x? Not Getting Notifications?
-
-Version 2.0 has changed how Slackistrano must be loaded in your Gemfile and Capfile. See the *Installation* section
-below current install.
+**NOTE:** This README documents version 3.1.0.beta. You can read about 3.0.1 [here](https://github.com/phallstrom/slackistrano/tree/v3.0.1).
 
 ## Requirements
 
-- Capistrano >= 3.1.0
+- Capistrano >= 3.5.0
 - Ruby >= 2.0
 - A Slack account
 
 ## Installation
 
-Add this line to your application's Gemfile:
+1. Add this line to your application's Gemfile:
 
-```ruby
-gem 'slackistrano'
-```
+   ```ruby
+   gem 'slackistrano'
+   ```
 
-And then execute:
+2. Execute:
 
-```bash
-$ bundle
-```
+   ```
+   $ bundle
+   ```
+
+3. Require the library in your application's Capfile:
+
+   ```ruby
+   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 is the default option.
- 2. Using *Slackbot*, which will not use one of the five free integrations. Enable via the `:slack_via_slackbot` option.
+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.
 
-In both case, you need to enable the integration inside Slack and get the token and/or webhook url that will be needed later.
+### Incoming Webhook
 
-Require the library in your application's Capfile:
+1. Configure your Slack's Incoming Webhook.
+2. Add the following to `config/deploy.rb`:
 
-```ruby
-require 'slackistrano/capistrano'
-```
+   ```ruby
+   set :slackistrano, {
+     channel: '#your-channel',
+     webhook: 'your-incoming-webhook-url'
+   }
+   ```
 
-If you post using *Incoming Webhooks* you need to set your webhook url in your application's config/deploy.rb:
+### Slackbot
 
-```ruby
-set :slack_webhook, "https://hooks.slack.com/services/XXX/XXX/XXX"
-```
+1. Configure your Slack's Slackbot (not Bot).
+2. Add the following to `config/deploy.rb`:
 
-If you choose to post using *Slackbot* you **must** set your team, token, and channel in your application's config/deploy.rb:
+   ```ruby
+   set :slackistrano, {
+     channel: '#your-channel',
+     team: 'your-team-name',
+     token: 'your-token'
+   }
+   ```
 
-```ruby
-set :slack_via_slackbot, true
-set :slack_team, "teamname"
-set :slack_token, "xxxxxxxxxxxxxxxxxxxxxxxx"
-set :slack_channel, '#general'
-```
+### Test your Configuration
 
-You can set `:slack_channel` (or any of the `:slack_channel_xxxx` settings) to an array and Slackistrano
-will post to each channel. For example:
+Test your setup by running the following command. This will post each stage's
+message to Slack in turn.
 
-```ruby
-set :slack_channel, ['#general', '#ops']
 ```
-
-Optionally, override the other slack settings.
-
-```ruby
-set :slack_channel_updating,   -> { nil } # Channel to post to. Defaults to :slack_channel.
-set :slack_channel_reverting,  -> { nil } # Channel to post to. Defaults to :slack_channel.
-set :slack_channel_updated,    -> { nil } # Channel to post to. Defaults to :slack_channel.
-set :slack_channel_reverted,   -> { nil } # Channel to post to. Defaults to :slack_channel.
-set :slack_channel_failed,     -> { nil } # Channel to post to. Defaults to :slack_channel.
-
-set :slack_icon_url,           -> { 'http://gravatar.com/avatar/885e1c523b7975c4003de162d8ee8fee?r=g&s=40' }
-set :slack_icon_emoji,         -> { nil } # Emoji to use. Overrides icon_url. Must be a string (ex: ':shipit:')
-set :slack_username,           -> { 'Slackistrano' }
-
-set :slack_run,                -> { true } # Set to false to disable all messages.
-set :slack_run_updating,       -> { true } # Set to false to disable deploy starting message.
-set :slack_run_reverting,      -> { true } # Set to false to disable rollback starting message.
-set :slack_run_updated,        -> { true } # Set to false to disable deploy finished message.
-set :slack_run_reverted,       -> { true } # Set to false to disable rollback finished message.
-set :slack_run_failed,         -> { true } # Set to false to disable failure message.
-
-set :slack_deploy_user,        -> { ENV['USER'] || ENV['USERNAME'] }
-
-set :slack_msg_updating,       -> { "#{fetch :slack_deploy_user} has started deploying branch #{fetch :branch} of #{fetch :application} to #{fetch :stage, 'an unknown stage'}" }
-set :slack_msg_reverting,      -> { "#{fetch :slack_deploy_user} has started rolling back branch #{fetch :branch} of #{fetch :application} to #{fetch :stage, 'an unknown stage'}" }
-set :slack_msg_updated,        -> { "#{fetch :slack_deploy_user} has finished deploying branch #{fetch :branch} of #{fetch :application} to #{fetch :stage, 'an unknown stage'}" }
-set :slack_msg_reverted,       -> { "#{fetch :slack_deploy_user} has finished rolling back branch of #{fetch :application} to #{fetch :stage, 'an unknown stage'}" }
-set :slack_msg_failed,         -> { "#{fetch :slack_deploy_user} has failed to #{fetch :slack_deploy_or_rollback} branch #{fetch :branch} of #{fetch :application} to #{fetch :stage, 'an unknown stage'}" }
-
-set :slack_fields_updating,    -> { [] }
-set :slack_fields_reverting,   -> { [] }
-set :slack_fields_updated,     -> { [] }
-set :slack_fields_reverted,    -> { [] }
-set :slack_fields_failed,      -> { [] }
-
-set :slack_fallback_updating,  -> { nil }
-set :slack_fallback_reverting, -> { nil }
-set :slack_fallback_updated,   -> { nil }
-set :slack_fallback_reverted,  -> { nil }
-set :slack_fallback_failed,    -> { nil }
-
-set :slack_title_updating,     -> { nil }
-set :slack_title_reverting,    -> { nil }
-set :slack_title_updated,      -> { nil }
-set :slack_title_reverted,     -> { nil }
-set :slack_title_failed,       -> { nil }
-
-set :slack_pretext_updating,   -> { nil }
-set :slack_pretext_reverting,  -> { nil }
-set :slack_pretext_updated,    -> { nil }
-set :slack_pretext_reverted,   -> { nil }
-set :slack_pretext_failed,     -> { nil }
+$ cap production slack:deploy:test
 ```
 
-**Note**: You may wish to disable one of the notifications if another service (ex:
-Honeybadger) also displays a deploy notification.
-
-Test your setup by running:
+## Usage
 
-```bash
-$ cap production slack:deploy:updating
-$ cap production slack:deploy:reverting
-$ cap production slack:deploy:updated
-$ cap production slack:deploy:reverted
-$ cap production slack:deploy:failed
-```
+Deploy your application like normal and you should see messages in the channel
+you specified.
 
-## Formatted messages
+## Customizing the Messaging
 
-Slack allows you to send complex content, composed by fields. You can use the `fields` and `fallback` variables in order to have a well formatted message as follows:
+You can customize the messaging posted to Slack by providing your own messaging
+class and overriding several methods. Here is one example:
 
 ```ruby
-set :slack_revision, `git rev-parse origin/#{fetch(:branch)}`.strip!
-set :slack_msg_updated, nil
-set :slack_fallback_updated, "#{fetch(:slack_deploy_user)} deployed #{fetch(:application)} on #{fetch(:stage)}"
-set :slack_fields_updated, [
-  {
-    title: "Project",
-    value: "<https://github.com/XXXXX/#{fetch(:application)}|#{fetch(:application)}>",
-    short: true
-  },
-  {
-    title: "Environment",
-    value: fetch(:stage),
-    short: true
-  },
-  {
-    title: "Deployer",
-    value: fetch(:slack_deploy_user),
-    short: true
-  },
-  {
-    title: "Revision",
-    value: "<https://github.com/XXXXX/#{fetch(:application)}/commit/#{fetch(:slack_revision)}|#{fetch(:slack_revision)[0..6]}>",
-    short: true
-  }
-]
+module Slackistrano
+  class CustomMessaging < Messaging::Base
+
+    # Send failed message to #ops. Send all other messages to default channels.
+    def channels_for(action)
+      if action == :failed
+        "#ops"
+      else
+        super
+      end
+    end
+
+    # Supress updating message.
+    def payload_for_updating
+      nil
+    end
+
+    # Supress 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: "Application Deployed",
+        fields: [
+          {title: "Project", value: application, short: true},
+          {title: "Environment", value: stage, short: true},
+          {title: "Deployer", value: deployer, short: true},
+          {title: "Time", value: elapsed_time, short: true},
+        ],
+        fallback: super[:text],
+      }]}
+    end
+
+    # Default reverted message.  Alternatively we could have simply not
+    # redefined this method at all.
+    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] = ":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
 ```
 
-It will produce the following format:
-![Formatted message](https://raw.githubusercontent.com/phallstrom/slackistrano/master/examples/fomatting_with_fields.png)
+The output would look like this:
+![Custom Messaging](https://raw.githubusercontent.com/phallstrom/slackistrano/overhaul/images/custom_messaging.jpg)
 
-**Note 1:** *The `fallback` field is required in order to display notifications when using `fields`.*
+To set this up:
 
-**Note 2:** *The `fields` configuration requires you to use webhooks.*
+1. Add the above class to your app, for example `lib/custom_messaging.rb`.
 
-More information: [https://api.slack.com/docs/attachments](https://api.slack.com/docs/attachments)
+2. Require the library after the requiring of Slackistrano in your application's Capfile.
 
-## Usage
+   ```ruby
+   require_relative 'lib/custom_messaging'
+   ```
 
-Deploy your application like normal and you should see messages in the channel
-you specified.
+3. Update the `slackistrano` configuration in `config/deploy.rb` and add the `klass` option.
+
+   ```ruby
+   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.
 
 ## TODO
 

data/lib/slackistrano.rb

@@ -1,7 +1,4 @@
 require 'slackistrano/version'
-require 'net/http'
-require 'json'
 
 module Slackistrano
-
 end

data/lib/slackistrano/capistrano.rb

@@ -1,3 +1,4 @@
+require_relative 'messaging/base'
 require 'net/http'
 require 'json'
 require 'forwardable'
@@ -7,163 +8,121 @@ load File.expand_path("../tasks/slack.rake", __FILE__)
 module Slackistrano
   class Capistrano
 
+    attr_reader :backend
+    private :backend
+
     extend Forwardable
     def_delegators :env, :fetch, :run_locally
 
-    #
-    #
-    #
     def initialize(env)
       @env = env
+      opts = fetch(:slackistrano, {}).dup
+      @messaging = if opts.empty?
+                     klass = Messaging::Deprecated.new(
+                       env: @env,
+                       team: fetch(:slack_team),
+                       channel: fetch(:slack_channel),
+                       token: fetch(:slack_token),
+                       webhook: fetch(:slack_webhook)
+                     )
+                   else
+                     klass = opts.delete(:klass) || Messaging::Default
+                     klass.new(opts.merge(env: @env))
+                   end
     end
 
-    #
-    #
-    #
     def run(action)
-      should_run = fetch("slack_run".to_sym)
-      should_run &&= fetch("slack_run_#{action}".to_sym)
-      return unless should_run
-
       _self = self
-      run_locally { _self.post(action, self) }
-
+      run_locally { _self.process(action, self) }
     end
 
-    #
-    #
-    #
-    def post(action, backend)
-      team = fetch(:slack_team)
-      token = fetch(:slack_token)
-      webhook = fetch(:slack_webhook)
-      via_slackbot = fetch(:slack_via_slackbot)
-
-      channels = fetch(:slack_channel)
-      channel_action = "slack_channel_#{action}".to_sym
-      channels = fetch(channel_action) if fetch(channel_action)
-      channels = Array(channels)
-      if via_slackbot == false && channels.empty?
-        channels = [nil] # default webhook channel
-      end
+    def process(action, backend)
+      @backend = backend
+
+      payload = @messaging.payload_for(action)
+      return if payload.nil?
 
       payload = {
-        username: fetch(:slack_username),
-        icon_url: fetch(:slack_icon_url),
-        icon_emoji: fetch(:slack_icon_emoji),
-      }
-
-      payload[:attachments] = case action
-                              when :updated
-                                make_attachments(action, color: 'good')
-                              when :reverted
-                                make_attachments(action, color: '#4CBDEC')
-                              when :failed
-                                make_attachments(action, color: 'danger')
-                              else
-                                make_attachments(action)
-                              end
+        username: @messaging.username,
+        icon_url: @messaging.icon_url,
+        icon_emoji: @messaging.icon_emoji,
+      }.merge(payload)
 
-      channels.each do |channel|
-        payload[:channel] = channel
-
-        dry_run = if ::Capistrano::Configuration.respond_to?(:dry_run?) 
-                    ::Capistrano::Configuration.dry_run?
-                  else
-                    ::Capistrano::Configuration.env.send(:config)[:sshkit_backend] == SSHKit::Backend::Printer
-                  end
-
-        if dry_run
-          backend.info("[slackistrano] Slackistrano Dry Run:")
-          backend.info("[slackistrano]   Team: #{team}")
-          backend.info("[slackistrano]   Webhook: #{webhook}")
-          backend.info("[slackistrano]   Via Slackbot: #{via_slackbot}")
-          backend.info("[slackistrano]   Payload: #{payload.to_json}")
-
-        # Post to the channel.
-        else
-
-          begin
-            response = post_to_slack(team: team,
-                                     token: token,
-                                     webhook: webhook,
-                                     via_slackbot: via_slackbot,
-                                     payload: payload)
-
-          rescue => e
-            backend.warn("[slackistrano] Error notifying Slack!")
-            backend.warn("[slackistrano]   Error: #{e.inspect}")
-          end
-
-          if response.code !~ /^2/
-            warn("[slackistrano] Slack API Failure!")
-            warn("[slackistrano]   URI: #{response.uri}")
-            warn("[slackistrano]   Code: #{response.code}")
-            warn("[slackistrano]   Message: #{response.message}")
-            warn("[slackistrano]   Body: #{response.body}") if response.message != response.body && response.body !~ /<html/
-          end
-        end
+      channels = Array(@messaging.channels_for(action))
+      if !@messaging.via_slackbot? == false && channels.empty?
+        channels = [nil] # default webhook channel
       end
 
+      channels.each do |channel|
+        post(payload.merge(channel: channel))
+      end
     end
 
-    #
-    #
-    #
-    def make_attachments(action, options={})
-      attachments = options.merge({
-        title:      fetch(:"slack_title_#{action}"),
-        pretext:    fetch(:"slack_pretext_#{action}"),
-        text:       fetch(:"slack_msg_#{action}"),
-        fields:     fetch(:"slack_fields_#{action}"),
-        fallback:   fetch(:"slack_fallback_#{action}"),
-        mrkdwn_in:  [:text, :pretext]
-      }).reject{|k, v| v.nil? }
-      [attachments]
+    private ##################################################
+
+    def post(payload)
+
+      if dry_run?
+        post_dry_run(payload)
+        return
+      end
+
+      begin
+        response = post_to_slack(payload)
+      rescue => e
+        backend.warn("[slackistrano] Error notifying Slack!")
+        backend.warn("[slackistrano]   Error: #{e.inspect}")
+      end
+
+      if response && response.code !~ /^2/
+        warn("[slackistrano] Slack API Failure!")
+        warn("[slackistrano]   URI: #{response.uri}")
+        warn("[slackistrano]   Code: #{response.code}")
+        warn("[slackistrano]   Message: #{response.message}")
+        warn("[slackistrano]   Body: #{response.body}") if response.message != response.body && response.body !~ /<html/
+      end
     end
-    private :make_attachments
-
-    #
-    #
-    #
-    def post_to_slack(via_slackbot: nil, team: nil, token: nil, webhook: nil, payload: {})
-      if via_slackbot
-        post_as_slackbot(team: team, token: token, webhook: webhook, payload: payload)
+
+    def post_to_slack(payload = {})
+      if @messaging.via_slackbot?
+        post_to_slack_as_slackbot(payload)
       else
-        post_as_webhook(team: team, token: token, webhook: webhook, payload: payload)
+        post_to_slack_as_webhook(payload)
       end
     end
-    private :post_to_slack
-
-    #
-    #
-    #
-    def post_as_slackbot(team: nil, token: nil, webhook: nil, payload: {})
-      uri = URI(URI.encode("https://#{team}.slack.com/services/hooks/slackbot?token=#{token}&channel=#{payload[:channel]}"))
-
-      text = payload[:attachments].collect { |a| a[:text] }.join("\n")
 
+    def post_to_slack_as_slackbot(payload = {})
+      uri = URI(URI.encode("https://#{@messaging.team}.slack.com/services/hooks/slackbot?token=#{@messaging.token}&channel=#{payload[:channel]}"))
+      text = (payload[:attachments] || [payload]).collect { |a| a[:text] }.join("\n")
       Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
         http.request_post uri, text
       end
     end
-    private :post_as_slackbot
 
-    #
-    #
-    #
-    def post_as_webhook(team: nil, token: nil, webhook: nil, payload: {})
+    def post_to_slack_as_webhook(payload = {})
       params = {'payload' => payload.to_json}
+      uri = URI(@messaging.webhook)
+      Net::HTTP.post_form(uri, params)
+    end
 
-      if webhook.nil?
-        webhook = "https://#{team}.slack.com/services/hooks/incoming-webhook"
-        params.merge!('token' => token)
+    def dry_run?
+      if ::Capistrano::Configuration.respond_to?(:dry_run?)
+        ::Capistrano::Configuration.dry_run?
+      else
+        ::Capistrano::Configuration.env.send(:config)[:sshkit_backend] == SSHKit::Backend::Printer
       end
+    end
 
-      uri = URI(webhook)
-      Net::HTTP.post_form(uri, params)
+    def post_dry_run(payload)
+        backend.info("[slackistrano] Slackistrano Dry Run:")
+      if @messaging.via_slackbot?
+        backend.info("[slackistrano]   Team: #{@messaging.team}")
+        backend.info("[slackistrano]   Token: #{@messaging.token}")
+      else
+        backend.info("[slackistrano]   Webhook: #{@messaging.webhook}")
+      end
+        backend.info("[slackistrano]   Payload: #{payload.to_json}")
     end
-    private :post_as_webhook
 
   end
 end