diff options
author | Brett Walker <bwalker@gitlab.com> | 2019-01-08 00:12:59 +0000 |
---|---|---|
committer | Mike Lewis <mlewis@gitlab.com> | 2019-01-08 00:12:59 +0000 |
commit | 413ab73846db3d92d3b852b5c803162598bcc6e3 (patch) | |
tree | b72b241023edccc7ddf055ba6386ffbdb656f7bd /doc/administration | |
parent | 31f2c7b00ee52516c288b1b2f7e2064897e36ad8 (diff) | |
download | gitlab-ce-413ab73846db3d92d3b852b5c803162598bcc6e3.tar.gz |
Document new incoming email address format
Diffstat (limited to 'doc/administration')
-rw-r--r-- | doc/administration/incoming_email.md | 70 |
1 files changed, 38 insertions, 32 deletions
diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 27a3710632d..05873e01a08 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -13,43 +13,45 @@ GitLab has several features based on receiving incoming emails: ## Requirements -Handling incoming emails requires an [IMAP]-enabled email account. GitLab -requires one of the following three strategies: +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: -- Email sub-addressing -- Dedicated email address +- Email sub-addressing (recommended) - Catch-all mailbox +- Dedicated email address (supports Reply by Email only) Let's walk through each of these options. -**If your provider or server supports email sub-addressing, we recommend using it. -Most features (other than reply by email) only work with sub-addressing.** - -[IMAP]: https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol - ### Email sub-addressing [Sub-addressing](https://en.wikipedia.org/wiki/Email_address#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. - -[Postfix mail server]: reply_by_email_postfix_setup.md +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. -### Dedicated email address +### Catch-all mailbox -This solution is really simple to set up: you just have to create an email -address dedicated to receive your users' replies to GitLab notifications. +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. -### Catch-all mailbox +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. -A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain will -"catch all" the emails addressed to the domain that do not exist in the mail -server. +### Dedicated email address -GitLab can be set up to allow users to comment on issues and merge requests by -replying to notification emails. +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). ## Set it up @@ -160,14 +162,16 @@ for a real-world example of this exploit. gitlab_rails['incoming_email_idle_timeout'] = 60 ``` - Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes - mailbox incoming@exchange.example.com + Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the + catch-all mailbox incoming@exchange.example.com ```ruby gitlab_rails['incoming_email_enabled'] = true - # The email address replies are sent to - Exchange does not support sub-addressing so %{key} is not used here - gitlab_rails['incoming_email_address'] = "incoming@exchange.example.com" + # 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" # Email account username # Typically this is the userPrincipalName (UPN) @@ -279,15 +283,17 @@ for a real-world example of this exploit. idle_timeout: 60 ``` - Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes - mailbox incoming@exchange.example.com + Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the + catch-all mailbox incoming@exchange.example.com ```yaml incoming_email: enabled: true - # The email address replies are sent to - Exchange does not support sub-addressing so %{key} is not used here - address: "incoming@exchange.example.com" + # 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" # Email account username # Typically this is the userPrincipalName (UPN) |