BigW Consortium Gitlab

README.md 8.8 KB
Newer Older
Douwe Maan committed
1 2 3 4
# Reply by email

GitLab can be set up to allow users to comment on issues and merge requests by replying to notification emails.

Douwe Maan committed
5
## Get a mailbox
Douwe Maan committed
6

7
Reply by email requires an IMAP-enabled email account, with a provider or server that supports [email sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing). Sub-addressing is a feature where any email to `user+some_arbitrary_tag@example.com` will end up in the mailbox for `user@example.com`, and is supported by providers such as Gmail, Google Apps, Yahoo! Mail, Outlook.com and iCloud, as well as the Postfix mail server which you can run on-premises.
8

9
If you want to use Gmail / Google Apps with Reply by email, make sure you have [IMAP access enabled](https://support.google.com/mail/troubleshooter/1668960?hl=en#ts=1665018) and [allow less secure apps to access the account](https://support.google.com/accounts/answer/6010255).
Douwe Maan committed
10 11

To set up a basic Postfix mail server with IMAP access on Ubuntu, follow [these instructions](./postfix.md).
12

Douwe Maan committed
13 14
## Set it up

15 16
### Omnibus package installations

17
1. Find the `incoming_email` section in `/etc/gitlab/gitlab.rb`, enable the feature and fill in the details for your specific IMAP server and email account:
18 19

    ```ruby
20
    # Configuration for Postfix mail server, assumes mailbox incoming@gitlab.example.com
21
    gitlab_rails['incoming_email_enabled'] = true
22 23 24
    
    # The email address including a placeholder for the key that references the item being replied to.
    # The `%{key}` placeholder is added after the user part, before the `@`.
25
    gitlab_rails['incoming_email_address'] = "incoming+%{key}@gitlab.example.com"
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
    
    # Email account username
    # With third party providers, this is usually the full email address.
    # With self-hosted email servers, this is usually the user part of the email address.
    gitlab_rails['incoming_email_email'] = "incoming"
    # Email account password
    gitlab_rails['incoming_email_password'] = "[REDACTED]"
    
    # IMAP server host
    gitlab_rails['incoming_email_host'] = "gitlab.example.com"
    # IMAP server port
    gitlab_rails['incoming_email_port'] = 143
    # Whether the IMAP server uses SSL
    gitlab_rails['incoming_email_ssl'] = false
    # Whether the IMAP server uses StartTLS
    gitlab_rails['incoming_email_start_tls'] = false

    # The mailbox where incoming mail will end up. Usually "inbox".
    gitlab_rails['incoming_email_mailbox_name'] = "inbox"
45 46 47
    ```

    ```ruby
48
    # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com
49
    gitlab_rails['incoming_email_enabled'] = true
50 51 52
    
    # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
    # The `%{key}` placeholder is added after the user part, after a `+` character, before the `@`.
53
    gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@gmail.com"
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
    
    # Email account username
    # With third party providers, this is usually the full email address.
    # With self-hosted email servers, this is usually the user part of the email address.
    gitlab_rails['incoming_email_email'] = "gitlab-incoming@gmail.com"
    # Email account password
    gitlab_rails['incoming_email_password'] = "[REDACTED]"
    
    # IMAP server host
    gitlab_rails['incoming_email_host'] = "imap.gmail.com"
    # IMAP server port
    gitlab_rails['incoming_email_port'] = 993
    # Whether the IMAP server uses SSL
    gitlab_rails['incoming_email_ssl'] = true
    # Whether the IMAP server uses StartTLS
    gitlab_rails['incoming_email_start_tls'] = false

    # The mailbox where incoming mail will end up. Usually "inbox".
    gitlab_rails['incoming_email_mailbox_name'] = "inbox"
73 74
    ```

75
    As mentioned, the part after `+` in the address is ignored, and any email sent here will end up in the mailbox for `incoming@gitlab.example.com`/`gitlab-incoming@gmail.com`.
76

77
1. Reconfigure GitLab and restart mailroom for the changes to take effect:
78 79 80

    ```sh
    sudo gitlab-ctl reconfigure
81
    sudo gitlab-ctl restart mailroom
82 83 84 85 86
    ```

1. Verify that everything is configured correctly:

    ```sh
87
    sudo gitlab-rake gitlab:incoming_email:check
88 89 90 91
    ```

1. Reply by email should now be working.

Douwe Maan committed
92 93
### Installations from source

94 95 96 97 98
1. Go to the GitLab installation directory:

    ```sh
    cd /home/git/gitlab
    ```
Douwe Maan committed
99

100
1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature and fill in the details for your specific IMAP server and email account:
101 102 103 104

    ```sh
    sudo editor config/gitlab.yml
    ```
105

Douwe Maan committed
106
    ```yaml
107
    # Configuration for Postfix mail server, assumes mailbox incoming@gitlab.example.com
108 109
    incoming_email:
      enabled: true
110 111 112

      # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
      # The `%{key}` placeholder is added after the user part, after a `+` character, before the `@`.
113
      address: "incoming+%{key}@gitlab.example.com"
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132

      # Email account username
      # With third party providers, this is usually the full email address.
      # With self-hosted email servers, this is usually the user part of the email address.
      user: "incoming"
      # Email account password
      password: "[REDACTED]"

      # IMAP server host
      host: "gitlab.example.com"
      # IMAP server port
      port: 143
      # Whether the IMAP server uses SSL
      ssl: false
      # Whether the IMAP server uses StartTLS
      start_tls: false

      # The mailbox where incoming mail will end up. Usually "inbox".
      mailbox: "inbox"
133 134 135
    ```

    ```yaml
136
    # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com
137
    incoming_email:
Douwe Maan committed
138 139
      enabled: true

140 141 142
      # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
      # The `%{key}` placeholder is added after the user part, after a `+` character, before the `@`.
      address: "gitlab-incoming+%{key}@gmail.com"
143

144 145 146 147 148 149
      # Email account username
      # With third party providers, this is usually the full email address.
      # With self-hosted email servers, this is usually the user part of the email address.
      user: "gitlab-incoming@gmail.com"
      # Email account password
      password: "[REDACTED]"
Douwe Maan committed
150

151 152 153 154 155 156 157 158
      # IMAP server host
      host: "imap.gmail.com"
      # IMAP server port
      port: 993
      # Whether the IMAP server uses SSL
      ssl: true
      # Whether the IMAP server uses StartTLS
      start_tls: false
Douwe Maan committed
159

160 161
      # The mailbox where incoming mail will end up. Usually "inbox".
      mailbox: "inbox"
162 163
    ```

164
    As mentioned, the part after `+` in the address is ignored, and any email sent here will end up in the mailbox for `incoming@gitlab.example.com`/`gitlab-incoming@gmail.com`.
Douwe Maan committed
165

166
1. Enable `mail_room` in the init script at `/etc/default/gitlab`:
167

Douwe Maan committed
168
    ```sh
Douwe Maan committed
169 170
    sudo mkdir -p /etc/default
    echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab
Douwe Maan committed
171 172
    ```

173
1. Restart GitLab:
174

Douwe Maan committed
175 176 177 178
    ```sh
    sudo service gitlab restart
    ```

179
1. Verify that everything is configured correctly:
180 181

    ```sh
182
    sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
183 184
    ```

185
1. Reply by email should now be working.
Douwe Maan committed
186

187 188 189 190
### Development

1. Go to the GitLab installation directory.

191
1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature and fill in the details for your specific IMAP server and email account:
192

193
    ```yaml
194
    # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com
195
    incoming_email:
196
      enabled: true
197 198 199

      # The email address including a placeholder for the key that references the item being replied to.
      # The `%{key}` placeholder is added after the user part, before the `@`.
200
      address: "gitlab-incoming+%{key}@gmail.com"
201

202 203 204 205 206 207
      # Email account username
      # With third party providers, this is usually the full email address.
      # With self-hosted email servers, this is usually the user part of the email address.
      user: "gitlab-incoming@gmail.com"
      # Email account password
      password: "[REDACTED]"
208

209 210 211 212 213 214 215 216
      # IMAP server host
      host: "imap.gmail.com"
      # IMAP server port
      port: 993
      # Whether the IMAP server uses SSL
      ssl: true
      # Whether the IMAP server uses StartTLS
      start_tls: false
217

218 219
      # The mailbox where incoming mail will end up. Usually "inbox".
      mailbox: "inbox"
220 221
    ```

222
    As mentioned, the part after `+` is ignored, and this will end up in the mailbox for `gitlab-incoming@gmail.com`.
223

224
1. Uncomment the `mail_room` line in your `Procfile`:
225 226 227 228 229

    ```yaml
    mail_room: bundle exec mail_room -q -c config/mail_room.yml
    ```

230
1. Restart GitLab:
231

232 233 234 235
    ```sh
    bundle exec foreman start
    ```

236
1. Verify that everything is configured correctly:
237 238

    ```sh
239
    bundle exec rake gitlab:incoming_email:check RAILS_ENV=development
240 241
    ```

242
1. Reply by email should now be working.