README.md in slackistrano-3.0.1 vs README.md in slackistrano-3.1.0.beta
- old
+ new
@@ -4,184 +4,181 @@
[](https://codeclimate.com/github/phallstrom/slackistrano)
[](https://travis-ci.org/phallstrom/slackistrano)
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:** 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).
-## 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.
-
## 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']
```
+$ cap production slack:deploy:test
+```
-Optionally, override the other slack settings.
+## Usage
-```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.
+Deploy your application like normal and you should see messages in the channel
+you specified.
-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' }
+## Customizing the Messaging
-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.
+You can customize the messaging posted to Slack by providing your own messaging
+class and overriding several methods. Here is one example:
-set :slack_deploy_user, -> { ENV['USER'] || ENV['USERNAME'] }
+```ruby
+module Slackistrano
+ class CustomMessaging < Messaging::Base
-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'}" }
+ # Send failed message to #ops. Send all other messages to default channels.
+ def channels_for(action)
+ if action == :failed
+ "#ops"
+ else
+ super
+ end
+ end
-set :slack_fields_updating, -> { [] }
-set :slack_fields_reverting, -> { [] }
-set :slack_fields_updated, -> { [] }
-set :slack_fields_reverted, -> { [] }
-set :slack_fields_failed, -> { [] }
+ # Supress updating message.
+ def payload_for_updating
+ nil
+ end
-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 }
+ # Supress reverting message.
+ def payload_for_reverting
+ nil
+ end
-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 }
+ # 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
-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 }
-```
+ # Default reverted message. Alternatively we could have simply not
+ # redefined this method at all.
+ def payload_for_reverted
+ super
+ end
-**Note**: You may wish to disable one of the notifications if another service (ex:
-Honeybadger) also displays a deploy notification.
+ # 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
-Test your setup by running:
+ # 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
-```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
+ end
+end
```
-## Formatted messages
+The output would look like this:
+
-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:
+To set this up:
-```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
- }
-]
-```
+1. Add the above class to your app, for example `lib/custom_messaging.rb`.
-It will produce the following format:
-
+2. Require the library after the requiring of Slackistrano in your application's Capfile.
-**Note 1:** *The `fallback` field is required in order to display notifications when using `fields`.*
+ ```ruby
+ require_relative 'lib/custom_messaging'
+ ```
-**Note 2:** *The `fields` configuration requires you to use webhooks.*
+3. Update the `slackistrano` configuration in `config/deploy.rb` and add the `klass` option.
-More information: [https://api.slack.com/docs/attachments](https://api.slack.com/docs/attachments)
+ ```ruby
+ set :slackistrano, {
+ klass: Slackistrano::CustomMessaging,
+ channel: '#your-channel',
+ webhook: 'your-incoming-webhook-url'
+ }
+ ```
-## Usage
-
-Deploy your application like normal and you should see messages in the channel
-you specified.
+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
- Notify about incorrect configuration settings.