Reorganize incoming email doc

Configuration examples were moved into their own section for the purpose
of organizing and being able to link directly.

1 files changed, 195 insertions, 190 deletions

diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md
index 05873e01a08..658b2f55d30 100644
--- a/doc/administration/incoming_email.md
+++ b/doc/administration/incoming_email.md
@@ -95,244 +95,249 @@ for a real-world example of this exploit.
 
 ### Omnibus package installations
 
-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:
+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).
 
-    Configuration for Postfix mail server, assumes mailbox
-    incoming@gitlab.example.com
+1. Reconfigure GitLab for the changes to take effect:
 
-    ```ruby
-    gitlab_rails['incoming_email_enabled'] = true
+    ```sh
+    sudo gitlab-ctl reconfigure
+    sudo gitlab-ctl restart
+    ```
 
-    # 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"
+1. Verify that everything is configured correctly:
 
-    # 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]"
+    ```sh
+    sudo gitlab-rake gitlab:incoming_email:check
+    ```
 
-    # 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
+Reply by email should now be working.
 
-    # 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
+### Installations from source
+
+1. Go to the GitLab installation directory:
+
+    ```sh
+    cd /home/git/gitlab
     ```
 
-    Configuration for Gmail / Google Apps, assumes mailbox
-    gitlab-incoming@gmail.com
+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).
 
-    ```ruby
-    gitlab_rails['incoming_email_enabled'] = true
+1. Enable `mail_room` in the init script at `/etc/default/gitlab`:
+
+    ```sh
+    sudo mkdir -p /etc/default
+    echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab
+    ```
+
+1. Restart GitLab:
+
+    ```sh
+    sudo service gitlab restart
+    ```
+
+1. Verify that everything is configured correctly:
+
+    ```sh
+    sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
+    ```
+
+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
 
     # 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"
+    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'] = "gitlab-incoming@gmail.com"
+    user: "incoming"
     # Email account password
-    gitlab_rails['incoming_email_password'] = "[REDACTED]"
+    password: "[REDACTED]"
 
     # IMAP server host
-    gitlab_rails['incoming_email_host'] = "imap.gmail.com"
+    host: "gitlab.example.com"
     # IMAP server port
-    gitlab_rails['incoming_email_port'] = 993
+    port: 143
     # Whether the IMAP server uses SSL
-    gitlab_rails['incoming_email_ssl'] = true
+    ssl: false
     # Whether the IMAP server uses StartTLS
-    gitlab_rails['incoming_email_start_tls'] = false
+    start_tls: false
 
     # The mailbox where incoming mail will end up. Usually "inbox".
-    gitlab_rails['incoming_email_mailbox_name'] = "inbox"
+    mailbox: "inbox"
     # The IDLE command timeout.
-    gitlab_rails['incoming_email_idle_timeout'] = 60
-    ```
+    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
 
-    Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the
-    catch-all mailbox 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 `@`).
+gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@gmail.com"
 
-    ```ruby
-    gitlab_rails['incoming_email_enabled'] = true
+# 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
 
     # 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"
+    address: "gitlab-incoming+%{key}@gmail.com"
 
     # Email account username
-    # Typically this is the userPrincipalName (UPN)
-    gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com"
+    # 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
-    gitlab_rails['incoming_email_password'] = "[REDACTED]"
+    password: "[REDACTED]"
 
     # IMAP server host
-    gitlab_rails['incoming_email_host'] = "exchange.example.com"
+    host: "imap.gmail.com"
     # IMAP server port
-    gitlab_rails['incoming_email_port'] = 993
+    port: 993
     # Whether the IMAP server uses SSL
-    gitlab_rails['incoming_email_ssl'] = true
-    ```
-
-1. Reconfigure GitLab for the changes to take effect:
+    ssl: true
+    # Whether the IMAP server uses StartTLS
+    start_tls: false
 
-    ```sh
-    sudo gitlab-ctl reconfigure
-    sudo gitlab-ctl restart
-    ```
+    # The mailbox where incoming mail will end up. Usually "inbox".
+    mailbox: "inbox"
+    # The IDLE command timeout.
+    idle_timeout: 60
+```
 
-1. Verify that everything is configured correctly:
+#### MS Exchange
 
-    ```sh
-    sudo gitlab-rake gitlab:incoming_email:check
-    ```
+Example configuration for Microsoft Exchange mail server with IMAP enabled. Assumes the
+catch-all mailbox incoming@exchange.example.com.
 
-1. Reply by email should now be working.
+Example for Omnibus installs:
 
-### Installations from source
+```ruby
+gitlab_rails['incoming_email_enabled'] = true
 
-1. Go to the GitLab installation directory:
+# 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"
 
-    ```sh
-    cd /home/git/gitlab
-    ```
+# 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]"
 
-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:
+# 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
+```
 
-    ```sh
-    sudo editor config/gitlab.yml
-    ```
+Example for source installs:
 
-    Configuration for Postfix mail server, assumes mailbox
-    incoming@gitlab.example.com
-
-    ```yaml
-    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 `@`).
-      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.
-      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"
-      # The IDLE command timeout.
-      idle_timeout: 60
-    ```
+```yaml
+incoming_email:
+    enabled: true
 
-    Configuration for Gmail / Google Apps, assumes mailbox
-    gitlab-incoming@gmail.com
-
-    ```yaml
-    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 `@`).
-      address: "gitlab-incoming+%{key}@gmail.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.
-      user: "gitlab-incoming@gmail.com"
-      # Email account password
-      password: "[REDACTED]"
-
-      # 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
-
-      # The mailbox where incoming mail will end up. Usually "inbox".
-      mailbox: "inbox"
-      # The IDLE command timeout.
-      idle_timeout: 60
-    ```
-
-    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 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)
-      user: "incoming@ad-domain.example.com"
-      # Email account password
-      password: "[REDACTED]"
-
-      # 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
-
-      # The mailbox where incoming mail will end up. Usually "inbox".
-      mailbox: "inbox"
-      # The IDLE command timeout.
-      idle_timeout: 60
-    ```
-
-1. Enable `mail_room` in the init script at `/etc/default/gitlab`:
-
-    ```sh
-    sudo mkdir -p /etc/default
-    echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab
-    ```
-
-1. Restart GitLab:
-
-    ```sh
-    sudo service gitlab restart
-    ```
+    # 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"
 
-1. Verify that everything is configured correctly:
+    # Email account username
+    # Typically this is the userPrincipalName (UPN)
+    user: "incoming@ad-domain.example.com"
+    # Email account password
+    password: "[REDACTED]"
 
-    ```sh
-    sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
-    ```
+    # 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
 
-1. Reply by email should now be working.
+    # The mailbox where incoming mail will end up. Usually "inbox".
+    mailbox: "inbox"
+    # The IDLE command timeout.
+    idle_timeout: 60
+```