diff --git a/app/assets/javascripts/dispatcher.js b/app/assets/javascripts/dispatcher.js
index 8d99b12102d..adff73af79c 100644
--- a/app/assets/javascripts/dispatcher.js
+++ b/app/assets/javascripts/dispatcher.js
@@ -126,6 +126,9 @@
             new TreeView();
           }
           break;
+        case 'projects:pipelines:show':
+          new gl.Pipelines();
+          break;
         case 'groups:activity':
           new Activities();
           break;
diff --git a/app/assets/javascripts/pipeline.js.es6 b/app/assets/javascripts/pipeline.js.es6
index 8813bb5dfef..6bf63ee6979 100644
--- a/app/assets/javascripts/pipeline.js.es6
+++ b/app/assets/javascripts/pipeline.js.es6
@@ -1,24 +1,40 @@
-(function() {
-  function toggleGraph() {
-    const $pipelineBtn = $(this).closest('.toggle-pipeline-btn');
-    const $pipelineGraph = $(this).closest('.row-content-block').next('.pipeline-graph');
-    const $btnText = $(this).find('.toggle-btn-text');
-    const $icon = $(this).find('.fa');
+((global) => {
 
-    $($pipelineBtn).add($pipelineGraph).toggleClass('graph-collapsed');
+  class Pipelines {
+    constructor() {
+      $(document).off('click', '.toggle-pipeline-btn').on('click', '.toggle-pipeline-btn', this.toggleGraph);
+      this.addMarginToBuildColumns();
+    }
 
-    const graphCollapsed = $pipelineGraph.hasClass('graph-collapsed');
-    const expandIcon = 'fa-caret-down';
-    const hideIcon = 'fa-caret-up';
+    toggleGraph() {
+      const $pipelineBtn = $(this).closest('.toggle-pipeline-btn');
+      const $pipelineGraph = $(this).closest('.row-content-block').next('.pipeline-graph');
+      const $btnText = $(this).find('.toggle-btn-text');
+      const graphCollapsed = $pipelineGraph.hasClass('graph-collapsed');
 
-    if(graphCollapsed) {
-      $btnText.text('Expand');
-      $icon.removeClass(hideIcon).addClass(expandIcon);
-    } else {
-      $btnText.text('Hide');
-      $icon.removeClass(expandIcon).addClass(hideIcon);
+      $($pipelineBtn).add($pipelineGraph).toggleClass('graph-collapsed');
+
+
+      graphCollapsed ? $btnText.text('Expand') : $btnText.text('Hide')
+    }
+
+    addMarginToBuildColumns() {
+      const $secondChildBuildNode = $('.build:nth-child(2)');
+      if ($secondChildBuildNode.length) {
+        const $firstChildBuildNode = $secondChildBuildNode.prev('.build');
+        const $multiBuildColumn = $secondChildBuildNode.closest('.stage-column');
+        const $previousColumn = $multiBuildColumn.prev('.stage-column');
+        $multiBuildColumn.addClass('left-margin');
+        $firstChildBuildNode.addClass('left-connector');
+        $previousColumn.each(function() {
+          $this = $(this);
+          if ($('.build', $this).length === 1) $this.addClass('no-margin');
+        });
+      }
+      $('.pipeline-graph').removeClass('hidden');
     }
   }
 
-  $(document).on('click', '.toggle-pipeline-btn', toggleGraph);
-})();
+  global.Pipelines = Pipelines;
+
+})(window.gl || (window.gl = {}));
diff --git a/app/assets/stylesheets/framework/variables.scss b/app/assets/stylesheets/framework/variables.scss
index 14ec310de2d..4c34ed3ebf7 100644
--- a/app/assets/stylesheets/framework/variables.scss
+++ b/app/assets/stylesheets/framework/variables.scss
@@ -17,8 +17,10 @@ $white-normal: #ededed;
 $white-dark: #ececec;
 
 $gray-light: #fafafa;
+$gray-lighter: #f9f9f9;
 $gray-normal: #f5f5f5;
 $gray-dark: #ededed;
+$gray-darker: #eee;
 $gray-darkest: #c9c9c9;
 
 $green-light: #38ae67;
@@ -33,6 +35,8 @@ $blue-medium-light: #3498cb;
 $blue-medium: #2f8ebf;
 $blue-medium-dark: #2d86b4;
 
+$blue-light-transparent: rgba(44, 159, 216, 0.05);
+
 $orange-light: #fc8a51;
 $orange-normal: #e75e40;
 $orange-dark: #ce5237;
@@ -91,6 +95,7 @@ $table-text-gray:       #8f8f8f;
 $gl-font-size:         15px;
 $gl-title-color:       #333;
 $gl-text-color:        #5c5c5c;
+$gl-text-color-light:  #8c8c8c;
 $gl-text-green:        #4a2;
 $gl-text-red:          #d12f19;
 $gl-text-orange:       #d90;
diff --git a/app/assets/stylesheets/pages/pipelines.scss b/app/assets/stylesheets/pages/pipelines.scss
index a2779704eff..05f59279637 100644
--- a/app/assets/stylesheets/pages/pipelines.scss
+++ b/app/assets/stylesheets/pages/pipelines.scss
@@ -303,16 +303,41 @@
 .stage-column {
   display: inline-block;
   vertical-align: top;
-  margin-right: 65px;
+
+  &:not(:last-child) {
+    margin-right: 44px;
+  }
+
+  &.left-margin {
+    &:not(:first-child) {
+      margin-left: 44px;
+
+      .left-connector {
+        &::before {
+          content: '';
+          position: absolute;
+          top: 48%;
+          left: -48px;
+          border-top: 2px solid $border-color;
+          width: 48px;
+          height: 1px;
+        }
+      }
+    }
+  }
+
+  &.no-margin {
+    margin: 0;
+  }
 
   li {
     list-style: none;
   }
 
   .stage-name {
-    margin-bottom: 15px;
+    margin: 0 0 15px 10px;
     font-weight: bold;
-    width: 150px;
+    width: 176px;
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
@@ -321,17 +346,23 @@
   .build {
     border: 1px solid $border-color;
     position: relative;
-    padding: 6px 10px;
+    padding: 7px 10px 8px;
     border-radius: 30px;
-    width: 150px;
+    width: 186px;
     margin-bottom: 10px;
 
+    &:hover {
+      background-color: $gray-lighter;
+      .dropdown-menu-toggle {
+        background-color: transparent;
+      }
+    }
+
     &.playable {
-      background-color: $gray-light;
 
       svg {
-        height: 12px;
-        width: 12px;
+        height: 13px;
+        width: 20px;
         position: relative;
         top: 1px;
 
@@ -342,10 +373,20 @@
     }
 
     .build-content {
-      width: 130px;
+      display: -ms-flexbox;
+      display: -webkit-flex;
+      display: flex;
+      width: 164px;
+
+      .ci-status-icon {
+        svg {
+          height: 20px;
+          width: 20px;
+        }
+      }
 
       .ci-status-text {
-        width: 110px;
+        width: 135px;
         white-space: nowrap;
         overflow: hidden;
         text-overflow: ellipsis;
@@ -356,44 +397,53 @@
       }
 
       a {
-        color: $layout-link-gray;
+        color: $gl-text-color-light;
         text-decoration: none;
-
-        &:hover {
-          .ci-status-text {
-            text-decoration: underline;
-          }
-        }
       }
 
       .dropdown-menu-toggle {
         border: none;
         width: auto;
         padding: 0;
-        color: $layout-link-gray;
+        color: $gl-text-color-light;
+        flex-grow: 1;
 
         .ci-status-text {
-          width: 80px;
+          max-width: 112px;
+          width: auto;
         }
       }
 
       .grouped-pipeline-dropdown {
         padding: 8px 0;
-        width: 200px;
+        width: 186px;
         left: auto;
-        right: -214px;
+        right: -197px;
         top: -9px;
         max-height: 245px;
         overflow-y: scroll;
 
-        a:hover {
-          .ci-status-text {
-            text-decoration: none;
+        a {
+          color: $gl-text-color;
+          padding: 7px 8px 8px;
+
+          &:hover {
+            background-color: $blue-light-transparent;
+            border-radius: 3px;
+
+            .ci-status-text {
+              text-decoration: none;
+            }
           }
         }
 
+        svg {
+          width: 14px;
+          height: 14px;
+        }
+
         .ci-status-text {
-          width: 145px;
+          width: 112px;
         }
 
         .arrow {
@@ -426,9 +476,10 @@
       }
 
       .badge {
-        background-color: $gray-dark;
-        color: $layout-link-gray;
+        background-color: $gray-darker;
+        color: $gl-text-color-light;
         font-weight: normal;
+        margin-left: $btn-xs-side-margin;
       }
     }
 
@@ -442,10 +493,10 @@
       &::after {
         content: '';
         position: absolute;
-        top: 50%;
-        right: -69px;
+        top: 48%;
+        right: -48px;
         border-top: 2px solid $border-color;
-        width: 69px;
+        width: 48px;
         height: 1px;
       }
     }
@@ -454,25 +505,25 @@
     &:not(:first-child) {
       &::after, &::before {
         content: '';
-        top: -47px;
+        top: -49px;
         position: absolute;
         border-bottom: 2px solid $border-color;
-        width: 20px;
-        height: 65px;
+        width: 25px;
+        height: 69px;
       }
 
       // Right connecting curves
       &::after {
-        right: -20px;
+        right: -25px;
         border-right: 2px solid $border-color;
-        border-radius: 0 0 15px;
+        border-radius: 0 0 20px;
       }
 
       // Left connecting curves
       &::before {
-        left: -20px;
+        left: -25px;
         border-left: 2px solid $border-color;
-        border-radius: 0 0 0 15px;
+        border-radius: 0 0 0 20px;
       }
     }
 
@@ -480,7 +531,7 @@
     &:nth-child(2) {
       &::after, &::before {
         height: 29px;
-        top: -10px;
+        top: -9px;
       }
       .curve {
         display: block;
@@ -538,20 +589,20 @@
       width: 21px;
       height: 25px;
       position: absolute;
-      top: -29px;
+      top: -32px;
       border-top: 2px solid $border-color;
     }
 
     &::after {
-      left: -39px;
+      left: -44px;
       border-right: 2px solid $border-color;
-      border-radius: 0 15px;
+      border-radius: 0 20px;
     }
 
     &::before {
-      right: -39px;
+      right: -44px;
       border-left: 2px solid $border-color;
-      border-radius: 15px 0 0;
+      border-radius: 20px 0 0;
     }
   }
 }
diff --git a/app/views/projects/ci/builds/_build_pipeline.html.haml b/app/views/projects/ci/builds/_build_pipeline.html.haml
index 547bc0c9c19..017d3ff6af2 100644
--- a/app/views/projects/ci/builds/_build_pipeline.html.haml
+++ b/app/views/projects/ci/builds/_build_pipeline.html.haml
@@ -5,8 +5,10 @@
     .ci-status-text= subject.name
 - elsif can?(current_user, :read_build, @project)
   = link_to namespace_project_build_path(subject.project.namespace, subject.project, subject) do
-    = render_status_with_link('build', subject.status)
+    %span.ci-status-icon
+      = render_status_with_link('build', subject.status)
     .ci-status-text= subject.name
 - else
-  = render_status_with_link('build', subject.status)
+  %span.ci-status-icon
+    = render_status_with_link('build', subject.status)
   = ci_icon_for_status(subject.status)
diff --git a/app/views/projects/commit/_pipeline.html.haml b/app/views/projects/commit/_pipeline.html.haml
index da5b9832ba5..288c06d9b67 100644
--- a/app/views/projects/commit/_pipeline.html.haml
+++ b/app/views/projects/commit/_pipeline.html.haml
@@ -1,45 +1,46 @@
-.row-content-block.build-content.middle-block.pipeline-actions
-  .pull-right
-    .btn.btn-grouped.btn-white.toggle-pipeline-btn
-      %span.toggle-btn-text Hide
-      %span pipeline graph
-      = icon('caret-up')
-    - if can?(current_user, :update_pipeline, pipeline.project)
-      - if pipeline.builds.latest.failed.any?(&:retryable?)
-        = link_to "Retry failed", retry_namespace_project_pipeline_path(pipeline.project.namespace, pipeline.project, pipeline.id), class: 'btn btn-grouped btn-primary', method: :post
+.pipeline-graph-container
+  .row-content-block.build-content.middle-block.pipeline-actions
+    .pull-right
+      .btn.btn-grouped.btn-white.toggle-pipeline-btn
+        %span.toggle-btn-text Hide
+        %span pipeline graph
+        %span.caret
+      - if can?(current_user, :update_pipeline, pipeline.project)
+        - if pipeline.builds.latest.failed.any?(&:retryable?)
+          = link_to "Retry failed", retry_namespace_project_pipeline_path(pipeline.project.namespace, pipeline.project, pipeline.id), class: 'btn btn-grouped btn-primary', method: :post
 
-      - if pipeline.builds.running_or_pending.any?
-        = link_to "Cancel running", cancel_namespace_project_pipeline_path(pipeline.project.namespace, pipeline.project, pipeline.id), data: { confirm: 'Are you sure?' }, class: 'btn btn-grouped btn-danger', method: :post
+        - if pipeline.builds.running_or_pending.any?
+          = link_to "Cancel running", cancel_namespace_project_pipeline_path(pipeline.project.namespace, pipeline.project, pipeline.id), data: { confirm: 'Are you sure?' }, class: 'btn btn-grouped btn-danger', method: :post
 
-  .oneline.clearfix
-    - if defined?(pipeline_details) && pipeline_details
-      Pipeline
-      = link_to "##{pipeline.id}", namespace_project_pipeline_path(pipeline.project.namespace, pipeline.project, pipeline.id), class: "monospace"
-      with
-      = pluralize pipeline.statuses.count(:id), "build"
-      - if pipeline.ref
-        for
-        = link_to pipeline.ref, namespace_project_commits_path(pipeline.project.namespace, pipeline.project, pipeline.ref), class: "monospace"
-      - if defined?(link_to_commit) && link_to_commit
-        for commit
-        = link_to pipeline.short_sha, namespace_project_commit_path(pipeline.project.namespace, pipeline.project, pipeline.sha), class: "monospace"
-      - if pipeline.duration
-        in
-        = time_interval_in_words pipeline.duration
+    .oneline.clearfix
+      - if defined?(pipeline_details) && pipeline_details
+        Pipeline
+        = link_to "##{pipeline.id}", namespace_project_pipeline_path(pipeline.project.namespace, pipeline.project, pipeline.id), class: "monospace"
+        with
+        = pluralize pipeline.statuses.count(:id), "build"
+        - if pipeline.ref
+          for
+          = link_to pipeline.ref, namespace_project_commits_path(pipeline.project.namespace, pipeline.project, pipeline.ref), class: "monospace"
+        - if defined?(link_to_commit) && link_to_commit
+          for commit
+          = link_to pipeline.short_sha, namespace_project_commit_path(pipeline.project.namespace, pipeline.project, pipeline.sha), class: "monospace"
+        - if pipeline.duration
+          in
+          = time_interval_in_words pipeline.duration
 
-.row-content-block.build-content.middle-block.pipeline-graph
-  .pipeline-visualization
-    %ul.stage-column-list
-      - stages = pipeline.stages_with_latest_statuses
-      - stages.each do |stage, statuses|
-        %li.stage-column
-          .stage-name
-            %a{name: stage}
-            - if stage
-              = stage.titleize
-          .builds-container
-            %ul
-              = render "projects/commit/pipeline_stage", statuses: statuses
+  .row-content-block.build-content.middle-block.pipeline-graph.hidden
+    .pipeline-visualization
+      %ul.stage-column-list
+        - stages = pipeline.stages_with_latest_statuses
+        - stages.each do |stage, statuses|
+          %li.stage-column
+            .stage-name
+              %a{name: stage}
+              - if stage
+                = stage.titleize
+            .builds-container
+              %ul
+                = render "projects/commit/pipeline_stage", statuses: statuses
 
 
 - if pipeline.yaml_errors.present?
diff --git a/app/views/projects/commit/_pipeline_stage.html.haml b/app/views/projects/commit/_pipeline_stage.html.haml
index 23c5c51fbc2..289aa5178b1 100644
--- a/app/views/projects/commit/_pipeline_stage.html.haml
+++ b/app/views/projects/commit/_pipeline_stage.html.haml
@@ -10,5 +10,5 @@
   - else
     %li.build
       .curve
-      .build-content
+      .dropdown.inline.build-content
         = render "projects/commit/pipeline_status_group", name: group_name, subject: grouped_statuses
diff --git a/app/views/projects/commit/_pipeline_status_group.html.haml b/app/views/projects/commit/_pipeline_status_group.html.haml
index 4e7a6f1af08..6ada719e006 100644
--- a/app/views/projects/commit/_pipeline_status_group.html.haml
+++ b/app/views/projects/commit/_pipeline_status_group.html.haml
@@ -1,11 +1,12 @@
 - group_status = CommitStatus.where(id: subject).status
-= render_status_with_link('build', group_status)
-.dropdown.inline
-  %button.dropdown-menu-toggle{ type: 'button', data: { toggle: 'dropdown' } }
-    %span.ci-status-text
-      = name
-    %span.badge= subject.size
-  %ul.dropdown-menu.grouped-pipeline-dropdown
-    .arrow
-    - subject.each do |status|
+%button.dropdown-menu-toggle{ type: 'button', data: { toggle: 'dropdown' } }
+  %span.ci-status-icon
+    = render_status_with_link('build', group_status)
+  %span.ci-status-text
+    = name
+  %span.badge= subject.size
+%ul.dropdown-menu.grouped-pipeline-dropdown
+  %li.arrow
+  - subject.each do |status|
+    %li
       = render "projects/#{status.to_partial_path}_pipeline", subject: status
diff --git a/app/views/projects/generic_commit_statuses/_generic_commit_status.html.haml b/app/views/projects/generic_commit_statuses/_generic_commit_status.html.haml
index 331dc1fcc29..80fe6be49b0 100644
--- a/app/views/projects/generic_commit_statuses/_generic_commit_status.html.haml
+++ b/app/views/projects/generic_commit_statuses/_generic_commit_status.html.haml
@@ -62,5 +62,3 @@
     %td.coverage
       - if generic_commit_status.try(:coverage)
         #{generic_commit_status.coverage}%
-
-  %td
diff --git a/app/views/projects/generic_commit_statuses/_generic_commit_status_pipeline.html.haml b/app/views/projects/generic_commit_statuses/_generic_commit_status_pipeline.html.haml
index 409f4701e4b..0a66d60accc 100644
--- a/app/views/projects/generic_commit_statuses/_generic_commit_status_pipeline.html.haml
+++ b/app/views/projects/generic_commit_statuses/_generic_commit_status_pipeline.html.haml
@@ -1,7 +1,9 @@
 - if subject.target_url
   = link_to subject.target_url do
-    = render_status_with_link('commit status', subject.status)
+    %span.ci-status-icon
+      = render_status_with_link('commit status', subject.status)
     %span.ci-status-text= subject.name
 - else
-  = render_status_with_link('commit status', subject.status)
+  %span.ci-status-icon
+    = render_status_with_link('commit status', subject.status)
   %span.ci-status-text= subject.name
diff --git a/config/gitlab.yml.example b/config/gitlab.yml.example
index a79356923b2..114ceac8e1f 100644
--- a/config/gitlab.yml.example
+++ b/config/gitlab.yml.example
@@ -112,7 +112,7 @@ production: &base
 
   ## Reply by email
   # Allow users to comment on issues and merge requests by replying to notification emails.
-  # For documentation on how to set this up, see http://doc.gitlab.com/ce/incoming_email/README.html
+  # For documentation on how to set this up, see http://doc.gitlab.com/ce/administration/reply_by_email.html
   incoming_email:
     enabled: false
 
diff --git a/doc/README.md b/doc/README.md
index 99fbfc3438d..e7712eed5d3 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -43,7 +43,7 @@
 - [System hooks](system_hooks/system_hooks.md) Notifications when users, projects and keys are changed.
 - [Update](update/README.md) Update guides to upgrade your installation.
 - [Welcome message](customization/welcome_message.md) Add a custom welcome message to the sign-in page.
-- [Reply by email](incoming_email/README.md) Allow users to comment on issues and merge requests by replying to notification emails.
+- [Reply by email](administration/reply_by_email.md) Allow users to comment on issues and merge requests by replying to notification emails.
 - [Migrate GitLab CI to CE/EE](migrate_ci_to_ce/README.md) Follow this guide to migrate your existing GitLab CI data to GitLab CE/EE.
 - [Git LFS configuration](workflow/lfs/lfs_administration.md)
 - [Housekeeping](administration/housekeeping.md) Keep your Git repository tidy and fast.
diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md
new file mode 100644
index 00000000000..5a9a1582877
--- /dev/null
+++ b/doc/administration/reply_by_email.md
@@ -0,0 +1,302 @@
+# Reply by email
+
+GitLab can be set up to allow users to comment on issues and merge requests by
+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.**
+
+[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.
+
+## How it works?
+
+### 1. GitLab sends a notification email
+
+When GitLab sends a notification and Reply by email is enabled, the `Reply-To`
+header is set to the address defined in your GitLab configuration, with the
+`%{key}` placeholder (if present) replaced by a specific "reply key". In
+addition, this "reply key" is also added to the `References` header.
+
+### 2. You reply to the notification email
+
+When you reply to the notification email, your email client will:
+
+- send the email to the `Reply-To` address it got from the notification email
+- set the `In-Reply-To` header to the value of the `Message-ID` header from the
+  notification email
+- set the `References` header to the value of the `Message-ID` plus the value of
+  the notification email's `References` header.
+
+### 3. GitLab receives your reply to the notification email
+
+When GitLab receives your reply, it will look for the "reply key" in the
+following headers, in this order:
+
+1. the `To` header
+1. the `References` header
+
+If it finds a reply key, it will be able to leave your reply as a comment on
+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).
+
+To set up a basic Postfix mail server with IMAP access on Ubuntu, follow
+[these instructions](./postfix.md).
+
+### 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"
+    ```
+
+    ```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"
+    ```
+
+1. Reconfigure GitLab and restart mailroom for the changes to take effect:
+
+    ```sh
+    sudo gitlab-ctl reconfigure
+    sudo gitlab-ctl restart mailroom
+    ```
+
+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"
+    ```
+
+    ```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"
+    ```
+
+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"
+    ```
+
+    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
new file mode 100644
index 00000000000..22f10489a6c
--- /dev/null
+++ b/doc/administration/reply_by_email_postfix_setup.md
@@ -0,0 +1,324 @@
+# Set up Postfix for Reply by 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].
+
+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.
+
+## Configure your server firewall
+
+1. Open up port 25 on your server so that people can send email into the server over SMTP.
+2. If the mail server is different from the server running GitLab, open up port 143 on your server so that GitLab can read email from the server over IMAP.
+
+## Install packages
+
+1. Install the `postfix` package if it is not installed already:
+
+    ```sh
+    sudo apt-get install postfix
+    ```
+
+    When asked about the environment, select 'Internet Site'. When asked to confirm the hostname, make sure it matches `gitlab.example.com`.
+
+1. Install the `mailutils` package.
+
+    ```sh
+    sudo apt-get install mailutils
+    ```
+
+## Create user
+
+1. Create a user for incoming email.
+
+    ```sh
+    sudo useradd -m -s /bin/bash incoming
+    ```
+
+1. Set a password for this user.
+
+    ```sh
+    sudo passwd incoming
+    ```
+
+    Be sure not to forget this, you'll need it later.
+
+## Test the out-of-the-box setup
+
+1. Connect to the local SMTP server:
+
+    ```sh
+    telnet localhost 25
+    ```
+
+    You should see a prompt like this:
+
+    ```sh
+    Trying 127.0.0.1...
+    Connected to localhost.
+    Escape character is '^]'.
+    220 gitlab.example.com ESMTP Postfix (Ubuntu)
+    ```
+
+    If you get a `Connection refused` error instead, verify that `postfix` is running:
+
+    ```sh
+    sudo postfix status
+    ```
+
+    If it is not, start it:
+
+    ```sh
+    sudo postfix start
+    ```
+
+1. Send the new `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt:
+
+    ```
+    ehlo localhost
+    mail from: root@localhost
+    rcpt to: incoming@localhost
+    data
+    Subject: Re: Some issue
+
+    Sounds good!
+    .
+    quit
+    ```
+
+    _**Note:** The `.` is a literal period on its own line._
+
+    _**Note:** If you receive an error after entering `rcpt to: incoming@localhost`
+    then your Postfix `my_network` configuration is not correct. The error will
+    say 'Temporary lookup failure'. See
+    [Configure Postfix to receive email from the Internet](#configure-postfix-to-receive-email-from-the-internet)._
+
+1. Check if the `incoming` user received the email:
+
+    ```sh
+    su - incoming
+    mail
+    ```
+
+    You should see output like this:
+
+    ```
+    "/var/mail/incoming": 1 message 1 unread
+    >U   1 root@localhost                           59/2842  Re: Some issue
+    ```
+
+    Quit the mail app:
+
+    ```sh
+    q
+    ```
+
+1. Log out of the `incoming` account and go back to being `root`:
+
+    ```sh
+    logout
+    ```
+
+## Configure Postfix to use Maildir-style mailboxes
+
+Courier, which we will install later to add IMAP authentication, requires mailboxes to have the Maildir format, rather than mbox.
+
+1. Configure Postfix to use Maildir-style mailboxes:
+
+    ```sh
+    sudo postconf -e "home_mailbox = Maildir/"
+    ```
+
+1. Restart Postfix:
+
+    ```sh
+    sudo /etc/init.d/postfix restart
+    ```
+
+1. Test the new setup:
+
+    1. Follow steps 1 and 2 of _[Test the out-of-the-box setup](#test-the-out-of-the-box-setup)_.
+    1. Check if the `incoming` user received the email:
+
+        ```sh
+        su - incoming
+        MAIL=/home/incoming/Maildir
+        mail
+        ```
+
+        You should see output like this:
+
+        ```
+        "/home/incoming/Maildir": 1 message 1 unread
+        >U   1 root@localhost                           59/2842  Re: Some issue
+        ```
+
+        Quit the mail app:
+
+        ```sh
+        q
+        ```
+
+    _**Note:** If `mail` returns an error `Maildir: Is a directory` then your
+    version of `mail` doesn't support Maildir style mailboxes. Install
+    `heirloom-mailx` by running `sudo apt-get install heirloom-mailx`. Then,
+    try the above steps again, substituting `heirloom-mailx` for the `mail`
+    command._
+
+1. Log out of the `incoming` account and go back to being `root`:
+
+    ```sh
+    logout
+    ```
+
+## Install the Courier IMAP server
+
+1. Install the `courier-imap` package:
+
+    ```sh
+    sudo apt-get install courier-imap
+    ```
+
+## Configure Postfix to receive email from the internet
+
+1. Let Postfix know about the domains that it should consider local:
+
+    ```sh
+    sudo postconf -e "mydestination = gitlab.example.com, localhost.localdomain, localhost"
+    ```
+
+1. Let Postfix know about the IPs that it should consider part of the LAN:
+
+    We'll assume `192.168.1.0/24` is your local LAN. You can safely skip this step if you don't have other machines in the same local network.
+
+    ```sh
+    sudo postconf -e "mynetworks = 127.0.0.0/8, 192.168.1.0/24"
+    ```
+
+1. Configure Postfix to receive mail on all interfaces, which includes the internet:
+
+    ```sh
+    sudo postconf -e "inet_interfaces = all"
+    ```
+
+1. Configure Postfix to use the `+` delimiter for sub-addressing:
+
+    ```sh
+    sudo postconf -e "recipient_delimiter = +"
+    ```
+
+1. Restart Postfix:
+
+    ```sh
+    sudo service postfix restart
+    ```
+
+## Test the final setup
+
+1. Test SMTP under the new setup:
+
+    1. Connect to the SMTP server:
+
+        ```sh
+        telnet gitlab.example.com 25
+        ```
+
+        You should see a prompt like this:
+
+        ```sh
+        Trying 123.123.123.123...
+        Connected to gitlab.example.com.
+        Escape character is '^]'.
+        220 gitlab.example.com ESMTP Postfix (Ubuntu)
+        ```
+
+        If you get a `Connection refused` error instead, make sure your firewall is setup to allow inbound traffic on port 25.
+
+    1. Send the `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt:
+
+        ```
+        ehlo gitlab.example.com
+        mail from: root@gitlab.example.com
+        rcpt to: incoming@gitlab.example.com
+        data
+        Subject: Re: Some issue
+
+        Sounds good!
+        .
+        quit
+        ```
+
+        (Note: The `.` is a literal period on its own line)
+
+    1. Check if the `incoming` user received the email:
+
+        ```sh
+        su - incoming
+        MAIL=/home/incoming/Maildir
+        mail
+        ```
+
+        You should see output like this:
+
+        ```
+        "/home/incoming/Maildir": 1 message 1 unread
+        >U   1 root@gitlab.example.com                           59/2842  Re: Some issue
+        ```
+
+        Quit the mail app:
+
+        ```sh
+        q
+        ```
+
+    1. Log out of the `incoming` account and go back to being `root`:
+
+        ```sh
+        logout
+        ```
+
+1. Test IMAP under the new setup:
+
+    1. Connect to the IMAP server:
+
+        ```sh
+        telnet gitlab.example.com 143
+        ```
+
+        You should see a prompt like this:
+
+        ```sh
+        Trying 123.123.123.123...
+        Connected to mail.example.gitlab.com.
+        Escape character is '^]'.
+        - OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE ACL ACL2=UNION] Courier-IMAP ready. Copyright 1998-2011 Double Precision, Inc.  See COPYING for distribution information.
+        ```
+
+    1. Sign in as the `incoming` user to test IMAP, by entering the following into the IMAP prompt:
+
+        ```
+        a login incoming PASSWORD
+        ```
+
+        Replace PASSWORD with the password you set on the `incoming` user earlier.
+
+        You should see output like this:
+
+        ```
+        a OK LOGIN Ok.
+        ```
+
+    1. Disconnect from the IMAP server:
+
+        ```sh
+        a logout
+        ```
+
+## Done!
+
+If all the tests were successful, Postfix is all set up and ready to receive email! Continue with the [Reply by email](./README.md) 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
diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md
index 483060395dd..b561c2f82aa 100644
--- a/doc/administration/restart_gitlab.md
+++ b/doc/administration/restart_gitlab.md
@@ -139,7 +139,7 @@ If you are using other init systems, like systemd, you can check the
 
 [omnibus-dl]: https://about.gitlab.com/downloads/ "Download the Omnibus packages"
 [install]: ../install/installation.md "Documentation to install GitLab from source"
-[mailroom]: ../incoming_email/README.md "Used for replying by email in GitLab issues and merge requests"
+[mailroom]: reply_by_email.md "Used for replying by email in GitLab issues and merge requests"
 [chef]: https://www.chef.io/chef/ "Chef official website"
 [src-service]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/init.d/gitlab "GitLab init service file"
 [gl-recipes]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/init "GitLab Recipes repository"
diff --git a/doc/incoming_email/README.md b/doc/incoming_email/README.md
index 5a9a1582877..db0f03f2c98 100644
--- a/doc/incoming_email/README.md
+++ b/doc/incoming_email/README.md
@@ -1,302 +1 @@
-# Reply by email
-
-GitLab can be set up to allow users to comment on issues and merge requests by
-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.**
-
-[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.
-
-## How it works?
-
-### 1. GitLab sends a notification email
-
-When GitLab sends a notification and Reply by email is enabled, the `Reply-To`
-header is set to the address defined in your GitLab configuration, with the
-`%{key}` placeholder (if present) replaced by a specific "reply key". In
-addition, this "reply key" is also added to the `References` header.
-
-### 2. You reply to the notification email
-
-When you reply to the notification email, your email client will:
-
-- send the email to the `Reply-To` address it got from the notification email
-- set the `In-Reply-To` header to the value of the `Message-ID` header from the
-  notification email
-- set the `References` header to the value of the `Message-ID` plus the value of
-  the notification email's `References` header.
-
-### 3. GitLab receives your reply to the notification email
-
-When GitLab receives your reply, it will look for the "reply key" in the
-following headers, in this order:
-
-1. the `To` header
-1. the `References` header
-
-If it finds a reply key, it will be able to leave your reply as a comment on
-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).
-
-To set up a basic Postfix mail server with IMAP access on Ubuntu, follow
-[these instructions](./postfix.md).
-
-### 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"
-    ```
-
-    ```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"
-    ```
-
-1. Reconfigure GitLab and restart mailroom for the changes to take effect:
-
-    ```sh
-    sudo gitlab-ctl reconfigure
-    sudo gitlab-ctl restart mailroom
-    ```
-
-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"
-    ```
-
-    ```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"
-    ```
-
-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"
-    ```
-
-    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.
+This document was moved to [administration/reply_by_email](../administration/reply_by_email.md).
diff --git a/doc/incoming_email/postfix.md b/doc/incoming_email/postfix.md
index 787d21f7f8f..90833238ac5 100644
--- a/doc/incoming_email/postfix.md
+++ b/doc/incoming_email/postfix.md
@@ -1,321 +1 @@
-# Set up Postfix for Reply by 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.
-
-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.
-
-## Configure your server firewall
-
-1. Open up port 25 on your server so that people can send email into the server over SMTP.
-2. If the mail server is different from the server running GitLab, open up port 143 on your server so that GitLab can read email from the server over IMAP.
-
-## Install packages
-
-1. Install the `postfix` package if it is not installed already:
-
-    ```sh
-    sudo apt-get install postfix
-    ```
-
-    When asked about the environment, select 'Internet Site'. When asked to confirm the hostname, make sure it matches `gitlab.example.com`.
-
-1. Install the `mailutils` package.
-
-    ```sh
-    sudo apt-get install mailutils
-    ```
-
-## Create user
-
-1. Create a user for incoming email.
-
-    ```sh
-    sudo useradd -m -s /bin/bash incoming
-    ```
-
-1. Set a password for this user.
-
-    ```sh
-    sudo passwd incoming
-    ```
-
-    Be sure not to forget this, you'll need it later.
-
-## Test the out-of-the-box setup
-
-1. Connect to the local SMTP server:
-    
-    ```sh
-    telnet localhost 25
-    ```
-
-    You should see a prompt like this:
-
-    ```sh
-    Trying 127.0.0.1...
-    Connected to localhost.
-    Escape character is '^]'.
-    220 gitlab.example.com ESMTP Postfix (Ubuntu)
-    ```
-
-    If you get a `Connection refused` error instead, verify that `postfix` is running:
-
-    ```sh
-    sudo postfix status
-    ```
-
-    If it is not, start it:
-
-    ```sh
-    sudo postfix start
-    ```
-
-1. Send the new `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt:
-    
-    ```
-    ehlo localhost
-    mail from: root@localhost
-    rcpt to: incoming@localhost
-    data
-    Subject: Re: Some issue
-
-    Sounds good!
-    .
-    quit
-    ```
-
-    _**Note:** The `.` is a literal period on its own line._
-
-    _**Note:** If you receive an error after entering `rcpt to: incoming@localhost`
-    then your Postfix `my_network` configuration is not correct. The error will
-    say 'Temporary lookup failure'. See
-    [Configure Postfix to receive email from the Internet](#configure-postfix-to-receive-email-from-the-internet)._
-
-1. Check if the `incoming` user received the email:
-    
-    ```sh
-    su - incoming
-    mail
-    ```
-
-    You should see output like this:
-
-    ```
-    "/var/mail/incoming": 1 message 1 unread
-    >U   1 root@localhost                           59/2842  Re: Some issue
-    ```
-
-    Quit the mail app:
-
-    ```sh
-    q
-    ```
-
-1. Log out of the `incoming` account and go back to being `root`:
-
-    ```sh
-    logout
-    ```
-
-## Configure Postfix to use Maildir-style mailboxes
-
-Courier, which we will install later to add IMAP authentication, requires mailboxes to have the Maildir format, rather than mbox.
-
-1. Configure Postfix to use Maildir-style mailboxes:
-    
-    ```sh
-    sudo postconf -e "home_mailbox = Maildir/"
-    ```
-
-1. Restart Postfix:
-    
-    ```sh
-    sudo /etc/init.d/postfix restart
-    ```
-
-1. Test the new setup:
-    
-    1. Follow steps 1 and 2 of _[Test the out-of-the-box setup](#test-the-out-of-the-box-setup)_.
-    1. Check if the `incoming` user received the email:
-    
-        ```sh
-        su - incoming
-        MAIL=/home/incoming/Maildir
-        mail
-        ```
-
-        You should see output like this:
-
-        ```
-        "/home/incoming/Maildir": 1 message 1 unread
-        >U   1 root@localhost                           59/2842  Re: Some issue
-        ```
-
-        Quit the mail app:
-
-        ```sh
-        q
-        ```
-
-    _**Note:** If `mail` returns an error `Maildir: Is a directory` then your
-    version of `mail` doesn't support Maildir style mailboxes. Install
-    `heirloom-mailx` by running `sudo apt-get install heirloom-mailx`. Then,
-    try the above steps again, substituting `heirloom-mailx` for the `mail`
-    command._
-
-1. Log out of the `incoming` account and go back to being `root`:
-
-    ```sh
-    logout
-    ```
-
-## Install the Courier IMAP server
-    
-1. Install the `courier-imap` package:
-
-    ```sh
-    sudo apt-get install courier-imap
-    ```
-
-## Configure Postfix to receive email from the internet
-
-1. Let Postfix know about the domains that it should consider local:
-    
-    ```sh
-    sudo postconf -e "mydestination = gitlab.example.com, localhost.localdomain, localhost"
-    ```
-
-1. Let Postfix know about the IPs that it should consider part of the LAN:
-    
-    We'll assume `192.168.1.0/24` is your local LAN. You can safely skip this step if you don't have other machines in the same local network.
-    
-    ```sh
-    sudo postconf -e "mynetworks = 127.0.0.0/8, 192.168.1.0/24"
-    ```
-
-1. Configure Postfix to receive mail on all interfaces, which includes the internet:
-    
-    ```sh
-    sudo postconf -e "inet_interfaces = all"
-    ```
-
-1. Configure Postfix to use the `+` delimiter for sub-addressing:
-    
-    ```sh
-    sudo postconf -e "recipient_delimiter = +"
-    ```
-
-1. Restart Postfix:
-    
-    ```sh
-    sudo service postfix restart
-    ```
-
-## Test the final setup
-
-1. Test SMTP under the new setup:
-    
-    1. Connect to the SMTP server:
-        
-        ```sh
-        telnet gitlab.example.com 25
-        ```
-
-        You should see a prompt like this:
-
-        ```sh
-        Trying 123.123.123.123...
-        Connected to gitlab.example.com.
-        Escape character is '^]'.
-        220 gitlab.example.com ESMTP Postfix (Ubuntu)
-        ```
-
-        If you get a `Connection refused` error instead, make sure your firewall is setup to allow inbound traffic on port 25.
-
-    1. Send the `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt:
-        
-        ```
-        ehlo gitlab.example.com
-        mail from: root@gitlab.example.com
-        rcpt to: incoming@gitlab.example.com
-        data
-        Subject: Re: Some issue
-
-        Sounds good!
-        .
-        quit
-        ```
-
-        (Note: The `.` is a literal period on its own line)
-
-    1. Check if the `incoming` user received the email:
-    
-        ```sh
-        su - incoming
-        MAIL=/home/incoming/Maildir
-        mail
-        ```
-
-        You should see output like this:
-
-        ```
-        "/home/incoming/Maildir": 1 message 1 unread
-        >U   1 root@gitlab.example.com                           59/2842  Re: Some issue
-        ```
-
-        Quit the mail app:
-
-        ```sh
-        q
-        ```
-
-    1. Log out of the `incoming` account and go back to being `root`:
-
-        ```sh
-        logout
-        ```
-
-1. Test IMAP under the new setup:
-    
-    1. Connect to the IMAP server:
-        
-        ```sh
-        telnet gitlab.example.com 143
-        ```
-
-        You should see a prompt like this:
-
-        ```sh
-        Trying 123.123.123.123...
-        Connected to mail.example.gitlab.com.
-        Escape character is '^]'.
-        - OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE ACL ACL2=UNION] Courier-IMAP ready. Copyright 1998-2011 Double Precision, Inc.  See COPYING for distribution information.
-        ```
-
-    1. Sign in as the `incoming` user to test IMAP, by entering the following into the IMAP prompt:
-
-        ```
-        a login incoming PASSWORD
-        ```
-
-        Replace PASSWORD with the password you set on the `incoming` user earlier.
-
-        You should see output like this:
-
-        ```
-        a OK LOGIN Ok.
-        ```
-
-    1. Disconnect from the IMAP server:
-
-        ```sh
-        a logout
-        ```
-
-## Done!
-
-If all the tests were successful, Postfix is all set up and ready to receive email! Continue with the [Reply by email](./README.md) guide to configure GitLab.
-
----------
-
-_This document was adapted from https://help.ubuntu.com/community/PostfixBasicSetupHowto, by contributors to the Ubuntu documentation wiki._
+This document was moved to [administration/reply_by_email_postfix_setup](../administration/reply_by_email_postfix_setup.md).
diff --git a/doc/install/installation.md b/doc/install/installation.md
index 378ab6857b8..1fa8678223a 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -563,7 +563,7 @@ Using a self-signed certificate is discouraged but if you must use it follow the
 
 ### Enable Reply by email
 
-See the ["Reply by email" documentation](../incoming_email/README.md) for more information on how to set this up.
+See the ["Reply by email" documentation](../administration/reply_by_email.md) for more information on how to set this up.
 
 ### LDAP Authentication
 
diff --git a/doc/workflow/importing/migrating_from_svn.md b/doc/workflow/importing/migrating_from_svn.md
index 4828bb5dce6..423b095e69e 100644
--- a/doc/workflow/importing/migrating_from_svn.md
+++ b/doc/workflow/importing/migrating_from_svn.md
@@ -4,6 +4,112 @@ Subversion (SVN) is a central version control system (VCS) while
 Git is a distributed version control system. There are some major differences
 between the two, for more information consult your favorite search engine.
 
+## Overview
+
+There are two approaches to SVN to Git migration:
+
+1. [Git/SVN Mirror](#smooth-migration-with-a-gitsvn-mirror-using-subgit) which:
+    - Makes the GitLab repository to mirror the SVN project.
+    - Git and SVN repositories are kept in sync; you can use either one.
+    - Smoothens the migration process and allows to manage migration risks.
+
+1. [Cut over migration](#cut-over-migration-with-svn2git) which:
+     - Translates and imports the existing data and history from SVN to Git.
+     - Is a fire and forget approach, good for smaller teams.
+
+## Smooth migration with a Git/SVN mirror using SubGit
+
+[SubGit](https://subgit.com) is a tool for a smooth, stress-free SVN to Git
+migration. It creates a writable Git mirror of a local or remote Subversion
+repository and that way you can use both Subversion and Git as long as you like.
+It requires access to your GitLab server as it talks with the Git repositories
+directly in a filesystem level.
+
+### SubGit prerequisites
+
+1. Install Oracle JRE 1.8 or newer. On Debian-based Linux distributions you can
+   follow [this article](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html).
+1. Download SubGit from https://subgit.com/download/.
+1. Unpack the downloaded SubGit zip archive to the `/opt` directory. The `subgit`
+   command will be available at `/opt/subgit-VERSION/bin/subgit`.
+
+### SubGit configuration
+
+The first step to mirror you SVN repository in GitLab is to create a new empty
+project which will be used as a mirror. For Omnibus installations the path to
+the repository will be located at
+`/var/opt/gitlab/git-data/repositories/USER/REPO.git` by default. For
+installations from source, the default repository directory will be
+`/home/git/repositories/USER/REPO.git`. For convenience, assign this path to a
+variable:
+
+```
+GIT_REPO_PATH=/var/opt/gitlab/git-data/repositories/USER/REPOS.git
+```
+
+SubGit will keep this repository in sync with a remote SVN project. For
+convenience, assign your remote SVN project URL to a variable:
+
+```
+SVN_PROJECT_URL=http://svn.company.com/repos/project
+```
+
+Next you need to run SubGit to set up a Git/SVN mirror. Make sure the following
+`subgit` command is ran on behalf of the same user that keeps ownership of
+GitLab Git repositories (by default `git`):
+
+```
+subgit configure --layout auto $SVN_PROJECT_URL $GIT_REPO_PATH
+```
+
+Adjust authors and branches mappings, if necessary. Open with your favorite
+text editor:
+
+```
+edit $GIT_REPO_PATH/subgit/authors.txt
+edit $GIT_REPO_PATH/subgit/config
+```
+
+For more information regarding the SubGit configuration options, refer to
+[SubGit's documentation](https://subgit.com/documentation.html) website.
+
+### Initial translation
+
+Now that SubGit has configured the Git/SVN repos, run `subgit` to perform the
+initial translation of existing SVN revisions into the Git repository:
+
+```
+subgit install $GIT_REPOS_PATH
+```
+
+After the initial translation is completed, the Git repository and the SVN
+project will be kept in sync by `subgit` - new Git commits will be translated to
+SVN revisions and new SVN revisions will be translated to Git commits. Mirror
+works transparently and does not require any special commands.
+
+If you would prefer to perform one-time cut over migration with `subgit`, use
+the `import` command instead of `install`:
+
+```
+subgit import $GIT_REPO_PATH
+```
+
+### SubGit licensing
+
+Running SubGit in a mirror mode requires a
+[registration](https://subgit.com/pricing.html). Registration is free for open
+source, academic and startup projects.
+
+We're currently working on deeper GitLab/SubGit integration. You may track our
+progress at [this issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/990).
+
+### SubGit support
+
+For any questions related to SVN to GitLab migration with SubGit, you can
+contact the SubGit team directly at [support@subgit.com](mailto:support@subgit.com).
+
+## Cut over migration with svn2git
+
 If you are currently using an SVN repository, you can migrate the repository
 to Git and GitLab. We recommend a hard cut over - run the migration command once
 and then have all developers start using the new GitLab repository immediately.
@@ -75,5 +181,3 @@ git push --tags origin
 ## Contribute to this guide
 We welcome all contributions that would expand this guide with instructions on
 how to migrate from SVN and other version control systems.
-
-
diff --git a/lib/tasks/gitlab/check.rake b/lib/tasks/gitlab/check.rake
index 5f4a6bbfa35..2ae48a970ce 100644
--- a/lib/tasks/gitlab/check.rake
+++ b/lib/tasks/gitlab/check.rake
@@ -671,7 +671,7 @@ namespace :gitlab do
           "Enable mail_room in the init.d configuration."
         )
         for_more_information(
-          "doc/incoming_email/README.md"
+          "doc/administration/reply_by_email.md"
         )
         fix_and_rerun
       end
@@ -690,7 +690,7 @@ namespace :gitlab do
           "Enable mail_room in your Procfile."
         )
         for_more_information(
-          "doc/incoming_email/README.md"
+          "doc/administration/reply_by_email.md"
         )
         fix_and_rerun
       end
@@ -747,7 +747,7 @@ namespace :gitlab do
           "Check that the information in config/gitlab.yml is correct"
         )
         for_more_information(
-          "doc/incoming_email/README.md"
+          "doc/administration/reply_by_email.md"
         )
         fix_and_rerun
       end