incoming_email.md 12.4 KB
Newer Older
1 2 3 4 5 6
# Incoming email

GitLab has several features based on receiving incoming emails:

- [Reply by Email](reply_by_email.md): allow GitLab users to comment on issues
  and merge requests by replying to notification emails.
7
- [New issue by email](../user/project/issues/managing_issues.md#new-issue-via-email):
8 9 10 11 12
  allow GitLab users to create a new issue by sending an email to a
  user-specific email address.
- [New merge request by email](../user/project/merge_requests/index.md#create-new-merge-requests-by-email):
  allow GitLab users to create a new merge request by sending an email to a
  user-specific email address.
13
- [Service Desk](../user/project/service_desk.md): provide e-mail support to
14
  your customers through GitLab. **(PREMIUM)**
15 16 17

## Requirements

18 19
Handling incoming emails requires an [IMAP](https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol)-enabled
email account. GitLab requires one of the following three strategies:
20

21
- Email sub-addressing (recommended)
22
- Catch-all mailbox
23
- Dedicated email address (supports Reply by Email only)
24 25 26 27 28 29

Let's walk through each of these options.

### Email sub-addressing

[Sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) is
30 31 32 33 34 35 36 37 38 39 40
a mail server feature where any email to `user+arbitrary_tag@example.com` will end up
in the mailbox for `user@example.com` . It is supported by providers such as
Gmail, Google Apps, Yahoo! Mail, Outlook.com, and iCloud, as well as the
[Postfix mail server](reply_by_email_postfix_setup.md), which you can run on-premises.

TIP: **Tip:**
If your provider or server supports email sub-addressing, we recommend using it.
A dedicated email address only supports Reply by Email functionality.
A catch-all mailbox supports the same features as sub-addressing as of GitLab 11.7,
but sub-addressing is still preferred because only one email address is used,
leaving a catch-all available for other purposes beyond GitLab.
41

42
### Catch-all mailbox
43

44 45 46
A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain
receives all emails addressed to the domain that do not match any addresses that
exist on the mail server.
47

48 49 50
As of GitLab 11.7, catch-all mailboxes support the same features as
email sub-addressing, but email sub-addressing remains our recommendation so that you
can reserve your catch-all mailbox for other purposes.
51

52
### Dedicated email address
53

54 55 56
This solution is relatively simple to set up: you just need to create an email
address dedicated to receive your users' replies to GitLab notifications. However,
this method only supports replies, and not the other features of [incoming email](#incoming-email).
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99

## Set it up

If you want to use Gmail / Google Apps for incoming emails, make sure you have
[IMAP access enabled](https://support.google.com/mail/troubleshooter/1668960?hl=en#ts=1665018)
and [allowed less secure apps to access the account](https://support.google.com/accounts/answer/6010255)
or [turn-on 2-step validation](https://support.google.com/accounts/answer/185839)
and use [an application password](https://support.google.com/mail/answer/185833).

To set up a basic Postfix mail server with IMAP access on Ubuntu, follow the
[Postfix setup documentation](reply_by_email_postfix_setup.md).

### Security Concerns

**WARNING:** Be careful when choosing the domain used for receiving incoming
email.

For the sake of example, suppose your top-level company domain is `hooli.com`.
All employees in your company have an email address at that domain via Google
Apps, and your company's private Slack instance requires a valid `@hooli.com`
email address in order to sign up.

If you also host a public-facing GitLab instance at `hooli.com` and set your
incoming email domain to `hooli.com`, an attacker could abuse the "Create new
issue by email" or
"[Create new merge request by email](../user/project/merge_requests/index.md#create-new-merge-requests-by-email)"
features by using a project's unique address as the email when signing up for
Slack, which would send a confirmation email, which would create a new issue or
merge request on the project owned by the attacker, allowing them to click the
confirmation link and validate their account on your company's private Slack
instance.

We recommend receiving incoming email on a subdomain, such as
`incoming.hooli.com`, and ensuring that you do not employ any services that
authenticate solely based on access to an email domain such as `*.hooli.com.`
Alternatively, use a dedicated domain for GitLab email communications such as
`hooli-gitlab.com`.

See GitLab issue [#30366](https://gitlab.com/gitlab-org/gitlab-ce/issues/30366)
for a real-world example of this exploit.

### Omnibus package installations

Cody West's avatar
Cody West committed
100 101
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 (see [examples](#config-examples) below).
102

Cody West's avatar
Cody West committed
103
1. Reconfigure GitLab for the changes to take effect:
104

105 106 107 108
   ```sh
   sudo gitlab-ctl reconfigure
   sudo gitlab-ctl restart
   ```
109

Cody West's avatar
Cody West committed
110
1. Verify that everything is configured correctly:
111

112 113 114
   ```sh
   sudo gitlab-rake gitlab:incoming_email:check
   ```
115

Cody West's avatar
Cody West committed
116
Reply by email should now be working.
117

Cody West's avatar
Cody West committed
118 119 120 121
### Installations from source

1. Go to the GitLab installation directory:

122 123 124
   ```sh
   cd /home/git/gitlab
   ```
125

Cody West's avatar
Cody West committed
126 127
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 (see [examples](#config-examples) below).
128

Cody West's avatar
Cody West committed
129 130
1. Enable `mail_room` in the init script at `/etc/default/gitlab`:

131 132 133 134
   ```sh
   sudo mkdir -p /etc/default
   echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab
   ```
Cody West's avatar
Cody West committed
135 136 137

1. Restart GitLab:

138 139 140
   ```sh
   sudo service gitlab restart
   ```
Cody West's avatar
Cody West committed
141 142 143

1. Verify that everything is configured correctly:

144 145 146
   ```sh
   sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
   ```
Cody West's avatar
Cody West committed
147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191

Reply by email should now be working.

### Config examples

#### Postfix

Example configuration for Postfix mail server. Assumes mailbox incoming@gitlab.example.com.

Example for Omnibus installs:

```ruby
gitlab_rails['incoming_email_enabled'] = true

# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "incoming+%{key}@gitlab.example.com"

# 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"
# The IDLE command timeout.
gitlab_rails['incoming_email_idle_timeout'] = 60
```

Example for source installs:

```yaml
incoming_email:
    enabled: true
192 193 194

    # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
    # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
Cody West's avatar
Cody West committed
195
    address: "incoming+%{key}@gitlab.example.com"
196 197 198 199

    # 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.
Cody West's avatar
Cody West committed
200
    user: "incoming"
201
    # Email account password
Cody West's avatar
Cody West committed
202
    password: "[REDACTED]"
203 204

    # IMAP server host
Cody West's avatar
Cody West committed
205
    host: "gitlab.example.com"
206
    # IMAP server port
Cody West's avatar
Cody West committed
207
    port: 143
208
    # Whether the IMAP server uses SSL
Cody West's avatar
Cody West committed
209
    ssl: false
210
    # Whether the IMAP server uses StartTLS
Cody West's avatar
Cody West committed
211
    start_tls: false
212 213

    # The mailbox where incoming mail will end up. Usually "inbox".
Cody West's avatar
Cody West committed
214
    mailbox: "inbox"
215
    # The IDLE command timeout.
Cody West's avatar
Cody West committed
216 217 218 219 220 221 222 223 224 225 226
    idle_timeout: 60
```

#### Gmail

Example configuration for Gmail/G Suite. Assumes mailbox gitlab-incoming@gmail.com.

Example for Omnibus installs:

```ruby
gitlab_rails['incoming_email_enabled'] = true
227

Cody West's avatar
Cody West committed
228 229 230
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@gmail.com"
231

Cody West's avatar
Cody West committed
232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258
# 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"
# The IDLE command timeout.
gitlab_rails['incoming_email_idle_timeout'] = 60
```

Example for source installs:

```yaml
incoming_email:
    enabled: true
259

260 261
    # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
    # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
Cody West's avatar
Cody West committed
262
    address: "gitlab-incoming+%{key}@gmail.com"
263 264

    # Email account username
Cody West's avatar
Cody West committed
265 266 267
    # 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"
268
    # Email account password
Cody West's avatar
Cody West committed
269
    password: "[REDACTED]"
270 271

    # IMAP server host
Cody West's avatar
Cody West committed
272
    host: "imap.gmail.com"
273
    # IMAP server port
Cody West's avatar
Cody West committed
274
    port: 993
275
    # Whether the IMAP server uses SSL
Cody West's avatar
Cody West committed
276 277 278
    ssl: true
    # Whether the IMAP server uses StartTLS
    start_tls: false
279

Cody West's avatar
Cody West committed
280 281 282 283 284
    # The mailbox where incoming mail will end up. Usually "inbox".
    mailbox: "inbox"
    # The IDLE command timeout.
    idle_timeout: 60
```
285

Cody West's avatar
Cody West committed
286
#### MS Exchange
287

Cody West's avatar
Cody West committed
288 289
Example configuration for Microsoft Exchange mail server with IMAP enabled. Assumes the
catch-all mailbox incoming@exchange.example.com.
290

Cody West's avatar
Cody West committed
291
Example for Omnibus installs:
292

Cody West's avatar
Cody West committed
293 294
```ruby
gitlab_rails['incoming_email_enabled'] = true
295

Cody West's avatar
Cody West committed
296 297 298 299
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
# Exchange does not support sub-addressing, so a catch-all mailbox must be used.
gitlab_rails['incoming_email_address'] = "incoming-%{key}@exchange.example.com"
300

Cody West's avatar
Cody West committed
301 302 303 304 305
# Email account username
# Typically this is the userPrincipalName (UPN)
gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"
306

Cody West's avatar
Cody West committed
307 308 309 310 311 312 313
# IMAP server host
gitlab_rails['incoming_email_host'] = "exchange.example.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true
```
314

Cody West's avatar
Cody West committed
315
Example for source installs:
316

Cody West's avatar
Cody West committed
317 318 319
```yaml
incoming_email:
    enabled: true
320

Cody West's avatar
Cody West committed
321 322 323 324
    # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
    # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
    # Exchange does not support sub-addressing, so a catch-all mailbox must be used.
    address: "incoming-%{key}@exchange.example.com"
325

Cody West's avatar
Cody West committed
326 327 328 329 330
    # Email account username
    # Typically this is the userPrincipalName (UPN)
    user: "incoming@ad-domain.example.com"
    # Email account password
    password: "[REDACTED]"
331

Cody West's avatar
Cody West committed
332 333 334 335 336 337 338 339
    # IMAP server host
    host: "exchange.example.com"
    # IMAP server port
    port: 993
    # Whether the IMAP server uses SSL
    ssl: true
    # Whether the IMAP server uses StartTLS
    start_tls: false
340

Cody West's avatar
Cody West committed
341 342 343 344 345
    # The mailbox where incoming mail will end up. Usually "inbox".
    mailbox: "inbox"
    # The IDLE command timeout.
    idle_timeout: 60
```