Merge remote-tracking branch 'origin/master' into 40781-os-to-ce

7 files changed, 417 insertions, 362 deletions

diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md
new file mode 100644
index 00000000000..6c5a466ced5
--- /dev/null
+++ b/doc/administration/incoming_email.md
@@ -0,0 +1,331 @@
+# 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.
+- [New issue by email](../user/project/issues/create_new_issue.md#new-issue-via-email):
+  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.
+
+## Requirements
+
+Handling incoming emails requires an [IMAP]-enabled email account. GitLab
+requires one of the following three strategies:
+
+- Email sub-addressing
+- Dedicated email address
+- Catch-all mailbox
+
+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
+
+### Dedicated email address
+
+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.
+
+### Catch-all mailbox
+
+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.
+
+GitLab can be set up to allow users to comment on issues and merge requests by
+replying to notification emails.
+
+## 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
+
+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:
+
+    Configuration for Postfix mail server, assumes mailbox
+    incoming@gitlab.example.com
+
+    ```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
+    ```
+
+    Configuration for Gmail / Google Apps, assumes mailbox
+    gitlab-incoming@gmail.com
+
+    ```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'] = "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.
+    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
+    ```
+
+    Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes
+    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"
+
+    # 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]"
+
+    # 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
+    ```
+
+1. Reconfigure GitLab for the changes to take effect:
+
+    ```sh
+    sudo gitlab-ctl reconfigure
+    ```
+
+1. Verify that everything is configured correctly:
+
+    ```sh
+    sudo gitlab-rake gitlab:incoming_email:check
+    ```
+
+1. Reply by email should now be working.
+
+### Installations from source
+
+1. Go to the GitLab installation directory:
+
+    ```sh
+    cd /home/git/gitlab
+    ```
+
+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:
+
+    ```sh
+    sudo editor config/gitlab.yml
+    ```
+
+    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
+    ```
+
+    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
+    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"
+
+      # 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
+    ```
+
+1. Verify that everything is configured correctly:
+
+    ```sh
+    sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
+    ```
+
+1. Reply by email should now be working.
diff --git a/doc/administration/index.md b/doc/administration/index.md
index 51444651bdb..69efaf75140 100644
--- a/doc/administration/index.md
+++ b/doc/administration/index.md
@@ -79,11 +79,19 @@ created in snippets, wikis, and repos.
 - [Sign-up restrictions](../user/admin_area/settings/sign_up_restrictions.md): block email addresses of specific domains, or whitelist only specific domains.
 - [Access restrictions](../user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols): Define which Git access protocols can be used to talk to GitLab (SSH, HTTP, HTTPS).
 - [Authentication/Authorization](../topics/authentication/index.md#gitlab-administrators): Enforce 2FA, configure external authentication with LDAP, SAML, CAS and additional Omniauth providers.
-- [Reply by email](reply_by_email.md): Allow users to comment on issues and merge requests by replying to notification emails.
-  - [Postfix for Reply by email](reply_by_email_postfix_setup.md): Set up a basic Postfix mail
+- [Incoming email](incoming_email.md): Configure incoming emails to allow
+  users to [reply by email], create [issues by email] and
+  [merge requests by email], and to enable [Service Desk].
+  - [Postfix for incoming email](reply_by_email_postfix_setup.md): Set up a
+  basic Postfix mail server with IMAP authentication on Ubuntu for incoming
+  emails.
 server with IMAP authentication on Ubuntu, to be used with Reply by email.
 - [User Cohorts](../user/admin_area/user_cohorts.md): Display the monthly cohorts of new users and their activities over time.
 
+[reply by email]: reply_by_email.md
+[issues by email]: ../user/project/issues/create_new_issue.md#new-issue-via-email
+[merge requests by email]: ../user/project/merge_requests/index.md#create-new-merge-requests-by-email
+
 ## Project settings
 
 - [Container Registry](container_registry.md): Configure Container Registry with GitLab.
diff --git a/doc/administration/logs.md b/doc/administration/logs.md
index 1b42d7979ed..00a2f3d01b8 100644
--- a/doc/administration/logs.md
+++ b/doc/administration/logs.md
@@ -23,7 +23,7 @@ requests from the API are logged to a separate file in `api_json.log`.
 Each line contains a JSON line that can be ingested by Elasticsearch, Splunk, etc. For example:
 
 ```json
-{"method":"GET","path":"/gitlab/gitlab-ce/issues/1234","format":"html","controller":"Projects::IssuesController","action":"show","status":200,"duration":229.03,"view":174.07,"db":13.24,"time":"2017-08-08T20:15:54.821Z","params":{"namespace_id":"gitlab","project_id":"gitlab-ce","id":"1234"},"remote_ip":"18.245.0.1","user_id":1,"username":"admin"}
+{"method":"GET","path":"/gitlab/gitlab-ce/issues/1234","format":"html","controller":"Projects::IssuesController","action":"show","status":200,"duration":229.03,"view":174.07,"db":13.24,"time":"2017-08-08T20:15:54.821Z","params":[{"key":"param_key","value":"param_value"}],"remote_ip":"18.245.0.1","user_id":1,"username":"admin","gitaly_calls":76}
 ```
 
 In this example, you can see this was a GET request for a specific issue. Notice each line also contains performance data:
@@ -31,6 +31,7 @@ In this example, you can see this was a GET request for a specific issue. Notice
 1. `duration`: the total time taken to retrieve the request
 2. `view`: total time taken inside the Rails views
 3. `db`: total time to retrieve data from the database
+4. `gitaly_calls`: total number of calls made to Gitaly
 
 User clone/fetch activity using http transport appears in this log as `action: git_upload_pack`.
 
diff --git a/doc/administration/monitoring/index.md b/doc/administration/monitoring/index.md
index b6320aba83e..d18dddf09c0 100644
--- a/doc/administration/monitoring/index.md
+++ b/doc/administration/monitoring/index.md
@@ -7,3 +7,4 @@ Explore our features to monitor your GitLab instance:
 - [GitHub imports](github_imports.md): Monitor the health and progress of GitLab's GitHub importer with various Prometheus metrics.
 - [Monitoring uptime](../../user/admin_area/monitoring/health_check.md): Check the server status using the health check endpoint.
   - [IP whitelists](ip_whitelist.md): Configure GitLab for monitoring endpoints that provide health check information when probed.
+- [nginx_status](https://docs.gitlab.com/omnibus/settings/nginx.html#enabling-disabling-nginx_status): Monitor your Nginx server status
diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md
new file mode 100644
index 00000000000..c91ac3012b9
--- /dev/null
+++ b/doc/administration/plugins.md
@@ -0,0 +1,66 @@
+# Plugins
+
+**Note:** Plugins must be configured on the filesystem of the GitLab
+server. Only GitLab server administrators will be able to complete these tasks.
+Please explore [system hooks] or [webhooks] as an option if you do not
+have filesystem access. 
+
+Introduced in GitLab 10.6.
+
+A plugin will run on each event so it's up to you to filter events or projects within a plugin code. You can have as many plugins as you want. Each plugin will be triggered by GitLab asynchronously in case of an event. For a list of events please see [system hooks] documentation.
+
+## Setup
+
+Plugins must be placed directly into `plugins` directory, subdirectories will be ignored. 
+There is an `example` directory inside `plugins` where you can find some basic examples. 
+
+Follow the steps below to set up a custom hook:
+
+1. On the GitLab server, navigate to the project's plugin directory.
+   For an installation from source the path is usually
+   `/home/git/gitlab/plugins/`. For Omnibus installs the path is
+   usually `/opt/gitlab/embedded/service/gitlab-rails/plugins`.
+1. Inside the `plugins` directory, create a file with a name of your choice, but without spaces or special characters.
+1. Make the hook file executable and make sure it's owned by the git user.
+1. Write the code to make the plugin function as expected. Plugin can be
+   in any language. Ensure the 'shebang' at the top properly reflects the language
+   type. For example, if the script is in Ruby the shebang will probably be
+   `#!/usr/bin/env ruby`.
+1. The data to the plugin will be provided as JSON on STDIN. It will be exactly same as one for [system hooks]
+
+That's it! Assuming the plugin code is properly implemented the hook will fire
+as appropriate. Plugins file list is updated for each event. There is no need to restart GitLab to apply a new plugin.
+
+If a plugin executes with non-zero exit code or GitLab fails to execute it, a
+message will be logged to `plugin.log`.
+
+## Validation
+
+Writing own plugin can be tricky and its easier if you can check it without altering the system. 
+We provided a rake task you can use with staging environment to test your plugin before using it in production. 
+The rake task will use a sample data and execute each of plugins. By output you should be able to determine if 
+system sees your plugin and if it was executed without errors.
+
+```bash
+# Omnibus installations
+sudo gitlab-rake plugins:validate
+
+# Installations from source
+bundle exec rake plugins:validate RAILS_ENV=production
+```
+
+Example of output can be next: 
+
+```
+-> bundle exec rake plugins:validate RAILS_ENV=production
+Validating plugins from /plugins directory
+* /home/git/gitlab/plugins/save_to_file.clj succeed (zero exit code)
+* /home/git/gitlab/plugins/save_to_file.rb failure (non-zero exit code)
+```
+
+[hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#Server-Side-Hooks
+[system hooks]: ../system_hooks/system_hooks.md
+[webhooks]: ../user/project/integrations/webhooks.md
+[5073]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5073
+[93]: https://gitlab.com/gitlab-org/gitlab-shell/merge_requests/93
+
diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md
index 3a2cced37bf..426245c7aca 100644
--- a/doc/administration/reply_by_email.md
+++ b/doc/administration/reply_by_email.md
@@ -5,33 +5,7 @@ replying to notification emails.
 
 ## Requirement
 
-Reply by email requires an IMAP-enabled email account. GitLab allows you to use
-three strategies for this feature:
-- using email sub-addressing
-- using a dedicated email address
-- using a catch-all mailbox
-
-### Email sub-addressing
-
-**If your provider or server supports email sub-addressing, we recommend using it.
-Some features (e.g. create new issue via email) only work with 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.
-
-### Dedicated email address
-
-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.
-
-### Catch-all mailbox
-
-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.
+Make sure [incoming email](incoming_email.md) is setup.
 
 ## How it works?
 
@@ -65,329 +39,3 @@ the entity the notification was about (issue, merge request, commit...).
 
 For more details about the `Message-ID`, `In-Reply-To`, and `References headers`,
 please consult [RFC 5322](https://tools.ietf.org/html/rfc5322#section-3.6.4).
-
-## Set it up
-
-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 [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
-
-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:
-
-    ```ruby
-    # Configuration for Postfix mail server, assumes mailbox incoming@gitlab.example.com
-    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
-    ```
-
-    ```ruby
-    # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com
-    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'] = "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.
-    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
-    ```
-
-    ```ruby
-    # Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes mailbox incoming@exchange.example.com
-    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"
-
-    # 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]"
-
-    # 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
-    ```
-
-1. Reconfigure GitLab for the changes to take effect:
-
-    ```sh
-    sudo gitlab-ctl reconfigure
-    ```
-
-1. Verify that everything is configured correctly:
-
-    ```sh
-    sudo gitlab-rake gitlab:incoming_email:check
-    ```
-
-1. Reply by email should now be working.
-
-### Installations from source
-
-1. Go to the GitLab installation directory:
-
-    ```sh
-    cd /home/git/gitlab
-    ```
-
-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:
-
-    ```sh
-    sudo editor config/gitlab.yml
-    ```
-
-    ```yaml
-    # Configuration for Postfix mail server, assumes mailbox incoming@gitlab.example.com
-    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
-    # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com
-    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
-    ```
-
-    ```yaml
-    # Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes mailbox incoming@exchange.example.com
-    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"
-
-      # 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
-    ```
-
-1. Verify that everything is configured correctly:
-
-    ```sh
-    sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
-    ```
-
-1. Reply by email should now be working.
-
-### Development
-
-1. Go to the GitLab installation directory.
-
-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:
-
-    ```yaml
-    # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com
-    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
-    ```
-
-    As mentioned, the part after `+` is ignored, and this will end up in the mailbox for `gitlab-incoming@gmail.com`.
-
-1. Uncomment the `mail_room` line in your `Procfile`:
-
-    ```yaml
-    mail_room: bundle exec mail_room -q -c config/mail_room.yml
-    ```
-
-1. Restart GitLab:
-
-    ```sh
-    bundle exec foreman start
-    ```
-
-1. Verify that everything is configured correctly:
-
-    ```sh
-    bundle exec rake gitlab:incoming_email:check RAILS_ENV=development
-    ```
-
-1. Reply by email should now be working.
diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md
index a1bb3851951..3e8b78e56d5 100644
--- a/doc/administration/reply_by_email_postfix_setup.md
+++ b/doc/administration/reply_by_email_postfix_setup.md
@@ -1,7 +1,7 @@
-# Set up Postfix for Reply by email
+# Set up Postfix for incoming email
 
 This document will take you through the steps of setting up a basic Postfix mail
-server with IMAP authentication on Ubuntu, to be used with [Reply by email].
+server with IMAP authentication on Ubuntu, to be used with [incoming email].
 
 The instructions make the assumption that you will be using the email address `incoming@gitlab.example.com`, that is, username `incoming` on host `gitlab.example.com`. Don't forget to change it to your actual host when executing the example code snippets.
 
@@ -177,12 +177,12 @@ Courier, which we will install later to add IMAP authentication, requires mailbo
     ```sh
     sudo apt-get install courier-imap
     ```
-    
+
     And start `imapd`:
     ```sh
     imapd start
     ```
-    
+
 1. The courier-authdaemon isn't started after installation. Without it, imap authentication will fail:
     ```sh
     sudo service courier-authdaemon start
@@ -329,10 +329,10 @@ Courier, which we will install later to add IMAP authentication, requires mailbo
 
 ## Done!
 
-If all the tests were successful, Postfix is all set up and ready to receive email! Continue with the [Reply by email](./reply_by_email.md) guide to configure GitLab.
+If all the tests were successful, Postfix is all set up and ready to receive email! Continue with the [incoming email] guide to configure GitLab.
 
 ---
 
 _This document was adapted from https://help.ubuntu.com/community/PostfixBasicSetupHowto, by contributors to the Ubuntu documentation wiki._
 
-[reply by email]: reply_by_email.md
+[incoming email]: incoming_email.md