Module: Capistrano::Mailgun

Defined in:
lib/capistrano-mailgun.rb,
lib/capistrano-mailgun/version.rb

Constant Summary collapse

VERSION = 
"1.3.0"

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.load_into(config) ⇒ Object

Load the base configuration into the given Capistrano::Instance. This is primarily used for testing and is executed automatically when requiring the library in a Capistrano recipe.



12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/capistrano-mailgun.rb', line 12

def self.load_into(config)
  config.load do

    Capistrano.plugin :mailgun, Capistrano::Mailgun

    def _cset(name, *args, &block)
      unless exists?(name)
        set(name, *args, &block)
      end
    end

    _cset(:mailgun_subject) do
      [ "[Deployment]", fetch(:stage, '').to_s.capitalize, fetch(:application, '').capitalize, 'deploy completed'].join(' ').gsub(/\s+/, ' ')
    end

    _cset(:mailgun_api_key)           { abort "Please set mailgun_api_key accordingly" }
    _cset(:mailgun_domain)            { abort "Please set mailgun_domain accordingly" }
    _cset(:mailgun_from)              { abort "Please set mailgun_from to your desired From field" }
    _cset(:mailgun_recipients)        { abort "Please specify mailgun_recipients" }
    _cset(:mailgun_recipient_domain)  { abort "Please set mailgun_recipient_domain accordingly" }

    # some internal variables that mailgun will use as the app runs
    _cset(:mailgun_deploy_servers)    { find_servers_for_task( find_task('deploy:update_code') ) }

    # set these to nil to not use, or set to path to your custom template
    _cset :mailgun_text_template, :deploy_text
    _cset :mailgun_html_template, :deploy_html

    _cset :mailgun_include_servers, false

    _cset(:deployer_username) do
      if fetch(:scm, '').to_sym == :git
        `git config user.name`.chomp
      else
        `whoami`.chomp
      end
    end

    # before update_code, fetch the current revision
    # this is needed to ensure that no matter when capistrano-mailgun fetches the commit logs that it
    # has the correct starting point.
    before 'deploy:update_code' do
      set :mailgun_previous_revision, fetch(:current_revision, nil) # the revision that's currently deployed at this moment
    end

    # default mailgun email tasks
    desc <<-DESC
      Send a mailgun deployment notification.

      This is here for convenience so you can force a notification to
      be sent from the commandline and also to simplify configuring
      after-deploy hooks and even after-mailgun-notify hooks.
    DESC
    task :mailgun_notify do
      mailgun.notify_of_deploy
    end



  end # config.load
end

Instance Method Details

#build_recipients(recipients, default_domain = nil) ⇒ Object

Given an array of recipients, it returns a comma-delimited, deduplicated string, suitable for populating the to, cc, and bcc fields of a Mailgun API call. Optionally, it will take a default_domain which will automatically be appended to any unqualified recipients (eg: 'spike' => '[email protected]')



119
120
121
122
123
124
125
126
127
 
# File 'lib/capistrano-mailgun.rb', line 119

def build_recipients(recipients, default_domain=nil)
  [*recipients].map do |r|
    if r.match /.+?@.+?$/ # the email contains an @ so it's fully-qualified.
      r
    else
      "#{ r }@#{ default_domain || fetch(:mailgun_recipient_domain) }"
    end
  end.uniq.sort.join(',')
end

#log_output(first_ref, last_ref) ⇒ Object

git log between first_ref to last_ref memoizes the output so this function can be called multiple times without re-running FIXME: memoization does not account for arguments

returns an array of 2-element arrays in the form of [ ref, log_text ]



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/capistrano-mailgun.rb', line 135

def log_output(first_ref, last_ref)
  return @log_output unless @log_output.nil?

  begin
    raise "Ref missing" if first_ref.nil? || last_ref.nil? # jump to resque block.

    log_output = run_locally("git log --oneline #{ first_ref }..#{ last_ref }")

    @log_output = log_output = log_output.split("\n").map do |line|
      fields = line.split("\s", 2)
      [ fields[0], fields[1] ]
    end
  rescue
    [ [ 'n/a', 'Log output not available.' ] ]
  end
end

#notify_of_deploy ⇒ Object

Sends the email via the Mailgun API using variables configured in Capistrano. It depends on the following Capistrano vars in addition to the default:

  • mailgun_recipients
  • mailgun_from
  • mailgun_subject Requires one or both of the following:
  • mailgun_text_template
  • mailgun_html_template

See README for explanations of the above variables.



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/capistrano-mailgun.rb', line 97

def notify_of_deploy
  options = {
    :to => fetch(:mailgun_recipients),
    :from => fetch(:mailgun_from),
    :subject => fetch(:mailgun_subject)
  }

  options[:cc] = fetch(:mailgun_cc) if fetch(:mailgun_cc, nil)
  options[:bcc] = fetch(:mailgun_bcc) if fetch(:mailgun_bcc, nil)

  if fetch(:mailgun_text_template, nil).nil? && fetch(:mailgun_html_template, nil).nil?
    abort "You must specify one (or both) of mailgun_text_template and mailgun_html_template to use notify_of_deploy"
  end

  options[:text_template] = fetch(:mailgun_text_template, nil)
  options[:html_template] = fetch(:mailgun_html_template, nil)

  send_email options
end

#send_email(options) ⇒ Object

Simple wrapper for sending an email with a given template Supports all options that the Mailgun API supports. In addition, it also accepts:

  • :text_template -- the path to the template for the text body. It will be processed and interpolated and set the text field when doing the API call.
  • :html_template -- the path to the template for the html body. It will be processed and interpolated and set the html field when doing the API call.

If mailgun_off is set, this function will do absolutely nothing.



80
81
82
83
84
85
 
# File 'lib/capistrano-mailgun.rb', line 80

def send_email(options)
  return if exists?(:mailgun_off)
  options = process_send_email_options(options)

  RestClient.post build_mailgun_uri( mailgun_api_key, mailgun_domain ), options
end