Merge branch 'master' into docs-patch-71docs-patch-71

992 files changed, 28916 insertions, 17534 deletions

diff --git a/doc/README.md b/doc/README.md
index 3863e17c268..8ce5d2e240a 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -9,7 +9,7 @@ description: 'Learn how to use and administer GitLab, the most scalable Git-base
 </div>
 <!-- the div above will not display on the docs site but will display on /help -->
 
-# GitLab Documentation
+# GitLab Docs
 
 Welcome to [GitLab](https://about.gitlab.com/) Documentation.
 
@@ -25,7 +25,7 @@ No matter how you use GitLab, we have documentation for you.
 | [**User Documentation**](user/index.md)<br/>Discover features and concepts for GitLab users.                                               | [**Administrator documentation**](administration/index.md)<br/>Everything GitLab self-managed administrators need to know. |
 | [**Contributing to GitLab**](#contributing-to-gitlab)<br/>At GitLab, everyone can contribute!                                              | [**New to Git and GitLab?**](#new-to-git-and-gitlab)<br/>We have resources to get you started.                             |
 | [**Building an integration with GitLab?**](#building-an-integration-with-gitlab)<br/>Consult our automation and integration documentation. | [**Coming to GitLab from another platform?**](#coming-to-gitlab-from-another-platform)<br/>Consult our handy guides.       |
-| [**Install GitLab**](https://about.gitlab.com/install/)<br/>Installation options for different platforms.                                  | [**Subscribe to GitLab**](#subscribe-to-gitlab)<br/>Get access to more features.                                           |
+| [**Install GitLab**](https://about.gitlab.com/install/)<br/>Installation options for different platforms.                                  | [**Customers**](subscriptions/index.md)<br/>Information for new and existing customers.                                    |
 | [**Update GitLab**](update/README.md)<br/>Update your GitLab self-managed instance to the latest version.                                  | [**GitLab Releases**](https://about.gitlab.com/releases/)<br/>What's new in GitLab.                                        |
 
 ## Popular Documentation
@@ -38,7 +38,7 @@ Have a look at some of our most popular documentation resources:
 | [GitLab CI/CD examples](ci/examples/README.md)                  | Get up to speed quickly with common CI/CD scenarios.             |
 | [GitLab Container Registry](user/project/container_registry.md) | Host containers within GitLab.                                   |
 | [GitLab Pages](user/project/pages/index.md)                     | Host static websites for your projects with GitLab.              |
-| [GitLab.com settings](user/gitlab_com/index.md)                 | Settings for [GitLab.com](#gitlabcom).                           |
+| [GitLab.com settings](user/gitlab_com/index.md)                 | Settings for GitLab.com.                                         |
 | [Kubernetes integration](user/project/clusters/index.md)        | Use GitLab with Kubernetes.                                      |
 | [SSH authentication](ssh/README.md)                             | Secure your network communications.                              |
 | [Using Docker images](ci/docker/using_docker_images.md)         | Build and test your applications with Docker.                    |
@@ -54,7 +54,7 @@ GitLab provides solutions for [all the stages of the DevOps lifecycle](https://a
 ![DevOps Stages](img/devops-stages.png)
 
 GitLab is like a top-of-the-line kitchen for making software. As the executive
-chef, you decide what software you want serve. Using your recipe, GitLab handles
+chef, you decide what software you want to serve. Using your recipe, GitLab handles
 all the prep work, cooking, and delivery, so you can turn around orders faster
 than ever.
 
@@ -86,7 +86,7 @@ The following documentation relates to the DevOps **Manage** stage:
 
 | Manage Topics                                                                         | Description                                                                                                                                                                                                                  |
 |:--------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [Authentication and<br/>Authorization](administration/auth/README.md) **[CORE ONLY]** | Supported authentication and authorization providers.                                                                                                                                                                        |
+| [Authentication and<br/>Authorization](administration/auth/README.md) **(CORE ONLY)** | Supported authentication and authorization providers.                                                                                                                                                                        |
 | [GitLab Cycle Analytics](user/project/cycle_analytics.md)                             | Measure the time it takes to go from an [idea to production](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) for each project you have. |
 | [Instance Statistics](user/instance_statistics/index.md)                              | Discover statistics on how many GitLab features you use and user activity.                                                                                                                                                   |
 
@@ -107,18 +107,18 @@ The following documentation relates to the DevOps **Plan** stage:
 
 | Plan Topics                                                                                                                                                                                                                                                        | Description                                                                                                                                      |
 |:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------|
-| [Burndown Charts](user/project/milestones/burndown_charts.md) **[STARTER]**                                                                                                                                                                                        | Watch your project's progress throughout a specific milestone.                                                                                   |
-| [Discussions](user/discussions/index.md)                                                                                                                                                                                                                           | Threads, comments, and resolvable discussions in issues, commits, and  merge requests.                                                           |
+| [Burndown Charts](user/project/milestones/burndown_charts.md) **(STARTER)**                                                                                                                                                                                        | Watch your project's progress throughout a specific milestone.                                                                                   |
+| [Discussions](user/discussions/index.md)                                                                                                                                                                                                                           | Threads, comments, and resolvable threads in issues, commits, and  merge requests.                                                           |
 | [Due Dates](user/project/issues/due_dates.md)                                                                                                                                                                                                                      | Keep track of issue deadlines.                                                                                                                   |
-| [Epics](user/group/epics/index.md) **[ULTIMATE]**                                                                                                                                                                                                                  | Tracking groups of issues that share a theme.                                                                                                    |
-| [Issues](user/project/issues/index.md), including [confidential issues](user/project/issues/confidential_issues.md),<br/>[issue and merge request templates](user/project/description_templates.md),<br/>and [moving issues](user/project/issues/moving_issues.md) | Project issues, restricting access to issues, create templates for submitting new issues and merge requests, and moving issues between projects. |
+| [Epics](user/group/epics/index.md) **(ULTIMATE)**                                                                                                                                                                                                                  | Tracking groups of issues that share a theme.                                                                                                    |
+| [Issues](user/project/issues/index.md), including [confidential issues](user/project/issues/confidential_issues.md),<br/>[issue and merge request templates](user/project/description_templates.md),<br/>and [moving issues](user/project/issues/managing_issues.md#moving-issues) | Project issues, restricting access to issues, create templates for submitting new issues and merge requests, and moving issues between projects. |
 | [Labels](user/project/labels.md)                                                                                                                                                                                                                                   | Categorize issues or merge requests with descriptive labels.                                                                                     |
 | [Milestones](user/project/milestones/index.md)                                                                                                                                                                                                                     | Set milestones for delivery of issues and merge requests, with optional due date.                                                                |
 | [Project Issue Board](user/project/issue_board.md)                                                                                                                                                                                                                 | Display issues on a Scrum or Kanban board.                                                                                                       |
 | [Quick Actions](user/project/quick_actions.md)                                                                                                                                                                                                                     | Shortcuts for common actions on issues or merge requests, replacing the need to click buttons or use dropdowns in GitLab's UI.                   |
-| [Related Issues](user/project/issues/related_issues.md) **[STARTER]**                                                                                                                                                                                              | Create a relationship between issues.                                                                                                            |
-| [Roadmap](user/group/roadmap/index.md) **[ULTIMATE]**                                                                                                                                                                                                              | Visualize epic timelines.                                                                                                                        |
-| [Service Desk](user/project/service_desk.md) **[PREMIUM]**                                                                                                                                                                                                         | A simple way to allow people to create issues in your GitLab instance without needing their own user account.                                    |
+| [Related Issues](user/project/issues/related_issues.md) **(STARTER)**                                                                                                                                                                                              | Create a relationship between issues.                                                                                                            |
+| [Roadmap](user/group/roadmap/index.md) **(ULTIMATE)**                                                                                                                                                                                                              | Visualize epic timelines.                                                                                                                        |
+| [Service Desk](user/project/service_desk.md) **(PREMIUM)**                                                                                                                                                                                                         | A simple way to allow people to create issues in your GitLab instance without needing their own user account.                                    |
 | [Time Tracking](workflow/time_tracking.md)                                                                                                                                                                                                                         | Track time spent on issues and merge requests.                                                                                                   |
 | [Todos](workflow/todos.md)                                                                                                                                                                                                                                         | Keep track of work requiring attention with a chronological list displayed on a simple dashboard.                                                |
 
@@ -143,14 +143,14 @@ The following documentation relates to the DevOps **Create** stage:
 
 | Create Topics - Projects and Groups                                                                                                                                                              | Description                                                                                      |
 |:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------|
-| [Advanced global search](user/search/advanced_global_search.md) **[STARTER]**                                                                                                                    | Leverage Elasticsearch for faster, more advanced code search across your entire GitLab instance. |
-| [Advanced syntax search](user/search/advanced_search_syntax.md) **[STARTER]**                                                                                                                    | Use advanced queries for more targeted search results.                                           |
-| [Contribution analytics](user/group/contribution_analytics/index.md) **[STARTER]**                                                                                                               | See detailed statistics of group contributors.                                                   |
+| [Advanced global search](user/search/advanced_global_search.md) **(STARTER)**                                                                                                                    | Leverage Elasticsearch for faster, more advanced code search across your entire GitLab instance. |
+| [Advanced syntax search](user/search/advanced_search_syntax.md) **(STARTER)**                                                                                                                    | Use advanced queries for more targeted search results.                                           |
+| [Contribution analytics](user/group/contribution_analytics/index.md) **(STARTER)**                                                                                                               | See detailed statistics of group contributors.                                                   |
 | [Create](gitlab-basics/create-project.md) and [fork](gitlab-basics/fork-project.md) projects, and<br/>[import and export projects<br/>between instances](user/project/settings/import_export.md) | Create, duplicate, and move projects.                                                            |
-| [File locking](user/project/file_lock.md) **[PREMIUM]**                                                                                                                                          | Lock files to avoid merge conflicts.                                                             |
+| [File locking](user/project/file_lock.md) **(PREMIUM)**                                                                                                                                          | Lock files to avoid merge conflicts.                                                             |
 | [GitLab Pages](user/project/pages/index.md)                                                                                                                                                      | Build, test, and deploy your static website with GitLab Pages.                                   |
 | [Groups](user/group/index.md) and [Subgroups](user/group/subgroups/index.md)                                                                                                                     | Organize your projects in groups.                                                                |
-| [Issues Analytics](user/group/issues_analytics/index.md) **[PREMIUM]**                                                                                                                           | Check how many issues were created per month.                                                    |
+| [Issues Analytics](user/group/issues_analytics/index.md) **(PREMIUM)**                                                                                                                           | Check how many issues were created per month.                                                    |
 | [Projects](user/project/index.md), including [project access](public_access/public_access.md)<br/>and [settings](user/project/settings/index.md)                                                 | Host source code, and control your project's visibility and set configuration.                   |
 | [Search through GitLab](user/search/index.md)                                                                                                                                                    | Search for issues, merge requests, projects, groups, and todos.                                  |
 | [Snippets](user/snippets.md)                                                                                                                                                                     | Snippets allow you to create little bits of code.                                                |
@@ -175,9 +175,9 @@ The following documentation relates to the DevOps **Create** stage:
 | [Files](user/project/repository/index.md#files)                                                                                                                                                                                                                                                             | Files management.                                                               |
 | [Jupyter Notebook files](user/project/repository/index.md#jupyter-notebook-files)                                                                                                                                                                                                                           | GitLab's support for `.ipynb` files.                                            |
 | [Protected branches](user/project/protected_branches.md)                                                                                                                                                                                                                                                    | Use protected branches.                                                         |
-| [Push rules](push_rules/push_rules.md) **[STARTER]**                                                                                                                                                                                                                                                        | Additional control over pushes to your projects.                                |
+| [Push rules](push_rules/push_rules.md) **(STARTER)**                                                                                                                                                                                                                                                        | Additional control over pushes to your projects.                                |
 | [Repositories](user/project/repository/index.md)                                                                                                                                                                                                                                                            | Manage source code repositories in GitLab's user interface.                     |
-| [Repository mirroring](workflow/repository_mirroring.md) **[STARTER]**                                                                                                                                                                                                                                      | Push to or pull from repositories outside of GitLab                             |
+| [Repository mirroring](workflow/repository_mirroring.md) **(STARTER)**                                                                                                                                                                                                                                      | Push to or pull from repositories outside of GitLab                             |
 | [Start a merge request](user/project/repository/web_editor.md#tips)                                                                                                                                                                                                                                         | Start merge request when committing via GitLab's user interface.                |
 
 <div align="right">
@@ -192,7 +192,7 @@ The following documentation relates to the DevOps **Create** stage:
 |:------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------|
 | [Checking out merge requests locally](user/project/merge_requests/index.md#checkout-merge-requests-locally) | Tips for working with merge requests locally.                                                                                                     |
 | [Cherry-picking](user/project/merge_requests/cherry_pick_changes.md)                                        | Use GitLab for cherry-picking changes.                                                                                                            |
-| [Merge request discussion resolution](user/discussions/index.md#moving-a-single-discussion-to-a-new-issue)  | Resolve discussions, move discussions in a merge request to an issue, and only allow merge requests to be merged if all discussions are resolved. |
+| [Merge request thread resolution](user/discussions/index.md#moving-a-single-thread-to-a-new-issue)          | Resolve threads, move threads in a merge request to an issue, and only allow merge requests to be merged if all threads are resolved. |
 | [Merge requests](user/project/merge_requests/index.md)                                                      | Merge request management.                                                                                                                         |
 | [Work In Progress "WIP" merge requests](user/project/merge_requests/work_in_progress_merge_requests.md)     | Prevent merges of work-in-progress merge requests.                                                                                                |
 
@@ -209,7 +209,7 @@ The following documentation relates to the DevOps **Create** stage:
 | [GitLab API](api/README.md)                                                   | Integrate GitLab via a simple and powerful API.                                                                        |
 | [GitLab Integration](integration/README.md)                                   | Integrate with multiple third-party services with GitLab to allow external issue trackers and external authentication. |
 | [GitLab Webhooks](user/project/integrations/webhooks.md)                      | Let GitLab notify you when new code has been pushed to your project.                                                   |
-| [JIRA Development Panel](integration/jira_development_panel.md) **[PREMIUM]** | See GitLab information in the JIRA Development Panel.                                                                  |
+| [Jira Development Panel](integration/jira_development_panel.md) **(PREMIUM)** | See GitLab information in the Jira Development Panel.                                                                  |
 | [Project Services](user/project/integrations/project_services.md)             | Integrate a project with external services, such as CI and chat.                                                       |
 | [Trello Power-Up](integration/trello_power_up.md)                             | Integrate with GitLab's Trello Power-Up.                                                                               |
 
@@ -233,10 +233,10 @@ The following documentation relates to the DevOps **Verify** stage:
 
 | Verify Topics                                                                     | Description                                                                                             |
 |:----------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------|
-| [Code Quality reports](user/project/merge_requests/code_quality.md) **[STARTER]** | Analyze source code quality.                                                                            |
+| [Code Quality reports](user/project/merge_requests/code_quality.md) **(STARTER)** | Analyze source code quality.                                                                            |
 | [GitLab CI/CD](ci/README.md)                                                      | Explore the features and capabilities of Continuous Integration with GitLab.                            |
 | [JUnit test reports](ci/junit_test_reports.md)                                    | Display JUnit test reports on merge requests.                                                           |
-| [Multi-project pipelines](ci/multi_project_pipelines.md) **[PREMIUM]**            | Visualize entire pipelines that span multiple projects, including all cross-project inter-dependencies. |
+| [Multi-project pipelines](ci/multi_project_pipelines.md) **(PREMIUM)**            | Visualize entire pipelines that span multiple projects, including all cross-project inter-dependencies. |
 | [Pipeline Graphs](ci/pipelines.md#visualizing-pipelines)                          | Visualize builds.                                                                                       |
 | [Review Apps](ci/review_apps/index.md)                                            | Preview changes to your application right from a merge request.                                         |
 
@@ -257,7 +257,7 @@ The following documentation relates to the DevOps **Package** stage:
 | Package Topics                                                  | Description                                            |
 |:----------------------------------------------------------------|:-------------------------------------------------------|
 | [GitLab Container Registry](user/project/container_registry.md) | Learn how to use GitLab's built-in Container Registry. |
-| [GitLab Packages](administration/packages.md) **[PREMIUM]**     | Use GitLab as an NPM registry or Maven repository.     |
+| [GitLab Packages](administration/packages.md) **(PREMIUM)**     | Use GitLab as an NPM registry or Maven repository.     |
 
 <div align="right">
   <a type="button" class="btn btn-default" href="#overview">
@@ -276,10 +276,10 @@ The following documentation relates to the DevOps **Release** stage:
 | Release Topics                                                                                                                      | Description                                                                                                                           |
 |:------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------|
 | [Auto Deploy](topics/autodevops/index.md#auto-deploy)                                                                               | Configure GitLab for the deployment of your application.                                                                              |
-| [Canary Deployments](user/project/canary_deployments.md) **[PREMIUM]**                                                              | Employ a popular CI strategy where a small portion of the fleet is updated to the new version first.                                  |
-| [Deploy Boards](user/project/deploy_boards.md) **[PREMIUM]**                                                                        | View the current health and status of each CI environment running on Kubernetes, displaying the status of the pods in the deployment. |
+| [Canary Deployments](user/project/canary_deployments.md) **(PREMIUM)**                                                              | Employ a popular CI strategy where a small portion of the fleet is updated to the new version first.                                  |
+| [Deploy Boards](user/project/deploy_boards.md) **(PREMIUM)**                                                                        | View the current health and status of each CI environment running on Kubernetes, displaying the status of the pods in the deployment. |
 | [Environments and deployments](ci/environments.md)                                                                                  | With environments, you can control the continuous deployment of your software within GitLab.                                          |
-| [Environment-specific variables](ci/variables/README.md#limiting-environment-scopes-of-environment-variables-premium) **[PREMIUM]** | Limit scope of variables to specific environments.                                                                                    |
+| [Environment-specific variables](ci/variables/README.md#limiting-environment-scopes-of-environment-variables) | Limit scope of variables to specific environments.                                                                                    |
 | [GitLab CI/CD](ci/README.md)                                                                                                        | Explore the features and capabilities of Continuous Deployment and Delivery with GitLab.                                              |
 | [GitLab Pages](user/project/pages/index.md)                                                                                         | Build, test, and deploy a static site directly from GitLab.                                                                           |
 | [Protected Runners](ci/runners/README.md#protected-runners)                                                                         | Select Runners to only pick jobs for protected branches and tags.                                                                     |
@@ -302,12 +302,12 @@ The following documentation relates to the DevOps **Configure** stage:
 | Configure Topics                                                                                                                   | Description                                                               |
 |:-----------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------|
 | [Auto DevOps](topics/autodevops/index.md)                                                                                          | Automatically employ a complete DevOps lifecycle.                         |
-| [Easy creation of Kubernetes<br/>clusters on GKE](user/project/clusters/index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) | Use Google Kubernetes Engine and GitLab.                                  |
+| [Create Kubernetes clusters on GKE](user/project/clusters/index.md#add-new-gke-cluster) | Use Google Kubernetes Engine and GitLab.                                  |
 | [Executable Runbooks](user/project/clusters/runbooks/index.md)                                                                     | Documented procedures that explain how to carry out particular processes. |
 | [GitLab ChatOps](ci/chatops/README.md)                                                                                             | Interact with CI/CD jobs through chat services.                           |
 | [Installing Applications](user/project/clusters/index.md#installing-applications)                                                  | Deploy Helm, Ingress, and Prometheus on Kubernetes.                       |
 | [Mattermost slash commands](user/project/integrations/mattermost_slash_commands.md)                                                | Enable and use slash commands from within Mattermost.                     |
-| [Multiple Kubernetes Clusters](user/project/clusters/index.md#multiple-kubernetes-clusters-premium) **[PREMIUM]**                  | Associate more than one Kubernetes clusters to your project.              |
+| [Multiple Kubernetes Clusters](user/project/clusters/index.md#multiple-kubernetes-clusters-premium) **(PREMIUM)**                  | Associate more than one Kubernetes clusters to your project.              |
 | [Protected variables](ci/variables/README.md#protected-environment-variables)                                                      | Restrict variables to protected branches and tags.                        |
 | [Serverless](user/project/clusters/serverless/index.md)                                                                            | Run serverless workloads on Kubernetes.                                   |
 | [Slack slash commands](user/project/integrations/slack_slash_commands.md)                                                          | Enable and use slash commands from within Slack.                          |
@@ -329,8 +329,8 @@ The following documentation relates to the DevOps **Monitor** stage:
 
 | Monitor Topics                                                                                  | Description                                                                                                                              |
 |:------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------|
-| [GitLab Performance Monitoring](administration/monitoring/performance/index.md) **[CORE ONLY]** | Use InfluxDB and Grafana to monitor the performance of your GitLab instance (will be eventually replaced by Prometheus).                 |
-| [GitLab Prometheus](administration/monitoring/prometheus/index.md) **[CORE ONLY]**              | Configure the bundled Prometheus to collect various metrics from your GitLab instance.                                                   |
+| [GitLab Performance Monitoring](administration/monitoring/performance/index.md) **(CORE ONLY)** | Use InfluxDB and Grafana to monitor the performance of your GitLab instance (will be eventually replaced by Prometheus).                 |
+| [GitLab Prometheus](administration/monitoring/prometheus/index.md) **(CORE ONLY)**              | Configure the bundled Prometheus to collect various metrics from your GitLab instance.                                                   |
 | [Health check](user/admin_area/monitoring/health_check.md)                                      | GitLab provides liveness and readiness probes to indicate service health and reachability to required services.                          |
 | [Prometheus project integration](user/project/integrations/prometheus.md)                       | Configure the Prometheus integration per project and monitor your CI/CD environments.                                                    |
 | [Prometheus metrics](user/project/integrations/prometheus_library/index.md)                     | Let Prometheus collect metrics from various services, like Kubernetes, NGINX, NGINX ingress controller, HAProxy, and Amazon Cloud Watch. |
@@ -353,97 +353,14 @@ The following documentation relates to the DevOps **Secure** stage:
 
 | Secure Topics                                                                                         | Description                                                            |
 |:------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------|
-| [Container Scanning](user/application_security/container_scanning/index.md) **[ULTIMATE]**            | Use Clair to scan docker images for known vulnerabilities.             |
-| [Dependency Scanning](user/application_security/dependency_scanning/index.md) **[ULTIMATE]**          | Analyze your dependencies for known vulnerabilities.                   |
-| [Dynamic Application Security Testing (DAST)](user/application_security/dast/index.md) **[ULTIMATE]** | Analyze running web applications for known vulnerabilities.            |
-| [Group Security Dashboard](user/application_security/security_dashboard/index.md) **[ULTIMATE]**      | View vulnerabilities in all the projects in a group and its subgroups. |
-| [License Management](user/application_security/license_management/index.md) **[ULTIMATE]**            | Search your project's dependencies for their licenses.                 |
-| [Project Security Dashboard](user/application_security/security_dashboard/index.md) **[ULTIMATE]**    | View the latest security reports for your project.                     |
-| [Static Application Security Testing (SAST)](user/application_security/sast/index.md) **[ULTIMATE]**  | Analyze source code for known vulnerabilities.                         |
-
-## Subscribe to GitLab
-
-There are two ways to use GitLab:
-
-- [GitLab self-managed](#gitlab-self-managed): Install, administer, and maintain your own GitLab instance.
-- [GitLab.com](#gitlabcom): GitLab's SaaS offering. You don't need to install anything to use GitLab.com,
-  you only need to [sign up](https://gitlab.com/users/sign_in) and start using GitLab straight away.
-
-For more information on managing your subscription and [Customers Portal](https://customers.gitlab.com) account, please see [Getting Started with Subscriptions](getting-started/subscription.md).
-
-The following sections outline tiers and features within GitLab self-managed and GitLab.com.
-
-<div align="right">
-  <a type="button" class="btn btn-default" href="#overview">
-    Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i>
-  </a>
-</div>
-
-### GitLab self-managed
-
-With GitLab self-managed, you deploy your own GitLab instance on-premises or on a cloud of your choice.
-GitLab self-managed is available for [free and with paid subscriptions](https://about.gitlab.com/pricing/#self-managed) in the following tiers:
-
-| Tier     | Includes                                       |
-|:---------|:-----------------------------------------------|
-| Core     | Core features.                                 |
-| Starter  | Core and Starter features.                     |
-| Premium  | Core, Starter, and Premium features.           |
-| Ultimate | Core, Starter, Premium, and Ultimate features. |
-
-The following resources are available for more information on GitLab self-managed:
-
-- [Feature comparison](https://about.gitlab.com/pricing/self-managed/feature-comparison/), for information on what features are available at each tier.
-- [GitLab pricing page](https://about.gitlab.com/pricing/#self-managed), for subscription information and a free trial.
-- Our [product marketing page](https://about.gitlab.com/handbook/marketing/product-marketing/), for additional information including:
-  - How [different tiers are licensed](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers).
-  - The different [GitLab distributions](https://about.gitlab.com/handbook/marketing/product-marketing/#distributions).
-
-<div align="right">
-  <a type="button" class="btn btn-default" href="#overview">
-    Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i>
-  </a>
-</div>
-
-### GitLab.com
-
-GitLab.com is hosted, managed, and administered by GitLab, Inc., with
-[free and paid subscriptions](https://about.gitlab.com/pricing/) for individuals
-and teams in the following tiers:
-
-| Tier   | Includes same features available in                 |
-|:-------|:----------------------------------------------------|
-| Free   | [Core](#gitlab-self-managed) self-managed tier.     |
-| Bronze | [Starter](#gitlab-self-managed) self-managed tier.  |
-| Silver | [Premium](#gitlab-self-managed) self-managed tier.  |
-| Gold   | [Ultimate](#gitlab-self-managed) self-managed tier. |
-
-GitLab.com subscriptions grant access
-to the same features available in GitLab self-managed, **except
-[administration](administration/index.md) tools and settings**.
-
-GitLab.com allows you to apply your subscription to a group or your personal user.
-
-When applied to a **group**, the group, all subgroups, and all projects under the selected group on GitLab.com will have the features of the associated plan. It is recommended to go with a group plan when managing projects and users of an organization.
-
-When associated with a **personal userspace** instead, all projects will have features with the subscription applied, but as it is not a group, group features will not be available.
-
-TIP: **Tip:**
-To support the open source community and encourage the development of open source projects, GitLab grants access to **Gold** features for all GitLab.com **public** projects, regardless of the subscription.
-
-The following resources are available for more information on GitLab.com:
-
-- [Feature comparison](https://about.gitlab.com/pricing/gitlab-com/feature-comparison/), for information on what features are available at each tier.
-- [GitLab pricing page](https://about.gitlab.com/pricing/), for subscription information and a free trial.
-- Our [product marketing page](https://about.gitlab.com/handbook/marketing/product-marketing/), for additional information including:
-  - How [different tiers are licensed](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers).
-  - The different [GitLab distributions](https://about.gitlab.com/handbook/marketing/product-marketing/#distributions).
-
-<div align="right">
-  <a type="button" class="btn btn-default" href="#overview">
-    Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i>
-  </a>
-</div>
+| [Container Scanning](user/application_security/container_scanning/index.md) **(ULTIMATE)**            | Use Clair to scan docker images for known vulnerabilities.             |
+| [Dependency List](user/application_security/dependency_list/index.md) **(ULTIMATE)**                  | View your project's dependencies and their known vulnerabilities.      |
+| [Dependency Scanning](user/application_security/dependency_scanning/index.md) **(ULTIMATE)**          | Analyze your dependencies for known vulnerabilities.                   |
+| [Dynamic Application Security Testing (DAST)](user/application_security/dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities.            |
+| [Group Security Dashboard](user/application_security/security_dashboard/index.md) **(ULTIMATE)**      | View vulnerabilities in all the projects in a group and its subgroups. |
+| [License Management](user/application_security/license_management/index.md) **(ULTIMATE)**            | Search your project's dependencies for their licenses.                 |
+| [Project Security Dashboard](user/application_security/security_dashboard/index.md) **(ULTIMATE)**    | View the latest security reports for your project.                     |
+| [Static Application Security Testing (SAST)](user/application_security/sast/index.md) **(ULTIMATE)**  | Analyze source code for known vulnerabilities.                         |
 
 ## New to Git and GitLab?
 
diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md
index d7a2e13b53e..02de2caf558 100644
--- a/doc/administration/audit_events.md
+++ b/doc/administration/audit_events.md
@@ -2,7 +2,7 @@
 last_updated: 2019-02-04
 ---
 
-# Audit Events **[STARTER]**
+# Audit Events **(STARTER)**
 
 GitLab offers a way to view the changes made within the GitLab server for owners and administrators on a [paid plan][ee].
 
@@ -32,7 +32,7 @@ There are two kinds of events logged:
 - Instance events scoped to the whole GitLab instance, used by your Compliance team to
   perform formal audits.
 
-### Group events **[STARTER]**
+### Group events **(STARTER)**
 
 NOTE: **Note:**
 You need Owner [permissions] to view the group Audit Events page.
@@ -59,7 +59,7 @@ From there, you can see the following actions:
 - 2FA enforcement/grace period changed
 - Roles allowed to create project changed
 
-### Project events **[STARTER]**
+### Project events **(STARTER)**
 
 NOTE: **Note:**
 You need Maintainer [permissions] or higher to view the project Audit Events page.
@@ -73,8 +73,10 @@ From there, you can see the following actions:
 - User was added to project and with which [permissions]
 - Permission changes of a user assigned to a project
 - User was removed from project
+- Project export was downloaded
+- Project repository was downloaded
 
-### Instance events **[PREMIUM ONLY]**
+### Instance events **(PREMIUM ONLY)**
 
 > [Introduced][ee-2336] in [GitLab Premium][ee] 9.3.
 
@@ -94,12 +96,13 @@ recorded:
 - Changed password
 - Ask for password reset
 - Grant OAuth access
+- Started/stopped user impersonation
 
 It is possible to filter particular actions by choosing an audit data type from
 the filter drop-down. You can further filter by specific group, project or user
 (for authentication events).
 
-![audit log](audit_log.png)
+![audit log](img/audit_log.png)
 
 ### Missing events
 
diff --git a/doc/administration/auditor_users.md b/doc/administration/auditor_users.md
index ef8c8197d6d..18c415b5ff7 100644
--- a/doc/administration/auditor_users.md
+++ b/doc/administration/auditor_users.md
@@ -1,4 +1,4 @@
-# Auditor users **[PREMIUM ONLY]**
+# Auditor users **(PREMIUM ONLY)**
 
 >[Introduced][ee-998] in [GitLab Premium][eep] 8.17.
 
@@ -52,7 +52,7 @@ section.
    **Admin Area > Users**. You will find the option of the access level under
    the 'Access' section.
 
-    ![Admin Area Form](auditor_access_form.png)
+   ![Admin Area Form](img/auditor_access_form.png)
 
 1. Click **Save changes** or **Create user** for the changes to take effect.
 
diff --git a/doc/administration/auth/README.md b/doc/administration/auth/README.md
index e215a0df6ec..2fc9db0632e 100644
--- a/doc/administration/auth/README.md
+++ b/doc/administration/auth/README.md
@@ -1,19 +1,34 @@
 ---
 comments: false
+type: index
 ---
 
-# Authentication and Authorization
+# GitLab authentication and authorization
 
 GitLab integrates with the following external authentication and authorization
-providers.
+providers:
 
-- [LDAP](ldap.md) Includes Active Directory, Apple Open Directory, Open LDAP,
-  and 389 Server
-  - [LDAP for GitLab EE](ldap-ee.md): LDAP additions to GitLab Enterprise Editions **[STARTER ONLY]**
-- [OmniAuth](../../integration/omniauth.md) Sign in via Twitter, GitHub, GitLab.com, Google,
-  Bitbucket, Facebook, Shibboleth, Crowd, Azure, Authentiq ID, and JWT
-- [CAS](../../integration/cas.md) Configure GitLab to sign in using CAS
-- [SAML](../../integration/saml.md) Configure GitLab as a SAML 2.0 Service Provider
-- [Okta](okta.md) Configure GitLab to sign in using Okta
-- [Authentiq](authentiq.md): Enable the Authentiq OmniAuth provider for passwordless authentication
-- [Smartcard](smartcard.md) Smartcard authentication **[PREMIUM ONLY]**
+- [Auth0](../../integration/auth0.md)
+- [Authentiq](authentiq.md)
+- [Azure](../../integration/azure.md)
+- [Bitbucket Cloud](../../integration/bitbucket.md)
+- [CAS](../../integration/cas.md)
+- [Crowd](../../integration/crowd.md)
+- [Facebook](../../integration/facebook.md)
+- [GitHub](../../integration/github.md)
+- [GitLab.com](../../integration/gitlab.md)
+- [Google](../../integration/google.md)
+- [JWT](jwt.md)
+- [Kerberos](../../integration/kerberos.md)
+- [LDAP](ldap.md): Includes Active Directory, Apple Open Directory, Open LDAP,
+  and 389 Server.
+  - [LDAP for GitLab EE](ldap-ee.md): LDAP additions to GitLab Enterprise Editions **(STARTER ONLY)**
+  - [Google Secure LDAP](google_secure_ldap.md)
+- [Okta](okta.md)
+- [Salesforce](../../integration/salesforce.md)
+- [SAML](../../integration/saml.md)
+- [SAML for GitLab.com groups](../../user/group/saml_sso/index.md) **(SILVER ONLY)**
+- [Shibboleth](../../integration/shibboleth.md)
+- [Smartcard](smartcard.md) **(PREMIUM ONLY)**
+- [Twitter](../../integration/twitter.md)
+- [UltraAuth](../../integration/ultra_auth.md)
diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md
index 726622d8599..b84eca4ef0d 100644
--- a/doc/administration/auth/authentiq.md
+++ b/doc/administration/auth/authentiq.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Authentiq OmniAuth Provider
 
 To enable the Authentiq OmniAuth provider for passwordless authentication you must register an application with Authentiq.
@@ -8,47 +12,48 @@ Authentiq will generate a Client ID and the accompanying Client Secret for you t
 
 1. On your GitLab server, open the configuration file:
 
-    For omnibus installation
-    ```sh
-    sudo editor /etc/gitlab/gitlab.rb
-    ```
+   For omnibus installation
+
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```sh
-    sudo -u git -H editor /home/git/gitlab/config/gitlab.yml
-    ```
+   ```sh
+   sudo -u git -H editor /home/git/gitlab/config/gitlab.yml
+   ```
 
 1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings to enable single sign-on and add Authentiq as an OAuth provider.
 
 1. Add the provider configuration for Authentiq:
 
-    For Omnibus packages:
-
-    ```ruby
-    gitlab_rails['omniauth_providers'] = [
-      {
-        "name" => "authentiq",
-        "app_id" => "YOUR_CLIENT_ID",
-        "app_secret" => "YOUR_CLIENT_SECRET",
-        "args" => {
-               "scope": 'aq:name email~rs address aq:push'
-         }
-      }
-    ]
-    ```
-
-    For installations from source:
-
-    ```yaml
-    - { name: 'authentiq',
-        app_id: 'YOUR_CLIENT_ID',
-        app_secret: 'YOUR_CLIENT_SECRET',
-        args: {
-               scope: 'aq:name email~rs address aq:push'
-              }
-      }
-    ```
+   For Omnibus packages:
+
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       "name" => "authentiq",
+       "app_id" => "YOUR_CLIENT_ID",
+       "app_secret" => "YOUR_CLIENT_SECRET",
+       "args" => {
+              "scope": 'aq:name email~rs address aq:push'
+        }
+     }
+   ]
+   ```
+
+   For installations from source:
+
+   ```yaml
+   - { name: 'authentiq',
+       app_id: 'YOUR_CLIENT_ID',
+       app_secret: 'YOUR_CLIENT_SECRET',
+       args: {
+              scope: 'aq:name email~rs address aq:push'
+             }
+     }
+   ```
 
 1. The `scope` is set to request the user's name, email (required and signed), and permission to send push notifications to sign in on subsequent visits.
    See [OmniAuth Authentiq strategy](https://github.com/AuthentiqID/omniauth-authentiq/wiki/Scopes,-callback-url-configuration-and-responses) for more information on scopes and modifiers.
@@ -65,3 +70,15 @@ On the sign in page there should now be an Authentiq icon below the regular sign
 - If not they will be prompted to download the app and then follow the procedure above.
 
 If everything goes right, the user will be returned to GitLab and will be signed in.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md
index 6db74958d5a..ac63b4f2b97 100644
--- a/doc/administration/auth/crowd.md
+++ b/doc/administration/auth/crowd.md
@@ -1,60 +1,67 @@
+---
+type: reference
+---
+
 # Atlassian Crowd OmniAuth Provider
 
+Authenticate to GitLab using the Atlassian Crowd OmniAuth provider.
+
 ## Configure a new Crowd application
 
 1. Choose 'Applications' in the top menu, then 'Add application'.
 1. Go through the 'Add application' steps, entering the appropriate details.
    The screenshot below shows an example configuration.
 
-    ![Example Crowd application configuration](img/crowd_application.png)
+   ![Example Crowd application configuration](img/crowd_application.png)
 
 ## Configure GitLab
 
 1. On your GitLab server, open the configuration file.
 
-    **Omnibus:**
+   **Omnibus:**
 
-    ```sh
-      sudo editor /etc/gitlab/gitlab.rb
-    ```
+   ```sh
+     sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    **Source:**
+   **Source:**
 
-    ```sh
-      cd /home/git/gitlab
+   ```sh
+     cd /home/git/gitlab
 
-      sudo -u git -H editor config/gitlab.yml
-    ```
+     sudo -u git -H editor config/gitlab.yml
+   ```
 
 1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration)
    for initial settings.
 
 1. Add the provider configuration:
 
-    **Omnibus:**
-
-    ```ruby
-      gitlab_rails['omniauth_providers'] = [
-        {
-          "name" => "crowd",
-          "args" => {
-            "crowd_server_url" => "CROWD_SERVER_URL",
-            "application_name" => "YOUR_APP_NAME",
-            "application_password" => "YOUR_APP_PASSWORD"
-          }
-        }
-      ]
-    ```
-
-    **Source:**
-
-    ```
-       - { name: 'crowd',
-           args: {
-             crowd_server_url: 'CROWD_SERVER_URL',
-             application_name: 'YOUR_APP_NAME',
-             application_password: 'YOUR_APP_PASSWORD' } }
-    ```
+   **Omnibus:**
+
+   ```ruby
+     gitlab_rails['omniauth_providers'] = [
+       {
+         "name" => "crowd",
+         "args" => {
+           "crowd_server_url" => "CROWD_SERVER_URL",
+           "application_name" => "YOUR_APP_NAME",
+           "application_password" => "YOUR_APP_PASSWORD"
+         }
+       }
+     ]
+   ```
+
+   **Source:**
+
+   ```
+      - { name: 'crowd',
+          args: {
+            crowd_server_url: 'CROWD_SERVER_URL',
+            application_name: 'YOUR_APP_NAME',
+            application_password: 'YOUR_APP_PASSWORD' } }
+   ```
+
 1. Change `CROWD_SERVER_URL` to the URL of your Crowd server.
 1. Change `YOUR_APP_NAME` to the application name from Crowd applications page.
 1. Change `YOUR_APP_PASSWORD` to the application password you've set.
@@ -77,4 +84,4 @@ could not authorize you from Crowd because invalid credentials
 
 Please make sure the Crowd users who need to login to GitLab are authorized to [the application](#configure-a-new-crowd-application) in the step of **Authorisation**. This could be verified by try "Authentication test" for Crowd as of 2.11.
 
-![Example Crowd application authorisation configuration](img/crowd_application_authorisation.png)
\ No newline at end of file
+![Example Crowd application authorisation configuration](img/crowd_application_authorisation.png)
diff --git a/doc/administration/auth/google_secure_ldap.md b/doc/administration/auth/google_secure_ldap.md
index 760af0cfd1a..55e6f53622c 100644
--- a/doc/administration/auth/google_secure_ldap.md
+++ b/doc/administration/auth/google_secure_ldap.md
@@ -1,4 +1,8 @@
-# Google Secure LDAP **[CORE ONLY]**
+---
+type: reference
+---
+
+# Google Secure LDAP **(CORE ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/46391) in GitLab 11.9.
 
@@ -13,7 +17,7 @@ The steps below cover:
 
 ## Configuring Google LDAP client
 
-1. Navigate to https://admin.google.com and sign in as a GSuite domain administrator.
+1. Navigate to <https://admin.google.com/Dashboard> and sign in as a GSuite domain administrator.
 
 1. Go to **Apps > LDAP > Add Client**.
 
@@ -66,7 +70,7 @@ values obtained during the LDAP client configuration earlier:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
+   ```ruby
    gitlab_rails['ldap_enabled'] = true
    gitlab_rails['ldap_servers'] = YAML.load <<-EOS # remember to close this block with 'EOS' below
      main: # 'main' is the GitLab 'provider ID' of this LDAP server
@@ -127,7 +131,7 @@ values obtained during the LDAP client configuration earlier:
            AcZSFJQjdg5BTyvdEDhaYUKGdRw=
            -----END PRIVATE KEY-----
    EOS
-    ```
+   ```
 
 1. Save the file and [reconfigure] GitLab for the changes to take effect.
 
@@ -137,7 +141,7 @@ values obtained during the LDAP client configuration earlier:
 
 1. Edit `config/gitlab.yml`:
 
-    ```yaml
+   ```yaml
    ldap:
      enabled: true
      servers:
@@ -202,6 +206,17 @@ values obtained during the LDAP client configuration earlier:
 
 1. Save the file and [restart] GitLab for the changes to take effect.
 
-
 [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure
 [restart]: ../restart_gitlab.md#installations-from-source
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md
index 1f67e8f5744..86dd398343b 100644
--- a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md
+++ b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md
@@ -1,15 +1,9 @@
 ---
-author: Chris Wilson
-author_gitlab: MrChrisW
-level: intermediary
-article_type: admin guide
-date: 2017-05-03
+type: howto
 ---
 
 # How to configure LDAP with GitLab CE
 
-## Introduction
-
 Managing a large number of users in GitLab can become a burden for system administrators. As an organization grows so do user accounts. Keeping these user accounts in sync across multiple enterprise applications often becomes a time consuming task.
 
 In this guide we will focus on configuring GitLab with Active Directory. [Active Directory](https://en.wikipedia.org/wiki/Active_Directory) is a popular LDAP compatible directory service provided by Microsoft, included in all modern Windows Server operating systems.
@@ -111,7 +105,7 @@ The initial configuration of LDAP in GitLab requires changes to the `gitlab.rb`
 
 The two Active Directory specific values are `active_directory: true` and `uid: 'sAMAccountName'`. `sAMAccountName` is an attribute returned by Active Directory used for GitLab usernames. See the example output from `ldapsearch` for a full list of attributes a "person" object (user) has in **AD** - [`ldapsearch` example](#using-ldapsearch-unix)
 
-> Both group_base and admin_group configuration options are only available in GitLab Enterprise Edition. See [GitLab EE - LDAP Features](../how_to_configure_ldap_gitlab_ee/index.html#gitlab-enterprise-edition---ldap-features) **[STARTER ONLY]**
+> Both group_base and admin_group configuration options are only available in GitLab Enterprise Edition. See [GitLab EE - LDAP Features](../how_to_configure_ldap_gitlab_ee/index.html#gitlab-enterprise-edition---ldap-features) **(STARTER ONLY)**
 
 ### Example `gitlab.rb` LDAP
 
@@ -267,4 +261,16 @@ have extended functionalities with LDAP, such as:
 - Updating user permissions
 - Multiple LDAP servers
 
-Read through the article on [LDAP for GitLab EE](../how_to_configure_ldap_gitlab_ee/index.md) **[STARTER ONLY]** for an overview.
+Read through the article on [LDAP for GitLab EE](../how_to_configure_ldap_gitlab_ee/index.md) **(STARTER ONLY)** for an overview.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md
index 4d82a7370bb..366acb9ed3e 100644
--- a/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md
+++ b/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md
@@ -1,16 +1,10 @@
 ---
-author: Chris Wilson
-author_gitlab: MrChrisW
-level: intermediary
-article_type: admin guide
-date: 2017-05-03
+type: howto
 ---
 
-# How to configure LDAP with GitLab EE **[STARTER ONLY]**
+# How to configure LDAP with GitLab EE **(STARTER ONLY)**
 
-## Introduction
-
-The present article follows [How to Configure LDAP with GitLab CE](../how_to_configure_ldap_gitlab_ce/index.md). Make sure to read through it before moving forward.
+This article expands on [How to Configure LDAP with GitLab CE](../how_to_configure_ldap_gitlab_ce/index.md). Make sure to read through it before moving forward.
 
 ## GitLab Enterprise Edition - LDAP features
 
@@ -117,3 +111,15 @@ Integration of GitLab with Active Directory (LDAP) reduces the complexity of use
 It has the advantage of improving user permission controls, whilst easing the deployment of GitLab into an existing [IT environment](https://www.techopedia.com/definition/29199/it-infrastructure). GitLab EE offers advanced group management and multiple LDAP servers.
 
 With the assistance of the [GitLab Support](https://about.gitlab.com/support) team, setting up GitLab with an existing AD/LDAP solution will be a smooth and painless process.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/auth/img/google_secure_ldap_add_step_1.png b/doc/administration/auth/img/google_secure_ldap_add_step_1.png
index fd254443d75..bee9c602a14 100644
--- a/doc/administration/auth/img/google_secure_ldap_add_step_1.png
+++ b/doc/administration/auth/img/google_secure_ldap_add_step_1.png
diff --git a/doc/administration/auth/img/google_secure_ldap_add_step_2.png b/doc/administration/auth/img/google_secure_ldap_add_step_2.png
index 611a21ae03c..b127410cb8c 100644
--- a/doc/administration/auth/img/google_secure_ldap_add_step_2.png
+++ b/doc/administration/auth/img/google_secure_ldap_add_step_2.png
diff --git a/doc/administration/auth/img/google_secure_ldap_client_settings.png b/doc/administration/auth/img/google_secure_ldap_client_settings.png
index 3c0b3f3d4bd..868e6645f56 100644
--- a/doc/administration/auth/img/google_secure_ldap_client_settings.png
+++ b/doc/administration/auth/img/google_secure_ldap_client_settings.png
diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md
index 497298503ad..e6b3287ce60 100644
--- a/doc/administration/auth/jwt.md
+++ b/doc/administration/auth/jwt.md
@@ -1,67 +1,71 @@
+---
+type: reference
+---
+
 # JWT OmniAuth provider
 
 To enable the JWT OmniAuth provider, you must register your application with JWT.
 JWT will provide you with a secret key for you to use.
 
-1.  On your GitLab server, open the configuration file.
-
-    For Omnibus GitLab:
-
-    ```sh
-    sudo editor /etc/gitlab/gitlab.rb
-    ```
-
-    For installations from source:
-
-    ```sh
-    cd /home/git/gitlab
-    sudo -u git -H editor config/gitlab.yml
-    ```
-
-1.  See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings.
-1.  Add the provider configuration.
-
-    For Omnibus GitLab:
-
-    ```ruby
-    gitlab_rails['omniauth_providers'] = [
-      { name: 'jwt',
-        args: {
-          secret: 'YOUR_APP_SECRET',
-          algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512'
-          uid_claim: 'email',
-          required_claims: ['name', 'email'],
-          info_maps: { name: 'name', email: 'email' },
-          auth_url: 'https://example.com/',
-          valid_within: 3600 # 1 hour
-        }
-      }
-    ]
-    ```
-
-    For installation from source:
-
-    ```
-    - { name: 'jwt',
-        args: {
-          secret: 'YOUR_APP_SECRET',
-          algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512'
-          uid_claim: 'email',
-          required_claims: ['name', 'email'],
-          info_map: { name: 'name', email: 'email' },
-          auth_url: 'https://example.com/',
-          valid_within: 3600 # 1 hour
-        }
-      }
-    ```
-
-    NOTE: **Note:** For more information on each configuration option refer to
-    the [OmniAuth JWT usage documentation](https://github.com/mbleigh/omniauth-jwt#usage).
-
-1.  Change `YOUR_APP_SECRET` to the client secret and set `auth_url` to your redirect URL.
-1.  Save the configuration file.
-1.  [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
-    installed GitLab via Omnibus or from source respectively.
+1. On your GitLab server, open the configuration file.
+
+   For Omnibus GitLab:
+
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
+
+   For installations from source:
+
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H editor config/gitlab.yml
+   ```
+
+1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings.
+1. Add the provider configuration.
+
+   For Omnibus GitLab:
+
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     { name: 'jwt',
+       args: {
+         secret: 'YOUR_APP_SECRET',
+         algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512'
+         uid_claim: 'email',
+         required_claims: ['name', 'email'],
+         info_maps: { name: 'name', email: 'email' },
+         auth_url: 'https://example.com/',
+         valid_within: 3600 # 1 hour
+       }
+     }
+   ]
+   ```
+
+   For installation from source:
+
+   ```
+   - { name: 'jwt',
+       args: {
+         secret: 'YOUR_APP_SECRET',
+         algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512'
+         uid_claim: 'email',
+         required_claims: ['name', 'email'],
+         info_map: { name: 'name', email: 'email' },
+         auth_url: 'https://example.com/',
+         valid_within: 3600 # 1 hour
+       }
+     }
+   ```
+
+   NOTE: **Note:** For more information on each configuration option refer to
+   the [OmniAuth JWT usage documentation](https://github.com/mbleigh/omniauth-jwt#usage).
+
+1. Change `YOUR_APP_SECRET` to the client secret and set `auth_url` to your redirect URL.
+1. Save the configuration file.
+1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
+   installed GitLab via Omnibus or from source respectively.
 
 On the sign in page there should now be a JWT icon below the regular sign in form.
 Click the icon to begin the authentication process. JWT will ask the user to
@@ -70,3 +74,15 @@ will be redirected to GitLab and will be signed in.
 
 [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure
 [restart GitLab]: ../restart_gitlab.md#installations-from-source
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/auth/ldap-ee.md b/doc/administration/auth/ldap-ee.md
index 30095d35705..34f3cfa353f 100644
--- a/doc/administration/auth/ldap-ee.md
+++ b/doc/administration/auth/ldap-ee.md
@@ -1,36 +1,30 @@
-# LDAP Additions in GitLab EE **[STARTER ONLY]**
-
-This is a continuation of the main [LDAP documentation](ldap.md), detailing LDAP
-features specific to GitLab Enterprise Edition Starter, Premium and Ultimate.
+---
+type: reference
+---
 
-## Overview
+# LDAP Additions in GitLab EE **(STARTER ONLY)**
 
-[LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)
-stands for **Lightweight Directory Access Protocol**, which
-is a standard application protocol for
-accessing and maintaining distributed directory information services
-over an Internet Protocol (IP) network.
+This section documents LDAP features specific to to GitLab Enterprise Edition
+[Starter](https://about.gitlab.com/pricing/#self-managed) and above.
 
-GitLab integrates with LDAP to support **user authentication**. This integration
-works with most LDAP-compliant directory servers, including Microsoft Active
-Directory, Apple Open Directory, Open LDAP, and 389 Server.
-**GitLab Enterprise Edition** includes enhanced integration, including group
-membership syncing.
+For documentation relevant to both Community Edition and Enterprise Edition,
+see the main [LDAP documentation](ldap.md).
 
 ## Use cases
 
-- User sync: Once a day, GitLab will update users against LDAP
+- User sync: Once a day, GitLab will update users against LDAP.
 - Group sync: Once an hour, GitLab will update group membership
-  based on LDAP group members
+  based on LDAP group members.
 
-## Multiple LDAP servers
+## Multiple LDAP servers **(STARTER ONLY)**
 
 With GitLab Enterprise Edition Starter, you can configure multiple LDAP servers
 that your GitLab instance will connect to.
 
-To add another LDAP server, you can start by duplicating the settings under
-[the main configuration](ldap.md#configuration) and edit them to match the
-additional LDAP server.
+To add another LDAP server:
+
+1. Duplicating the settings under [the main configuration](ldap.md#configuration).
+1. Edit them to match the additional LDAP server.
 
 Be sure to choose a different provider ID made of letters a-z and numbers 0-9.
 This ID will be stored in the database so that GitLab can remember which LDAP
@@ -43,19 +37,19 @@ users against LDAP.
 
 The process will execute the following access checks:
 
-1. Ensure the user is still present in LDAP
-1. If the LDAP server is Active Directory, ensure the user is active (not
-   blocked/disabled state). This will only be checked if
-   `active_directory: true` is set in the LDAP configuration [^1]
+- Ensure the user is still present in LDAP.
+- If the LDAP server is Active Directory, ensure the user is active (not
+  blocked/disabled state). This will only be checked if
+  `active_directory: true` is set in the LDAP configuration. [^1]
 
 The user will be set to `ldap_blocked` state in GitLab if the above conditions
 fail. This means the user will not be able to login or push/pull code.
 
 The process will also update the following user information:
 
-1. Email address
-1. If `sync_ssh_keys` is set, SSH public keys
-1. If Kerberos is enabled, Kerberos identity
+- Email address.
+- If `sync_ssh_keys` is set, SSH public keys.
+- If Kerberos is enabled, Kerberos identity.
 
 NOTE: **Note:**
 The LDAP sync process updates existing users while new users will
@@ -68,9 +62,6 @@ first time GitLab will trigger a sync for groups the user should be a member of.
 That way they don't need to wait for the hourly sync to be granted
 access to their groups and projects.
 
-In GitLab Premium, we can also add a GitLab group to sync with one or multiple LDAP groups or we can
-also add a filter. The filter must comply with the syntax defined in [RFC 2254](https://tools.ietf.org/search/rfc2254).
-
 A group sync process will run every hour on the hour, and `group_base` must be set
 in LDAP configuration for LDAP synchronizations based on group CN to work. This allows
 GitLab group membership to be automatically updated based on LDAP group members.
@@ -85,19 +76,19 @@ following.
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_servers'] = YAML.load <<-EOS
-    main:
-      ## snip...
-      ##
-      ## Base where we can search for groups
-      ##
-      ##   Ex. ou=groups,dc=gitlab,dc=example
-      ##
-      ##
-      group_base: ou=groups,dc=example,dc=com
-    EOS
-    ```
+   ```ruby
+   gitlab_rails['ldap_servers'] = YAML.load <<-EOS
+   main:
+     ## snip...
+     ##
+     ## Base where we can search for groups
+     ##
+     ##   Ex. ou=groups,dc=gitlab,dc=example
+     ##
+     ##
+     group_base: ou=groups,dc=example,dc=com
+   EOS
+   ```
 
 1. [Reconfigure GitLab][reconfigure] for the changes to take effect.
 
@@ -105,24 +96,37 @@ following.
 
 1. Edit `/home/git/gitlab/config/gitlab.yml`:
 
-    ```yaml
-    production:
-      ldap:
-        servers:
-          main:
-            # snip...
-            group_base: ou=groups,dc=example,dc=com
-    ```
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           group_base: ou=groups,dc=example,dc=com
+   ```
 
 1. [Restart GitLab][restart] for the changes to take effect.
 
----
-
 To take advantage of group sync, group owners or maintainers will need to create an
-LDAP group link in their group **Settings > LDAP Groups** page. Multiple LDAP
-groups and/or filters can be linked with a single GitLab group. When the link is
-created, an access level/role is specified (Guest, Reporter, Developer, Maintainer,
-or Owner).
+LDAP group link in their group **Settings > LDAP Groups** page.
+
+Multiple LDAP groups and [filters](#filters-premium-only) can be linked with
+a single GitLab group. When the link is created, an access level/role is
+specified (Guest, Reporter, Developer, Maintainer, or Owner).
+
+### Filters **(PREMIUM ONLY)**
+
+In GitLab Premium, you can add an LDAP user filter for group synchronization.
+Filters allow for complex logic without creating a special LDAP group.
+
+To sync GitLab group membership based on an LDAP filter:
+
+1. Open the **LDAP Synchronization** page for the GitLab group.
+1. Select **LDAP user filter** as the **Sync method**.
+1. Enter an LDAP user filter in the **LDAP user filter** field.
+
+The filter must comply with the
+syntax defined in [RFC 2254](https://tools.ietf.org/search/rfc2254).
 
 ## Administrator sync
 
@@ -140,30 +144,30 @@ group, as opposed to the full DN.
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_servers'] = YAML.load <<-EOS
-    main:
-      ## snip...
-      ##
-      ## Base where we can search for groups
-      ##
-      ##   Ex. ou=groups,dc=gitlab,dc=example
-      ##
-      ##
-      group_base: ou=groups,dc=example,dc=com
-
-      ##
-      ## The CN of a group containing GitLab administrators
-      ##
-      ##   Ex. administrators
-      ##
-      ##   Note: Not `cn=administrators` or the full DN
-      ##
-      ##
-      admin_group: my_admin_group
-
-    EOS
-    ```
+   ```ruby
+   gitlab_rails['ldap_servers'] = YAML.load <<-EOS
+   main:
+     ## snip...
+     ##
+     ## Base where we can search for groups
+     ##
+     ##   Ex. ou=groups,dc=gitlab,dc=example
+     ##
+     ##
+     group_base: ou=groups,dc=example,dc=com
+
+     ##
+     ## The CN of a group containing GitLab administrators
+     ##
+     ##   Ex. administrators
+     ##
+     ##   Note: Not `cn=administrators` or the full DN
+     ##
+     ##
+     admin_group: my_admin_group
+
+   EOS
+   ```
 
 1. [Reconfigure GitLab][reconfigure] for the changes to take effect.
 
@@ -171,40 +175,51 @@ group, as opposed to the full DN.
 
 1. Edit `/home/git/gitlab/config/gitlab.yml`:
 
-    ```yaml
-    production:
-      ldap:
-        servers:
-          main:
-            # snip...
-            group_base: ou=groups,dc=example,dc=com
-            admin_group: my_admin_group
-    ```
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           group_base: ou=groups,dc=example,dc=com
+           admin_group: my_admin_group
+   ```
 
 1. [Restart GitLab][restart] for the changes to take effect.
 
+## Global group memberships lock
+
+"Lock memberships to LDAP synchronization" setting allows instance administrators
+to lock down user abilities to invite new members to a group.
+
+When enabled, the following applies:
+
+- Only administrator can manage memberships of any group including access levels.
+- Users are not allowed to share project with other groups or invite members to
+  a project created in a group.
+
 ## Adjusting LDAP user sync schedule
 
 > Introduced in GitLab Enterprise Edition Starter.
 
 NOTE: **Note:**
 These are cron formatted values. You can use a crontab generator to create
-these values, for example http://www.crontabgenerator.com/.
+these values, for example <http://www.crontabgenerator.com/>.
 
 By default, GitLab will run a worker once per day at 01:30 a.m. server time to
 check and update GitLab users against LDAP.
 
 You can manually configure LDAP user sync times by setting the
 following configuration values. The example below shows how to set LDAP user
-sync to run once every 12 hours at the top of the hour. 
+sync to run once every 12 hours at the top of the hour.
 
 **Omnibus installations**
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_sync_worker_cron'] = "0 */12 * * *"
-    ```
+   ```ruby
+   gitlab_rails['ldap_sync_worker_cron'] = "0 */12 * * *"
+   ```
 
 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -212,11 +227,11 @@ sync to run once every 12 hours at the top of the hour.
 
 1. Edit `config/gitlab.yaml`:
 
-    ```yaml
-    cron_jobs:
-      ldap_sync_worker_cron:
-        "0 */12 * * *"
-    ```
+   ```yaml
+   cron_jobs:
+     ldap_sync_worker_cron:
+       "0 */12 * * *"
+   ```
 
 1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect.
 
@@ -224,7 +239,7 @@ sync to run once every 12 hours at the top of the hour.
 
 NOTE: **Note:**
 These are cron formatted values. You can use a crontab generator to create
-these values, for example http://www.crontabgenerator.com/.
+these values, for example <http://www.crontabgenerator.com/>.
 
 By default, GitLab will run a group sync process every hour, on the hour.
 
@@ -236,16 +251,16 @@ for installations with a large number of LDAP users. Please review the
 your installation compares before proceeding.
 
 You can manually configure LDAP group sync times by setting the
-following configuration values. The example below shows how to set group 
-sync to run once every 2 hours at the top of the hour. 
+following configuration values. The example below shows how to set group
+sync to run once every 2 hours at the top of the hour.
 
 **Omnibus installations**
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * * *"
-    ```
+   ```ruby
+   gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * * *"
+   ```
 
 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -253,11 +268,11 @@ sync to run once every 2 hours at the top of the hour.
 
 1. Edit `config/gitlab.yaml`:
 
-    ```yaml
-    cron_jobs:
-      ldap_group_sync_worker_cron:
-          "*/30 * * * *"
-    ```
+   ```yaml
+   cron_jobs:
+     ldap_group_sync_worker_cron:
+         "*/30 * * * *"
+   ```
 
 1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect.
 
@@ -274,20 +289,20 @@ task.
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_servers'] = YAML.load <<-EOS
-    main:
-      ## snip...
-      ##
-      ## An array of CNs of groups containing users that should be considered external
-      ##
-      ##   Ex. ['interns', 'contractors']
-      ##
-      ##   Note: Not `cn=interns` or the full DN
-      ##
-      external_groups: ['interns', 'contractors']
-    EOS
-    ```
+   ```ruby
+   gitlab_rails['ldap_servers'] = YAML.load <<-EOS
+   main:
+     ## snip...
+     ##
+     ## An array of CNs of groups containing users that should be considered external
+     ##
+     ##   Ex. ['interns', 'contractors']
+     ##
+     ##   Note: Not `cn=interns` or the full DN
+     ##
+     external_groups: ['interns', 'contractors']
+   EOS
+   ```
 
 1. [Reconfigure GitLab][reconfigure] for the changes to take effect.
 
@@ -295,14 +310,14 @@ task.
 
 1. Edit `config/gitlab.yaml`:
 
-    ```yaml
-    production:
-      ldap:
-        servers:
-          main:
-            # snip...
-            external_groups: ['interns', 'contractors']
-    ```
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           external_groups: ['interns', 'contractors']
+   ```
 
 1. [Restart GitLab][restart] for the changes to take effect.
 
@@ -321,10 +336,18 @@ administrative duties.
 
 ### Supported LDAP group types/attributes
 
-GitLab supports LDAP groups that use member attributes `member`, `submember`,
-`uniquemember`, `memberof` and `memberuid`. This means group sync supports, at
-least, LDAP groups with object class `groupOfNames`, `posixGroup`, and
-`groupOfUniqueName`. Other object classes should work fine as long as members
+GitLab supports LDAP groups that use member attributes:
+
+- `member`
+- `submember`
+- `uniquemember`
+- `memberof`
+- `memberuid`.
+
+This means group sync supports, at least, LDAP groups with object class:
+`groupOfNames`, `posixGroup`, and `groupOfUniqueName`.
+
+Other object classes should work fine as long as members
 are defined as one of the mentioned attributes. This also means GitLab supports
 Microsoft Active Directory, Apple Open Directory, Open LDAP, and 389 Server.
 Other LDAP servers should work, too.
@@ -332,11 +355,12 @@ Other LDAP servers should work, too.
 Active Directory also supports nested groups. Group sync will recursively
 resolve membership if `active_directory: true` is set in the configuration file.
 
-> **Note:** Nested group membership will only be resolved if the nested group
-  also falls within the configured `group_base`. For example, if GitLab sees a
-  nested group with DN `cn=nested_group,ou=special_groups,dc=example,dc=com` but
-  the configured `group_base` is `ou=groups,dc=example,dc=com`, `cn=nested_group`
-  will be ignored.
+NOTE: **Note:**
+Nested group membership will only be resolved if the nested group
+also falls within the configured `group_base`. For example, if GitLab sees a
+nested group with DN `cn=nested_group,ou=special_groups,dc=example,dc=com` but
+the configured `group_base` is `ou=groups,dc=example,dc=com`, `cn=nested_group`
+will be ignored.
 
 ### Queries
 
@@ -391,7 +415,7 @@ main: # 'main' is the GitLab 'provider ID' of this LDAP server
 
 [^1]: In Active Directory, a user is marked as disabled/blocked if the user
       account control attribute (`userAccountControl:1.2.840.113556.1.4.803`)
-      has bit 2 set. See https://ctogonewild.com/2009/09/03/bitmask-searches-in-ldap/
+      has bit 2 set. See <https://ctogonewild.com/2009/09/03/bitmask-searches-in-ldap/>
       for more information.
 
 ### User DN has changed
@@ -411,10 +435,10 @@ things to check to debug the situation.
 - Ensure LDAP configuration has a `group_base` specified. This configuration is
   required for group sync to work properly.
 - Ensure the correct LDAP group link is added to the GitLab group. Check group
-  links by visiting the GitLab group, then **Settings dropdown -> LDAP groups**.
-- Check that the user has an LDAP identity
+  links by visiting the GitLab group, then **Settings dropdown > LDAP groups**.
+- Check that the user has an LDAP identity:
   1. Sign in to GitLab as an administrator user.
-  1. Navigate to **Admin area -> Users**.
+  1. Navigate to **Admin area > Users**.
   1. Search for the user
   1. Open the user, by clicking on their name. Do not click 'Edit'.
   1. Navigate to the **Identities** tab. There should be an LDAP identity with
@@ -425,68 +449,74 @@ Often, the best way to learn more about why group sync is behaving a certain
 way is to enable debug logging. There is verbose output that details every
 step of the sync.
 
-1. Start a Rails console
+1. Start a Rails console:
 
-    ```bash
-    # For Omnibus installations
-    sudo gitlab-rails console
+   ```bash
+   # For Omnibus installations
+   sudo gitlab-rails console
+
+   # For installations from source
+   sudo -u git -H bundle exec rails console production
+   ```
 
-    # For installations from source
-    sudo -u git -H bundle exec rails console production
-    ```
 1. Set the log level to debug (only for this session):
 
-    ```ruby
-    Rails.logger.level = Logger::DEBUG
-    ```
+   ```ruby
+   Rails.logger.level = Logger::DEBUG
+   ```
+
 1. Choose a GitLab group to test with. This group should have an LDAP group link
    already configured. If the output is `nil`, the group could not be found.
    If a bunch of group attributes are output, your group was found successfully.
 
-    ```ruby
-    group = Group.find_by(name: 'my_group')
+   ```ruby
+   group = Group.find_by(name: 'my_group')
+
+   # Output
+   => #<Group:0x007fe825196558 id: 1234, name: "my_group"...>
+   ```
 
-    # Output
-    => #<Group:0x007fe825196558 id: 1234, name: "my_group"...>
-    ```
 1. Run a group sync for this particular group.
 
-    ```ruby
-    EE::Gitlab::Auth::LDAP::Sync::Group.execute_all_providers(group)
-    ```
+   ```ruby
+   EE::Gitlab::Auth::LDAP::Sync::Group.execute_all_providers(group)
+   ```
+
 1. Look through the output of the sync. See [example log output](#example-log-output)
    below for more information about the output.
 1. If you still aren't able to see why the user isn't being added, query the
    LDAP group directly to see what members are listed. Still in the Rails console,
    run the following query:
 
-    ```ruby
-    adapter = Gitlab::Auth::LDAP::Adapter.new('ldapmain') # If `main` is the LDAP provider
-    ldap_group = EE::Gitlab::Auth::LDAP::Group.find_by_cn('group_cn_here', adapter)
+   ```ruby
+   adapter = Gitlab::Auth::LDAP::Adapter.new('ldapmain') # If `main` is the LDAP provider
+   ldap_group = EE::Gitlab::Auth::LDAP::Group.find_by_cn('group_cn_here', adapter)
+
+   # Output
+   => #<EE::Gitlab::Auth::LDAP::Group:0x007fcbdd0bb6d8
+   ```
 
-    # Output
-    => #<EE::Gitlab::Auth::LDAP::Group:0x007fcbdd0bb6d8
-    ```
 1. Query the LDAP group's member DNs and see if the user's DN is in the list.
    One of the DNs here should match the 'Identifier' from the LDAP identity
    checked earlier. If it doesn't, the user does not appear to be in the LDAP
    group.
 
-    ```ruby
-    ldap_group.member_dns
+   ```ruby
+   ldap_group.member_dns
+
+   # Output
+   => ["uid=john,ou=people,dc=example,dc=com", "uid=mary,ou=people,dc=example,dc=com"]
+   ```
 
-    # Output
-    => ["uid=john,ou=people,dc=example,dc=com", "uid=mary,ou=people,dc=example,dc=com"]
-    ```
 1. Some LDAP servers don't store members by DN. Rather, they use UIDs instead.
    If you didn't see results from the last query, try querying by UIDs instead.
 
-    ```ruby
-    ldap_group.member_uids
+   ```ruby
+   ldap_group.member_uids
 
-    # Output
-    => ['john','mary']
-    ```
+   # Output
+   => ['john','mary']
+   ```
 
 #### Example log output
 
@@ -523,8 +553,9 @@ and more DNs may be added, or existing entries modified, based on additional
 LDAP group lookups. The very last occurrence of this entry should indicate
 exactly which users GitLab believes should be added to the group.
 
-> **Note:** 10 is 'Guest', 20 is 'Reporter', 30 is 'Developer', 40 is 'Maintainer'
-  and 50 is 'Owner'
+NOTE: **Note:**
+10 is 'Guest', 20 is 'Reporter', 30 is 'Developer', 40 is 'Maintainer'
+and 50 is 'Owner'.
 
 ```bash
 Resolved 'my_group' group member access: {"uid=john0,ou=people,dc=example,dc=com"=>30,
diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md
index 54279897e04..186bf4c4825 100644
--- a/doc/administration/auth/ldap.md
+++ b/doc/administration/auth/ldap.md
@@ -1,32 +1,50 @@
-[//]: # (Do *NOT* modify this file in EE documentation. All changes in this)
-[//]: # (file should happen in CE, too. If the change is EE-specific, put)
-[//]: # (it in `ldap-ee.md`.)
+---
+type: reference
+---
+
+<!-- If the change is EE-specific, put it in `ldap-ee.md`, NOT here. -->
 
 # LDAP
 
 GitLab integrates with LDAP to support user authentication.
-This integration works with most LDAP-compliant directory
-servers, including Microsoft Active Directory, Apple Open Directory, Open LDAP,
-and 389 Server. GitLab Enterprise Editions include enhanced integration,
+
+This integration works with most LDAP-compliant directory servers, including:
+
+- Microsoft Active Directory
+- Apple Open Directory
+- Open LDAP
+- 389 Server.
+
+GitLab Enterprise Editions (EE) include enhanced integration,
 including group membership syncing as well as multiple LDAP servers support.
 
-## GitLab EE
+For more details about EE-specific LDAP features, see the
+[LDAP Enterprise Edition documentation](ldap-ee.md).
 
-The information on this page is relevant for both GitLab CE and EE. For more
-details about EE-specific LDAP features, see the
-[LDAP Enterprise Edition documentation](ldap-ee.md). **[STARTER ONLY]**
+NOTE: **Note:**
+The information on this page is relevant for both GitLab CE and EE.
+
+## Overview
+
+[LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)
+stands for **Lightweight Directory Access Protocol**, which is a standard
+application protocol for accessing and maintaining distributed directory
+information services over an Internet Protocol (IP) network.
 
 ## Security
 
-GitLab assumes that LDAP users are not able to change their LDAP 'mail', 'email'
-or 'userPrincipalName' attribute. An LDAP user who is allowed to change their
-email on the LDAP server can potentially
-[take over any account](#enabling-ldap-sign-in-for-existing-gitlab-users)
-on your GitLab server.
+GitLab assumes that LDAP users:
+
+- Are not able to change their LDAP `mail`, `email`, or `userPrincipalName` attribute.
+  An LDAP user who is allowed to change their email on the LDAP server can potentially
+  [take over any account](#enabling-ldap-sign-in-for-existing-gitlab-users)
+  on your GitLab server.
+- Have unique email addresses, otherwise it is possible for LDAP users with the same
+  email address to share the same GitLab account.
 
 We recommend against using LDAP integration if your LDAP users are
-allowed to change their 'mail', 'email' or 'userPrincipalName'  attribute on
-the LDAP server.
+allowed to change their 'mail', 'email' or 'userPrincipalName' attribute on
+the LDAP server or share email addresses.
 
 ### User deletion
 
@@ -48,7 +66,7 @@ LDAP-enabled users can always authenticate with Git using their GitLab username
 or email and LDAP password, even if password authentication for Git is disabled
 in the application settings.
 
-## Google Secure LDAP **[CORE ONLY]**
+## Google Secure LDAP **(CORE ONLY)**
 
 > Introduced in GitLab 11.9.
 
@@ -62,9 +80,12 @@ NOTE: **Note**:
 In GitLab Enterprise Edition Starter, you can configure multiple LDAP servers
 to connect to one GitLab server.
 
-For a complete guide on configuring LDAP with GitLab Community Edition, please check
-the admin guide [How to configure LDAP with GitLab CE](how_to_configure_ldap_gitlab_ce/index.md).
-For GitLab Enterprise Editions, see also [How to configure LDAP with GitLab EE](how_to_configure_ldap_gitlab_ee/index.md). **[STARTER ONLY]**
+For a complete guide on configuring LDAP with:
+
+- GitLab Community Edition, see
+  [How to configure LDAP with GitLab CE](how_to_configure_ldap_gitlab_ce/index.md).
+- Enterprise Editions, see
+  [How to configure LDAP with GitLab EE](how_to_configure_ldap_gitlab_ee/index.md). **(STARTER ONLY)**
 
 To enable LDAP integration you need to add your LDAP server settings in
 `/etc/gitlab/gitlab.rb` or `/home/git/gitlab/config/gitlab.yml` for Omnibus
@@ -382,35 +403,48 @@ production:
 Tip: If you want to limit access to the nested members of an Active Directory
 group, you can use the following syntax:
 
-```
+```text
 (memberOf:1.2.840.113556.1.4.1941:=CN=My Group,DC=Example,DC=com)
 ```
 
 Find more information about this "LDAP_MATCHING_RULE_IN_CHAIN" filter at
 <https://docs.microsoft.com/en-us/windows/desktop/ADSI/search-filter-syntax>. Support for
 nested members in the user filter should not be confused with
-[group sync nested groups support](ldap-ee.md#supported-ldap-group-typesattributes). **[STARTER ONLY]**
+[group sync nested groups support](ldap-ee.md#supported-ldap-group-typesattributes). **(STARTER ONLY)**
 
 Please note that GitLab does not support the custom filter syntax used by
 omniauth-ldap.
 
 ### Escaping special characters
 
-If the `user_filter` DN contains special characters. For example, a comma:
+The `user_filter` DN can contain special characters. For example:
 
-```
-OU=GitLab, Inc,DC=gitlab,DC=com
-```
+- A comma:
 
-This character needs to be escaped as documented in [RFC 4515](https://tools.ietf.org/search/rfc4515).
+  ```text
+  OU=GitLab, Inc,DC=gitlab,DC=com
+  ```
 
-Due to the way the string is parsed, the special character needs to be converted
-to hex and `\\5C\\` (`5C` = `\` in hex) added before it.
-As an example the above DN would look like
+- Open and close brackets:
 
-```
-OU=GitLab\\5C\\2C Inc,DC=gitlab,DC=com
-```
+  ```text
+  OU=Gitlab (Inc),DC=gitlab,DC=com
+  ```
+
+  These characters must be escaped as documented in
+  [RFC 4515](https://tools.ietf.org/search/rfc4515).
+
+- Escape commas with `\2C`. For example:
+
+  ```text
+  OU=GitLab\2C Inc,DC=gitlab,DC=com
+  ```
+
+- Escape open and close brackets with `\28` and `\29`, respectively. For example:
+
+  ```text
+  OU=Gitlab \28Inc\29,DC=gitlab,DC=com
+  ```
 
 ## Enabling LDAP sign-in for existing GitLab users
 
@@ -434,13 +468,13 @@ the configuration option `lowercase_usernames`. By default, this configuration o
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_servers'] = YAML.load <<-EOS
-    main:
-      # snip...
-      lowercase_usernames: true
-    EOS
-    ```
+   ```ruby
+   gitlab_rails['ldap_servers'] = YAML.load <<-EOS
+   main:
+     # snip...
+     lowercase_usernames: true
+   EOS
+   ```
 
 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -448,14 +482,14 @@ the configuration option `lowercase_usernames`. By default, this configuration o
 
 1. Edit `config/gitlab.yaml`:
 
-    ```yaml
-    production:
-      ldap:
-        servers:
-          main:
-            # snip...
-            lowercase_usernames: true
-    ```
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           lowercase_usernames: true
+   ```
 
 1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect.
 
@@ -483,13 +517,20 @@ be mandatory and clients cannot be authenticated with the TLS protocol.
 
 ## Troubleshooting
 
+If a user account is blocked or unblocked due to the LDAP configuration, a
+message will be logged to `application.log`.
+
+If there is an unexpected error during an LDAP lookup (configuration error,
+timeout), the login is rejected and a message will be logged to
+`production.log`.
+
 ### Debug LDAP user filter with ldapsearch
 
-This example uses ldapsearch and assumes you are using ActiveDirectory. The
+This example uses `ldapsearch` and assumes you are using ActiveDirectory. The
 following query returns the login names of the users that will be allowed to
 log in to GitLab if you configure your own user_filter.
 
-```
+```sh
 ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt  -b "$base" "$user_filter" sAMAccountName
 ```
 
@@ -508,26 +549,17 @@ ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt  -b "$ba
 - Run the following check command to make sure that the LDAP settings are
   correct and GitLab can see your users:
 
-    ```bash
-    # For Omnibus installations
-    sudo gitlab-rake gitlab:ldap:check
+  ```bash
+  # For Omnibus installations
+  sudo gitlab-rake gitlab:ldap:check
 
-    # For installations from source
-    sudo -u git -H bundle exec rake gitlab:ldap:check RAILS_ENV=production
-    ```
+  # For installations from source
+  sudo -u git -H bundle exec rake gitlab:ldap:check RAILS_ENV=production
+  ```
 
-### Connection Refused
+### Connection refused
 
 If you are getting 'Connection Refused' errors when trying to connect to the
 LDAP server please double-check the LDAP `port` and `encryption` settings used by
 GitLab. Common combinations are `encryption: 'plain'` and `port: 389`, OR
 `encryption: 'simple_tls'` and `port: 636`.
-
-### Troubleshooting
-
-If a user account is blocked or unblocked due to the LDAP configuration, a
-message will be logged to `application.log`.
-
-If there is an unexpected error during an LDAP lookup (configuration error,
-timeout), the login is rejected and a message will be logged to
-`production.log`.
diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md
index 00422ec347c..3445f916ef4 100644
--- a/doc/administration/auth/oidc.md
+++ b/doc/administration/auth/oidc.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # OpenID Connect OmniAuth provider
 
 GitLab can use [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) as an OmniAuth provider.
@@ -5,101 +9,103 @@ GitLab can use [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0
 To enable the OpenID Connect OmniAuth provider, you must register your application with an OpenID Connect provider.
 The OpenID Connect will provide you with a client details and secret for you to use.
 
-1.  On your GitLab server, open the configuration file.
-
-    For Omnibus GitLab:
-
-    ```sh
-    sudo editor /etc/gitlab/gitlab.rb
-    ```
-
-    For installations from source:
-
-    ```sh
-    cd /home/git/gitlab
-    sudo -u git -H editor config/gitlab.yml
-    ```
-
-    See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings.
-
-1.  Add the provider configuration.
-
-    For Omnibus GitLab:
-
-    ```ruby
-    gitlab_rails['omniauth_providers'] = [
-      { 'name' => 'openid_connect',
-        'label' => '<your_oidc_label>',
-        'args' => {
-          "name' => 'openid_connect',
-          'scope' => ['openid','profile'],
-          'response_type' => 'code',
-          'issuer' => '<your_oidc_url>',
-          'discovery' => true,
-          'client_auth_method' => 'query',
-          'uid_field' => '<uid_field>',
-          'client_options' => {
-            'identifier' => '<your_oidc_client_id>',
-            'secret' => '<your_oidc_client_secret>',
-            'redirect_uri' => '<your_gitlab_url>/users/auth/openid_connect/callback'
-          }
-        }
-      }
-    ]
-    ```
-
-    For installation from source:
-
-    ```yaml
-      - { name: 'openid_connect',
-          label: '<your_oidc_label>',
-          args: {
-            name: 'openid_connect',
-            scope: ['openid','profile'],
-            response_type: 'code',
-            issuer: '<your_oidc_url>',
-            discovery: true,
-            client_auth_method: 'query',
-            uid_field: '<uid_field>',
-            client_options: {
-              identifier: '<your_oidc_client_id>',
-              secret: '<your_oidc_client_secret>',
-              redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback'
-            }
-          }
-        }
-    ```
-
-    > **Note:**
-    >
-    > - For more information on each configuration option refer to
-        the [OmniAuth OpenID Connect usage documentation](https://github.com/m0n9oose/omniauth_openid_connect#usage) and
-        the [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html).
+1. On your GitLab server, open the configuration file.
+
+   For Omnibus GitLab:
+
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
+
+   For installations from source:
+
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H editor config/gitlab.yml
+   ```
+
+   See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings.
+
+1. Add the provider configuration.
+
+   For Omnibus GitLab:
+
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     { 'name' => 'openid_connect',
+       'label' => '<your_oidc_label>',
+       'args' => {
+         "name' => 'openid_connect',
+         'scope' => ['openid','profile'],
+         'response_type' => 'code',
+         'issuer' => '<your_oidc_url>',
+         'discovery' => true,
+         'client_auth_method' => 'query',
+         'uid_field' => '<uid_field>',
+         'client_options' => {
+           'identifier' => '<your_oidc_client_id>',
+           'secret' => '<your_oidc_client_secret>',
+           'redirect_uri' => '<your_gitlab_url>/users/auth/openid_connect/callback'
+         }
+       }
+     }
+   ]
+   ```
+
+   For installation from source:
+
+   ```yaml
+     - { name: 'openid_connect',
+         label: '<your_oidc_label>',
+         args: {
+           name: 'openid_connect',
+           scope: ['openid','profile'],
+           response_type: 'code',
+           issuer: '<your_oidc_url>',
+           discovery: true,
+           client_auth_method: 'query',
+           uid_field: '<uid_field>',
+           client_options: {
+             identifier: '<your_oidc_client_id>',
+             secret: '<your_oidc_client_secret>',
+             redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback'
+           }
+         }
+       }
+   ```
+
+   NOTE: **Note:**
+   For more information on each configuration option refer to the [OmniAuth OpenID Connect usage documentation](https://github.com/m0n9oose/omniauth_openid_connect#usage)
+   and the [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html).
 
 1. For the configuration above, change the values for the provider to match your OpenID Connect client setup. Use the following as a guide:
-    - `<your_oidc_label>` is the label that will be displayed on the login page.
-    - `<your_oidc_url>` (optional) is the URL that points to the OpenID Connect provider. For example, `https://example.com/auth/realms/your-realm`.
-      If this value is not provided, the URL is constructed from the `client_options` in the following format: `<client_options.scheme>://<client_options.host>:<client_options.port>`.
-    - If `discovery` is set to `true`, the OpenID Connect provider will try to auto discover the client options using `<your_oidc_url>/.well-known/openid-configuration`. Defaults to `false`.
-    - `<uid_field>` (optional) is the field name from the `user_info` details that will be used as `uid` value. For example, `preferred_username`.
-      If this value is not provided or the field with the configured value is missing from the `user_info` details, the `uid` will use the `sub` field.
-    - `client_options` are the OpenID Connect client-specific options. Specifically:
-
-      - `identifier` is the client identifier as configured in the OpenID Connect service provider.
-      - `secret` is the client secret as configured in the OpenID Connect service provider.
-      - `redirect_uri` is the GitLab URL to redirect the user to after successful login. For example, `http://example.com/users/auth/openid_connect/callback`.
-      - `end_session_endpoint` (optional) is the URL to the endpoint that end the session (logout). Can be provided if auto-discovery disabled or unsuccessful.
-
-      The following `client_options` are optional unless auto-discovery is disabled or unsuccessful:
-
-        - `authorization_endpoint` is the URL to the endpoint that authorizes the end user.
-        - `token_endpoint` is the URL to the endpoint that provides Access Token.
-        - `userinfo_endpoint` is the URL to the endpoint that provides the user information.
-        - `jwks_uri` is the URL to the endpoint where the Token signer publishes its keys.
-
-1.  Save the configuration file.
-1.  [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source)
-    for the changes to take effect if you installed GitLab via Omnibus or from source respectively.
+   - `<your_oidc_label>` is the label that will be displayed on the login page.
+   - `<your_oidc_url>` (optional) is the URL that points to the OpenID Connect provider. For example, `https://example.com/auth/realms/your-realm`.
+     If this value is not provided, the URL is constructed from the `client_options` in the following format: `<client_options.scheme>://<client_options.host>:<client_options.port>`.
+   - If `discovery` is set to `true`, the OpenID Connect provider will try to auto discover the client options using `<your_oidc_url>/.well-known/openid-configuration`. Defaults to `false`.
+   - `client_auth_method` (optional) specifies the method used for authenticating the client with the OpenID Connect provider.
+     - Supported values are:
+       - `basic` - HTTP Basic Authentication
+       - `jwt_bearer` - JWT based authentication (private key and client secret signing)
+       - `mtls` - Mutual TLS or X.509 certificate validation
+       - Any other value will POST the client id and secret in the request body
+     - If not specified, defaults to `basic`.
+   - `<uid_field>` (optional) is the field name from the `user_info` details that will be used as `uid` value. For example, `preferred_username`.
+     If this value is not provided or the field with the configured value is missing from the `user_info` details, the `uid` will use the `sub` field.
+   - `client_options` are the OpenID Connect client-specific options. Specifically:
+     - `identifier` is the client identifier as configured in the OpenID Connect service provider.
+     - `secret` is the client secret as configured in the OpenID Connect service provider.
+     - `redirect_uri` is the GitLab URL to redirect the user to after successful login. For example, `http://example.com/users/auth/openid_connect/callback`.
+     - `end_session_endpoint` (optional) is the URL to the endpoint that end the session (logout). Can be provided if auto-discovery disabled or unsuccessful.
+     - The following `client_options` are optional unless auto-discovery is disabled or unsuccessful:
+       - `authorization_endpoint` is the URL to the endpoint that authorizes the end user.
+       - `token_endpoint` is the URL to the endpoint that provides Access Token.
+       - `userinfo_endpoint` is the URL to the endpoint that provides the user information.
+       - `jwks_uri` is the URL to the endpoint where the Token signer publishes its keys.
+
+1. Save the configuration file.
+1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source)
+   for the changes to take effect if you installed GitLab via Omnibus or from source respectively.
 
 On the sign in page, there should now be an OpenID Connect icon below the regular sign in form.
 Click the icon to begin the authentication process. The OpenID Connect provider will ask the user to
@@ -139,25 +145,25 @@ for more details:
  }
 ```
 
-### Troubleshooting
+## Troubleshooting
 
 If you're having trouble, here are some tips:
 
 1. Ensure `discovery` is set to `true`. Setting it to `false` requires
-specifying all the URLs and keys required to make OpenID work.
+   specifying all the URLs and keys required to make OpenID work.
 
 1. Check your system clock to ensure the time is synchronized properly.
 
 1. As mentioned in [the
-documentation](https://github.com/m0n9oose/omniauth_openid_connect),
-make sure `issuer` corresponds to the base URL of the Discovery URL. For
-example, `https://accounts.google.com` is used for the URL
-`https://accounts.google.com/.well-known/openid-configuration`.
+   documentation](https://github.com/m0n9oose/omniauth_openid_connect),
+   make sure `issuer` corresponds to the base URL of the Discovery URL. For
+   example, `https://accounts.google.com` is used for the URL
+   `https://accounts.google.com/.well-known/openid-configuration`.
 
 1. The OpenID Connect client uses HTTP Basic Authentication to send the
-OAuth2 access token. For example, if you are seeing 401 errors upon
-retrieving the `userinfo` endpoint, you may want to check your OpenID
-Web server configuration. For example, for
-[oauth2-server-php](https://github.com/bshaffer/oauth2-server-php), you
-may need to [add a configuration parameter to
-Apache](https://github.com/bshaffer/oauth2-server-php/issues/926#issuecomment-387502778).
+   OAuth2 access token if `client_auth_method` is not defined or if set to `basic`.
+   If you are seeing 401 errors upon retrieving the `userinfo` endpoint, you may
+   want to check your OpenID Web server configuration. For example, for
+   [oauth2-server-php](https://github.com/bshaffer/oauth2-server-php), you
+   may need to [add a configuration parameter to
+   Apache](https://github.com/bshaffer/oauth2-server-php/issues/926#issuecomment-387502778).
diff --git a/doc/administration/auth/okta.md b/doc/administration/auth/okta.md
index aa4e1b0d2e0..5524c3ba092 100644
--- a/doc/administration/auth/okta.md
+++ b/doc/administration/auth/okta.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Okta SSO provider
 
 Okta is a [Single Sign-on provider](https://www.okta.com/products/single-sign-on/) that can be used to authenticate
@@ -16,7 +20,7 @@ The following documentation enables Okta as a SAML provider.
 1. Next, you'll need the to fill in the SAML general config. Here's an example
    image.
 
-    ![Okta admin panel view](img/okta_admin_panel.png)
+   ![Okta admin panel view](img/okta_admin_panel.png)
 
 1. The last part of the configuration is the feedback section where you can
    just say you're a customer and creating an app for internal use.
@@ -24,7 +28,7 @@ The following documentation enables Okta as a SAML provider.
    profile. Click on the SAML 2.0 config instructions button which should
    look like the following:
 
-    ![Okta SAML settings](img/okta_saml_settings.png)
+   ![Okta SAML settings](img/okta_saml_settings.png)
 
 1. On the screen that comes up take note of the
    **Identity Provider Single Sign-On URL** which you'll use for the
@@ -38,112 +42,112 @@ Now that the Okta app is configured, it's time to enable it in GitLab.
 
 ## Configure GitLab
 
-1.  On your GitLab server, open the configuration file:
-
-    **For Omnibus GitLab installations**
-
-    ```sh
-    sudo editor /etc/gitlab/gitlab.rb
-    ```
-
-    **For installations from source**
-
-    ```sh
-    cd /home/git/gitlab
-    sudo -u git -H editor config/gitlab.yml
-    ```
-
-1.  See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration)
-    for initial settings.
-
-1.  To allow your users to use Okta to sign up without having to manually create
-    an account first, don't forget to add the following values to your
-    configuration:
-
-    **For Omnibus GitLab installations**
-
-    ```ruby
-    gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
-    gitlab_rails['omniauth_block_auto_created_users'] = false
-    ```
-
-    **For installations from source**
-
-    ```yaml
-    allow_single_sign_on: ["saml"]
-    block_auto_created_users: false
-    ```
-
-1.  You can also automatically link Okta users with existing GitLab users if
-    their email addresses match by adding the following setting:
-
-    **For Omnibus GitLab installations**
-
-    ```ruby
-    gitlab_rails['omniauth_auto_link_saml_user'] = true
-    ```
-
-    **For installations from source**
-
-    ```yaml
-    auto_link_saml_user: true
-    ```
-
-1.  Add the provider configuration.
-
-      >**Notes:**
-      >
-      >- Change the value for `assertion_consumer_service_url` to match the HTTPS endpoint
-         of GitLab (append `users/auth/saml/callback` to the HTTPS URL of your GitLab
-         installation to generate the correct value).
-      >   
-      >- To get the `idp_cert_fingerprint` fingerprint, first download the
-         certificate from the Okta app you registered and then run:
-         `openssl x509 -in okta.cert -noout -fingerprint`. Substitute `okta.cert`
-         with the location of your certificate.
-      >
-      >- Change the value of `idp_sso_target_url`, with the value of the
-         **Identity Provider Single Sign-On URL** from the step when you
-         configured the Okta app.
-      >     
-      >- Change the value of `issuer` to the value of the **Audience Restriction** from your Okta app configuration. This will identify GitLab
-         to the IdP.
-      >     
-      >- Leave `name_identifier_format` as-is.
-
-    **For Omnibus GitLab installations**
-
-    ```ruby
-    gitlab_rails['omniauth_providers'] = [
-      {
-        name: 'saml',
-        args: {
-                 assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
-                 idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
-                 idp_sso_target_url: 'https://gitlab.oktapreview.com/app/gitlabdev773716_gitlabsaml_1/exk8odl81tBrjpD4B0h7/sso/saml',
-                 issuer: 'https://gitlab.example.com',
-                 name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
-               },
-        label: 'Okta' # optional label for SAML login button, defaults to "Saml"
-      }
-    ]
-    ```
-
-    **For installations from source**
-
-    ```yaml
-    - {
-        name: 'saml',
-        args: {
-               assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
-               idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
-               idp_sso_target_url: 'https://gitlab.oktapreview.com/app/gitlabdev773716_gitlabsaml_1/exk8odl81tBrjpD4B0h7/sso/saml',
-               issuer: 'https://gitlab.example.com',
-               name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
-             },
-        label: 'Okta' # optional label for SAML login button, defaults to "Saml"
-      }
-    ```
+1. On your GitLab server, open the configuration file:
+
+   **For Omnibus GitLab installations**
+
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
+
+   **For installations from source**
+
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H editor config/gitlab.yml
+   ```
+
+1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration)
+   for initial settings.
+
+1. To allow your users to use Okta to sign up without having to manually create
+   an account first, don't forget to add the following values to your
+   configuration:
+
+   **For Omnibus GitLab installations**
+
+   ```ruby
+   gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
+   gitlab_rails['omniauth_block_auto_created_users'] = false
+   ```
+
+   **For installations from source**
+
+   ```yaml
+   allow_single_sign_on: ["saml"]
+   block_auto_created_users: false
+   ```
+
+1. You can also automatically link Okta users with existing GitLab users if
+   their email addresses match by adding the following setting:
+
+   **For Omnibus GitLab installations**
+
+   ```ruby
+   gitlab_rails['omniauth_auto_link_saml_user'] = true
+   ```
+
+   **For installations from source**
+
+   ```yaml
+   auto_link_saml_user: true
+   ```
+
+1. Add the provider configuration.
+
+   >**Notes:**
+   >
+   >- Change the value for `assertion_consumer_service_url` to match the HTTPS endpoint
+      of GitLab (append `users/auth/saml/callback` to the HTTPS URL of your GitLab
+      installation to generate the correct value).
+   >
+   >- To get the `idp_cert_fingerprint` fingerprint, first download the
+      certificate from the Okta app you registered and then run:
+      `openssl x509 -in okta.cert -noout -fingerprint`. Substitute `okta.cert`
+      with the location of your certificate.
+   >
+   >- Change the value of `idp_sso_target_url`, with the value of the
+      **Identity Provider Single Sign-On URL** from the step when you
+      configured the Okta app.
+   >
+   >- Change the value of `issuer` to the value of the **Audience Restriction** from your Okta app configuration. This will identify GitLab
+      to the IdP.
+   >
+   >- Leave `name_identifier_format` as-is.
+
+   **For Omnibus GitLab installations**
+
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       name: 'saml',
+       args: {
+                assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+                idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+                idp_sso_target_url: 'https://gitlab.oktapreview.com/app/gitlabdev773716_gitlabsaml_1/exk8odl81tBrjpD4B0h7/sso/saml',
+                issuer: 'https://gitlab.example.com',
+                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
+              },
+       label: 'Okta' # optional label for SAML login button, defaults to "Saml"
+     }
+   ]
+   ```
+
+   **For installations from source**
+
+   ```yaml
+   - {
+       name: 'saml',
+       args: {
+              assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+              idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+              idp_sso_target_url: 'https://gitlab.oktapreview.com/app/gitlabdev773716_gitlabsaml_1/exk8odl81tBrjpD4B0h7/sso/saml',
+              issuer: 'https://gitlab.example.com',
+              name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
+            },
+       label: 'Okta' # optional label for SAML login button, defaults to "Saml"
+     }
+   ```
 
 1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../restart_gitlab.md#installations-from-source) GitLab for Omnibus and installations
    from source respectively for the changes to take effect.
@@ -157,3 +161,15 @@ Make sure the groups exist and are assigned to the Okta app.
 
 You can take a look of the [SAML documentation](../../integration/saml.md#marking-users-as-external-based-on-saml-groups) on external groups since
 it works the same.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md
index b33c5359b44..4f236d1afb8 100644
--- a/doc/administration/auth/smartcard.md
+++ b/doc/administration/auth/smartcard.md
@@ -1,4 +1,8 @@
-# Smartcard authentication **[PREMIUM ONLY]**
+---
+type: reference
+---
+
+# Smartcard authentication **(PREMIUM ONLY)**
 
 GitLab supports authentication using smartcards.
 
@@ -22,7 +26,7 @@ To use a smartcard with an X.509 certificate to authenticate against a local
 database with GitLab, `CN` and `emailAddress` must be defined in the
 certificate. For example:
 
-```
+```text
 Certificate:
     Data:
         Version: 1 (0x0)
@@ -56,11 +60,11 @@ attribute. As a prerequisite, you must use an LDAP server that:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['smartcard_enabled'] = true
-    gitlab_rails['smartcard_ca_file'] = "/etc/ssl/certs/CA.pem"
-    gitlab_rails['smartcard_client_certificate_required_port'] = 3444
-    ```
+   ```ruby
+   gitlab_rails['smartcard_enabled'] = true
+   gitlab_rails['smartcard_ca_file'] = "/etc/ssl/certs/CA.pem"
+   gitlab_rails['smartcard_client_certificate_required_port'] = 3444
+   ```
 
 1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure)
    GitLab for the changes to take effect.
@@ -154,15 +158,15 @@ attribute. As a prerequisite, you must use an LDAP server that:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_servers'] = YAML.load <<-EOS
-    main:
-      # snip...
-      # Enable smartcard authentication against the LDAP server. Valid values
-      # are "false", "optional", and "required".
-      smartcard_auth: optional
-    EOS
-    ```
+   ```ruby
+   gitlab_rails['ldap_servers'] = YAML.load <<-EOS
+   main:
+     # snip...
+     # Enable smartcard authentication against the LDAP server. Valid values
+     # are "false", "optional", and "required".
+     smartcard_auth: optional
+   EOS
+   ```
 
 1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure)
    GitLab for the changes to take effect.
@@ -171,16 +175,56 @@ attribute. As a prerequisite, you must use an LDAP server that:
 
 1. Edit `config/gitlab.yml`:
 
-    ```yaml
-    production:
-      ldap:
-        servers:
-          main:
-            # snip...
-            # Enable smartcard authentication against the LDAP server. Valid values
-            # are "false", "optional", and "required".
-            smartcard_auth: optional
-    ```
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           # Enable smartcard authentication against the LDAP server. Valid values
+           # are "false", "optional", and "required".
+           smartcard_auth: optional
+   ```
 
 1. Save the file and [restart](../restart_gitlab.md#installations-from-source)
    GitLab for the changes to take effect.
+
+### Require browser session with smartcard sign-in for Git access
+
+**For Omnibus installations**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['smartcard_required_for_git_access'] = true
+   ```
+
+1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure)
+   GitLab for the changes to take effect.
+
+**For installations from source**
+
+1. Edit `config/gitlab.yml`:
+
+   ```yaml
+   ## Smartcard authentication settings
+   smartcard:
+     # snip...
+     # Browser session with smartcard sign-in is required for Git access
+     required_for_git_access: true
+   ```
+
+1. Save the file and [restart](../restart_gitlab.md#installations-from-source)
+   GitLab for the changes to take effect.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md
index 4d55f2357c1..d0adeb89543 100644
--- a/doc/administration/container_registry.md
+++ b/doc/administration/container_registry.md
@@ -1,7 +1,5 @@
 # GitLab Container Registry administration
 
-> **Notes:**
->
 > - [Introduced][ce-4040] in GitLab 8.8.
 > - Container Registry manifest `v1` support was added in GitLab 8.9 to support
 >   Docker versions earlier than 1.10.
@@ -29,8 +27,6 @@ but not recommended and out of the scope of this document.
 Read the [insecure Registry documentation][docker-insecure] if you want to
 implement this.
 
----
-
 **Installations from source**
 
 If you have installed GitLab from source:
@@ -118,50 +114,44 @@ GitLab from source respectively.
 Be careful to choose a port different than the one that Registry listens to (`5000` by default),
 otherwise you will run into conflicts.
 
----
-
 **Omnibus GitLab installations**
 
 1. Your `/etc/gitlab/gitlab.rb` should contain the Registry URL as well as the
    path to the existing TLS certificate and key used by GitLab:
 
-    ```ruby
-    registry_external_url 'https://gitlab.example.com:4567'
-    ```
+   ```ruby
+   registry_external_url 'https://gitlab.example.com:4567'
+   ```
 
-    Note how the `registry_external_url` is listening on HTTPS under the
-    existing GitLab URL, but on a different port.
+   Note how the `registry_external_url` is listening on HTTPS under the
+   existing GitLab URL, but on a different port.
 
-    If your TLS certificate is not in `/etc/gitlab/ssl/gitlab.example.com.crt`
-    and key not in `/etc/gitlab/ssl/gitlab.example.com.key` uncomment the lines
-    below:
+   If your TLS certificate is not in `/etc/gitlab/ssl/gitlab.example.com.crt`
+   and key not in `/etc/gitlab/ssl/gitlab.example.com.key` uncomment the lines
+   below:
 
-    ```ruby
-    registry_nginx['ssl_certificate'] = "/path/to/certificate.pem"
-    registry_nginx['ssl_certificate_key'] = "/path/to/certificate.key"
-    ```
+   ```ruby
+   registry_nginx['ssl_certificate'] = "/path/to/certificate.pem"
+   registry_nginx['ssl_certificate_key'] = "/path/to/certificate.key"
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **Installations from source**
 
 1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
    configure it with the following settings:
 
-    ```
-    registry:
-      enabled: true
-      host: gitlab.example.com
-      port: 4567
-    ```
+   ```
+   registry:
+     enabled: true
+     host: gitlab.example.com
+     port: 4567
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 1. Make the relevant changes in NGINX as well (domain, port, TLS certificates path).
 
----
-
 Users should now be able to login to the Container Registry with their GitLab
 credentials using:
 
@@ -179,8 +169,6 @@ domain (e.g., `registry.gitlab.example.com`).
 Let's assume that you want the container Registry to be accessible at
 `https://registry.gitlab.example.com`.
 
----
-
 **Omnibus GitLab installations**
 
 1. Place your TLS certificate and key in
@@ -188,17 +176,17 @@ Let's assume that you want the container Registry to be accessible at
    `/etc/gitlab/ssl/registry.gitlab.example.com.key` and make sure they have
    correct permissions:
 
-    ```bash
-    chmod 600 /etc/gitlab/ssl/registry.gitlab.example.com.*
-    ```
+   ```bash
+   chmod 600 /etc/gitlab/ssl/registry.gitlab.example.com.*
+   ```
 
 1. Once the TLS certificate is in place, edit `/etc/gitlab/gitlab.rb` with:
 
-    ```ruby
-    registry_external_url 'https://registry.gitlab.example.com'
-    ```
+   ```ruby
+   registry_external_url 'https://registry.gitlab.example.com'
+   ```
 
-    Note how the `registry_external_url` is listening on HTTPS.
+   Note how the `registry_external_url` is listening on HTTPS.
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -212,24 +200,20 @@ look like:
 > registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key"
 > ```
 
----
-
 **Installations from source**
 
 1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
    configure it with the following settings:
 
-    ```
-    registry:
-      enabled: true
-      host: registry.gitlab.example.com
-    ```
+   ```yaml
+   registry:
+     enabled: true
+     host: registry.gitlab.example.com
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 1. Make the relevant changes in NGINX as well (domain, port, TLS certificates path).
 
----
-
 Users should now be able to login to the Container Registry using their GitLab
 credentials:
 
@@ -248,23 +232,21 @@ Registry application itself.
 
 1. Open `/etc/gitlab/gitlab.rb` and set `registry['enable']` to `false`:
 
-    ```ruby
-    registry['enable'] = false
-    ```
+   ```ruby
+   registry['enable'] = false
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **Installations from source**
 
 1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
    set `enabled` to `false`:
 
-    ```
-    registry:
-      enabled: false
-    ```
+   ```yaml
+   registry:
+     enabled: false
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -274,35 +256,31 @@ If the Container Registry is enabled, then it will be available on all new
 projects. To disable this function and let the owners of a project to enable
 the Container Registry by themselves, follow the steps below.
 
----
-
 **Omnibus GitLab installations**
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
-    ```ruby
-    gitlab_rails['gitlab_default_projects_features_container_registry'] = false
-    ```
+   ```ruby
+   gitlab_rails['gitlab_default_projects_features_container_registry'] = false
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **Installations from source**
 
 1. Open `/home/git/gitlab/config/gitlab.yml`, find the `default_projects_features`
    entry and configure it so that `container_registry` is set to `false`:
 
-    ```
-    ## Default project features settings
-    default_projects_features:
-      issues: true
-      merge_requests: true
-      wiki: true
-      snippets: false
-      builds: true
-      container_registry: false
-    ```
+   ```yaml
+   ## Default project features settings
+   default_projects_features:
+     issues: true
+     merge_requests: true
+     wiki: true
+     snippets: false
+     builds: true
+     container_registry: false
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -323,8 +301,6 @@ This path is accessible to:
 > **Warning** You should confirm that all GitLab, Registry and web server users
 have access to this directory.
 
----
-
 **Omnibus GitLab installations**
 
 The default location where images are stored in Omnibus, is
@@ -332,14 +308,12 @@ The default location where images are stored in Omnibus, is
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['registry_path'] = "/path/to/registry/storage"
-    ```
+   ```ruby
+   gitlab_rails['registry_path'] = "/path/to/registry/storage"
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **Installations from source**
 
 The default location where images are stored in source installations, is
@@ -348,10 +322,10 @@ The default location where images are stored in source installations, is
 1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
    change the `path` setting:
 
-    ```
-    registry:
-      path: shared/registry
-    ```
+   ```yaml
+   registry:
+     path: shared/registry
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -393,17 +367,17 @@ To configure the `s3` storage driver in Omnibus:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    registry['storage'] = {
-      's3' => {
-        'accesskey' => 's3-access-key',
-        'secretkey' => 's3-secret-key-for-access-key',
-        'bucket' => 'your-s3-bucket',
-        'region' => 'your-s3-region',
-        'regionendpoint' => 'your-s3-regionendpoint'
-      }
-    }
-    ```
+   ```ruby
+   registry['storage'] = {
+     's3' => {
+       'accesskey' => 's3-access-key',
+       'secretkey' => 's3-secret-key-for-access-key',
+       'bucket' => 'your-s3-bucket',
+       'region' => 'your-s3-region',
+       'regionendpoint' => 'your-s3-regionendpoint'
+     }
+   }
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -442,23 +416,21 @@ In the examples below we set the Registry's port to `5001`.
 
 1. Open `/etc/gitlab/gitlab.rb` and set `registry['registry_http_addr']`:
 
-    ```ruby
-    registry['registry_http_addr'] = "localhost:5001"
-    ```
+   ```ruby
+   registry['registry_http_addr'] = "localhost:5001"
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **Installations from source**
 
 1. Open the configuration file of your Registry server and edit the
    [`http:addr`][registry-http-config] value:
 
-    ```
-    http
-      addr: localhost:5001
-    ```
+   ```yaml
+   http
+     addr: localhost:5001
+   ```
 
 1. Save the file and restart the Registry server.
 
@@ -476,14 +448,14 @@ You can use GitLab as an auth endpoint and use a non-bundled Container Registry.
 
 1. Open `/etc/gitlab/gitlab.rb` and set necessary configurations:
 
-    ```ruby
-    gitlab_rails['registry_enabled'] = true
-    gitlab_rails['registry_host'] = "registry.gitlab.example.com"
-    gitlab_rails['registry_port'] = "5005"
-    gitlab_rails['registry_api_url'] = "http://localhost:5000"
-    gitlab_rails['registry_path'] = "/var/opt/gitlab/gitlab-rails/shared/registry"
-    gitlab_rails['registry_issuer'] = "omnibus-gitlab-issuer"
-    ```
+   ```ruby
+   gitlab_rails['registry_enabled'] = true
+   gitlab_rails['registry_host'] = "registry.gitlab.example.com"
+   gitlab_rails['registry_port'] = "5005"
+   gitlab_rails['registry_api_url'] = "http://localhost:5000"
+   gitlab_rails['registry_path'] = "/var/opt/gitlab/gitlab-rails/shared/registry"
+   gitlab_rails['registry_issuer'] = "omnibus-gitlab-issuer"
+   ```
 
 1. A certificate keypair is required for GitLab and the Container Registry to
    communicate securely.  By default omnibus-gitlab will generate one keypair,
@@ -492,19 +464,19 @@ You can use GitLab as an auth endpoint and use a non-bundled Container Registry.
    custom certificate key. To do that, add the following to
    `/etc/gitlab/gitlab.rb`
 
-    ```ruby
-    gitlab_rails['registry_key_path'] = "/custom/path/to/registry-key.key"
-    # registry['internal_key'] should contain the contents of the custom key
-    # file. Line breaks in the key file should be marked using `\n` character
-    # Example:
-    registry['internal_key'] = "---BEGIN RSA PRIVATE KEY---\nMIIEpQIBAA\n"
-    ```
+   ```ruby
+   gitlab_rails['registry_key_path'] = "/custom/path/to/registry-key.key"
+   # registry['internal_key'] should contain the contents of the custom key
+   # file. Line breaks in the key file should be marked using `\n` character
+   # Example:
+   registry['internal_key'] = "---BEGIN RSA PRIVATE KEY---\nMIIEpQIBAA\n"
+   ```
 
-    **Note:** The file specified at `registry_key_path` gets populated with the
-    content specified by `internal_key`, each time reconfigure is executed. If
-    no file is specified, omnibus-gitlab will default it to
-    `/var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key` and will populate
-    it.
+   **Note:** The file specified at `registry_key_path` gets populated with the
+   content specified by `internal_key`, each time reconfigure is executed. If
+   no file is specified, omnibus-gitlab will default it to
+   `/var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key` and will populate
+   it.
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -512,18 +484,18 @@ You can use GitLab as an auth endpoint and use a non-bundled Container Registry.
 
 1. Open `/home/git/gitlab/config/gitlab.yml`, and edit the configuration settings under `registry`:
 
-    ```
-    ## Container Registry
+   ```yaml
+   ## Container Registry
 
-    registry:
-      enabled: true
-      host: "registry.gitlab.example.com"
-      port: "5005"
-      api_url: "http://localhost:5000"
-      path: /var/opt/gitlab/gitlab-rails/shared/registry
-      key: /var/opt/gitlab/gitlab-rails/certificate.key
-      issuer: omnibus-gitlab-issuer
-    ```
+   registry:
+     enabled: true
+     host: "registry.gitlab.example.com"
+     port: "5005"
+     api_url: "http://localhost:5000"
+     path: /var/opt/gitlab/gitlab-rails/shared/registry
+     key: /var/opt/gitlab/gitlab-rails/certificate.key
+     issuer: omnibus-gitlab-issuer
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -550,25 +522,23 @@ To configure a notification endpoint in Omnibus:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    registry['notifications'] = [
-      {
-        'name' => 'test_endpoint',
-        'url' => 'https://gitlab.example.com/notify',
-        'timeout' => '500ms',
-        'threshold' => 5,
-        'backoff' => '1s',
-        'headers' => {
-          "Authorization" => ["AUTHORIZATION_EXAMPLE_TOKEN"]
-        }
-      }
-    ]
-    ```
+   ```ruby
+   registry['notifications'] = [
+     {
+       'name' => 'test_endpoint',
+       'url' => 'https://gitlab.example.com/notify',
+       'timeout' => '500ms',
+       'threshold' => 5,
+       'backoff' => '1s',
+       'headers' => {
+         "Authorization" => ["AUTHORIZATION_EXAMPLE_TOKEN"]
+       }
+     }
+   ]
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **Installations from source**
 
 Configuring the notification endpoint is done in your registry config YML file created
@@ -629,33 +599,31 @@ Start with a value between `25000000` (25MB) and `50000000` (50MB).
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    registry['storage'] = {
-      's3' => {
-        'accesskey' => 'AKIAKIAKI',
-        'secretkey' => 'secret123',
-        'bucket'    => 'gitlab-registry-bucket-AKIAKIAKI',
-        'chunksize' => 25000000
-      }
-    }
-    ```
+   ```ruby
+   registry['storage'] = {
+     's3' => {
+       'accesskey' => 'AKIAKIAKI',
+       'secretkey' => 'secret123',
+       'bucket'    => 'gitlab-registry-bucket-AKIAKIAKI',
+       'chunksize' => 25000000
+     }
+   }
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **For installations from source**
 
 1. Edit `config/gitlab.yml`:
 
-    ```yaml
-    storage:
-      s3:
-        accesskey: 'AKIAKIAKI'
-        secretkey: 'secret123'
-        bucket:    'gitlab-registry-bucket-AKIAKIAKI'
-        chunksize: 25000000
-    ```
+   ```yaml
+   storage:
+     s3:
+       accesskey: 'AKIAKIAKI'
+       secretkey: 'secret123'
+       bucket:    'gitlab-registry-bucket-AKIAKIAKI'
+       chunksize: 25000000
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -669,26 +637,70 @@ You can add a configuration option for backwards compatibility.
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    registry['compatibility_schema1_enabled'] = true
-    ```
+   ```ruby
+   registry['compatibility_schema1_enabled'] = true
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **For installations from source**
 
 1. Edit the YML configuration file you created when you [deployed the registry][registry-deploy]. Add the following snippet:
 
-    ```yaml
-    compatibility:
-        schema1:
-            enabled: true
-    ```
+   ```yaml
+   compatibility:
+       schema1:
+           enabled: true
+   ```
 
 1. Restart the registry for the changes to take affect.
 
+### Docker connection error
+
+A Docker connection error can occur when there are special characters in either the group,
+project or branch name. Special characters can include:
+
+- Leading underscore
+- Trailing hyphen/dash
+- Double hyphen/dash
+
+To get around this, you can [change the group path](../user/group/index.md#changing-a-groups-path),
+[change the project path](../user/project/settings/index.md#renaming-a-repository) or change the
+branch name. Another option is to create a [push rule](../push_rules/push_rules.html) to prevent
+this at the instance level.
+
+### Image push errors
+
+When getting errors or "retrying" loops in an attempt to push an image but `docker login` works fine,
+there is likely an issue with the headers forwarded to the registry by NGINX. The default recommended
+NGINX configurations should handle this, but it might occur in custom setups where the SSL is
+offloaded to a third party reverse proxy.
+
+This problem was discussed in a [docker project issue][docker-image-push-issue] and a simple solution
+would be to enable relative urls in the registry.
+
+**For Omnibus installations**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   registry['env'] = {
+     "REGISTRY_HTTP_RELATIVEURLS" => true
+   }
+   ```
+
+1. Save the file and [reconfigure GitLab][] for the changes to take effect.
+
+**For installations from source**
+
+1. Edit the YML configuration file you created when you [deployed the registry][registry-deploy]. Add the following snippet:
+
+   ```yaml
+   http:
+       relativeurls: true
+   ```
+
+1. Restart the registry for the changes to take affect.
 
 [ce-18239]: https://gitlab.com/gitlab-org/gitlab-ce/issues/18239
 [docker-insecure-self-signed]: https://docs.docker.com/registry/insecure/#use-self-signed-certificates
@@ -708,3 +720,4 @@ You can add a configuration option for backwards compatibility.
 [new-domain]: #configure-container-registry-under-its-own-domain
 [notifications-config]: https://docs.docker.com/registry/notifications/
 [registry-notifications-config]: https://docs.docker.com/registry/configuration/#notifications
+[docker-image-push-issue]: https://github.com/docker/distribution/issues/970
diff --git a/doc/administration/custom_hooks.md b/doc/administration/custom_hooks.md
index 113514e1ee8..32462a95a1a 100644
--- a/doc/administration/custom_hooks.md
+++ b/doc/administration/custom_hooks.md
@@ -21,7 +21,7 @@ administrators can add custom git hooks to any GitLab project.
 ## Create a custom Git hook for a repository
 
 Server-side Git hooks are typically placed in the repository's `hooks`
-subdirectory. In GitLab, hook directories are are symlinked to the gitlab-shell
+subdirectory. In GitLab, hook directories are symlinked to the gitlab-shell
 `hooks` directory for ease of maintenance between gitlab-shell upgrades.
 Custom hooks are implemented differently, but the behavior is exactly the same
 once the hook is created. Follow the steps below to set up a custom hook for a
diff --git a/doc/administration/database_load_balancing.md b/doc/administration/database_load_balancing.md
index 7f3be402b84..dc4cc401fca 100644
--- a/doc/administration/database_load_balancing.md
+++ b/doc/administration/database_load_balancing.md
@@ -1,4 +1,4 @@
-# Database Load Balancing **[PREMIUM ONLY]**
+# Database Load Balancing **(PREMIUM ONLY)**
 
 > [Introduced][ee-1283] in [GitLab Premium][eep] 9.0.
 
@@ -40,16 +40,16 @@ For example, say you have a primary (`db1.gitlab.com`) and two secondaries,
 `db2.gitlab.com` and `db3.gitlab.com`. For this setup you will need to have 3
 load balancers, one for every host. For example:
 
-* `primary.gitlab.com` forwards to `db1.gitlab.com`
-* `secondary1.gitlab.com` forwards to `db2.gitlab.com`
-* `secondary2.gitlab.com` forwards to `db3.gitlab.com`
+- `primary.gitlab.com` forwards to `db1.gitlab.com`
+- `secondary1.gitlab.com` forwards to `db2.gitlab.com`
+- `secondary2.gitlab.com` forwards to `db3.gitlab.com`
 
 Now let's say that a failover happens and db2 becomes the new primary. This
 means forwarding should now happen as follows:
 
-* `primary.gitlab.com` forwards to `db2.gitlab.com`
-* `secondary1.gitlab.com` forwards to `db1.gitlab.com`
-* `secondary2.gitlab.com` forwards to `db3.gitlab.com`
+- `primary.gitlab.com` forwards to `db2.gitlab.com`
+- `secondary1.gitlab.com` forwards to `db1.gitlab.com`
+- `secondary2.gitlab.com` forwards to `db3.gitlab.com`
 
 GitLab does not take care of this for you, so you will need to do so yourself.
 
@@ -74,9 +74,9 @@ the following. This will balance the load between `host1.example.com` and
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
-    ```ruby
-    gitlab_rails['db_load_balancing'] = { 'hosts' => ['host1.example.com', 'host2.example.com'] }
-    ```
+   ```ruby
+   gitlab_rails['db_load_balancing'] = { 'hosts' => ['host1.example.com', 'host2.example.com'] }
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -86,16 +86,16 @@ the following. This will balance the load between `host1.example.com` and
 
 1. Edit `/home/git/gitlab/config/database.yml` and add or amend the following lines:
 
-    ```yaml
-    production:
-      username: gitlab
-      database: gitlab
-      encoding: unicode
-      load_balancing:
-        hosts:
-          - host1.example.com
-          - host2.example.com
-    ```
+   ```yaml
+   production:
+     username: gitlab
+     database: gitlab
+     encoding: unicode
+     load_balancing:
+       hosts:
+         - host1.example.com
+         - host2.example.com
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -209,9 +209,9 @@ without it immediately leading to errors being presented to the users.
 
 The load balancer logs various messages, such as:
 
-* When a host is marked as offline
-* When a host comes back online
-* When all secondaries are offline
+- When a host is marked as offline
+- When a host comes back online
+- When all secondaries are offline
 
 Each log message contains the tag `[DB-LB]` to make searching/filtering of such
 log entries easier. For example:
@@ -265,7 +265,7 @@ production:
     replica_check_interval: 30
 ```
 
-[hot-standby]: https://www.postgresql.org/docs/9.6/static/hot-standby.html
+[hot-standby]: https://www.postgresql.org/docs/9.6/hot-standby.html
 [ee-1283]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1283
 [eep]: https://about.gitlab.com/pricing/
 [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab"
diff --git a/doc/administration/dependency_proxy.md b/doc/administration/dependency_proxy.md
index 4dc1f4dcba4..d2c52b67e67 100644
--- a/doc/administration/dependency_proxy.md
+++ b/doc/administration/dependency_proxy.md
@@ -1,6 +1,6 @@
-# GitLab Dependency Proxy administration **[PREMIUM ONLY]**
+# GitLab Dependency Proxy administration **(PREMIUM ONLY)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing) 11.11.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11.
 
 GitLab can be utilized as a dependency proxy for a variety of common package managers.
 
@@ -70,6 +70,7 @@ To change the local storage path:
      enabled: true
      storage_path: shared/dependency_proxy
    ```
+
 1. [Restart GitLab] for the changes to take effect.
 
 ### Using object storage
diff --git a/doc/administration/environment_variables.md b/doc/administration/environment_variables.md
index e6c8f59549f..37d7194af53 100644
--- a/doc/administration/environment_variables.md
+++ b/doc/administration/environment_variables.md
@@ -13,6 +13,7 @@ override certain values.
 
 Variable | Type | Description
 -------- | ---- | -----------
+`ENABLE_BOOTSNAP`                          | string  | Enables Bootsnap for speeding up initial Rails boot (`1` to enable)
 `GITLAB_CDN_HOST`                          | string  | Sets the base URL for a CDN to serve static assets (e.g. `//mycdnsubdomain.fictional-cdn.com`)
 `GITLAB_ROOT_PASSWORD`                     | string  | Sets the password for the `root` user on installation
 `GITLAB_HOST`                              | string  | The full URL of the GitLab server (including `http://` or `https://`)
@@ -42,7 +43,7 @@ The list of `GITLAB_DATABASE_XXX` variables that you can set is:
 
 Variable | Default value | Overridden by `DATABASE_URL`?
 -------- | ------------- | -----------------------------
-`GITLAB_DATABASE_ADAPTER`   | `postgresql` (for MySQL use `mysql2`) | Yes
+`GITLAB_DATABASE_ADAPTER`   | `postgresql`                          | Yes
 `GITLAB_DATABASE_DATABASE`  | `gitlab_#{ENV['RAILS_ENV']`           | Yes
 `GITLAB_DATABASE_USERNAME`  | `root`                                | Yes
 `GITLAB_DATABASE_PASSWORD`  | None                                  | Yes
@@ -64,4 +65,4 @@ instructions](https://docs.gitlab.com/omnibus/settings/environment-variables.htm
 
 It's possible to preconfigure the GitLab docker image by adding the environment
 variable `GITLAB_OMNIBUS_CONFIG` to the `docker run` command.
-For more information see the ['preconfigure-docker-container' section in the Omnibus documentation](http://docs.gitlab.com/omnibus/docker/#preconfigure-docker-container).
+For more information see the ['preconfigure-docker-container' section in the Omnibus documentation](https://docs.gitlab.com/omnibus/docker/#preconfigure-docker-container).
diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md
index d4c8c2d3624..27866b7536e 100644
--- a/doc/administration/geo/disaster_recovery/background_verification.md
+++ b/doc/administration/geo/disaster_recovery/background_verification.md
@@ -1,4 +1,4 @@
-# Automatic background verification **[PREMIUM ONLY]**
+# Automatic background verification **(PREMIUM ONLY)**
 
 NOTE: **Note:**
 Automatic background verification of repositories and wikis was added in
@@ -143,11 +143,13 @@ If the **primary** and **secondary** nodes have a checksum verification mismatch
 1. On the project admin page get the **Gitaly storage name**, and **Gitaly relative path**:
    ![Project admin page](img/checksum-differences-admin-project-page.png)
 
-1. Navigate to the project's repository directory on both **primary** and **secondary** nodes (the path is usually `/var/opt/gitlab/git-data/repositories`). Note that if `git_data_dirs` is customized, check the directory layout on your server to be sure.
+1. Navigate to the project's repository directory on both **primary** and **secondary** nodes
+   (the path is usually `/var/opt/gitlab/git-data/repositories`). Note that if `git_data_dirs`
+   is customized, check the directory layout on your server to be sure.
 
-    ```sh
-    cd /var/opt/gitlab/git-data/repositories
-    ```
+   ```sh
+   cd /var/opt/gitlab/git-data/repositories
+   ```
 
 1. Run the following command on the **primary** node, redirecting the output to a file:
 
@@ -169,14 +171,21 @@ If the **primary** and **secondary** nodes have a checksum verification mismatch
 
 ## Current limitations
 
-Until [issue #5064][ee-5064] is completed, background verification doesn't cover
-CI job artifacts and traces, LFS objects, or user uploads in file storage.
-Verify their integrity manually by following [these instructions][foreground-verification]
-on both nodes, and comparing the output between them.
+Automatic background verification doesn't cover attachments, LFS objects,
+job artifacts, and user uploads in file storage. You can keep track of the
+progress to include them in [ee-1430]. For now, you can verify their integrity
+manually by following [these instructions][foreground-verification] on both
+nodes, and comparing the output between them.
+
+In GitLab EE 12.1, Geo calculates checksums for attachments, LFS objects and
+archived traces on secondary nodes after the transfer, compares it with the
+stored checksums, and rejects transfers if mismatched. Please note that Geo
+currently does not support an automatic way to verify these data if they have
+been synced before GitLab EE 12.1.
 
 Data in object storage is **not verified**, as the object store is responsible
 for ensuring the integrity of the data.
 
 [reset-verification]: background_verification.md#reset-verification-for-projects-where-verification-has-failed
 [foreground-verification]: ../../raketasks/check.md
-[ee-5064]: https://gitlab.com/gitlab-org/gitlab-ee/issues/5064
+[ee-1430]: https://gitlab.com/groups/gitlab-org/-/epics/1430
diff --git a/doc/administration/geo/disaster_recovery/bring_primary_back.md b/doc/administration/geo/disaster_recovery/bring_primary_back.md
index f4d31a98080..64d7ef2d609 100644
--- a/doc/administration/geo/disaster_recovery/bring_primary_back.md
+++ b/doc/administration/geo/disaster_recovery/bring_primary_back.md
@@ -1,4 +1,4 @@
-# Bring a demoted primary node back online **[PREMIUM ONLY]**
+# Bring a demoted primary node back online **(PREMIUM ONLY)**
 
 After a failover, it is possible to fail back to the demoted **primary** node to
 restore your original configuration. This process consists of two steps:
@@ -21,20 +21,20 @@ To bring the former **primary** node up to date:
 1. SSH into the former **primary** node that has fallen behind.
 1. Make sure all the services are up:
 
-    ```sh
-    sudo gitlab-ctl start
-    ```
-
-    > **Note 1:** If you [disabled the **primary** node permanently][disaster-recovery-disable-primary],
-    > you need to undo those steps now. For Debian/Ubuntu you just need to run
-    > `sudo systemctl enable gitlab-runsvdir`. For CentOS 6, you need to install
-    > the GitLab instance from scratch and set it up as a **secondary** node by
-    > following [Setup instructions][setup-geo]. In this case, you don't need to follow the next step.
-    >
-    > **Note 2:** If you [changed the DNS records](index.md#step-4-optional-updating-the-primary-domain-dns-record)
-    > for this node during disaster recovery procedure you may need to [block
-    > all the writes to this node](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/gitlab-geo/planned-failover.md#block-primary-traffic)
-    > during this procedure.
+   ```sh
+   sudo gitlab-ctl start
+   ```
+
+   NOTE: **Note:** If you [disabled the **primary** node permanently][disaster-recovery-disable-primary],
+   you need to undo those steps now. For Debian/Ubuntu you just need to run
+   `sudo systemctl enable gitlab-runsvdir`. For CentOS 6, you need to install
+   the GitLab instance from scratch and set it up as a **secondary** node by
+   following [Setup instructions][setup-geo]. In this case, you don't need to follow the next step.
+
+   NOTE: **Note:** If you [changed the DNS records](index.md#step-4-optional-updating-the-primary-domain-dns-record)
+   for this node during disaster recovery procedure you may need to [block
+   all the writes to this node](planned_failover.md#prevent-updates-to-the-primary-node)
+   during this procedure.
 
 1. [Setup database replication][database-replication]. Note that in this
    case, **primary** node refers to the current **primary** node, and **secondary** node refers to the
diff --git a/doc/administration/geo/disaster_recovery/img/checksum-differences-admin-project-page.png b/doc/administration/geo/disaster_recovery/img/checksum-differences-admin-project-page.png
index fd51523104b..0a7b841897b 100644
--- a/doc/administration/geo/disaster_recovery/img/checksum-differences-admin-project-page.png
+++ b/doc/administration/geo/disaster_recovery/img/checksum-differences-admin-project-page.png
diff --git a/doc/administration/geo/disaster_recovery/img/checksum-differences-admin-projects.png b/doc/administration/geo/disaster_recovery/img/checksum-differences-admin-projects.png
index b2a6da69d3d..85759d903a4 100644
--- a/doc/administration/geo/disaster_recovery/img/checksum-differences-admin-projects.png
+++ b/doc/administration/geo/disaster_recovery/img/checksum-differences-admin-projects.png
diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md
index 71dc797f281..ba95843b0b0 100644
--- a/doc/administration/geo/disaster_recovery/index.md
+++ b/doc/administration/geo/disaster_recovery/index.md
@@ -1,4 +1,4 @@
-# Disaster Recovery **[PREMIUM ONLY]**
+# Disaster Recovery (Geo) **(PREMIUM ONLY)**
 
 Geo replicates your database, your Git repositories, and few other assets.
 We will support and replicate more data in the future, that will enable you to
@@ -39,48 +39,50 @@ must disable the **primary** node.
 
 1. SSH into the **primary** node to stop and disable GitLab, if possible:
 
-    ```sh
-    sudo gitlab-ctl stop
-    ```
+   ```sh
+   sudo gitlab-ctl stop
+   ```
 
-    Prevent GitLab from starting up again if the server unexpectedly reboots:
+   Prevent GitLab from starting up again if the server unexpectedly reboots:
 
-    ```sh
-    sudo systemctl disable gitlab-runsvdir
-    ```
+   ```sh
+   sudo systemctl disable gitlab-runsvdir
+   ```
 
-    > **CentOS only**: In CentOS 6 or older, there is no easy way to prevent GitLab from being
-    > started if the machine reboots isn't available (see [gitlab-org/omnibus-gitlab#3058]).
-    > It may be safest to uninstall the GitLab package completely:
+   NOTE: **Note:**
+   (**CentOS only**) In CentOS 6 or older, there is no easy way to prevent GitLab from being
+   started if the machine reboots isn't available (see [gitlab-org/omnibus-gitlab#3058]).
+   It may be safest to uninstall the GitLab package completely:
 
-    ```sh
-    yum remove gitlab-ee
-    ```
+   ```sh
+   yum remove gitlab-ee
+   ```
 
-    > **Ubuntu 14.04 LTS**: If you are using an older version of Ubuntu
-    > or any other distro based on the Upstart init system, you can prevent GitLab
-    > from starting if the machine reboots by doing the following:
+   NOTE: **Note:**
+   (**Ubuntu 14.04 LTS**) If you are using an older version of Ubuntu
+   or any other distro based on the Upstart init system, you can prevent GitLab
+   from starting if the machine reboots by doing the following:
 
-    ```sh
-    initctl stop gitlab-runsvvdir
-    echo 'manual' > /etc/init/gitlab-runsvdir.override
-    initctl reload-configuration
-    ```
+   ```sh
+   initctl stop gitlab-runsvvdir
+   echo 'manual' > /etc/init/gitlab-runsvdir.override
+   initctl reload-configuration
+   ```
 
 1. If you do not have SSH access to the **primary** node, take the machine offline and
-    prevent it from rebooting by any means at your disposal.
-    Since there are many ways you may prefer to accomplish this, we will avoid a
-    single recommendation. You may need to:
-      - Reconfigure the load balancers.
-      - Change DNS records (e.g., point the primary DNS record to the **secondary**
-        node in order to stop usage of the **primary** node).
-      - Stop the virtual servers.
-      - Block traffic through a firewall.
-      - Revoke object storage permissions from the **primary** node.
-      - Physically disconnect a machine.
-
-1. If you plan to
-   [update the primary domain DNS record](#step-4-optional-updating-the-primary-domain-dns-record),
+   prevent it from rebooting by any means at your disposal.
+   Since there are many ways you may prefer to accomplish this, we will avoid a
+   single recommendation. You may need to:
+
+   - Reconfigure the load balancers.
+   - Change DNS records (e.g., point the primary DNS record to the **secondary**
+     node in order to stop usage of the **primary** node).
+   - Stop the virtual servers.
+   - Block traffic through a firewall.
+   - Revoke object storage permissions from the **primary** node.
+   - Physically disconnect a machine.
+
+1. If you plan to [update the primary domain DNS record](#step-4-optional-updating-the-primary-domain-dns-record),
    you may wish to lower the TTL now to speed up propagation.
 
 ### Step 3. Promoting a **secondary** node
@@ -94,26 +96,26 @@ the **secondary** to the **primary**.
 
 1. SSH in to your **secondary** node and login as root:
 
-    ```sh
-    sudo -i
-    ```
+   ```sh
+   sudo -i
+   ```
 
 1. Edit `/etc/gitlab/gitlab.rb` to reflect its new status as **primary** by
    removing any lines that enabled the `geo_secondary_role`:
 
-    ```ruby
-    ## In pre-11.5 documentation, the role was enabled as follows. Remove this line.
-    geo_secondary_role['enable'] = true
+   ```ruby
+   ## In pre-11.5 documentation, the role was enabled as follows. Remove this line.
+   geo_secondary_role['enable'] = true
 
-    ## In 11.5+ documentation, the role was enabled as follows. Remove this line.
-    roles ['geo_secondary_role']
-    ```
+   ## In 11.5+ documentation, the role was enabled as follows. Remove this line.
+   roles ['geo_secondary_role']
+   ```
 
 1. Promote the **secondary** node to the **primary** node. Execute:
 
-    ```sh
-    gitlab-ctl promote-to-primary-node
-    ```
+   ```sh
+   gitlab-ctl promote-to-primary-node
+   ```
 
 1. Verify you can connect to the newly promoted **primary** node using the URL used
    previously for the **secondary** node.
@@ -129,31 +131,31 @@ do this manually.
 1. SSH in to the database node in the **secondary** and trigger PostgreSQL to
    promote to read-write:
 
-    ```bash
-    sudo gitlab-pg-ctl promote
-    ```
+   ```bash
+   sudo gitlab-pg-ctl promote
+   ```
 
 1. Edit `/etc/gitlab/gitlab.rb` on every machine in the **secondary** to
    reflect its new status as **primary** by removing any lines that enabled the
    `geo_secondary_role`:
 
-    ```ruby
-    ## In pre-11.5 documentation, the role was enabled as follows. Remove this line.
-    geo_secondary_role['enable'] = true
+   ```ruby
+   ## In pre-11.5 documentation, the role was enabled as follows. Remove this line.
+   geo_secondary_role['enable'] = true
 
-    ## In 11.5+ documentation, the role was enabled as follows. Remove this line.
-    roles ['geo_secondary_role']
-    ```
+   ## In 11.5+ documentation, the role was enabled as follows. Remove this line.
+   roles ['geo_secondary_role']
+   ```
 
-    After making these changes [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) each
-    machine so the changes take effect.
+   After making these changes [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) each
+   machine so the changes take effect.
 
 1. Promote the **secondary** to **primary**. SSH into a single application
    server and execute:
 
-    ```bash
-    sudo gitlab-rake geo:set_secondary_as_primary
-    ```
+   ```bash
+   sudo gitlab-rake geo:set_secondary_as_primary
+   ```
 
 1. Verify you can connect to the newly promoted **primary** using the URL used
    previously for the **secondary**.
@@ -167,37 +169,37 @@ secondary domain, like changing Git remotes and API URLs.
 
 1. SSH into the **secondary** node and login as root:
 
-    ```sh
-    sudo -i
-    ```
+   ```sh
+   sudo -i
+   ```
 
 1. Update the primary domain's DNS record. After updating the primary domain's
    DNS records to point to the **secondary** node, edit `/etc/gitlab/gitlab.rb` on the
    **secondary** node to reflect the new URL:
 
-    ```ruby
-    # Change the existing external_url configuration
-    external_url 'https://<new_external_url>'
-    ```
+   ```ruby
+   # Change the existing external_url configuration
+   external_url 'https://<new_external_url>'
+   ```
 
-    NOTE: **Note**
-    Changing `external_url` won't prevent access via the old secondary URL, as
-    long as the secondary DNS records are still intact.
+   NOTE: **Note**
+   Changing `external_url` won't prevent access via the old secondary URL, as
+   long as the secondary DNS records are still intact.
 
 1. Reconfigure the **secondary** node for the change to take effect:
 
-    ```sh
-    gitlab-ctl reconfigure
-    ```
+   ```sh
+   gitlab-ctl reconfigure
+   ```
 
 1. Execute the command below to update the newly promoted **primary** node URL:
 
-    ```sh
-    gitlab-rake geo:update_primary_node_url
-    ```
+   ```sh
+   gitlab-rake geo:update_primary_node_url
+   ```
 
-    This command will use the changed `external_url` configuration defined
-    in `/etc/gitlab/gitlab.rb`.
+   This command will use the changed `external_url` configuration defined
+   in `/etc/gitlab/gitlab.rb`.
 
 1. Verify you can connect to the newly promoted **primary** using its URL.
    If you updated the DNS records for the primary domain, these changes may
@@ -231,62 +233,61 @@ and after that you also need two extra steps.
 
 1. SSH into the new **primary** node and login as root:
 
-    ```sh
-    sudo -i
-    ```
+   ```sh
+   sudo -i
+   ```
 
 1. Edit `/etc/gitlab/gitlab.rb`
 
-    ```ruby
-    ## Enable a Geo Primary role (if you haven't yet)
-    roles ['geo_primary_role']
+   ```ruby
+   ## Enable a Geo Primary role (if you haven't yet)
+   roles ['geo_primary_role']
 
-    ##
-    # Allow PostgreSQL client authentication from the primary and secondary IPs. These IPs may be
-    # public or VPC addresses in CIDR format, for example ['198.51.100.1/32', '198.51.100.2/32']
-    ##
-    postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32']
+   ##
+   # Allow PostgreSQL client authentication from the primary and secondary IPs. These IPs may be
+   # public or VPC addresses in CIDR format, for example ['198.51.100.1/32', '198.51.100.2/32']
+   ##
+   postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32']
 
-    # Every secondary server needs to have its own slot so specify the number of secondary nodes you're going to have
-    postgresql['max_replication_slots'] = 1
+   # Every secondary server needs to have its own slot so specify the number of secondary nodes you're going to have
+   postgresql['max_replication_slots'] = 1
 
-    ##
-    ## Disable automatic database migrations temporarily
-    ## (until PostgreSQL is restarted and listening on the private address).
-    ##
-    gitlab_rails['auto_migrate'] = false
+   ##
+   ## Disable automatic database migrations temporarily
+   ## (until PostgreSQL is restarted and listening on the private address).
+   ##
+   gitlab_rails['auto_migrate'] = false
+   ```
 
-    ```
-
-    (For more details about these settings you can read [Configure the primary server][configure-the-primary-server])
+   (For more details about these settings you can read [Configure the primary server][configure-the-primary-server])
 
 1. Save the file and reconfigure GitLab for the database listen changes and
    the replication slot changes to be applied.
 
-    ```sh
-    gitlab-ctl reconfigure
-    ```
+   ```sh
+   gitlab-ctl reconfigure
+   ```
 
-    Restart PostgreSQL for its changes to take effect:
+   Restart PostgreSQL for its changes to take effect:
 
-    ```sh
-    gitlab-ctl restart postgresql
-    ```
+   ```sh
+   gitlab-ctl restart postgresql
+   ```
 
 1. Re-enable migrations now that PostgreSQL is restarted and listening on the
    private address.
 
-    Edit `/etc/gitlab/gitlab.rb` and **change** the configuration to `true`:
+   Edit `/etc/gitlab/gitlab.rb` and **change** the configuration to `true`:
 
-    ```ruby
-    gitlab_rails['auto_migrate'] = true
-    ```
+   ```ruby
+   gitlab_rails['auto_migrate'] = true
+   ```
 
-    Save the file and reconfigure GitLab:
+   Save the file and reconfigure GitLab:
 
-    ```sh
-    gitlab-ctl reconfigure
-    ```
+   ```sh
+   gitlab-ctl reconfigure
+   ```
 
 ### Step 2. Initiate the replication process
 
diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md
index b8071b5993f..0c2d48854f0 100644
--- a/doc/administration/geo/disaster_recovery/planned_failover.md
+++ b/doc/administration/geo/disaster_recovery/planned_failover.md
@@ -1,4 +1,4 @@
-# Disaster recovery for planned failover **[PREMIUM ONLY]**
+# Disaster recovery for planned failover **(PREMIUM ONLY)**
 
 The primary use-case of Disaster Recovery is to ensure business continuity in
 the event of unplanned outage, but it can be used in conjunction with a planned
@@ -143,26 +143,26 @@ access to the **primary** node during the maintenance window.
    all HTTP, HTTPS and SSH traffic to/from the **primary** node, **except** for your IP and
    the **secondary** node's IP.
 
-    For instance, you might run the following commands on the server(s) making up your **primary** node:
+   For instance, you might run the following commands on the server(s) making up your **primary** node:
 
-    ```sh
-    sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 22 -j ACCEPT
-    sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 22 -j ACCEPT
-    sudo iptables -A INPUT --destination-port 22 -j REJECT
+   ```sh
+   sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 22 -j ACCEPT
+   sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 22 -j ACCEPT
+   sudo iptables -A INPUT --destination-port 22 -j REJECT
 
-    sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 80 -j ACCEPT
-    sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 80 -j ACCEPT
-    sudo iptables -A INPUT --tcp-dport 80 -j REJECT
+   sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 80 -j ACCEPT
+   sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 80 -j ACCEPT
+   sudo iptables -A INPUT --tcp-dport 80 -j REJECT
 
-    sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 443 -j ACCEPT
-    sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 443 -j ACCEPT
-    sudo iptables -A INPUT --tcp-dport 443 -j REJECT
-    ```
+   sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 443 -j ACCEPT
+   sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 443 -j ACCEPT
+   sudo iptables -A INPUT --tcp-dport 443 -j REJECT
+   ```
 
-    From this point, users will be unable to view their data or make changes on the
-    **primary** node. They will also be unable to log in to the **secondary** node.
-    However, existing sessions will work for the remainder of the maintenance period, and
-    public data will be accessible throughout.
+   From this point, users will be unable to view their data or make changes on the
+   **primary** node. They will also be unable to log in to the **secondary** node.
+   However, existing sessions will work for the remainder of the maintenance period, and
+   public data will be accessible throughout.
 
 1. Verify the **primary** node is blocked to HTTP traffic by visiting it in browser via
    another IP. The server should refuse connection.
@@ -187,10 +187,11 @@ access to the **primary** node during the maintenance window.
    before it is completed will cause the work to be lost.
 1. On the **primary** node, navigate to **Admin Area > Geo** and wait for the
    following conditions to be true of the **secondary** node you are failing over to:
-    - All replication meters to each 100% replicated, 0% failures.
-    - All verification meters reach 100% verified, 0% failures.
-    - Database replication lag is 0ms.
-    - The Geo log cursor is up to date (0 events behind).
+
+   - All replication meters to each 100% replicated, 0% failures.
+   - All verification meters reach 100% verified, 0% failures.
+   - Database replication lag is 0ms.
+   - The Geo log cursor is up to date (0 events behind).
 
 1. On the **secondary** node, navigate to **Admin Area > Monitoring > Background Jobs > Queues**
    and wait for all the `geo` queues to drop to 0 queued and 0 running jobs.
diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md
index 3d4f69d3abe..fd076bb79d8 100644
--- a/doc/administration/geo/replication/configuration.md
+++ b/doc/administration/geo/replication/configuration.md
@@ -1,4 +1,4 @@
-# Geo configuration **[PREMIUM ONLY]**
+# Geo configuration **(PREMIUM ONLY)**
 
 ## Configuring a new **secondary** node
 
@@ -16,11 +16,10 @@ The basic steps of configuring a **secondary** node are to:
 You are encouraged to first read through all the steps before executing them
 in your testing/production environment.
 
-> **Notes:**
-> - **Do not** setup any custom authentication for the **secondary** nodes. This will be
-  handled by the **primary** node.
-> - Any change that requires access to the **Admin Area** needs to be done in the
-  **primary** node because the **secondary** node is a read-only replica.
+NOTE: **Note:**
+**Do not** set up any custom authentication for the **secondary** nodes. This will be handled by the **primary** node.
+Any change that requires access to the **Admin Area** needs to be done in the
+**primary** node because the **secondary** node is a read-only replica.
 
 ### Step 1. Manually replicate secret GitLab values
 
@@ -31,47 +30,47 @@ they must be manually replicated to the **secondary** node.
 
 1. SSH into the **primary** node, and execute the command below:
 
-    ```sh
-    sudo cat /etc/gitlab/gitlab-secrets.json
-    ```
+   ```sh
+   sudo cat /etc/gitlab/gitlab-secrets.json
+   ```
 
-    This will display the secrets that need to be replicated, in JSON format.
+   This will display the secrets that need to be replicated, in JSON format.
 
 1. SSH into the **secondary** node and login as the `root` user:
 
-    ```sh
-    sudo -i
-    ```
+   ```sh
+   sudo -i
+   ```
 
 1. Make a backup of any existing secrets:
 
-    ```sh
-    mv /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.`date +%F`
-    ```
+   ```sh
+   mv /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.`date +%F`
+   ```
 
 1. Copy `/etc/gitlab/gitlab-secrets.json` from the **primary** node to the **secondary** node, or
    copy-and-paste the file contents between nodes:
 
-    ```sh
-    sudo editor /etc/gitlab/gitlab-secrets.json
+   ```sh
+   sudo editor /etc/gitlab/gitlab-secrets.json
 
-    # paste the output of the `cat` command you ran on the primary
-    # save and exit
-    ```
+   # paste the output of the `cat` command you ran on the primary
+   # save and exit
+   ```
 
 1. Ensure the file permissions are correct:
 
-    ```sh
-    chown root:root /etc/gitlab/gitlab-secrets.json
-    chmod 0600 /etc/gitlab/gitlab-secrets.json
-    ```
+   ```sh
+   chown root:root /etc/gitlab/gitlab-secrets.json
+   chmod 0600 /etc/gitlab/gitlab-secrets.json
+   ```
 
 1. Reconfigure the **secondary** node for the change to take effect:
 
-    ```sh
-    gitlab-ctl reconfigure
-    gitlab-ctl restart
-    ```
+   ```sh
+   gitlab-ctl reconfigure
+   gitlab-ctl restart
+   ```
 
 ### Step 2. Manually replicate the **primary** node's SSH host keys
 
@@ -89,80 +88,80 @@ keys must be manually replicated to the **secondary** node.
 
 1. SSH into the **secondary** node and login as the `root` user:
 
-    ```sh
-    sudo -i
-    ```
+   ```sh
+   sudo -i
+   ```
 
 1. Make a backup of any existing SSH host keys:
 
-    ```sh
-    find /etc/ssh -iname ssh_host_* -exec cp {} {}.backup.`date +%F` \;
-    ```
+   ```sh
+   find /etc/ssh -iname ssh_host_* -exec cp {} {}.backup.`date +%F` \;
+   ```
 
 1. Copy OpenSSH host keys from the **primary** node:
 
-    If you can access your **primary** node using the **root** user:
+   If you can access your **primary** node using the **root** user:
 
-    ```sh
-    # Run this from the secondary node, change `<primary_node_fqdn>` for the IP or FQDN of the server
-    scp root@<primary_node_fqdn>:/etc/ssh/ssh_host_*_key* /etc/ssh
-    ```
+   ```sh
+   # Run this from the secondary node, change `<primary_node_fqdn>` for the IP or FQDN of the server
+   scp root@<primary_node_fqdn>:/etc/ssh/ssh_host_*_key* /etc/ssh
+   ```
 
-    If you only have access through a user with **sudo** privileges:
+   If you only have access through a user with **sudo** privileges:
 
-    ```sh
-    # Run this from your primary node:
-    sudo tar --transform 's/.*\///g' -zcvf ~/geo-host-key.tar.gz /etc/ssh/ssh_host_*_key*
+   ```sh
+   # Run this from your primary node:
+   sudo tar --transform 's/.*\///g' -zcvf ~/geo-host-key.tar.gz /etc/ssh/ssh_host_*_key*
 
-    # Run this from your secondary node:
-    scp <user_with_sudo>@<primary_node_fqdn>:geo-host-key.tar.gz .
-    tar zxvf ~/geo-host-key.tar.gz -C /etc/ssh
-    ```
+   # Run this from your secondary node:
+   scp <user_with_sudo>@<primary_node_fqdn>:geo-host-key.tar.gz .
+   tar zxvf ~/geo-host-key.tar.gz -C /etc/ssh
+   ```
 
 1. On your **secondary** node, ensure the file permissions are correct:
 
-    ```sh
-    chown root:root /etc/ssh/ssh_host_*_key*
-    chmod 0600 /etc/ssh/ssh_host_*_key*
-    ```
+   ```sh
+   chown root:root /etc/ssh/ssh_host_*_key*
+   chmod 0600 /etc/ssh/ssh_host_*_key*
+   ```
 
 1. To verify key fingerprint matches, execute the following command on both nodes:
 
-    ```sh
-    for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done
-    ```
+   ```sh
+   for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done
+   ```
 
-    You should get an output similar to this one and they should be identical on both nodes:
+   You should get an output similar to this one and they should be identical on both nodes:
 
-    ```sh
-    1024 SHA256:FEZX2jQa2bcsd/fn/uxBzxhKdx4Imc4raXrHwsbtP0M root@serverhostname (DSA)
-    256 SHA256:uw98R35Uf+fYEQ/UnJD9Br4NXUFPv7JAUln5uHlgSeY root@serverhostname (ECDSA)
-    256 SHA256:sqOUWcraZQKd89y/QQv/iynPTOGQxcOTIXU/LsoPmnM root@serverhostname (ED25519)
-    2048 SHA256:qwa+rgir2Oy86QI+PZi/QVR+MSmrdrpsuH7YyKknC+s root@serverhostname (RSA)
-    ```
+   ```sh
+   1024 SHA256:FEZX2jQa2bcsd/fn/uxBzxhKdx4Imc4raXrHwsbtP0M root@serverhostname (DSA)
+   256 SHA256:uw98R35Uf+fYEQ/UnJD9Br4NXUFPv7JAUln5uHlgSeY root@serverhostname (ECDSA)
+   256 SHA256:sqOUWcraZQKd89y/QQv/iynPTOGQxcOTIXU/LsoPmnM root@serverhostname (ED25519)
+   2048 SHA256:qwa+rgir2Oy86QI+PZi/QVR+MSmrdrpsuH7YyKknC+s root@serverhostname (RSA)
+   ```
 
 1. Verify that you have the correct public keys for the existing private keys:
 
-    ```sh
-    # This will print the fingerprint for private keys:
-    for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done
+   ```sh
+   # This will print the fingerprint for private keys:
+   for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done
 
-    # This will print the fingerprint for public keys:
-    for file in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf $file; done
-    ```
+   # This will print the fingerprint for public keys:
+   for file in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf $file; done
+   ```
 
-    NOTE: **Note**:
-    The output for private keys and public keys command should generate the same fingerprint.
+   NOTE: **Note:**
+   The output for private keys and public keys command should generate the same fingerprint.
 
 1. Restart sshd on your **secondary** node:
 
-    ```sh
-    # Debian or Ubuntu installations
-    sudo service ssh reload
+   ```sh
+   # Debian or Ubuntu installations
+   sudo service ssh reload
 
-    # CentOS installations
-    sudo service sshd reload
-    ```
+   # CentOS installations
+   sudo service sshd reload
+   ```
 
 ### Step 3. Add the **secondary** node
 
@@ -176,22 +175,22 @@ keys must be manually replicated to the **secondary** node.
 1. Click the **Add node** button.
 1. SSH into your GitLab **secondary** server and restart the services:
 
-    ```sh
-    gitlab-ctl restart
-    ```
+   ```sh
+   gitlab-ctl restart
+   ```
 
-    Check if there are any common issue with your Geo setup by running:
+   Check if there are any common issue with your Geo setup by running:
 
-    ```sh
-    gitlab-rake gitlab:geo:check
-    ```
+   ```sh
+   gitlab-rake gitlab:geo:check
+   ```
 
 1. SSH into your **primary** server and login as root to verify the
    **secondary** node is reachable or there are any common issue with your Geo setup:
 
-    ```sh
-    gitlab-rake gitlab:geo:check
-    ```
+   ```sh
+   gitlab-rake gitlab:geo:check
+   ```
 
 Once added to the admin panel and restarted, the **secondary** node will automatically start
 replicating missing data from the **primary** node in a process known as **backfill**.
@@ -243,16 +242,15 @@ node's Geo Nodes dashboard in your browser.
 ![Geo dashboard](img/geo_node_dashboard.png)
 
 If your installation isn't working properly, check the
-[troubleshooting document].
+[troubleshooting document](troubleshooting.md).
 
 The two most obvious issues that can become apparent in the dashboard are:
 
 1. Database replication not working well.
 1. Instance to instance notification not working. In that case, it can be
    something of the following:
-     - You are using a custom certificate or custom CA (see the
-       [troubleshooting document]).
-     - The instance is firewalled (check your firewall rules).
+   - You are using a custom certificate or custom CA (see the [troubleshooting document](troubleshooting.md)).
+   - The instance is firewalled (check your firewall rules).
 
 Please note that disabling a **secondary** node will stop the synchronization process.
 
@@ -304,5 +302,4 @@ See the [troubleshooting document](troubleshooting.md).
 [gitlab-org/gitlab-ee#3789]: https://gitlab.com/gitlab-org/gitlab-ee/issues/3789
 [gitlab-com/infrastructure#2821]: https://gitlab.com/gitlab-com/infrastructure/issues/2821
 [omnibus-ssl]: https://docs.gitlab.com/omnibus/settings/ssl.html
-[troubleshooting document]: troubleshooting.md
 [using-geo]: using_a_geo_server.md
diff --git a/doc/administration/geo/replication/database.md b/doc/administration/geo/replication/database.md
index 1e5a56c3f4e..9272287a4a7 100644
--- a/doc/administration/geo/replication/database.md
+++ b/doc/administration/geo/replication/database.md
@@ -1,4 +1,4 @@
-# Geo database replication **[PREMIUM ONLY]**
+# Geo database replication **(PREMIUM ONLY)**
 
 NOTE: **Note:**
 The following steps are for Omnibus installs only. Using Geo with source-based installs was **deprecated** in GitLab 11.5.
@@ -52,186 +52,188 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
 
 1. SSH into your GitLab **primary** server and login as root:
 
-    ```sh
-    sudo -i
-    ```
+   ```sh
+   sudo -i
+   ```
 
 1. Execute the command below to define the node as **primary** node:
 
-    ```sh
-    gitlab-ctl set-geo-primary-node
-    ```
+   ```sh
+   gitlab-ctl set-geo-primary-node
+   ```
 
-    This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`.
+   This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`.
 
 1. GitLab 10.4 and up only: Do the following to make sure the `gitlab` database user has a password defined:
 
-    Generate a MD5 hash of the desired password:
+   Generate a MD5 hash of the desired password:
 
-    ```sh
-    gitlab-ctl pg-password-md5 gitlab
-    # Enter password: <your_password_here>
-    # Confirm password: <your_password_here>
-    # fca0b89a972d69f00eb3ec98a5838484
-    ```
+   ```sh
+   gitlab-ctl pg-password-md5 gitlab
+   # Enter password: <your_password_here>
+   # Confirm password: <your_password_here>
+   # fca0b89a972d69f00eb3ec98a5838484
+   ```
 
-    Edit `/etc/gitlab/gitlab.rb`:
+   Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab`
-    postgresql['sql_user_password'] = '<md5_hash_of_your_password>'
+   ```ruby
+   # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab`
+   postgresql['sql_user_password'] = '<md5_hash_of_your_password>'
 
-    # Every node that runs Unicorn or Sidekiq needs to have the database
-    # password specified as below. If you have a high-availability setup, this
-    # must be present in all application nodes.
-    gitlab_rails['db_password'] = '<your_password_here>'
-    ```
+   # Every node that runs Unicorn or Sidekiq needs to have the database
+   # password specified as below. If you have a high-availability setup, this
+   # must be present in all application nodes.
+   gitlab_rails['db_password'] = '<your_password_here>'
+   ```
 
 1. Omnibus GitLab already has a [replication user]
    called `gitlab_replicator`. You must set the password for this user manually.
    You will be prompted to enter a password:
 
-    ```sh
-    gitlab-ctl set-replication-password
-    ```
+   ```sh
+   gitlab-ctl set-replication-password
+   ```
 
-    This command will also read the `postgresql['sql_replication_user']` Omnibus
-    setting in case you have changed `gitlab_replicator` username to something
-    else.
+   This command will also read the `postgresql['sql_replication_user']` Omnibus
+   setting in case you have changed `gitlab_replicator` username to something
+   else.
 
-    If you are using an external database not managed by Omnibus GitLab, you need
-    to create the replicator user and define a password to it manually:
+   If you are using an external database not managed by Omnibus GitLab, you need
+   to create the replicator user and define a password to it manually:
 
-    ```sql
-    --- Create a new user 'replicator'
-    CREATE USER gitlab_replicator;
+   ```sql
+   --- Create a new user 'replicator'
+   CREATE USER gitlab_replicator;
 
-    --- Set/change a password and grants replication privilege
-    ALTER USER gitlab_replicator WITH REPLICATION ENCRYPTED PASSWORD '<replication_password>';
-    ```
+   --- Set/change a password and grants replication privilege
+   ALTER USER gitlab_replicator WITH REPLICATION ENCRYPTED PASSWORD '<replication_password>';
+   ```
 
 1. Configure PostgreSQL to listen on network interfaces:
 
-    For security reasons, PostgreSQL does not listen on any network interfaces
-    by default. However, Geo requires the **secondary** node to be able to
-    connect to the **primary** node's database. For this reason, we need the address of
-    each node. Note: For external PostgreSQL instances, see [additional instructions](external_database.md).
-
-    If you are using a cloud provider, you can lookup the addresses for each
-    Geo node through your cloud provider's management console.
-
-    To lookup the address of a Geo node, SSH in to the Geo node and execute:
-
-    ```sh
-    ##
-    ## Private address
-    ##
-    ip route get 255.255.255.255 | awk '{print "Private address:", $NF; exit}'
-
-    ##
-    ## Public address
-    ##
-    echo "External address: $(curl --silent ipinfo.io/ip)"
-    ```
-
-    In most cases, the following addresses will be used to configure GitLab
-    Geo:
-
-    | Configuration                           | Address                                               |
-    |:----------------------------------------|:------------------------------------------------------|
-    | `postgresql['listen_address']`          | **Primary** node's public or VPC private address.     |
-    | `postgresql['md5_auth_cidr_addresses']` | **Secondary** node's public or VPC private addresses. |
-
-    If you are using Google Cloud Platform, SoftLayer, or any other vendor that
-    provides a virtual private cloud (VPC) you can use the **secondary** node's private
-    address (corresponds to "internal address" for Google Cloud Platform) for
-    `postgresql['md5_auth_cidr_addresses']` and `postgresql['listen_address']`.
-
-    The `listen_address` option opens PostgreSQL up to network connections
-    with the interface corresponding to the given address. See [the PostgreSQL
-    documentation][pg-docs-runtime-conn] for more details.
-
-    Depending on your network configuration, the suggested addresses may not
-    be correct. If your **primary** node and **secondary** nodes connect over a local
-    area network, or a virtual network connecting availability zones like
-    [Amazon's VPC](https://aws.amazon.com/vpc/) or [Google's VPC](https://cloud.google.com/vpc/)
-    you should use the **secondary** node's private address for `postgresql['md5_auth_cidr_addresses']`.
-
-    Edit `/etc/gitlab/gitlab.rb` and add the following, replacing the IP
-    addresses with addresses appropriate to your network configuration:
-
-    ```ruby
-    ##
-    ## Geo Primary role
-    ## - configure dependent flags automatically to enable Geo
-    ##
-    roles ['geo_primary_role']
-
-    ##
-    ## Primary address
-    ## - replace '<primary_node_ip>' with the public or VPC address of your Geo primary node
-    ##
-    postgresql['listen_address'] = '<primary_node_ip>'
-
-    ##
-    # Allow PostgreSQL client authentication from the primary and secondary IPs. These IPs may be
-    # public or VPC addresses in CIDR format, for example ['198.51.100.1/32', '198.51.100.2/32']
-    ##
-    postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32']
-
-    ##
-    ## Replication settings
-    ## - set this to be the number of Geo secondary nodes you have
-    ##
-    postgresql['max_replication_slots'] = 1
-    # postgresql['max_wal_senders'] = 10
-    # postgresql['wal_keep_segments'] = 10
-
-    ##
-    ## Disable automatic database migrations temporarily
-    ## (until PostgreSQL is restarted and listening on the private address).
-    ##
-    gitlab_rails['auto_migrate'] = false
-    ```
+   For security reasons, PostgreSQL does not listen on any network interfaces
+   by default. However, Geo requires the **secondary** node to be able to
+   connect to the **primary** node's database. For this reason, we need the address of
+   each node.
+
+   NOTE: **Note:** For external PostgreSQL instances, see [additional instructions](external_database.md).
+
+   If you are using a cloud provider, you can lookup the addresses for each
+   Geo node through your cloud provider's management console.
+
+   To lookup the address of a Geo node, SSH in to the Geo node and execute:
+
+   ```sh
+   ##
+   ## Private address
+   ##
+   ip route get 255.255.255.255 | awk '{print "Private address:", $NF; exit}'
+
+   ##
+   ## Public address
+   ##
+   echo "External address: $(curl --silent ipinfo.io/ip)"
+   ```
+
+   In most cases, the following addresses will be used to configure GitLab
+   Geo:
+
+   | Configuration                           | Address                                               |
+   |:----------------------------------------|:------------------------------------------------------|
+   | `postgresql['listen_address']`          | **Primary** node's public or VPC private address.     |
+   | `postgresql['md5_auth_cidr_addresses']` | **Secondary** node's public or VPC private addresses. |
+
+   If you are using Google Cloud Platform, SoftLayer, or any other vendor that
+   provides a virtual private cloud (VPC) you can use the **secondary** node's private
+   address (corresponds to "internal address" for Google Cloud Platform) for
+   `postgresql['md5_auth_cidr_addresses']` and `postgresql['listen_address']`.
+
+   The `listen_address` option opens PostgreSQL up to network connections
+   with the interface corresponding to the given address. See [the PostgreSQL
+   documentation][pg-docs-runtime-conn] for more details.
+
+   Depending on your network configuration, the suggested addresses may not
+   be correct. If your **primary** node and **secondary** nodes connect over a local
+   area network, or a virtual network connecting availability zones like
+   [Amazon's VPC](https://aws.amazon.com/vpc/) or [Google's VPC](https://cloud.google.com/vpc/)
+   you should use the **secondary** node's private address for `postgresql['md5_auth_cidr_addresses']`.
+
+   Edit `/etc/gitlab/gitlab.rb` and add the following, replacing the IP
+   addresses with addresses appropriate to your network configuration:
+
+   ```ruby
+   ##
+   ## Geo Primary role
+   ## - configure dependent flags automatically to enable Geo
+   ##
+   roles ['geo_primary_role']
+
+   ##
+   ## Primary address
+   ## - replace '<primary_node_ip>' with the public or VPC address of your Geo primary node
+   ##
+   postgresql['listen_address'] = '<primary_node_ip>'
+
+   ##
+   # Allow PostgreSQL client authentication from the primary and secondary IPs. These IPs may be
+   # public or VPC addresses in CIDR format, for example ['198.51.100.1/32', '198.51.100.2/32']
+   ##
+   postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32']
+
+   ##
+   ## Replication settings
+   ## - set this to be the number of Geo secondary nodes you have
+   ##
+   postgresql['max_replication_slots'] = 1
+   # postgresql['max_wal_senders'] = 10
+   # postgresql['wal_keep_segments'] = 10
+
+   ##
+   ## Disable automatic database migrations temporarily
+   ## (until PostgreSQL is restarted and listening on the private address).
+   ##
+   gitlab_rails['auto_migrate'] = false
+   ```
 
 1. Optional: If you want to add another **secondary** node, the relevant setting would look like:
 
-    ```ruby
-    postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32', '<another_secondary_node_ip>/32']
-    ```
+   ```ruby
+   postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32', '<another_secondary_node_ip>/32']
+   ```
 
-    You may also want to edit the `wal_keep_segments` and `max_wal_senders` to
-    match your database replication requirements. Consult the [PostgreSQL -
-    Replication documentation][pg-docs-runtime-replication]
-    for more information.
+   You may also want to edit the `wal_keep_segments` and `max_wal_senders` to
+   match your database replication requirements. Consult the [PostgreSQL -
+   Replication documentation][pg-docs-runtime-replication]
+   for more information.
 
 1. Save the file and reconfigure GitLab for the database listen changes and
    the replication slot changes to be applied:
 
-    ```sh
-    gitlab-ctl reconfigure
-    ```
+   ```sh
+   gitlab-ctl reconfigure
+   ```
 
-    Restart PostgreSQL for its changes to take effect:
+   Restart PostgreSQL for its changes to take effect:
 
-    ```sh
-    gitlab-ctl restart postgresql
-    ```
+   ```sh
+   gitlab-ctl restart postgresql
+   ```
 
 1. Re-enable migrations now that PostgreSQL is restarted and listening on the
    private address.
 
-    Edit `/etc/gitlab/gitlab.rb` and **change** the configuration to `true`:
+   Edit `/etc/gitlab/gitlab.rb` and **change** the configuration to `true`:
 
-    ```ruby
-    gitlab_rails['auto_migrate'] = true
-    ```
+   ```ruby
+   gitlab_rails['auto_migrate'] = true
+   ```
 
-    Save the file and reconfigure GitLab:
+   Save the file and reconfigure GitLab:
 
-    ```sh
-    gitlab-ctl reconfigure
-    ```
+   ```sh
+   gitlab-ctl reconfigure
+   ```
 
 1. Now that the PostgreSQL server is set up to accept remote connections, run
    `netstat -plnt | grep 5432` to make sure that PostgreSQL is listening on port
@@ -241,143 +243,143 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
    will be used automatically to protect your PostgreSQL traffic from
    eavesdroppers, but to protect against active ("man-in-the-middle") attackers,
    the **secondary** node needs a copy of the certificate. Make a copy of the PostgreSQL
-    `server.crt` file on the **primary** node by running this command:
+   `server.crt` file on the **primary** node by running this command:
 
-    ```sh
-    cat ~gitlab-psql/data/server.crt
-    ```
+   ```sh
+   cat ~gitlab-psql/data/server.crt
+   ```
 
-    Copy the output into a clipboard or into a local file. You
-    will need it when setting up the **secondary** node! The certificate is not sensitive
-    data.
+   Copy the output into a clipboard or into a local file. You
+   will need it when setting up the **secondary** node! The certificate is not sensitive
+   data.
 
 ### Step 2. Configure the **secondary** server
 
 1. SSH into your GitLab **secondary** server and login as root:
 
-    ```
-    sudo -i
-    ```
+   ```
+   sudo -i
+   ```
 
 1. Stop application server and Sidekiq
 
-    ```
-    gitlab-ctl stop unicorn
-    gitlab-ctl stop sidekiq
-    ```
+   ```
+   gitlab-ctl stop unicorn
+   gitlab-ctl stop sidekiq
+   ```
 
-    NOTE: **Note**:
-    This step is important so we don't try to execute anything before the node is fully configured.
+   NOTE: **Note:**
+   This step is important so we don't try to execute anything before the node is fully configured.
 
 1. [Check TCP connectivity][rake-maintenance] to the **primary** node's PostgreSQL server:
 
-    ```sh
-    gitlab-rake gitlab:tcp_check[<primary_node_ip>,5432]
-    ```
+   ```sh
+   gitlab-rake gitlab:tcp_check[<primary_node_ip>,5432]
+   ```
 
-    NOTE: **Note**:
-    If this step fails, you may be using the wrong IP address, or a firewall may
-    be preventing access to the server. Check the IP address, paying close
-    attention to the difference between public and private addresses and ensure
-    that, if a firewall is present, the **secondary** node is permitted to connect to the
-    **primary** node on port 5432.
+   NOTE: **Note:**
+   If this step fails, you may be using the wrong IP address, or a firewall may
+   be preventing access to the server. Check the IP address, paying close
+   attention to the difference between public and private addresses and ensure
+   that, if a firewall is present, the **secondary** node is permitted to connect to the
+   **primary** node on port 5432.
 
 1. Create a file `server.crt` in the **secondary** server, with the content you got on the last step of the **primary** node's setup:
 
-    ```
-    editor server.crt
-    ```
+   ```
+   editor server.crt
+   ```
 
 1. Set up PostgreSQL TLS verification on the **secondary** node:
 
-    Install the `server.crt` file:
+   Install the `server.crt` file:
 
-    ```sh
-    install \
-       -D \
-       -o gitlab-psql \
-       -g gitlab-psql \
-       -m 0400 \
-       -T server.crt ~gitlab-psql/.postgresql/root.crt
-    ```
+   ```sh
+   install \
+      -D \
+      -o gitlab-psql \
+      -g gitlab-psql \
+      -m 0400 \
+      -T server.crt ~gitlab-psql/.postgresql/root.crt
+   ```
 
-    PostgreSQL will now only recognize that exact certificate when verifying TLS
-    connections. The certificate can only be replicated by someone with access
-    to the private key, which is **only** present on the **primary** node.
+   PostgreSQL will now only recognize that exact certificate when verifying TLS
+   connections. The certificate can only be replicated by someone with access
+   to the private key, which is **only** present on the **primary** node.
 
 1. Test that the `gitlab-psql` user can connect to the **primary** node's database
    (the default Omnibus database name is gitlabhq_production):
 
-    ```sh
-    sudo \
-       -u gitlab-psql /opt/gitlab/embedded/bin/psql \
-       --list \
-       -U gitlab_replicator \
-       -d "dbname=gitlabhq_production sslmode=verify-ca" \
-       -W \
-       -h <primary_node_ip>
-    ```
+   ```sh
+   sudo \
+      -u gitlab-psql /opt/gitlab/embedded/bin/psql \
+      --list \
+      -U gitlab_replicator \
+      -d "dbname=gitlabhq_production sslmode=verify-ca" \
+      -W \
+      -h <primary_node_ip>
+   ```
 
-    When prompted enter the password you set in the first step for the
-    `gitlab_replicator` user. If all worked correctly, you should see
-    the list of **primary** node's databases.
+   When prompted enter the password you set in the first step for the
+   `gitlab_replicator` user. If all worked correctly, you should see
+   the list of **primary** node's databases.
 
-    A failure to connect here indicates that the TLS configuration is incorrect.
-    Ensure that the contents of `~gitlab-psql/data/server.crt` on the **primary** node
-    match the contents of `~gitlab-psql/.postgresql/root.crt` on the **secondary** node.
+   A failure to connect here indicates that the TLS configuration is incorrect.
+   Ensure that the contents of `~gitlab-psql/data/server.crt` on the **primary** node
+   match the contents of `~gitlab-psql/.postgresql/root.crt` on the **secondary** node.
 
 1. Configure PostgreSQL to enable FDW support:
 
-    This step is similar to how we configured the **primary** instance.
-    We need to enable this, to enable FDW support, even if using a single node.
-
-    Edit `/etc/gitlab/gitlab.rb` and add the following, replacing the IP
-    addresses with addresses appropriate to your network configuration:
-
-    ```ruby
-    ##
-    ## Geo Secondary role
-    ## - configure dependent flags automatically to enable Geo
-    ##
-    roles ['geo_secondary_role']
-
-    ##
-    ## Secondary address
-    ## - replace '<secondary_node_ip>' with the public or VPC address of your Geo secondary node
-    ##
-    postgresql['listen_address'] = '<secondary_node_ip>'
-    postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32']
-
-    ##
-    ## Database credentials password (defined previously in primary node)
-    ## - replicate same values here as defined in primary node
-    ##
-    postgresql['sql_user_password'] = '<md5_hash_of_your_password>'
-    gitlab_rails['db_password'] = '<your_password_here>'
-
-    ##
-    ## Enable FDW support for the Geo Tracking Database (improves performance)
-    ##
-    geo_secondary['db_fdw'] = true
-    ```
-
-    For external PostgreSQL instances, see [additional instructions](external_database.md).
-    If you bring a former **primary** node back online to serve as a **secondary** node, then you also need to remove `roles ['geo_primary_role']` or `geo_primary_role['enable'] = true`.
+   This step is similar to how we configured the **primary** instance.
+   We need to enable this, to enable FDW support, even if using a single node.
+
+   Edit `/etc/gitlab/gitlab.rb` and add the following, replacing the IP
+   addresses with addresses appropriate to your network configuration:
+
+   ```ruby
+   ##
+   ## Geo Secondary role
+   ## - configure dependent flags automatically to enable Geo
+   ##
+   roles ['geo_secondary_role']
+
+   ##
+   ## Secondary address
+   ## - replace '<secondary_node_ip>' with the public or VPC address of your Geo secondary node
+   ##
+   postgresql['listen_address'] = '<secondary_node_ip>'
+   postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32']
+
+   ##
+   ## Database credentials password (defined previously in primary node)
+   ## - replicate same values here as defined in primary node
+   ##
+   postgresql['sql_user_password'] = '<md5_hash_of_your_password>'
+   gitlab_rails['db_password'] = '<your_password_here>'
+
+   ##
+   ## Enable FDW support for the Geo Tracking Database (improves performance)
+   ##
+   geo_secondary['db_fdw'] = true
+   ```
+
+   For external PostgreSQL instances, see [additional instructions](external_database.md).
+   If you bring a former **primary** node back online to serve as a **secondary** node, then you also need to remove `roles ['geo_primary_role']` or `geo_primary_role['enable'] = true`.
 
 1. Reconfigure GitLab for the changes to take effect:
 
-    ```sh
-    gitlab-ctl reconfigure
-    ```
+   ```sh
+   gitlab-ctl reconfigure
+   ```
 
 1. Restart PostgreSQL for the IP change to take effect and reconfigure again:
 
-    ```sh
-    gitlab-ctl restart postgresql
-    gitlab-ctl reconfigure
-    ```
+   ```sh
+   gitlab-ctl restart postgresql
+   gitlab-ctl reconfigure
+   ```
 
-    This last reconfigure will provision the FDW configuration and enable it.
+   This last reconfigure will provision the FDW configuration and enable it.
 
 ### Step 3. Initiate the replication process
 
@@ -394,9 +396,9 @@ data before running `pg_basebackup`.
 
 1. SSH into your GitLab **secondary** server and login as root:
 
-    ```sh
-    sudo -i
-    ```
+   ```sh
+   sudo -i
+   ```
 
 1. Choose a database-friendly name to use for your **secondary** node to
    use as the replication slot name. For example, if your domain is
@@ -404,38 +406,40 @@ data before running `pg_basebackup`.
    name as shown in the commands below.
 
 1. Execute the command below to start a backup/restore and begin the replication
-    CAUTION: **Warning:** Each Geo **secondary** node must have its own unique replication slot name.
-    Using the same slot name between two secondaries will break PostgreSQL replication.
-
-    ```sh
-    gitlab-ctl replicate-geo-database \
-       --slot-name=<secondary_node_name> \
-       --host=<primary_node_ip>
-    ```
-
-    When prompted, enter the _plaintext_ password you set up for the `gitlab_replicator`
-    user in the first step.
-
-    This command also takes a number of additional options. You can use `--help`
-    to list them all, but here are a couple of tips:
-     - If PostgreSQL is listening on a non-standard port, add `--port=` as well.
-     - If your database is too large to be transferred in 30 minutes, you will need
-       to increase the timeout, e.g., `--backup-timeout=3600` if you expect the
-       initial replication to take under an hour.
-     - Pass `--sslmode=disable` to skip PostgreSQL TLS authentication altogether
-       (e.g., you know the network path is secure, or you are using a site-to-site
-       VPN). This is **not** safe over the public Internet!
-     - You can read more details about each `sslmode` in the
-       [PostgreSQL documentation][pg-docs-ssl];
-       the instructions above are carefully written to ensure protection against
-       both passive eavesdroppers and active "man-in-the-middle" attackers.
-     - Change the `--slot-name` to the name of the replication slot
-       to be used on the **primary** database. The script will attempt to create the
-       replication slot automatically if it does not exist.
-     - If you're repurposing an old server into a Geo **secondary** node, you'll need to
-       add `--force` to the command line.
-     - When not in a production machine you can disable backup step if you
-       really sure this is what you want by adding `--skip-backup`
+
+   CAUTION: **Warning:** Each Geo **secondary** node must have its own unique replication slot name.
+   Using the same slot name between two secondaries will break PostgreSQL replication.
+
+   ```sh
+   gitlab-ctl replicate-geo-database \
+      --slot-name=<secondary_node_name> \
+      --host=<primary_node_ip>
+   ```
+
+   When prompted, enter the _plaintext_ password you set up for the `gitlab_replicator`
+   user in the first step.
+
+   This command also takes a number of additional options. You can use `--help`
+   to list them all, but here are a couple of tips:
+
+   - If PostgreSQL is listening on a non-standard port, add `--port=` as well.
+   - If your database is too large to be transferred in 30 minutes, you will need
+     to increase the timeout, e.g., `--backup-timeout=3600` if you expect the
+     initial replication to take under an hour.
+   - Pass `--sslmode=disable` to skip PostgreSQL TLS authentication altogether
+     (e.g., you know the network path is secure, or you are using a site-to-site
+     VPN). This is **not** safe over the public Internet!
+   - You can read more details about each `sslmode` in the
+     [PostgreSQL documentation][pg-docs-ssl];
+     the instructions above are carefully written to ensure protection against
+     both passive eavesdroppers and active "man-in-the-middle" attackers.
+   - Change the `--slot-name` to the name of the replication slot
+     to be used on the **primary** database. The script will attempt to create the
+     replication slot automatically if it does not exist.
+   - If you're repurposing an old server into a Geo **secondary** node, you'll need to
+     add `--force` to the command line.
+   - When not in a production machine you can disable backup step if you
+     really sure this is what you want by adding `--skip-backup`
 
 The replication process is now complete.
 
@@ -452,46 +456,42 @@ it will need a separate read-only user to make [PostgreSQL FDW queries][FDW]
 work:
 
 1. On the **primary** Geo database, enter the PostgreSQL on the console as an
-    admin user. If you are using an Omnibus-managed database, log onto the **primary**
-    node that is running the PostgreSQL database (the default Omnibus database name is gitlabhq_production):
+   admin user. If you are using an Omnibus-managed database, log onto the **primary**
+   node that is running the PostgreSQL database (the default Omnibus database name is gitlabhq_production):
 
-    ```sh
-     sudo \
-        -u gitlab-psql /opt/gitlab/embedded/bin/psql \
-        -h /var/opt/gitlab/postgresql gitlabhq_production
-    ```
+   ```sh
+    sudo \
+       -u gitlab-psql /opt/gitlab/embedded/bin/psql \
+       -h /var/opt/gitlab/postgresql gitlabhq_production
+   ```
 
 1. Then create the read-only user:
 
-    ```sql
-    -- NOTE: Use the password defined earlier
-    CREATE USER gitlab_geo_fdw WITH password 'mypassword';
-    GRANT CONNECT ON DATABASE gitlabhq_production to gitlab_geo_fdw;
-    GRANT USAGE ON SCHEMA public TO gitlab_geo_fdw;
-    GRANT SELECT ON ALL TABLES IN SCHEMA public TO gitlab_geo_fdw;
-    GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO gitlab_geo_fdw;
+   ```sql
+   -- NOTE: Use the password defined earlier
+   CREATE USER gitlab_geo_fdw WITH password 'mypassword';
+   GRANT CONNECT ON DATABASE gitlabhq_production to gitlab_geo_fdw;
+   GRANT USAGE ON SCHEMA public TO gitlab_geo_fdw;
+   GRANT SELECT ON ALL TABLES IN SCHEMA public TO gitlab_geo_fdw;
+   GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO gitlab_geo_fdw;
 
-    -- Tables created by "gitlab" should be made read-only for "gitlab_geo_fdw"
-    -- automatically.
-    ALTER DEFAULT PRIVILEGES FOR USER gitlab IN SCHEMA public GRANT SELECT ON TABLES TO gitlab_geo_fdw;
-    ALTER DEFAULT PRIVILEGES FOR USER gitlab IN SCHEMA public GRANT SELECT ON SEQUENCES TO gitlab_geo_fdw;
-    ```
+   -- Tables created by "gitlab" should be made read-only for "gitlab_geo_fdw"
+   -- automatically.
+   ALTER DEFAULT PRIVILEGES FOR USER gitlab IN SCHEMA public GRANT SELECT ON TABLES TO gitlab_geo_fdw;
+   ALTER DEFAULT PRIVILEGES FOR USER gitlab IN SCHEMA public GRANT SELECT ON SEQUENCES TO gitlab_geo_fdw;
+   ```
 
 1. On the **secondary** nodes, change `/etc/gitlab/gitlab.rb`:
 
-    ```
-    geo_postgresql['fdw_external_user'] = 'gitlab_geo_fdw'
-    ```
+   ```
+   geo_postgresql['fdw_external_user'] = 'gitlab_geo_fdw'
+   ```
 
 1. Save the file and reconfigure GitLab for the changes to be applied:
 
-    ```sh
-    gitlab-ctl reconfigure
-    ```
-
-## MySQL replication
-
-MySQL replication is not supported for Geo.
+   ```sh
+   gitlab-ctl reconfigure
+   ```
 
 ## Troubleshooting
 
diff --git a/doc/administration/geo/replication/docker_registry.md b/doc/administration/geo/replication/docker_registry.md
index 5b02b861c61..d5c2d2362b1 100644
--- a/doc/administration/geo/replication/docker_registry.md
+++ b/doc/administration/geo/replication/docker_registry.md
@@ -1,4 +1,4 @@
-# Docker Registry for a secondary node **[PREMIUM ONLY]**
+# Docker Registry for a secondary node **(PREMIUM ONLY)**
 
 You can set up a [Docker Registry] on your
 **secondary** Geo node that mirrors the one on the **primary** Geo node.
diff --git a/doc/administration/geo/replication/external_database.md b/doc/administration/geo/replication/external_database.md
index 177ca68613e..256195998a7 100644
--- a/doc/administration/geo/replication/external_database.md
+++ b/doc/administration/geo/replication/external_database.md
@@ -1,10 +1,10 @@
-# Geo with external PostgreSQL instances **[PREMIUM ONLY]**
+# Geo with external PostgreSQL instances **(PREMIUM ONLY)**
 
 This document is relevant if you are using a PostgreSQL instance that is *not
 managed by Omnibus*. This includes cloud-managed instances like AWS RDS, or
 manually installed and configured PostgreSQL instances.
 
-NOTE: **Note**:
+NOTE: **Note:**
 We strongly recommend running Omnibus-managed instances as they are actively
 developed and tested. We aim to be compatible with most external
 (not managed by Omnibus) databases but we do not guarantee compatibility.
@@ -13,18 +13,17 @@ developed and tested. We aim to be compatible with most external
 
 1. SSH into a GitLab **primary** application server and login as root:
 
-    ```sh
-    sudo -i
-    ```
+   ```sh
+   sudo -i
+   ```
 
 1. Execute the command below to define the node as **primary** node:
 
-    ```sh
-    gitlab-ctl set-geo-primary-node
-    ```
-
-    This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`.
+   ```sh
+   gitlab-ctl set-geo-primary-node
+   ```
 
+   This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`.
 
 ### Configure the external database to be replicated
 
@@ -101,26 +100,27 @@ To configure the connection to the external read-replica database and enable Log
 
 1. SSH into a GitLab **secondary** application server and login as root:
 
-    ```bash
-    sudo -i
-    ```
+   ```bash
+   sudo -i
+   ```
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the following
 
-    ```ruby
-    ##
-    ## Geo Secondary role
-    ## - configure dependent flags automatically to enable Geo
-    ##
-    roles ['geo_secondary_role']
+   ```ruby
+   ##
+   ## Geo Secondary role
+   ## - configure dependent flags automatically to enable Geo
+   ##
+   roles ['geo_secondary_role']
+
+   # note this is shared between both databases,
+   # make sure you define the same password in both
+   gitlab_rails['db_password'] = '<your_password_here>'
 
-    # note this is shared between both databases,
-    # make sure you define the same password in both
-    gitlab_rails['db_password'] = '<your_password_here>'
+   gitlab_rails['db_username'] = 'gitlab'
+   gitlab_rails['db_host'] = '<database_read_replica_host>'
+   ```
 
-    gitlab_rails['db_username'] = 'gitlab'
-    gitlab_rails['db_host'] = '<database_read_replica_host>'
-    ```
 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure)
 
 ### Configure the tracking database
@@ -147,73 +147,72 @@ the tracking database on port 5432.
 
 1. SSH into a GitLab **secondary** server and login as root:
 
-    ```bash
-    sudo -i
-    ```
+   ```bash
+   sudo -i
+   ```
 
 1. Edit `/etc/gitlab/gitlab.rb` with the connection params and credentials for
-    the machine with the PostgreSQL instance:
+   the machine with the PostgreSQL instance:
 
-    ```ruby
-    geo_secondary['db_username'] = 'gitlab_geo'
-    geo_secondary['db_password'] = '<your_password_here>'
+   ```ruby
+   geo_secondary['db_username'] = 'gitlab_geo'
+   geo_secondary['db_password'] = '<your_password_here>'
 
-    geo_secondary['db_host'] = '<tracking_database_host>'
-    geo_secondary['db_port'] = <tracking_database_port>      # change to the correct port
-    geo_secondary['db_fdw'] = true       # enable FDW
-    geo_postgresql['enable'] = false     # don't use internal managed instance
-    ```
+   geo_secondary['db_host'] = '<tracking_database_host>'
+   geo_secondary['db_port'] = <tracking_database_port>      # change to the correct port
+   geo_secondary['db_fdw'] = true       # enable FDW
+   geo_postgresql['enable'] = false     # don't use internal managed instance
+   ```
 
 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure)
 
 1. Run the tracking database migrations:
 
-    ```bash
-    gitlab-rake geo:db:create
-    gitlab-rake geo:db:migrate
-    ```
-
-1. Configure the
-    [PostgreSQL FDW](https://www.postgresql.org/docs/9.6/static/postgres-fdw.html)
-    connection and credentials:
-
-    Save the script below in a file, ex. `/tmp/geo_fdw.sh` and modify the connection
-    params to match your environment. Execute it to set up the FDW connection.
-
-    ```bash
-    #!/bin/bash
-
-    # Secondary Database connection params:
-    DB_HOST="<public_ip_or_vpc_private_ip>"
-    DB_NAME="gitlabhq_production"
-    DB_USER="gitlab"
-    DB_PASS="<your_password_here>"
-    DB_PORT="5432"
-
-    # Tracking Database connection params:
-    GEO_DB_HOST="<public_ip_or_vpc_private_ip>"
-    GEO_DB_NAME="gitlabhq_geo_production"
-    GEO_DB_USER="gitlab_geo"
-    GEO_DB_PORT="5432"
-
-    query_exec () {
-      gitlab-psql -h $GEO_DB_HOST -d $GEO_DB_NAME -p $GEO_DB_PORT -c "${1}"
-    }
-
-    query_exec "CREATE EXTENSION postgres_fdw;"
-    query_exec "CREATE SERVER gitlab_secondary FOREIGN DATA WRAPPER postgres_fdw OPTIONS (host '${DB_HOST}', dbname '${DB_NAME}', port '${DB_PORT}');"
-    query_exec "CREATE USER MAPPING FOR ${GEO_DB_USER} SERVER gitlab_secondary OPTIONS (user '${DB_USER}', password '${DB_PASS}');"
-    query_exec "CREATE SCHEMA gitlab_secondary;"
-    query_exec "GRANT USAGE ON FOREIGN SERVER gitlab_secondary TO ${GEO_DB_USER};"
-    ```
-
-    NOTE: **Note:** The script template above uses `gitlab-psql` as it's intended to be executed from the Geo machine,
-    but you can change it to `psql` and run it from any machine that has access to the database. We also recommend using
-    `psql` for AWS RDS.
+   ```bash
+   gitlab-rake geo:db:create
+   gitlab-rake geo:db:migrate
+   ```
+
+1. Configure the [PostgreSQL FDW](https://www.postgresql.org/docs/9.6/static/postgres-fdw.html)
+   connection and credentials:
+
+   Save the script below in a file, ex. `/tmp/geo_fdw.sh` and modify the connection
+   params to match your environment. Execute it to set up the FDW connection.
+
+   ```bash
+   #!/bin/bash
+
+   # Secondary Database connection params:
+   DB_HOST="<public_ip_or_vpc_private_ip>"
+   DB_NAME="gitlabhq_production"
+   DB_USER="gitlab"
+   DB_PASS="<your_password_here>"
+   DB_PORT="5432"
+
+   # Tracking Database connection params:
+   GEO_DB_HOST="<public_ip_or_vpc_private_ip>"
+   GEO_DB_NAME="gitlabhq_geo_production"
+   GEO_DB_USER="gitlab_geo"
+   GEO_DB_PORT="5432"
+
+   query_exec () {
+     gitlab-psql -h $GEO_DB_HOST -d $GEO_DB_NAME -p $GEO_DB_PORT -c "${1}"
+   }
+
+   query_exec "CREATE EXTENSION postgres_fdw;"
+   query_exec "CREATE SERVER gitlab_secondary FOREIGN DATA WRAPPER postgres_fdw OPTIONS (host '${DB_HOST}', dbname '${DB_NAME}', port '${DB_PORT}');"
+   query_exec "CREATE USER MAPPING FOR ${GEO_DB_USER} SERVER gitlab_secondary OPTIONS (user '${DB_USER}', password '${DB_PASS}');"
+   query_exec "CREATE SCHEMA gitlab_secondary;"
+   query_exec "GRANT USAGE ON FOREIGN SERVER gitlab_secondary TO ${GEO_DB_USER};"
+   ```
+
+   NOTE: **Note:** The script template above uses `gitlab-psql` as it's intended to be executed from the Geo machine,
+   but you can change it to `psql` and run it from any machine that has access to the database. We also recommend using
+   `psql` for AWS RDS.
 
 1. Save the file and [restart GitLab](../../restart_gitlab.md#omnibus-gitlab-restart)
 1. Populate the FDW tables:
 
-    ```bash
-    gitlab-rake geo:db:refresh_foreign_tables
-    ```
+   ```bash
+   gitlab-rake geo:db:refresh_foreign_tables
+   ```
diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md
index dd1af0dbf9c..b3580a706c3 100644
--- a/doc/administration/geo/replication/faq.md
+++ b/doc/administration/geo/replication/faq.md
@@ -1,4 +1,4 @@
-# Geo Frequently Asked Questions **[PREMIUM ONLY]**
+# Geo Frequently Asked Questions **(PREMIUM ONLY)**
 
 ## What are the minimum requirements to run Geo?
 
@@ -6,8 +6,8 @@ The requirements are listed [on the index page](index.md#requirements-for-runnin
 
 ## How does Geo know which projects to sync?
 
-On each **secondary** node, there is a read-only replicated copy of the GitLab database. 
-A **secondary** node also has a tracking database where it stores which projects have been synced. 
+On each **secondary** node, there is a read-only replicated copy of the GitLab database.
+A **secondary** node also has a tracking database where it stores which projects have been synced.
 Geo compares the two databases to find projects that are not yet tracked.
 
 At the start, this tracking database is empty, so Geo will start trying to update from every project that it can see in the GitLab database.
@@ -15,19 +15,19 @@ At the start, this tracking database is empty, so Geo will start trying to updat
 For each project to sync:
 
 1. Geo will issue a `git fetch geo --mirror` to get the latest information from the **primary** node.
-If there are no changes, the sync will be fast and end quickly. Otherwise, it will pull the latest commits.
+   If there are no changes, the sync will be fast and end quickly. Otherwise, it will pull the latest commits.
 1. The **secondary** node will update the tracking database to store the fact that it has synced projects A, B, C, etc.
 1. Repeat until all projects are synced.
 
-When someone pushes a commit to the **primary** node, it generates an event in the GitLab database that the repository has changed. 
+When someone pushes a commit to the **primary** node, it generates an event in the GitLab database that the repository has changed.
 The **secondary** node sees this event, marks the project in question as dirty, and schedules the project to be resynced.
 
 To ensure that problems with pipelines (for example, syncs failing too many times or jobs being lost) don't permanently stop projects syncing, Geo also periodically checks the tracking database for projects that are marked as dirty. This check happens when
-the number of concurrent syncs falls below `repos_max_capacity` and there are no new projects waiting to be synced. 
+the number of concurrent syncs falls below `repos_max_capacity` and there are no new projects waiting to be synced.
 
-Geo also has a checksum feature which runs a SHA256 sum across all the Git references to the SHA values. 
-If the refs don't match between the **primary** node and the **secondary** node, then the **secondary** node will mark that project as dirty and try to resync it. 
-So even if we have an outdated tracking database, the validation should activate and find discrepancies in the repository state and resync.   
+Geo also has a checksum feature which runs a SHA256 sum across all the Git references to the SHA values.
+If the refs don't match between the **primary** node and the **secondary** node, then the **secondary** node will mark that project as dirty and try to resync it.
+So even if we have an outdated tracking database, the validation should activate and find discrepancies in the repository state and resync.
 
 ## Can I use Geo in a disaster recovery situation?
 
diff --git a/doc/administration/geo/replication/high_availability.md b/doc/administration/geo/replication/high_availability.md
index 921a3ef1c7a..c737fa37077 100644
--- a/doc/administration/geo/replication/high_availability.md
+++ b/doc/administration/geo/replication/high_availability.md
@@ -1,4 +1,4 @@
-# Geo High Availability **[PREMIUM ONLY]**
+# Geo High Availability **(PREMIUM ONLY)**
 
 This document describes a minimal reference architecture for running Geo
 in a high availability configuration. If your HA setup differs from the one
@@ -50,17 +50,17 @@ The following steps enable a GitLab cluster to serve as the **primary** node.
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the following:
 
-    ```ruby
-    ##
-    ## Enable the Geo primary role
-    ##
-    roles ['geo_primary_role']
+   ```ruby
+   ##
+   ## Enable the Geo primary role
+   ##
+   roles ['geo_primary_role']
 
-    ##
-    ## Disable automatic migrations
-    ##
-    gitlab_rails['auto_migrate'] = false
-    ```
+   ##
+   ## Disable automatic migrations
+   ##
+   gitlab_rails['auto_migrate'] = false
+   ```
 
 After making these changes, [reconfigure GitLab][gitlab-reconfigure] so the changes take effect.
 
@@ -79,9 +79,9 @@ The **primary** database will require modification later, as part of
 A **secondary** cluster is similar to any other GitLab HA cluster, with two
 major differences:
 
-* The main PostgreSQL database is a read-only replica of the **primary** node's
+- The main PostgreSQL database is a read-only replica of the **primary** node's
   PostgreSQL database.
-* There is also a single PostgreSQL database for the **secondary** cluster,
+- There is also a single PostgreSQL database for the **secondary** cluster,
   called the "tracking database", which tracks the synchronization state of
   various resources.
 
@@ -93,9 +93,9 @@ from the normal HA setup.
 Configure the following services, again using the non-Geo high availability
 documentation:
 
-* [Configuring Redis for GitLab HA](../../high_availability/redis.md) for high
+- [Configuring Redis for GitLab HA](../../high_availability/redis.md) for high
   availability.
-* [NFS](../../high_availability/nfs.md) which will store data that is
+- [NFS](../../high_availability/nfs.md) which will store data that is
   synchronized from the **primary** node.
 
 ### Step 2: Configure the main read-only replica PostgreSQL database on the **secondary** node
@@ -107,36 +107,36 @@ Configure the [**secondary** database](database.md) as a read-only replica of
 the **primary** database. Use the following as a guide.
 
 1. Edit `/etc/gitlab/gitlab.rb` in the replica database machine, and add the
-    following:
-
-    ```ruby
-    ##
-    ## Configure the PostgreSQL role
-    ##
-    roles ['postgres_role']
-
-    ##
-    ## Secondary address
-    ## - replace '<secondary_node_ip>' with the public or VPC address of your Geo secondary node
-    ## - replace '<tracking_database_ip>' with the public or VPC address of your Geo tracking database node
-    ##
-    postgresql['listen_address'] = '<secondary_node_ip>'
-    postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32', '<tracking_database_ip>/32']
-
-    ##
-    ## Database credentials password (defined previously in primary node)
-    ## - replicate same values here as defined in primary node
-    ##
-    postgresql['sql_user_password'] = '<md5_hash_of_your_password>'
-    gitlab_rails['db_password'] = '<your_password_here>'
-
-    ##
-    ## When running the Geo tracking database on a separate machine, disable it
-    ## here and allow connections from the tracking database host. And ensure
-    ## the tracking database IP is in postgresql['md5_auth_cidr_addresses'] above.
-    ##
-    geo_postgresql['enable'] = false
-    ```
+   following:
+
+   ```ruby
+   ##
+   ## Configure the PostgreSQL role
+   ##
+   roles ['postgres_role']
+
+   ##
+   ## Secondary address
+   ## - replace '<secondary_node_ip>' with the public or VPC address of your Geo secondary node
+   ## - replace '<tracking_database_ip>' with the public or VPC address of your Geo tracking database node
+   ##
+   postgresql['listen_address'] = '<secondary_node_ip>'
+   postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32', '<tracking_database_ip>/32']
+
+   ##
+   ## Database credentials password (defined previously in primary node)
+   ## - replicate same values here as defined in primary node
+   ##
+   postgresql['sql_user_password'] = '<md5_hash_of_your_password>'
+   gitlab_rails['db_password'] = '<your_password_here>'
+
+   ##
+   ## When running the Geo tracking database on a separate machine, disable it
+   ## here and allow connections from the tracking database host. And ensure
+   ## the tracking database IP is in postgresql['md5_auth_cidr_addresses'] above.
+   ##
+   geo_postgresql['enable'] = false
+   ```
 
 After making these changes, [reconfigure GitLab][gitlab-reconfigure] so the changes take effect.
 
@@ -151,47 +151,47 @@ only a single machine, rather than as a PostgreSQL cluster.
 Configure the tracking database.
 
 1. Edit `/etc/gitlab/gitlab.rb` in the tracking database machine, and add the
-    following:
-
-    ```ruby
-    ##
-    ## Enable the Geo secondary tracking database
-    ##
-    geo_postgresql['enable'] = true
-    geo_postgresql['listen_address'] = '<ip_address_of_this_host>'
-    geo_postgresql['sql_user_password'] = '<tracking_database_password_md5_hash>'
-
-    ##
-    ## Configure FDW connection to the replica database
-    ##
-    geo_secondary['db_fdw'] = true
-    geo_postgresql['fdw_external_password'] = '<replica_database_password_plaintext>'
-    geo_postgresql['md5_auth_cidr_addresses'] = ['<replica_database_ip>/32']
-    gitlab_rails['db_host'] = '<replica_database_ip>'
-
-    # Prevent reconfigure from attempting to run migrations on the replica DB
-    gitlab_rails['auto_migrate'] = false
-
-    ##
-    ## Disable all other services that aren't needed, since we don't have a role
-    ## that does this.
-    ##
-    alertmanager['enable'] = false
-    consul['enable'] = false
-    gitaly['enable'] = false
-    gitlab_monitor['enable'] = false
-    gitlab_workhorse['enable'] = false
-    nginx['enable'] = false
-    node_exporter['enable'] = false
-    pgbouncer_exporter['enable'] = false
-    postgresql['enable'] = false
-    prometheus['enable'] = false
-    redis['enable'] = false
-    redis_exporter['enable'] = false
-    repmgr['enable'] = false
-    sidekiq['enable'] = false
-    unicorn['enable'] = false
-    ```
+   following:
+
+   ```ruby
+   ##
+   ## Enable the Geo secondary tracking database
+   ##
+   geo_postgresql['enable'] = true
+   geo_postgresql['listen_address'] = '<ip_address_of_this_host>'
+   geo_postgresql['sql_user_password'] = '<tracking_database_password_md5_hash>'
+
+   ##
+   ## Configure FDW connection to the replica database
+   ##
+   geo_secondary['db_fdw'] = true
+   geo_postgresql['fdw_external_password'] = '<replica_database_password_plaintext>'
+   geo_postgresql['md5_auth_cidr_addresses'] = ['<replica_database_ip>/32']
+   gitlab_rails['db_host'] = '<replica_database_ip>'
+
+   # Prevent reconfigure from attempting to run migrations on the replica DB
+   gitlab_rails['auto_migrate'] = false
+
+   ##
+   ## Disable all other services that aren't needed, since we don't have a role
+   ## that does this.
+   ##
+   alertmanager['enable'] = false
+   consul['enable'] = false
+   gitaly['enable'] = false
+   gitlab_monitor['enable'] = false
+   gitlab_workhorse['enable'] = false
+   nginx['enable'] = false
+   node_exporter['enable'] = false
+   pgbouncer_exporter['enable'] = false
+   postgresql['enable'] = false
+   prometheus['enable'] = false
+   redis['enable'] = false
+   redis_exporter['enable'] = false
+   repmgr['enable'] = false
+   sidekiq['enable'] = false
+   unicorn['enable'] = false
+   ```
 
 After making these changes, [reconfigure GitLab][gitlab-reconfigure] so the changes take effect.
 
@@ -211,50 +211,50 @@ following modifications:
 1. Edit `/etc/gitlab/gitlab.rb` on each application server in the **secondary**
    cluster, and add the following:
 
-    ```ruby
-    ##
-    ## Enable the Geo secondary role
-    ##
-    roles ['geo_secondary_role', 'application_role']
-
-    ##
-    ## Disable automatic migrations
-    ##
-    gitlab_rails['auto_migrate'] = false
-
-    ##
-    ## Configure the connection to the tracking DB. And disable application
-    ## servers from running tracking databases.
-    ##
-    geo_secondary['db_host'] = '<geo_tracking_db_host>'
-    geo_secondary['db_password'] = '<geo_tracking_db_password>'
-    geo_postgresql['enable'] = false
-
-    ##
-    ## Configure connection to the streaming replica database, if you haven't
-    ## already
-    ##
-    gitlab_rails['db_host'] = '<replica_database_host>'
-    gitlab_rails['db_password'] = '<replica_database_password>'
-
-    ##
-    ## Configure connection to Redis, if you haven't already
-    ##
-    gitlab_rails['redis_host'] = '<redis_host>'
-    gitlab_rails['redis_password'] = '<redis_password>'
-
-    ##
-    ## If you are using custom users not managed by Omnibus, you need to specify
-    ## UIDs and GIDs like below, and ensure they match between servers in a
-    ## cluster to avoid permissions issues
-    ##
-    user['uid'] = 9000
-    user['gid'] = 9000
-    web_server['uid'] = 9001
-    web_server['gid'] = 9001
-    registry['uid'] = 9002
-    registry['gid'] = 9002
-    ```
+   ```ruby
+   ##
+   ## Enable the Geo secondary role
+   ##
+   roles ['geo_secondary_role', 'application_role']
+
+   ##
+   ## Disable automatic migrations
+   ##
+   gitlab_rails['auto_migrate'] = false
+
+   ##
+   ## Configure the connection to the tracking DB. And disable application
+   ## servers from running tracking databases.
+   ##
+   geo_secondary['db_host'] = '<geo_tracking_db_host>'
+   geo_secondary['db_password'] = '<geo_tracking_db_password>'
+   geo_postgresql['enable'] = false
+
+   ##
+   ## Configure connection to the streaming replica database, if you haven't
+   ## already
+   ##
+   gitlab_rails['db_host'] = '<replica_database_host>'
+   gitlab_rails['db_password'] = '<replica_database_password>'
+
+   ##
+   ## Configure connection to Redis, if you haven't already
+   ##
+   gitlab_rails['redis_host'] = '<redis_host>'
+   gitlab_rails['redis_password'] = '<redis_password>'
+
+   ##
+   ## If you are using custom users not managed by Omnibus, you need to specify
+   ## UIDs and GIDs like below, and ensure they match between servers in a
+   ## cluster to avoid permissions issues
+   ##
+   user['uid'] = 9000
+   user['gid'] = 9000
+   web_server['uid'] = 9001
+   web_server['gid'] = 9001
+   registry['uid'] = 9002
+   registry['gid'] = 9002
+   ```
 
 NOTE: **Note:**
 If you had set up PostgreSQL cluster using the omnibus package and you had set
@@ -270,15 +270,15 @@ After making these changes [Reconfigure GitLab][gitlab-reconfigure] so the chang
 
 On the secondary the following GitLab frontend services will be enabled:
 
-* geo-logcursor
-* gitlab-pages
-* gitlab-workhorse
-* logrotate
-* nginx
-* registry
-* remote-syslog
-* sidekiq
-* unicorn
+- geo-logcursor
+- gitlab-pages
+- gitlab-workhorse
+- logrotate
+- nginx
+- registry
+- remote-syslog
+- sidekiq
+- unicorn
 
 Verify these services by running `sudo gitlab-ctl status` on the frontend
 application servers.
diff --git a/doc/administration/geo/replication/img/geo_architecture.png b/doc/administration/geo/replication/img/geo_architecture.png
index d318cd5d0f4..aac63be41ff 100644
--- a/doc/administration/geo/replication/img/geo_architecture.png
+++ b/doc/administration/geo/replication/img/geo_architecture.png
diff --git a/doc/administration/geo/replication/index.md b/doc/administration/geo/replication/index.md
index 54377f7ae4e..dbd466b906d 100644
--- a/doc/administration/geo/replication/index.md
+++ b/doc/administration/geo/replication/index.md
@@ -1,6 +1,12 @@
-# Geo Replication **[PREMIUM ONLY]**
+# Replication (Geo) **(PREMIUM ONLY)**
 
-Geo is the solution for widely distributed development teams.
+> - Introduced in GitLab Enterprise Edition 8.9.
+> - Using Geo in combination with
+>   [High Availability](../../high_availability/README.md)
+>   is considered **Generally Available** (GA) in
+>   [GitLab Premium](https://about.gitlab.com/pricing/) 10.4.
+
+Replication with Geo is the solution for widely distributed development teams.
 
 ## Overview
 
@@ -8,14 +14,8 @@ Fetching large repositories can take a long time for teams located far from a si
 
 Geo provides local, read-only instances of your GitLab instances, reducing the time it takes to clone and fetch large repositories and speeding up development.
 
-> - Geo is part of [GitLab Premium](https://about.gitlab.com/pricing/#self-managed).
-> - Introduced in GitLab Enterprise Edition 8.9.
-> - We recommend you use:
->   - At least GitLab Enterprise Edition 10.0 for basic Geo features.
->   - The latest version for a better experience.
-> - Make sure that all nodes run the same GitLab version.
-> - Geo requires PostgreSQL 9.6 and Git 2.9, in addition to GitLab's usual [minimum requirements](../../../install/requirements.md).
-> - Using Geo in combination with [High Availability](../../high_availability/README.md) is considered **Generally Available** (GA) in GitLab [GitLab Premium](https://about.gitlab.com/pricing/) 10.4.
+NOTE: **Note:**
+Check the [requirements](#requirements-for-running-geo) carefully before setting up Geo.
 
 For a video introduction to Geo, see [Introduction to GitLab Geo - GitLab Features](https://www.youtube.com/watch?v=-HDLxSjEh6w).
 
@@ -80,8 +80,8 @@ In this diagram:
 - If present, the [LDAP server](#ldap) should be configured to replicate for [Disaster Recovery](../disaster_recovery/index.md) scenarios.
 - A **secondary** node performs different type of synchronizations against the **primary** node, using a special
   authorization protected by JWT:
-   - Repositories are cloned/updated via Git over HTTPS.
-   - Attachments, LFS objects, and other files are downloaded via HTTPS using a private API endpoint.
+  - Repositories are cloned/updated via Git over HTTPS.
+  - Attachments, LFS objects, and other files are downloaded via HTTPS using a private API endpoint.
 
 From the perspective of a user performing Git operations:
 
@@ -107,10 +107,17 @@ The following are required to run Geo:
 - An operating system that supports OpenSSH 6.9+ (needed for
   [fast lookup of authorized SSH keys in the database](../../operations/fast_ssh_key_lookup.md))
   The following operating systems are known to ship with a current version of OpenSSH:
-    - [CentOS](https://www.centos.org) 7.4+
-    - [Ubuntu](https://www.ubuntu.com) 16.04+
+  - [CentOS](https://www.centos.org) 7.4+
+  - [Ubuntu](https://www.ubuntu.com) 16.04+
 - PostgreSQL 9.6+ with [FDW](https://www.postgresql.org/docs/9.6/postgres-fdw.html) support and [Streaming Replication](https://wiki.postgresql.org/wiki/Streaming_Replication)
 - Git 2.9+
+- All nodes must run the same GitLab version.
+
+Additionally, check GitLab's [minimum requirements](../../../install/requirements.md),
+and we recommend you use:
+
+- At least GitLab Enterprise Edition 10.0 for basic Geo features.
+- The latest version for a better experience.
 
 ### Firewall rules
 
@@ -178,7 +185,7 @@ The steps below should be followed in the order they appear. **Make sure the Git
 
 If you installed GitLab using the Omnibus packages (highly recommended):
 
-1. [Install GitLab Enterprise Edition](https://about.gitlab.com/installation/) on the server that will serve as the **secondary** node. Do not create an account or log in to the new **secondary** node.
+1. [Install GitLab Enterprise Edition](https://about.gitlab.com/install/) on the server that will serve as the **secondary** node. Do not create an account or log in to the new **secondary** node.
 1. [Upload the GitLab License](../../../user/admin_area/license.md) on the **primary** node to unlock Geo. The license must be for [GitLab Premium](https://about.gitlab.com/pricing/) or higher.
 1. [Set up the database replication](database.md) (`primary (read-write) <-> secondary (read-only)` topology).
 1. [Configure fast lookup of authorized SSH keys in the database](../../operations/fast_ssh_key_lookup.md). This step is required and needs to be done on **both** the **primary** and **secondary** nodes.
@@ -239,35 +246,48 @@ This list of limitations only reflects the latest version of GitLab. If you are
 - Object pools for forked project deduplication work only on the **primary** node, and are duplicated on the **secondary** node.
 - [External merge request diffs](../../merge_request_diffs.md) will not be replicated if they are on-disk, and viewing merge requests will fail. However, external MR diffs in object storage **are** supported. The default configuration (in-database) does work.
 
-### Limitations on replication
-
-Only the following items are replicated to the **secondary** node:
-
-- All database content. For example, snippets, epics, issues, merge requests, groups, and project metadata.
-- Project repositories.
-- Project wiki repositories.
-- User uploads. For example, attachments to issues, merge requests, epics, and avatars.
-- CI job artifacts and traces.
+### Limitations on replication/verification
+
+The following table lists the GitLab features along with their replication
+and verification status on a **secondary** node.
+
+You can keep track of the progress to include the missing items in:
+
+- [ee-893](https://gitlab.com/groups/gitlab-org/-/epics/893).
+- [ee-1430](https://gitlab.com/groups/gitlab-org/-/epics/1430).
+
+| Feature | Replicated | Verified |
+|-----------|------------|----------|
+| All database content (e.g. snippets, epics, issues, merge requests, groups, and project metadata)  | Yes | Yes |
+| Project repository | Yes | Yes |
+| Project wiki repository | Yes | Yes |
+| Project designs repository | No | No |
+| Uploads (e.g. attachments to issues, merge requests, epics, and avatars) | Yes | Yes, only on transfer, or manually (1) |
+| LFS Objects | Yes | Yes, only on transfer, or manually (1) |
+| CI job artifacts (other than traces) | Yes | No, only manually (1) |
+| Archived traces | Yes | Yes, only on transfer, or manually (1) |
+| Personal snippets | Yes | Yes |
+| Version-controlled personal snippets ([unsupported](https://gitlab.com/gitlab-org/gitlab-ce/issues/13426)) | No | No |
+| Project snippets | Yes | Yes |
+| Version-controlled project snippets ([unsupported](https://gitlab.com/gitlab-org/gitlab-ce/issues/13426)) | No | No |
+| Object pools for forked project deduplication | No | No |
+| [Server-side Git Hooks](../../custom_hooks.md) | No | No |
+| [Elasticsearch integration](../../../integration/elasticsearch.md) | No | No |
+| [GitLab Pages](../../pages/index.md) | No | No |
+| [Container Registry](../../container_registry.md) ([track progress](https://gitlab.com/gitlab-org/gitlab-ee/issues/2870)) | No | No |
+| [NPM Registry](../../npm_registry.md) | No | No |
+| [Maven Packages](../../maven_packages.md) | No | No |
+| [External merge request diffs](../../merge_request_diffs.md) | No, if they are on-disk | No |
+| Content in object storage ([track progress](https://gitlab.com/groups/gitlab-org/-/epics/1526)) | No | No |
+
+1. The integrity can be verified manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them.
 
 DANGER: **DANGER**
-Data not on this list is unavailable on the **secondary** node. Failing over without manually replicating data not on this list will cause the data to be **lost**.
-
-### Examples of data not replicated
-
-Take special note that these examples of GitLab features are both:
-
-- Commonly used.
-- **Not** replicated by Geo at present.
-
-Examples include:
-
-- [Elasticsearch integration](../../../integration/elasticsearch.md).
-- [Container Registry](../../container_registry.md). [Object Storage](object_storage.md) can mitigate this.
-- [GitLab Pages](../../pages/index.md).
-- [Mattermost integration](https://docs.gitlab.com/omnibus/gitlab-mattermost/).
-
-CAUTION: **Caution:**
-If you wish to use them on a **secondary** node, or to execute a failover successfully, you will need to replicate their data using some other means.
+Features not on this list, or with **No** in the **Replicated** column,
+are not replicated on the **secondary** node. Failing over without manually
+replicating data from those features will cause the data to be **lost**.
+If you wish to use those features on a **secondary** node, or to execute a failover
+successfully, you must replicate their data using some other means.
 
 ## Frequently Asked Questions
 
diff --git a/doc/administration/geo/replication/object_storage.md b/doc/administration/geo/replication/object_storage.md
index c3c11dbaf1e..878b67a8f8e 100644
--- a/doc/administration/geo/replication/object_storage.md
+++ b/doc/administration/geo/replication/object_storage.md
@@ -1,4 +1,4 @@
-# Geo with Object storage **[PREMIUM ONLY]**
+# Geo with Object storage **(PREMIUM ONLY)**
 
 Geo can be used in combination with Object Storage (AWS S3, or
 other compatible object storage).
@@ -34,10 +34,10 @@ the bucket used by **secondary** nodes.
 
 If you are using Google Cloud Storage, consider using
 [Multi-Regional Storage](https://cloud.google.com/storage/docs/storage-classes#multi-regional).
-Or you can use the [Storage Transfer Service](https://cloud.google.com/storage/transfer/),
+Or you can use the [Storage Transfer Service](https://cloud.google.com/storage-transfer/docs/),
 although this only supports daily synchronization.
 
 For manual synchronization, or scheduled by `cron`, please have a look at:
 
-- [`s3cmd sync`](http://s3tools.org/s3cmd-sync)
+- [`s3cmd sync`](https://s3tools.org/s3cmd-sync)
 - [`gsutil rsync`](https://cloud.google.com/storage/docs/gsutil/commands/rsync)
diff --git a/doc/administration/geo/replication/remove_geo_node.md b/doc/administration/geo/replication/remove_geo_node.md
index b190fe7d42d..e24eb2bd428 100644
--- a/doc/administration/geo/replication/remove_geo_node.md
+++ b/doc/administration/geo/replication/remove_geo_node.md
@@ -1,4 +1,4 @@
-# Removing secondary Geo nodes **[PREMIUM ONLY]**
+# Removing secondary Geo nodes **(PREMIUM ONLY)**
 
 **Secondary** nodes can be removed from the Geo cluster using the Geo admin page of the **primary** node. To remove a **secondary** node:
 
@@ -10,41 +10,42 @@ Once removed from the Geo admin page, you must stop and uninstall the **secondar
 
 1. On the **secondary** node, stop GitLab:
 
-    ```bash
-    sudo gitlab-ctl stop
-    ```
+   ```bash
+   sudo gitlab-ctl stop
+   ```
+
 1. On the **secondary** node, uninstall GitLab:
 
-    ```bash
-    # Stop gitlab and remove its supervision process
-    sudo gitlab-ctl uninstall
-    
-    # Debian/Ubuntu
-    sudo dpkg --remove gitlab-ee
-    
-    # Redhat/Centos
-    sudo rpm --erase gitlab-ee
-    ```
+   ```bash
+   # Stop gitlab and remove its supervision process
+   sudo gitlab-ctl uninstall
+
+   # Debian/Ubuntu
+   sudo dpkg --remove gitlab-ee
+
+   # Redhat/Centos
+   sudo rpm --erase gitlab-ee
+   ```
 
 Once GitLab has been uninstalled from the **secondary** node, the replication slot must be dropped from the **primary** node's database as follows:
 
 1. On the **primary** node, start a PostgreSQL console session:
 
-    ```bash
-    sudo gitlab-psql 
-    ```
-    
-    NOTE: **Note:**
-    Using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions.
+   ```bash
+   sudo gitlab-psql
+   ```
+
+   NOTE: **Note:**
+   Using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions.
 
 1. Find the name of the relevant replication slot. This is the slot that is specified with `--slot-name` when running the replicate command: `gitlab-ctl replicate-geo-database`.
 
-    ```sql
-    SELECT * FROM pg_replication_slots;
-    ```
-    
+   ```sql
+   SELECT * FROM pg_replication_slots;
+   ```
+
 1. Remove the replication slot for the **secondary** node:
 
-    ```sql
-    SELECT pg_drop_replication_slot('<name_of_slot>');
-    ```  
+   ```sql
+   SELECT pg_drop_replication_slot('<name_of_slot>');
+   ```
diff --git a/doc/administration/geo/replication/security_review.md b/doc/administration/geo/replication/security_review.md
index cd54e2dc8c4..ed3f1faa93e 100644
--- a/doc/administration/geo/replication/security_review.md
+++ b/doc/administration/geo/replication/security_review.md
@@ -1,4 +1,4 @@
-# Geo security review (Q&A) **[PREMIUM ONLY]**
+# Geo security review (Q&A) **(PREMIUM ONLY)**
 
 The following security review of the Geo feature set focuses on security
 aspects of the feature as they apply to customers running their own GitLab
@@ -115,7 +115,7 @@ questions from [owasp.org](https://www.owasp.org).
 ### What operating systems support the application?
 
 - Geo imposes no additional restrictions on operating system (see the
-  [GitLab installation](https://about.gitlab.com/installation/) page for more
+  [GitLab installation](https://about.gitlab.com/install/) page for more
   details), however we recommend using the operating systems listed in the [Geo documentation](index.md#requirements-for-running-geo).
 
 ### What details regarding required OS components and lock‐down needs have been defined?
diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md
index c5bdd36ba70..fe1557fd8b5 100644
--- a/doc/administration/geo/replication/troubleshooting.md
+++ b/doc/administration/geo/replication/troubleshooting.md
@@ -1,15 +1,23 @@
-# Geo Troubleshooting **[PREMIUM ONLY]**
-
-NOTE: **Note:**
-This list is an attempt to document all the moving parts that can go wrong.
-We are working into getting all this steps verified automatically in a
-rake task in the future.
+# Geo Troubleshooting **(PREMIUM ONLY)**
 
 Setting up Geo requires careful attention to details and sometimes it's easy to
-miss a step. Here is a list of questions you should ask to try to detect
-what you need to fix (all commands and path locations are for Omnibus installs):
+miss a step.
+
+Here is a list of steps you should take to attempt to fix problem:
+
+- Perform [basic troubleshooting](#basic-troubleshooting).
+- Fix any [replication errors](#fixing-replication-errors).
+- Fix any [Foreign Data Wrapper](#fixing-foreign-data-wrapper-errors) errors.
+- Fix any [common](#fixing-common-errors) errors.
+
+## Basic troubleshooting
+
+Before attempting more advanced troubleshooting:
 
-## First check the health of the **secondary** node
+- Check [the health of the **secondary** node](#check-the-health-of-the-secondary-node).
+- Check [if PostgreSQL replication is working](#check-if-postgresql-replication-is-working).
+
+### Check the health of the **secondary** node
 
 Visit the **primary** node's **Admin Area > Geo** (`/admin/geo/nodes`) in
 your browser. We perform the following health checks on each **secondary** node
@@ -23,10 +31,12 @@ to help identify if something is wrong:
 
 ![Geo health check](img/geo_node_healthcheck.png)
 
-For information on how to resolve common errors reported from the UI, see [common errors](#common-errors).
+For information on how to resolve common errors reported from the UI, see
+[Fixing Common Errors](#fixing-common-errors).
 
 If the UI is not working, or you are unable to log in, you can run the Geo
 health check manually to get this information as well as a few more details.
+
 This rake task can be run on an app node in the **primary** or **secondary**
 Geo nodes:
 
@@ -36,7 +46,7 @@ sudo gitlab-rake gitlab:geo:check
 
 Example output:
 
-```
+```text
 Checking Geo ...
 
 GitLab Geo is available ... yes
@@ -68,7 +78,7 @@ sudo gitlab-rake geo:status
 
 Example output:
 
-```
+```text
 http://secondary.example.com/
 -----------------------------------------------------
                         GitLab Version: 11.10.4-ee
@@ -89,16 +99,21 @@ http://secondary.example.com/
                 Last status report was: 2 minutes ago
 ```
 
-## Is Postgres replication working?
+### Check if PostgreSQL replication is working
+
+To check if PostgreSQL replication is working, check if:
 
-### Are my nodes pointing to the correct database instance?
+- [Nodes are pointing to the correct database instance](#are-nodes-pointing-to-the-correct-database-instance).
+- [Geo can detect the current node correctly](#can-geo-detect-the-current-node-correctly).
+
+#### Are nodes pointing to the correct database instance?
 
 You should make sure your **primary** Geo node points to the instance with
 writing permissions.
 
 Any **secondary** nodes should point only to read-only instances.
 
-### Can Geo detect my current node correctly?
+#### Can Geo detect the current node correctly?
 
 Geo uses the defined node from the **Admin Area > Geo** screen, and tries to match
 it with the value defined in the `/etc/gitlab/gitlab.rb` configuration file.
@@ -112,29 +127,38 @@ sudo gitlab-rails runner "puts Gitlab::Geo.current_node.inspect"
 
 and expect something like:
 
-```
+```ruby
 #<GeoNode id: 2, schema: "https", host: "gitlab.example.com", port: 443, relative_url_root: "", primary: false, ...>
 ```
 
 By running the command above, `primary` should be `true` when executed in
 the **primary** node, and `false` on any **secondary** node.
 
-## How do I fix the message, "ERROR:  replication slots can only be used if max_replication_slots > 0"?
+## Fixing replication errors
+
+The following sections outline troubleshooting steps for fixing replication
+errors.
+
+### Message: "ERROR:  replication slots can only be used if max_replication_slots > 0"?
 
 This means that the `max_replication_slots` PostgreSQL variable needs to
 be set on the **primary** database. In GitLab 9.4, we have made this setting
 default to 1. You may need to increase this value if you have more
-**secondary** nodes. Be sure to restart PostgreSQL for this to take
+**secondary** nodes.
+
+Be sure to restart PostgreSQL for this to take
 effect. See the [PostgreSQL replication
 setup][database-pg-replication] guide for more details.
 
-## How do I fix the message, "FATAL:  could not start WAL streaming: ERROR:  replication slot "geo_secondary_my_domain_com" does not exist"?
+### Message: "FATAL:  could not start WAL streaming: ERROR:  replication slot "geo_secondary_my_domain_com" does not exist"?
 
 This occurs when PostgreSQL does not have a replication slot for the
-**secondary** node by that name. You may want to rerun the [replication
+**secondary** node by that name.
+
+You may want to rerun the [replication
 process](database.md) on the **secondary** node .
 
-## How do I fix the message, "Command exceeded allowed execution time" when setting up replication?
+### Message: "Command exceeded allowed execution time" when setting up replication?
 
 This may happen while [initiating the replication process][database-start-replication] on the **secondary** node,
 and indicates that your initial dataset is too large to be replicated in the default timeout (30 minutes).
@@ -153,24 +177,24 @@ sudo gitlab-ctl \
 This will give the initial replication up to six hours to complete, rather than
 the default thirty minutes. Adjust as required for your installation.
 
-## How do I fix the message, "PANIC: could not write to file 'pg_xlog/xlogtemp.123': No space left on device"
+### Message: "PANIC: could not write to file 'pg_xlog/xlogtemp.123': No space left on device"
 
 Determine if you have any unused replication slots in the **primary** database. This can cause large amounts of
 log data to build up in `pg_xlog`. Removing the unused slots can reduce the amount of space used in the `pg_xlog`.
 
 1. Start a PostgreSQL console session:
 
-    ```sh
-    sudo gitlab-psql gitlabhq_production
-    ```
+   ```sh
+   sudo gitlab-psql gitlabhq_production
+   ```
 
-    > Note that using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions.
+   Note: **Note:** Using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions.
 
 1. View your replication slots with:
 
-    ```sql
-    SELECT * FROM pg_replication_slots;
-    ```
+   ```sql
+   SELECT * FROM pg_replication_slots;
+   ```
 
 Slots where `active` is `f` are not active.
 
@@ -180,15 +204,16 @@ Slots where `active` is `f` are not active.
 - If you are no longer using the slot (e.g. you no longer have Geo enabled), you can remove it with in the
   PostgreSQL console session:
 
-    ```sql
-    SELECT pg_drop_replication_slot('<name_of_extra_slot>');
-    ```
+  ```sql
+  SELECT pg_drop_replication_slot('<name_of_extra_slot>');
+  ```
 
-## Very large repositories never successfully synchronize on the **secondary** node
+### Very large repositories never successfully synchronize on the **secondary** node
 
 GitLab places a timeout on all repository clones, including project imports
 and Geo synchronization operations. If a fresh `git clone` of a repository
 on the primary takes more than a few minutes, you may be affected by this.
+
 To increase the timeout, add the following line to `/etc/gitlab/gitlab.rb`
 on the **secondary** node:
 
@@ -205,96 +230,100 @@ sudo gitlab-ctl reconfigure
 This will increase the timeout to three hours (10800 seconds). Choose a time
 long enough to accommodate a full clone of your largest repositories.
 
-## How to reset Geo **secondary** node replication
+### Resetting Geo **secondary** node replication
 
 If you get a **secondary** node in a broken state and want to reset the replication state,
 to start again from scratch, there are a few steps that can help you:
 
 1. Stop Sidekiq and the Geo LogCursor
 
-    It's possible to make Sidekiq stop gracefully, but making it stop getting new jobs and
-    wait until the current jobs to finish processing.
+   It's possible to make Sidekiq stop gracefully, but making it stop getting new jobs and
+   wait until the current jobs to finish processing.
 
-    You need to send a **SIGTSTP** kill signal for the first phase and them a **SIGTERM**
-    when all jobs have finished. Otherwise just use the `gitlab-ctl stop` commands.
+   You need to send a **SIGTSTP** kill signal for the first phase and them a **SIGTERM**
+   when all jobs have finished. Otherwise just use the `gitlab-ctl stop` commands.
 
-    ```sh
-    gitlab-ctl status sidekiq
-    # run: sidekiq: (pid 10180) <- this is the PID you will use
-    kill -TSTP 10180 # change to the correct PID
+   ```sh
+   gitlab-ctl status sidekiq
+   # run: sidekiq: (pid 10180) <- this is the PID you will use
+   kill -TSTP 10180 # change to the correct PID
 
-    gitlab-ctl stop sidekiq
-    gitlab-ctl stop geo-logcursor
-    ```
+   gitlab-ctl stop sidekiq
+   gitlab-ctl stop geo-logcursor
+   ```
 
-    You can watch sidekiq logs to know when sidekiq jobs processing have finished:
+   You can watch sidekiq logs to know when sidekiq jobs processing have finished:
 
-    ```sh
-    gitlab-ctl tail sidekiq
-    ```
+   ```sh
+   gitlab-ctl tail sidekiq
+   ```
 
 1. Rename repository storage folders and create new ones
 
-    ```sh
-    mv /var/opt/gitlab/git-data/repositories /var/opt/gitlab/git-data/repositories.old
-    mkdir -p /var/opt/gitlab/git-data/repositories
-    chown git:git /var/opt/gitlab/git-data/repositories
-    ```
+   ```sh
+   mv /var/opt/gitlab/git-data/repositories /var/opt/gitlab/git-data/repositories.old
+   mkdir -p /var/opt/gitlab/git-data/repositories
+   chown git:git /var/opt/gitlab/git-data/repositories
+   ```
 
-    TIP: **Tip**
-    You may want to remove the `/var/opt/gitlab/git-data/repositories.old` in the future
-    as soon as you confirmed that you don't need it anymore, to save disk space.
+   TIP: **Tip**
+   You may want to remove the `/var/opt/gitlab/git-data/repositories.old` in the future
+   as soon as you confirmed that you don't need it anymore, to save disk space.
 
 1. _(Optional)_ Rename other data folders and create new ones
 
-    CAUTION: **Caution**:
-    You may still have files on the **secondary** node that have been removed from **primary** node but
-    removal have not been reflected. If you skip this step, they will never be removed
-    from this Geo node.
+   CAUTION: **Caution**:
+   You may still have files on the **secondary** node that have been removed from **primary** node but
+   removal have not been reflected. If you skip this step, they will never be removed
+   from this Geo node.
 
-    Any uploaded content like file attachments, avatars or LFS objects are stored in a
-    subfolder in one of the two paths below:
+   Any uploaded content like file attachments, avatars or LFS objects are stored in a
+   subfolder in one of the two paths below:
 
-    1. /var/opt/gitlab/gitlab-rails/shared
-    1. /var/opt/gitlab/gitlab-rails/uploads
+   - /var/opt/gitlab/gitlab-rails/shared
+   - /var/opt/gitlab/gitlab-rails/uploads
 
-    To rename all of them:
+   To rename all of them:
 
-    ```sh
-    gitlab-ctl stop
+   ```sh
+   gitlab-ctl stop
 
-    mv /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-rails/shared.old
-    mkdir -p /var/opt/gitlab/gitlab-rails/shared
+   mv /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-rails/shared.old
+   mkdir -p /var/opt/gitlab/gitlab-rails/shared
 
-    mv /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/uploads.old
-    mkdir -p /var/opt/gitlab/gitlab-rails/uploads
-    ```
+   mv /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/uploads.old
+   mkdir -p /var/opt/gitlab/gitlab-rails/uploads
+   ```
 
-    Reconfigure in order to recreate the folders and make sure permissions and ownership
-    are correctly
+   Reconfigure in order to recreate the folders and make sure permissions and ownership
+   are correctly
 
-    ```sh
-    gitlab-ctl reconfigure
-    ```
+   ```sh
+   gitlab-ctl reconfigure
+   ```
 
 1. Reset the Tracking Database
 
-    ```sh
-    gitlab-rake geo:db:reset
-    ```
+   ```sh
+   gitlab-rake geo:db:reset
+   ```
 
 1. Restart previously stopped services
 
-    ```sh
-    gitlab-ctl start
-    ```
+   ```sh
+   gitlab-ctl start
+   ```
+
+## Fixing Foreign Data Wrapper errors
 
-## How do I fix a "Foreign Data Wrapper (FDW) is not configured" error?
+This section documents ways to fix potential Foreign Data Wrapper errors.
+
+### "Foreign Data Wrapper (FDW) is not configured" error
 
 When setting up Geo, you might see this warning in the `gitlab-rake
 gitlab:geo:check` output:
 
-```
+```text
 GitLab Geo tracking database Foreign Data Wrapper schema is up-to-date? ... foreign data wrapper is not configured
 ```
 
@@ -302,12 +331,12 @@ There are a few key points to remember:
 
 1. The FDW settings are configured on the Geo **tracking** database.
 1. The configured foreign server enables a login to the Geo
-**secondary**, read-only database.
+   **secondary**, read-only database.
 
 By default, the Geo secondary and tracking database are running on the
 same host on different ports. That is, 5432 and 5431 respectively.
 
-### Checking configuration
+#### Checking configuration
 
 NOTE: **Note:**
 The following steps are for Omnibus installs only. Using Geo with source-based installs was **deprecated** in GitLab 11.5.
@@ -316,110 +345,108 @@ To check the configuration:
 
 1. Enter the database console:
 
-    ```sh
-    gitlab-geo-psql
-    ```
+   ```sh
+   gitlab-geo-psql
+   ```
 
 1. Check whether any tables are present. If everything is working, you
-should see something like this:
-
-    ```sql
-    gitlabhq_geo_production=# SELECT * from information_schema.foreign_tables;
-      foreign_table_catalog  | foreign_table_schema |               foreign_table_name                | foreign_server_catalog  | foreign_server_n
-    ame
-    -------------------------+----------------------+-------------------------------------------------+-------------------------+-----------------
-    ----
-     gitlabhq_geo_production | gitlab_secondary     | abuse_reports                                   | gitlabhq_geo_production | gitlab_secondary
-     gitlabhq_geo_production | gitlab_secondary     | appearances                                     | gitlabhq_geo_production | gitlab_secondary
-     gitlabhq_geo_production | gitlab_secondary     | application_setting_terms                       | gitlabhq_geo_production | gitlab_secondary
-     gitlabhq_geo_production | gitlab_secondary     | application_settings                            | gitlabhq_geo_production | gitlab_secondary
-    <snip>
-    ```
-
-    However, if the query returns with `0 rows`, then continue onto the next steps.
+   should see something like this:
+
+   ```sql
+   gitlabhq_geo_production=# SELECT * from information_schema.foreign_tables;
+     foreign_table_catalog  | foreign_table_schema |               foreign_table_name                | foreign_server_catalog  | foreign_server_name
+   -------------------------+----------------------+-------------------------------------------------+-------------------------+---------------------
+    gitlabhq_geo_production | gitlab_secondary     | abuse_reports                                   | gitlabhq_geo_production | gitlab_secondary
+    gitlabhq_geo_production | gitlab_secondary     | appearances                                     | gitlabhq_geo_production | gitlab_secondary
+    gitlabhq_geo_production | gitlab_secondary     | application_setting_terms                       | gitlabhq_geo_production | gitlab_secondary
+    gitlabhq_geo_production | gitlab_secondary     | application_settings                            | gitlabhq_geo_production | gitlab_secondary
+   <snip>
+   ```
+
+   However, if the query returns with `0 rows`, then continue onto the next steps.
 
 1. Check that the foreign server mapping is correct via `\des+`. The
    results should look something like this:
 
-    ```sql
-    gitlabhq_geo_production=# \des+
-    List of foreign servers
-    -[ RECORD 1 ]--------+------------------------------------------------------------
-    Name                 | gitlab_secondary
-    Owner                | gitlab-psql
-    Foreign-data wrapper | postgres_fdw
-    Access privileges    | "gitlab-psql"=U/"gitlab-psql"                              +
-                         | gitlab_geo=U/"gitlab-psql"
-    Type                 |
-    Version              |
-    FDW Options          | (host '0.0.0.0', port '5432', dbname 'gitlabhq_production')
-    Description          |
-    ```
-
-    NOTE: **Note:** Pay particular attention to the host and port under
-    FDW options. That configuration should point to the Geo secondary
-    database.
-
-    If you need to experiment with changing the host or password, the
-    following queries demonstrate how:
-
-    ```sql
-    ALTER SERVER gitlab_secondary OPTIONS (SET host '<my_new_host>');
-    ALTER SERVER gitlab_secondary OPTIONS (SET port 5432);
-    ```
-
-    If you change the host and/or port, you will also have to adjust the
-    following settings in `/etc/gitlab/gitlab.rb` and run `gitlab-ctl
-    reconfigure`:
-
-    - `gitlab_rails['db_host']`
-    - `gitlab_rails['db_port']`
+   ```sql
+   gitlabhq_geo_production=# \des+
+   List of foreign servers
+   -[ RECORD 1 ]--------+------------------------------------------------------------
+   Name                 | gitlab_secondary
+   Owner                | gitlab-psql
+   Foreign-data wrapper | postgres_fdw
+   Access privileges    | "gitlab-psql"=U/"gitlab-psql"                              +
+                        | gitlab_geo=U/"gitlab-psql"
+   Type                 |
+   Version              |
+   FDW Options          | (host '0.0.0.0', port '5432', dbname 'gitlabhq_production')
+   Description          |
+   ```
+
+   NOTE: **Note:** Pay particular attention to the host and port under
+   FDW options. That configuration should point to the Geo secondary
+   database.
+
+   If you need to experiment with changing the host or password, the
+   following queries demonstrate how:
+
+   ```sql
+   ALTER SERVER gitlab_secondary OPTIONS (SET host '<my_new_host>');
+   ALTER SERVER gitlab_secondary OPTIONS (SET port 5432);
+   ```
+
+   If you change the host and/or port, you will also have to adjust the
+   following settings in `/etc/gitlab/gitlab.rb` and run `gitlab-ctl
+   reconfigure`:
+
+   - `gitlab_rails['db_host']`
+   - `gitlab_rails['db_port']`
 
 1. Check that the user mapping is configured properly via `\deu+`:
 
-    ```sql
-    gitlabhq_geo_production=# \deu+
-                                                 List of user mappings
-          Server      | User name  |                                  FDW Options
-    ------------------+------------+--------------------------------------------------------------------------------
-     gitlab_secondary | gitlab_geo | ("user" 'gitlab', password 'YOUR-PASSWORD-HERE')
-    (1 row)
-    ```
+   ```sql
+   gitlabhq_geo_production=# \deu+
+                                                List of user mappings
+         Server      | User name  |                                  FDW Options
+   ------------------+------------+--------------------------------------------------------------------------------
+    gitlab_secondary | gitlab_geo | ("user" 'gitlab', password 'YOUR-PASSWORD-HERE')
+   (1 row)
+   ```
 
-    Make sure the password is correct. You can test that logins work by running `psql`:
+   Make sure the password is correct. You can test that logins work by running `psql`:
 
-    ```sh
-    # Connect to the tracking database as the `gitlab_geo` user
-    sudo \
-       -u git /opt/gitlab/embedded/bin/psql \
-       -h /var/opt/gitlab/geo-postgresql \
-       -p 5431 \
-       -U gitlab_geo \
-       -W \
-       -d gitlabhq_geo_production
-    ```
+   ```sh
+   # Connect to the tracking database as the `gitlab_geo` user
+   sudo \
+      -u git /opt/gitlab/embedded/bin/psql \
+      -h /var/opt/gitlab/geo-postgresql \
+      -p 5431 \
+      -U gitlab_geo \
+      -W \
+      -d gitlabhq_geo_production
+   ```
 
-    If you need to correct the password, the following query shows how:
+   If you need to correct the password, the following query shows how:
 
-    ```sql
-    ALTER USER MAPPING FOR gitlab_geo SERVER gitlab_secondary OPTIONS (SET password '<my_new_password>');
-    ```
+   ```sql
+   ALTER USER MAPPING FOR gitlab_geo SERVER gitlab_secondary OPTIONS (SET password '<my_new_password>');
+   ```
 
-    If you change the user or password, you will also have to adjust the
-    following settings in `/etc/gitlab/gitlab.rb` and run `gitlab-ctl
-    reconfigure`:
+   If you change the user or password, you will also have to adjust the
+   following settings in `/etc/gitlab/gitlab.rb` and run `gitlab-ctl
+   reconfigure`:
 
-    - `gitlab_rails['db_username']`
-    - `gitlab_rails['db_password']`
+   - `gitlab_rails['db_username']`
+   - `gitlab_rails['db_password']`
 
-    If you are using [PgBouncer in front of the secondary
-    database](database.md#pgbouncer-support-optional), be sure to update
-    the following settings:
+   If you are using [PgBouncer in front of the secondary
+   database](database.md#pgbouncer-support-optional), be sure to update
+   the following settings:
 
-    - `geo_postgresql['fdw_external_user']`
-    - `geo_postgresql['fdw_external_password']`
+   - `geo_postgresql['fdw_external_user']`
+   - `geo_postgresql['fdw_external_password']`
 
-### Manual reload of FDW schema
+#### Manual reload of FDW schema
 
 If you're still unable to get FDW working, you may want to try a manual
 reload of the FDW schema. To manually reload the FDW schema:
@@ -427,41 +454,66 @@ reload of the FDW schema. To manually reload the FDW schema:
 1. On the node running the Geo tracking database, enter the PostgreSQL console via
    the `gitlab_geo` user:
 
-    ```sh
-    sudo \
-       -u git /opt/gitlab/embedded/bin/psql \
-       -h /var/opt/gitlab/geo-postgresql \
-       -p 5431 \
-       -U gitlab_geo \
-       -W \
-       -d gitlabhq_geo_production
-    ```
+   ```sh
+   sudo \
+      -u git /opt/gitlab/embedded/bin/psql \
+      -h /var/opt/gitlab/geo-postgresql \
+      -p 5431 \
+      -U gitlab_geo \
+      -W \
+      -d gitlabhq_geo_production
+   ```
 
-    Be sure to adjust the port and hostname for your configuration. You
-    may be asked to enter a password.
+   Be sure to adjust the port and hostname for your configuration. You
+   may be asked to enter a password.
 
 1. Reload the schema via:
 
-    ```sql
-    DROP SCHEMA IF EXISTS gitlab_secondary CASCADE;
-    CREATE SCHEMA gitlab_secondary;
-    GRANT USAGE ON FOREIGN SERVER gitlab_secondary TO gitlab_geo;
-    IMPORT FOREIGN SCHEMA public FROM SERVER gitlab_secondary INTO gitlab_secondary;
-    ```
+   ```sql
+   DROP SCHEMA IF EXISTS gitlab_secondary CASCADE;
+   CREATE SCHEMA gitlab_secondary;
+   GRANT USAGE ON FOREIGN SERVER gitlab_secondary TO gitlab_geo;
+   IMPORT FOREIGN SCHEMA public FROM SERVER gitlab_secondary INTO gitlab_secondary;
+   ```
 
 1. Test that queries work:
 
-    ```sql
-    SELECT * from information_schema.foreign_tables;
-    SELECT * FROM gitlab_secondary.projects limit 1;
-    ```
+   ```sql
+   SELECT * from information_schema.foreign_tables;
+   SELECT * FROM gitlab_secondary.projects limit 1;
+   ```
 
 [database-start-replication]: database.md#step-3-initiate-the-replication-process
 [database-pg-replication]: database.md#postgresql-replication
 
-## Common errors
+### "Geo database has an outdated FDW remote schema" error
+
+GitLab can error with a `Geo database has an outdated FDW remote schema` message.
+
+For example:
+
+```text
+Geo database has an outdated FDW remote schema. It contains 229 of 236 expected tables. Please refer to Geo Troubleshooting.
+```
+
+To resolve this, run the following command:
+
+```sh
+sudo gitlab-rake geo:db:refresh_foreign_tables
+```
+
+## Expired artifacts
 
-This section documents common errors reported in the admin UI and how to fix them.
+If you notice for some reason there are more artifacts on the Geo
+secondary node than on the Geo primary node, you can use the rake task
+to [cleanup orphan artifact files](../../../raketasks/cleanup.md#remove-orphan-artifact-files).
+
+On a Geo **secondary** node, this command will also clean up all Geo
+registry record related to the orphan files on disk.
+
+## Fixing common errors
+
+This section documents common errors reported in the Admin UI and how to fix them.
 
 ### Geo database configuration file is missing
 
@@ -470,9 +522,22 @@ GitLab cannot find or doesn't have permission to access the `database_geo.yml` c
 In an Omnibus GitLab installation, the file should be in `/var/opt/gitlab/gitlab-rails/etc`.
 If it doesn't exist or inadvertent changes have been made to it, run `sudo gitlab-ctl reconfigure` to restore it to its correct state.
 
-
 If this path is mounted on a remote volume, please check your volume configuration and that it has correct permissions.
 
+### An existing tracking database cannot be reused
+
+Geo cannot reuse an existing tracking database.
+
+It is safest to use a fresh secondary, or reset the whole secondary by following
+[Resetting Geo secondary node replication](#resetting-geo-secondary-node-replication).
+
+If you are not concerned about possible orphaned directories and files, then you
+can simply reset the existing tracking database with:
+
+```sh
+sudo gitlab-rake geo:db:reset
+```
+
 ### Geo node has a database that is writable which is an indication it is not configured for replication with the primary node.
 
 This error refers to a problem with the database replica on a **secondary** node,
@@ -503,7 +568,7 @@ Make sure you follow the [Geo database replication](database.md) instructions fo
 
 If you are using GitLab Omnibus installation, something might have failed during upgrade. You can:
 
-- Run `sudo gitlab-ctl reconfigure`. 
+- Run `sudo gitlab-ctl reconfigure`.
 - Manually trigger the database migration by running: `sudo gitlab-rake geo:db:migrate` as root on the **secondary** node.
 
 ### Geo database is not configured to use Foreign Data Wrapper
@@ -511,4 +576,4 @@ If you are using GitLab Omnibus installation, something might have failed during
 This error means the Geo Tracking Database doesn't have the FDW server and credentials
 configured.
 
-See [How do I fix a "Foreign Data Wrapper (FDW) is not configured" error?](#how-do-i-fix-a-foreign-data-wrapper-fdw-is-not-configured-error).
+See ["Foreign Data Wrapper (FDW) is not configured" error?](#foreign-data-wrapper-fdw-is-not-configured-error).
diff --git a/doc/administration/geo/replication/tuning.md b/doc/administration/geo/replication/tuning.md
index 1943f2230df..3ee9937774a 100644
--- a/doc/administration/geo/replication/tuning.md
+++ b/doc/administration/geo/replication/tuning.md
@@ -1,4 +1,4 @@
-# Tuning Geo **[PREMIUM ONLY]**
+# Tuning Geo **(PREMIUM ONLY)**
 
 ## Changing the sync capacity values
 
diff --git a/doc/administration/geo/replication/updating_the_geo_nodes.md b/doc/administration/geo/replication/updating_the_geo_nodes.md
index 933a75c47d8..39174780e24 100644
--- a/doc/administration/geo/replication/updating_the_geo_nodes.md
+++ b/doc/administration/geo/replication/updating_the_geo_nodes.md
@@ -1,4 +1,4 @@
-# Updating the Geo nodes **[PREMIUM ONLY]**
+# Updating the Geo nodes **(PREMIUM ONLY)**
 
 Depending on which version of Geo you are updating to/from, there may be
 different steps.
@@ -10,10 +10,33 @@ all you need to do is update GitLab itself:
 
 1. Log into each node (**primary** and **secondary** nodes).
 1. [Update GitLab][update].
-1. [Update tracking database on **secondary** node](#update-tracking-database-on-secondary-node) when
-   the tracking database is enabled.
 1. [Test](#check-status-after-updating) **primary** and **secondary** nodes, and check version in each.
 
+### Check status after updating
+
+Now that the update process is complete, you may want to check whether
+everything is working correctly:
+
+1. Run the Geo raketask on all nodes, everything should be green:
+
+   ```sh
+   sudo gitlab-rake gitlab:geo:check
+   ```
+
+1. Check the **primary** node's Geo dashboard for any errors.
+1. Test the data replication by pushing code to the **primary** node and see if it
+   is received by **secondary** nodes.
+
+## Upgrading to GitLab 12.1
+
+By default, GitLab 12.1 will attempt to automatically upgrade the embedded PostgreSQL server to 10.7 from 9.6. Please see [the omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) for the recommended procedure.
+
+This can be temporarily disabled by running the following before ugprading:
+
+```sh
+sudo touch /etc/gitlab/disable-postgresql-upgrade
+```
+
 ## Upgrading to GitLab 10.8
 
 Before 10.8, broadcast messages would not propagate without flushing the cache on the **secondary** nodes. This has been fixed in 10.8, but requires one last cache flush on each **secondary** node:
@@ -30,70 +53,70 @@ We now require this change as we use this password to enable the Foreign Data Wr
 the Geo Tracking Database. We are also improving security by disabling the use of **trust**
 authentication method.
 
-1. **[primary]** Login to your **primary** node and run:
+1. **(primary)** Login to your **primary** node and run:
 
-    ```sh
-    gitlab-ctl pg-password-md5 gitlab
-    # Enter password: <your_password_here>
-    # Confirm password: <your_password_here>
-    # fca0b89a972d69f00eb3ec98a5838484
-    ```
+   ```sh
+   gitlab-ctl pg-password-md5 gitlab
+   # Enter password: <your_password_here>
+   # Confirm password: <your_password_here>
+   # fca0b89a972d69f00eb3ec98a5838484
+   ```
 
-    Copy the generated hash and edit `/etc/gitlab/gitlab.rb`:
+   Copy the generated hash and edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab`
-    postgresql['sql_user_password'] = '<md5_hash_of_your_password>'
+   ```ruby
+   # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab`
+   postgresql['sql_user_password'] = '<md5_hash_of_your_password>'
 
-    # Every node that runs Unicorn or Sidekiq needs to have the database
-    # password specified as below. If you have a high-availability setup, this
-    # must be present in all application nodes.
-    gitlab_rails['db_password'] = '<your_password_here>'
-    ```
+   # Every node that runs Unicorn or Sidekiq needs to have the database
+   # password specified as below. If you have a high-availability setup, this
+   # must be present in all application nodes.
+   gitlab_rails['db_password'] = '<your_password_here>'
+   ```
 
-    Still in the configuration file, locate and remove the `trust_auth_cidr_address`:
+   Still in the configuration file, locate and remove the `trust_auth_cidr_address`:
 
-    ```ruby
-    postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/32','1.2.3.4/32'] # <- Remove this
-    ```
+   ```ruby
+   postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/32','1.2.3.4/32'] # <- Remove this
+   ```
 
-1. **[primary]** Reconfigure and restart:
+1. **(primary)** Reconfigure and restart:
 
-    ```sh
-    sudo gitlab-ctl reconfigure
-    sudo gitlab-ctl restart
-    ```
+   ```sh
+   sudo gitlab-ctl reconfigure
+   sudo gitlab-ctl restart
+   ```
 
-1. **[secondary]** Login to all **secondary** nodes and edit `/etc/gitlab/gitlab.rb`:
+1. **(secondary)** Login to all **secondary** nodes and edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab`
-    postgresql['sql_user_password'] = '<md5_hash_of_your_password>'
+   ```ruby
+   # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab`
+   postgresql['sql_user_password'] = '<md5_hash_of_your_password>'
 
-    # Every node that runs Unicorn or Sidekiq needs to have the database
-    # password specified as below. If you have a high-availability setup, this
-    # must be present in all application nodes.
-    gitlab_rails['db_password'] = '<your_password_here>'
+   # Every node that runs Unicorn or Sidekiq needs to have the database
+   # password specified as below. If you have a high-availability setup, this
+   # must be present in all application nodes.
+   gitlab_rails['db_password'] = '<your_password_here>'
 
-    # Enable Foreign Data Wrapper
-    geo_secondary['db_fdw'] = true
+   # Enable Foreign Data Wrapper
+   geo_secondary['db_fdw'] = true
 
-    # Secondary address in CIDR format, for example '5.6.7.8/32'
-    postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32']
-    ```
+   # Secondary address in CIDR format, for example '5.6.7.8/32'
+   postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32']
+   ```
 
-    Still in the configuration file, locate and remove the `trust_auth_cidr_address`:
+   Still in the configuration file, locate and remove the `trust_auth_cidr_address`:
 
-    ```ruby
-    postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/32','5.6.7.8/32'] # <- Remove this
-    ```
+   ```ruby
+   postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/32','5.6.7.8/32'] # <- Remove this
+   ```
 
-1. **[secondary]** Reconfigure and restart:
+1. **(secondary)** Reconfigure and restart:
 
-    ```sh
-    sudo gitlab-ctl reconfigure
-    sudo gitlab-ctl restart
-    ```
+   ```sh
+   sudo gitlab-ctl reconfigure
+   sudo gitlab-ctl restart
+   ```
 
 ## Upgrading to GitLab 10.5
 
@@ -169,11 +192,11 @@ After you've verified that HTTP/HTTPS replication is working, you should remove
 the now-unused SSH keys from your secondaries, as they may cause problems if the
 **secondary** node if ever promoted to a **primary** node:
 
-1. **[secondary]** Login to **all** your **secondary** nodes and run:
+1. **(secondary)** Login to **all** your **secondary** nodes and run:
 
-    ```ruby
-    sudo -u git -H rm ~git/.ssh/id_rsa ~git/.ssh/id_rsa.pub
-    ```
+   ```ruby
+   sudo -u git -H rm ~git/.ssh/id_rsa ~git/.ssh/id_rsa.pub
+   ```
 
 ### Hashed Storage
 
@@ -236,12 +259,12 @@ instructions below.
 When in doubt, it does not hurt to do a resync. The easiest way to do this in
 Omnibus is the following:
 
-  1. Make sure you have Omnibus GitLab on the **primary** server.
-  1. Run `gitlab-ctl reconfigure` and `gitlab-ctl restart postgresql`. This will enable replication slots on the **primary** database.
-  1. Check the steps about defining `postgresql['sql_user_password']`, `gitlab_rails['db_password']`.
-  1. Make sure `postgresql['max_replication_slots']` matches the number of **secondary** Geo nodes locations.
-  1. Install GitLab on the **secondary** server.
-  1. Re-run the [database replication process][database-replication].
+1. Make sure you have Omnibus GitLab on the **primary** server.
+1. Run `gitlab-ctl reconfigure` and `gitlab-ctl restart postgresql`. This will enable replication slots on the **primary** database.
+1. Check the steps about defining `postgresql['sql_user_password']`, `gitlab_rails['db_password']`.
+1. Make sure `postgresql['max_replication_slots']` matches the number of **secondary** Geo nodes locations.
+1. Install GitLab on the **secondary** server.
+1. Re-run the [database replication process](database.md#step-3-initiate-the-replication-process).
 
 ## Special update notes for 9.0.x
 
@@ -260,174 +283,156 @@ Make sure to follow the steps in the exact order as they appear below and pay
 extra attention in what node (either **primary** or **secondary**) you execute them! Each step
 is prepended with the relevant node for better clarity:
 
-1. **[secondary]** Login to **all** your **secondary** nodes and stop all services:
+1. **(secondary)** Login to **all** your **secondary** nodes and stop all services:
 
-    ```ruby
-    sudo gitlab-ctl stop
-    ```
+   ```ruby
+   sudo gitlab-ctl stop
+   ```
 
-1. **[secondary]** Make a backup of the `recovery.conf` file on **all**
+1. **(secondary)** Make a backup of the `recovery.conf` file on **all**
    **secondary** nodes to preserve PostgreSQL's credentials:
 
-    ```sh
-    sudo cp /var/opt/gitlab/postgresql/data/recovery.conf /var/opt/gitlab/
-    ```
+   ```sh
+   sudo cp /var/opt/gitlab/postgresql/data/recovery.conf /var/opt/gitlab/
+   ```
 
-1. **[primary]** Update the **primary** node to GitLab 9.0 following the
+1. **(primary)** Update the **primary** node to GitLab 9.0 following the
    [regular update docs][update]. At the end of the update, the **primary** node
    will be running with PostgreSQL 9.6.
 
-1. **[primary]** To prevent a de-synchronization of the repository replication,
+1. **(primary)** To prevent a de-synchronization of the repository replication,
    stop all services except `postgresql` as we will use it to re-initialize the
    **secondary** node's database:
 
-    ```sh
-    sudo gitlab-ctl stop
-    sudo gitlab-ctl start postgresql
-    ```
+   ```sh
+   sudo gitlab-ctl stop
+   sudo gitlab-ctl start postgresql
+   ```
 
-1. **[secondary]** Run the following steps on each of the **secondary** nodes:
+1. **(secondary)** Run the following steps on each of the **secondary** nodes:
 
-    1. **[secondary]**  Stop all services:
+   1. **(secondary)**  Stop all services:
 
-        ```sh
-        sudo gitlab-ctl stop
-        ```
+      ```sh
+      sudo gitlab-ctl stop
+      ```
 
-    1. **[secondary]** Prevent running database migrations:
+   1. **(secondary)** Prevent running database migrations:
 
-        ```sh
-        sudo touch /etc/gitlab/skip-auto-migrations
-        ```
+      ```sh
+      sudo touch /etc/gitlab/skip-auto-migrations
+      ```
 
-    1. **[secondary]** Move the old database to another directory:
+   1. **(secondary)** Move the old database to another directory:
 
-        ```sh
-        sudo mv /var/opt/gitlab/postgresql{,.bak}
-        ```
+      ```sh
+      sudo mv /var/opt/gitlab/postgresql{,.bak}
+      ```
 
-    1. **[secondary]** Update to GitLab 9.0 following the [regular update docs][update].
-       At the end of the update, the node will be running with PostgreSQL 9.6.
+   1. **(secondary)** Update to GitLab 9.0 following the [regular update docs][update].
+      At the end of the update, the node will be running with PostgreSQL 9.6.
 
-    1. **[secondary]** Make sure all services are up:
+   1. **(secondary)** Make sure all services are up:
 
-        ```sh
-        sudo gitlab-ctl start
-        ```
+      ```sh
+      sudo gitlab-ctl start
+      ```
 
-    1. **[secondary]** Reconfigure GitLab:
+   1. **(secondary)** Reconfigure GitLab:
 
-        ```sh
-        sudo gitlab-ctl reconfigure
-        ```
+      ```sh
+      sudo gitlab-ctl reconfigure
+      ```
 
-    1. **[secondary]** Run the PostgreSQL upgrade command:
+   1. **(secondary)** Run the PostgreSQL upgrade command:
 
-        ```sh
-        sudo gitlab-ctl pg-upgrade
-        ```
+      ```sh
+      sudo gitlab-ctl pg-upgrade
+      ```
 
-    1. **[secondary]** See the stored credentials for the database that you will
-       need to re-initialize the replication:
+   1. **(secondary)** See the stored credentials for the database that you will
+      need to re-initialize the replication:
 
-        ```sh
-        sudo grep -s primary_conninfo /var/opt/gitlab/recovery.conf
-        ```
+      ```sh
+      sudo grep -s primary_conninfo /var/opt/gitlab/recovery.conf
+      ```
 
-    1. **[secondary]** Create the `replica.sh` script as described in the
-       [database configuration document][database-source-replication].
+   1. **(secondary)** Save the snippet below in a file, let's say `/tmp/replica.sh`. Modify the
+      embedded paths if necessary:
 
-    1. 1. **[secondary]** Save the snippet below in a file, let's say `/tmp/replica.sh`. Modify the
-       embedded paths if necessary:
+      ```
+      #!/bin/bash
 
-        ```
-        #!/bin/bash
+      PORT="5432"
+      USER="gitlab_replicator"
+      echo ---------------------------------------------------------------
+      echo WARNING: Make sure this script is run from the secondary server
+      echo ---------------------------------------------------------------
+      echo
+      echo Enter the IP or FQDN of the primary PostgreSQL server
+      read HOST
+      echo Enter the password for $USER@$HOST
+      read -s PASSWORD
+      echo Enter the required sslmode
+      read SSLMODE
 
-        PORT="5432"
-        USER="gitlab_replicator"
-        echo ---------------------------------------------------------------
-        echo WARNING: Make sure this script is run from the secondary server
-        echo ---------------------------------------------------------------
-        echo
-        echo Enter the IP or FQDN of the primary PostgreSQL server
-        read HOST
-        echo Enter the password for $USER@$HOST
-        read -s PASSWORD
-        echo Enter the required sslmode
-        read SSLMODE
+      echo Stopping PostgreSQL and all GitLab services
+      sudo service gitlab stop
+      sudo service postgresql stop
 
-        echo Stopping PostgreSQL and all GitLab services
-        sudo service gitlab stop
-        sudo service postgresql stop
+      echo Backing up postgresql.conf
+      sudo -u postgres mv /var/opt/gitlab/postgresql/data/postgresql.conf /var/opt/gitlab/postgresql/
 
-        echo Backing up postgresql.conf
-        sudo -u postgres mv /var/opt/gitlab/postgresql/data/postgresql.conf /var/opt/gitlab/postgresql/
+      echo Cleaning up old cluster directory
+      sudo -u postgres rm -rf /var/opt/gitlab/postgresql/data
 
-        echo Cleaning up old cluster directory
-        sudo -u postgres rm -rf /var/opt/gitlab/postgresql/data
+      echo Starting base backup as the replicator user
+      echo Enter the password for $USER@$HOST
+      sudo -u postgres /opt/gitlab/embedded/bin/pg_basebackup -h $HOST -D /var/opt/gitlab/postgresql/data -U gitlab_replicator -v -x -P
 
-        echo Starting base backup as the replicator user
-        echo Enter the password for $USER@$HOST
-        sudo -u postgres /opt/gitlab/embedded/bin/pg_basebackup -h $HOST -D /var/opt/gitlab/postgresql/data -U gitlab_replicator -v -x -P
+      echo Writing recovery.conf file
+      sudo -u postgres bash -c "cat > /var/opt/gitlab/postgresql/data/recovery.conf <<- _EOF1_
+        standby_mode = 'on'
+        primary_conninfo = 'host=$HOST port=$PORT user=$USER password=$PASSWORD sslmode=$SSLMODE'
+      _EOF1_
+      "
 
-        echo Writing recovery.conf file
-        sudo -u postgres bash -c "cat > /var/opt/gitlab/postgresql/data/recovery.conf <<- _EOF1_
-          standby_mode = 'on'
-          primary_conninfo = 'host=$HOST port=$PORT user=$USER password=$PASSWORD sslmode=$SSLMODE'
-        _EOF1_
-        "
+      echo Restoring postgresql.conf
+      sudo -u postgres mv /var/opt/gitlab/postgresql/postgresql.conf /var/opt/gitlab/postgresql/data/
 
-        echo Restoring postgresql.conf
-        sudo -u postgres mv /var/opt/gitlab/postgresql/postgresql.conf /var/opt/gitlab/postgresql/data/
+      echo Starting PostgreSQL
+      sudo service postgresql start
+      ```
 
-        echo Starting PostgreSQL
-        sudo service postgresql start
-        ```
+   1. **(secondary)** Run the recovery script using the credentials from the
+      previous step:
 
-    1. **[secondary]** Run the recovery script using the credentials from the
-       previous step:
+      ```sh
+      sudo bash /tmp/replica.sh
+      ```
 
-        ```sh
-        sudo bash /tmp/replica.sh
-        ```
+   1. **(secondary)** Reconfigure GitLab:
 
-    1. **[secondary]** Reconfigure GitLab:
+      ```sh
+      sudo gitlab-ctl reconfigure
+      ```
 
-        ```sh
-        sudo gitlab-ctl reconfigure
-        ```
+   1. **(secondary)** Start all services:
 
-    1. **[secondary]** Start all services:
+      ```sh
+      sudo gitlab-ctl start
+      ```
 
-        ```sh
-        sudo gitlab-ctl start
-        ```
+   1. **(secondary)** Repeat the steps for the remaining **secondary** nodes.
 
-    1. **[secondary]** Repeat the steps for the remaining **secondary** nodes.
-
-1. **[primary]** After all **secondary** nodes are updated, start all services in
+1. **(primary)** After all **secondary** nodes are updated, start all services in
    **primary** node:
 
-    ```sh
-    sudo gitlab-ctl start
-    ```
-
-## Check status after updating
-
-Now that the update process is complete, you may want to check whether
-everything is working correctly:
-
-1. Run the Geo raketask on all nodes, everything should be green:
-
-    ```sh
-    sudo gitlab-rake gitlab:geo:check
-    ```
-
-1. Check the **primary** node's Geo dashboard for any errors.
-1. Test the data replication by pushing code to the **primary** node and see if it
-   is received by **secondary** nodes.
+   ```sh
+   sudo gitlab-ctl start
+   ```
 
-## Update tracking database on **secondary** node
+### Update tracking database on **secondary** node
 
 After updating a **secondary** node, you might need to run migrations on
 the tracking database. The tracking database was added in GitLab 9.1,
@@ -435,9 +440,9 @@ and it is required since 10.0.
 
 1. Run database migrations on tracking database:
 
-    ```sh
-    sudo gitlab-rake geo:db:migrate
-    ```
+   ```sh
+   sudo gitlab-rake geo:db:migrate
+   ```
 
 1. Repeat this step for each **secondary** node.
 
diff --git a/doc/administration/geo/replication/using_a_geo_server.md b/doc/administration/geo/replication/using_a_geo_server.md
index f1f1fe48748..55b5d486676 100644
--- a/doc/administration/geo/replication/using_a_geo_server.md
+++ b/doc/administration/geo/replication/using_a_geo_server.md
@@ -1,6 +1,6 @@
 [//]: # (Please update EE::GitLab::GeoGitAccess::GEO_SERVER_DOCS_URL if this file is moved)
 
-# Using a Geo Server **[PREMIUM ONLY]**
+# Using a Geo Server **(PREMIUM ONLY)**
 
 After you set up the [database replication and configure the Geo nodes][req], use your closest GitLab node as you would a normal standalone GitLab instance.
 
diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md
index 53a85dfad6c..150494c47e5 100644
--- a/doc/administration/gitaly/index.md
+++ b/doc/administration/gitaly/index.md
@@ -2,127 +2,124 @@
 
 [Gitaly](https://gitlab.com/gitlab-org/gitaly) is the service that
 provides high-level RPC access to Git repositories. Without it, no other
-components can read or write Git data.
+components can read or write Git data. GitLab components that access Git
+repositories (gitlab-rails, gitlab-shell, gitlab-workhorse, etc.) act as clients
+to Gitaly. End users do not have direct access to Gitaly.
 
-GitLab components that access Git repositories (gitlab-rails,
-gitlab-shell, gitlab-workhorse) act as clients to Gitaly. End users do
-not have direct access to Gitaly.
+In the rest of this page, Gitaly server is referred to the standalone node that
+only runs Gitaly, and Gitaly client to the GitLab Rails node that runs all other
+processes except Gitaly.
 
 ## Configuring Gitaly
 
 The Gitaly service itself is configured via a TOML configuration file.
-This file is documented [in the gitaly
+This file is documented [in the Gitaly
 repository](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/configuration/README.md).
 
-To change a Gitaly setting in Omnibus you can use
-`gitaly['my_setting']` in `/etc/gitlab/gitlab.rb`. Changes will be applied
-when you run `gitlab-ctl reconfigure`.
+In case you want to change some of its settings:
 
-```ruby
-gitaly['prometheus_listen_addr'] = 'localhost:9236'
-```
-
-To change a Gitaly setting in installations from source you can edit
-`/home/git/gitaly/config.toml`. Changes will be applied when you run
-`service gitlab restart`.
+**For Omnibus GitLab**
 
-```toml
-prometheus_listen_addr = "localhost:9236"
-```
+1. Edit `/etc/gitlab/gitlab.rb` and add or change the [Gitaly settings](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/1dd07197c7e5ae23626aad5a4a070a800b670380/files/gitlab-config-template/gitlab.rb.template#L1622-1676).
+1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
 
-## Client-side GRPC logs
+**For installations from source**
 
-Gitaly uses the [gRPC](https://grpc.io/) RPC framework. The Ruby gRPC
-client has its own log file which may contain useful information when
-you are seeing Gitaly errors. You can control the log level of the
-gRPC client with the `GRPC_LOG_LEVEL` environment variable. The
-default level is `WARN`.
+1. Edit `/home/git/gitaly/config.toml` and add or change the [Gitaly settings](https://gitlab.com/gitlab-org/gitaly/blob/master/config.toml.example).
+1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source).
 
 ## Running Gitaly on its own server
 
-> This is an optional way to deploy Gitaly which can benefit GitLab
+This is an optional way to deploy Gitaly which can benefit GitLab
 installations that are larger than a single machine. Most
 installations will be better served with the default configuration
 used by Omnibus and the GitLab source installation guide.
 
 Starting with GitLab 11.4, Gitaly is able to serve all Git requests without
-needed a shared NFS mount for Git repository data.
+requiring a shared NFS mount for Git repository data.
 Between 11.4 and 11.8 the exception was the
-[Elastic Search indexer](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer).
+[Elasticsearch indexer](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer).
 But since 11.8 the indexer uses Gitaly for data access as well. NFS can still
 be leveraged for redudancy on block level of the Git data. But only has to
 be mounted on the Gitaly server.
 
-NOTE: **Note:** While Gitaly can be used as a replacement for NFS, we do not recommend
-using EFS as it may impact GitLab's performance. Please review the [relevant documentation](../high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs)
+Starting with GitLab 11.8, it is possible to use ElasticSearch in conjunction with
+a Gitaly setup that isn't utilising NFS. In order to use ElasticSearch in this
+scenario, the [new repository indexer](../../integration/elasticsearch.md#elasticsearch-repository-indexer-beta)
+needs to be enabled in your GitLab configuration.
+
+NOTE: **Note:** While Gitaly can be used as a replacement for NFS, it's not recommended
+to use EFS as it may impact GitLab's performance. Review the [relevant documentation](../high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs)
 for more details.
 
 ### Network architecture
 
--   gitlab-rails shards repositories into "repository storages"
--   `gitlab-rails/config/gitlab.yml` contains a map from storage names to
-    (Gitaly address, Gitaly token) pairs
--   the `storage name` -\> `(Gitaly address, Gitaly token)` map in
-    `gitlab.yml` is the single source of truth for the Gitaly network
-    topology
--   a (Gitaly address, Gitaly token) corresponds to a Gitaly server
--   a Gitaly server hosts one or more storages
--   Gitaly addresses must be specified in such a way that they resolve
-    correctly for ALL Gitaly clients
--   Gitaly clients are: unicorn, sidekiq, gitlab-workhorse,
-    gitlab-shell, Elasticsearch Indexer, and Gitaly itself
--   special case: a Gitaly server must be able to make RPC calls **to
-    itself** via its own (Gitaly address, Gitaly token) pair as
-    specified in `gitlab-rails/config/gitlab.yml`
--   Gitaly servers must not be exposed to the public internet
-
-Gitaly network traffic is unencrypted by default, but supports
-[TLS](#tls-support). Authentication is done through a static token.
-
-NOTE: **Note:** Gitaly network traffic is unencrypted so we recommend a firewall to
-restrict access to your Gitaly server.
+The following list depicts what the network architecture of Gitaly is:
+
+- GitLab Rails shards repositories into [repository storages](../repository_storage_paths.md).
+- `/config/gitlab.yml` contains a map from storage names to
+  `(Gitaly address, Gitaly token)` pairs.
+- the `storage name` -\> `(Gitaly address, Gitaly token)` map in
+  `/config/gitlab.yml` is the single source of truth for the Gitaly network
+  topology.
+- A `(Gitaly address, Gitaly token)` corresponds to a Gitaly server.
+- A Gitaly server hosts one or more storages.
+- Gitaly addresses must be specified in such a way that they resolve
+  correctly for ALL Gitaly clients.
+- Gitaly clients are: Unicorn, Sidekiq, gitlab-workhorse,
+  gitlab-shell, Elasticsearch Indexer, and Gitaly itself.
+- A Gitaly server must be able to make RPC calls **to itself** via its own
+  `(Gitaly address, Gitaly token)` pair as specified in `/config/gitlab.yml`.
+- Gitaly servers must not be exposed to the public internet as Gitaly's network
+  traffic is unencrypted by default. The use of firewall is highly recommended
+  to restrict access to the Gitaly server. Another option is to
+  [use TLS](#tls-support).
+- Authentication is done through a static token which is shared among the Gitaly
+  and GitLab Rails nodes.
 
 Below we describe how to configure a Gitaly server at address
 `gitaly.internal:8075` with secret token `abc123secret`. We assume
 your GitLab installation has two repository storages, `default` and
 `storage1`.
 
-### Installation
+### 1. Installation
 
-First install Gitaly using either Omnibus or from source.
+First install Gitaly using either Omnibus GitLab or install it from source:
 
-Omnibus: [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab
-package you want using **steps 1 and 2** from the GitLab downloads page but
-**_do not_** provide the `EXTERNAL_URL=` value.
+- For Omnibus GitLab: [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab
+  package you want using **steps 1 and 2** from the GitLab downloads page but
+  **_do not_** provide the `EXTERNAL_URL=` value.
+- From source: [Install Gitaly](../../install/installation.md#install-gitaly).
 
-Source: [Install Gitaly](../../install/installation.md#install-gitaly)
+### 2. Client side token configuration
 
-### Client side token configuration
+Configure a token on the instance that runs the GitLab Rails application.
 
-Configure a token on the client side.
+**For Omnibus GitLab**
 
-Omnibus installations:
+1. On the client node(s), edit `/etc/gitlab/gitlab.rb`:
 
-```ruby
-# /etc/gitlab/gitlab.rb
-gitlab_rails['gitaly_token'] = 'abc123secret'
-```
+   ```ruby
+   gitlab_rails['gitaly_token'] = 'abc123secret'
+   ```
 
-Source installations:
+1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
 
-```yaml
-# /home/git/gitlab/config/gitlab.yml
-gitlab:
-  gitaly:
-    token: 'abc123secret'
-```
+**For installations from source**
 
-You need to reconfigure (Omnibus) or restart (source) for these
-changes to be picked up.
+1. On the client node(s), edit `/home/git/gitlab/config/gitlab.yml`:
 
-### Gitaly server configuration
+   ```yaml
+   gitlab:
+     gitaly:
+       token: 'abc123secret'
+   ```
 
-Next, on the Gitaly server, we need to configure storage paths, enable
+1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source).
+
+### 3. Gitaly server configuration
+
+Next, on the Gitaly server, you need to configure storage paths, enable
 the network listener and configure the token.
 
 NOTE: **Note:** if you want to reduce the risk of downtime when you enable
@@ -137,129 +134,194 @@ the Gitaly server. The easiest way to accomplish this is to copy `/etc/gitlab/gi
 from an existing GitLab server to the Gitaly server. Without this shared secret,
 Git operations in GitLab will result in an API error.
 
-NOTE: **Note:** In most or all cases the storage paths below end in `/repositories` which is
-different than `path` in `git_data_dirs` of Omnibus installations. Check the
-directory layout on your Gitaly server to be sure.
-
-Omnibus installations:
-
-<!--
-updates to following example must also be made at
-https://gitlab.com/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab
--->
-
-```ruby
-# /etc/gitlab/gitlab.rb
-
-# Avoid running unnecessary services on the Gitaly server
-postgresql['enable'] = false
-redis['enable'] = false
-nginx['enable'] = false
-prometheus['enable'] = false
-unicorn['enable'] = false
-sidekiq['enable'] = false
-gitlab_workhorse['enable'] = false
-
-# Prevent database connections during 'gitlab-ctl reconfigure'
-gitlab_rails['rake_cache_clear'] = false
-gitlab_rails['auto_migrate'] = false
-
-# Configure the gitlab-shell API callback URL. Without this, `git push` will
-# fail. This can be your 'front door' GitLab URL or an internal load
-# balancer.
-# Don't forget to copy `/etc/gitlab/gitlab-secrets.json` from web server to Gitaly server.
-gitlab_rails['internal_api_url'] = 'https://gitlab.example.com'
-
-# Make Gitaly accept connections on all network interfaces. You must use
-# firewalls to restrict access to this address/port.
-gitaly['listen_addr'] = "0.0.0.0:8075"
-gitaly['auth_token'] = 'abc123secret'
-
-gitaly['storage'] = [
-  { 'name' => 'default', 'path' => '/mnt/gitlab/default/repositories' },
-  { 'name' => 'storage1', 'path' => '/mnt/gitlab/storage1/repositories' },
-]
-
-# To use TLS for Gitaly you need to add
-gitaly['tls_listen_addr'] = "0.0.0.0:9999"
-gitaly['certificate_path'] = "path/to/cert.pem"
-gitaly['key_path'] = "path/to/key.pem"
-```
+NOTE: **Note:**
+In most or all cases, the storage paths below end in `/repositories` which is
+not that case with `path` in `git_data_dirs` of Omnibus GitLab installations.
+Check the directory layout on your Gitaly server to be sure.
 
-Source installations:
+**For Omnibus GitLab**
 
-```toml
-# /home/git/gitaly/config.toml
-listen_addr = '0.0.0.0:8075'
-tls_listen_addr = '0.0.0.0:9999'
+1. Edit `/etc/gitlab/gitlab.rb`:
 
-[tls]
-certificate_path = /path/to/cert.pem
-key_path = /path/to/key.pem
+   <!--
+   updates to following example must also be made at
+   https://gitlab.com/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab
+   -->
 
-[auth]
-token = 'abc123secret'
+   ```ruby
+   # /etc/gitlab/gitlab.rb
 
-[[storage]]
-name = 'default'
-path = '/mnt/gitlab/default/repositories'
+   # Avoid running unnecessary services on the Gitaly server
+   postgresql['enable'] = false
+   redis['enable'] = false
+   nginx['enable'] = false
+   prometheus['enable'] = false
+   unicorn['enable'] = false
+   sidekiq['enable'] = false
+   gitlab_workhorse['enable'] = false
 
-[[storage]]
-name = 'storage1'
-path = '/mnt/gitlab/storage1/repositories'
-```
+   # Prevent database connections during 'gitlab-ctl reconfigure'
+   gitlab_rails['rake_cache_clear'] = false
+   gitlab_rails['auto_migrate'] = false
+
+   # Configure the gitlab-shell API callback URL. Without this, `git push` will
+   # fail. This can be your 'front door' GitLab URL or an internal load
+   # balancer.
+   # Don't forget to copy `/etc/gitlab/gitlab-secrets.json` from web server to Gitaly server.
+   gitlab_rails['internal_api_url'] = 'https://gitlab.example.com'
+
+   # Make Gitaly accept connections on all network interfaces. You must use
+   # firewalls to restrict access to this address/port.
+   gitaly['listen_addr'] = "0.0.0.0:8075"
+   gitaly['auth_token'] = 'abc123secret'
+
+   gitaly['storage'] = [
+     { 'name' => 'default' },
+     { 'name' => 'storage1' },
+   ]
+
+   # To use TLS for Gitaly you need to add
+   gitaly['tls_listen_addr'] = "0.0.0.0:9999"
+   gitaly['certificate_path'] = "path/to/cert.pem"
+   gitaly['key_path'] = "path/to/key.pem"
+   ```
+
+   NOTE: **Note:**
+   In some cases, you'll have to set `path` for `gitaly['storage']` in the
+   format `'path' => '/mnt/gitlab/<storage name>/repositories'`.
+
+1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
+
+**For installations from source**
+
+1. On the client node(s), edit `/home/git/gitaly/config.toml`:
+
+   ```toml
+   listen_addr = '0.0.0.0:8075'
+   tls_listen_addr = '0.0.0.0:9999'
+
+   [tls]
+   certificate_path = /path/to/cert.pem
+   key_path = /path/to/key.pem
+
+   [auth]
+   token = 'abc123secret'
+
+   [[storage]]
+   name = 'default'
 
-Again, reconfigure (Omnibus) or restart (source).
+   [[storage]]
+   name = 'storage1'
+   ```
 
-### Converting clients to use the Gitaly server
+   NOTE: **Note:**
+   In some cases, you'll have to set `path` for each `[[storage]]` in the
+   format `path = '/mnt/gitlab/<storage name>/repositories'`.
 
-Now as the final step update the client machines to switch from using
-their local Gitaly service to the new Gitaly server you just
-configured. This is a risky step because if there is any sort of
-network, firewall, or name resolution problem preventing your GitLab
-server from reaching the Gitaly server then all Gitaly requests will
-fail.
+1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source).
 
-Additionally, you need to 
+### 4. Converting clients to use the Gitaly server
+
+As the final step, you need to update the client machines to switch from using
+their local Gitaly service to the new Gitaly server you just configured. This
+is a risky step because if there is any sort of network, firewall, or name
+resolution problem preventing your GitLab server from reaching the Gitaly server,
+then all Gitaly requests will fail.
+
+Additionally, you need to
 [disable Rugged if previously manually enabled](../high_availability/nfs.md#improving-nfs-performance-with-gitlab).
 
 We assume that your Gitaly server can be reached at
 `gitaly.internal:8075` from your GitLab server, and that Gitaly can read and
 write to `/mnt/gitlab/default` and `/mnt/gitlab/storage1` respectively.
 
-Omnibus installations:
+**For Omnibus GitLab**
 
-```ruby
-# /etc/gitlab/gitlab.rb
-git_data_dirs({
-  'default' => { 'gitaly_address' => 'tcp://gitaly.internal:8075' },
-  'storage1' => { 'gitaly_address' => 'tcp://gitaly.internal:8075' },
-})
+1. Edit `/etc/gitlab/gitlab.rb`:
 
-gitlab_rails['gitaly_token'] = 'abc123secret'
-```
+   ```ruby
+   git_data_dirs({
+     'default' => { 'gitaly_address' => 'tcp://gitaly.internal:8075' },
+     'storage1' => { 'gitaly_address' => 'tcp://gitaly.internal:8075' },
+   })
 
-Source installations:
+   gitlab_rails['gitaly_token'] = 'abc123secret'
+   ```
 
-```yaml
-# /home/git/gitlab/config/gitlab.yml
-gitlab:
-  repositories:
-    storages:
-      default:
-        gitaly_address: tcp://gitaly.internal:8075
-      storage1:
-        gitaly_address: tcp://gitaly.internal:8075
+   NOTE: **Note:**
+   In some cases, you'll have to set `path` for each `git_data_dirs` in the
+   format `'path' => '/mnt/gitlab/<storage name>'`.
 
-  gitaly:
-    token: 'abc123secret'
-```
+1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
+1. Tail the logs to see the requests:
+
+   ```sh
+   sudo gitlab-ctl tail gitaly
+   ```
+
+**For installations from source**
+
+1. Edit `/home/git/gitlab/config/gitlab.yml`:
+
+   ```yaml
+   gitlab:
+     repositories:
+       storages:
+         default:
+           gitaly_address: tcp://gitaly.internal:8075
+         storage1:
+           gitaly_address: tcp://gitaly.internal:8075
+
+     gitaly:
+       token: 'abc123secret'
+   ```
+
+   NOTE: **Note:**
+   In some cases, you'll have to set `path` for each of the `storages` in the
+   format `path: /mnt/gitlab/<storage name>/repositories`.
+
+1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source).
+1. Tail the logs to see the requests:
+
+   ```sh
+   tail -f /home/git/gitlab/log/gitaly.log
+   ```
+
+When you tail the Gitaly logs on your Gitaly server you should see requests
+coming in. One sure way to trigger a Gitaly request is to clone a repository
+from your GitLab server over HTTP.
+
+### Disabling the Gitaly service in a cluster environment
+
+If you are running Gitaly [as a remote
+service](#running-gitaly-on-its-own-server) you may want to disable
+the local Gitaly service that runs on your GitLab server by default.
+Disabling Gitaly only makes sense when you run GitLab in a custom
+cluster configuration, where different services run on different
+machines. Disabling Gitaly on all machines in the cluster is not a
+valid configuration.
+
+To disable Gitaly on a client node:
+
+**For Omnibus GitLab**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitaly['enable'] = false
+   ```
+
+1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
+
+**For installations from source**
 
-Now reconfigure (Omnibus) or restart (source). When you tail the
-Gitaly logs on your Gitaly server (`sudo gitlab-ctl tail gitaly` or
-`tail -f /home/git/gitlab/log/gitaly.log`) you should see requests
-coming in. One sure way to trigger a Gitaly request is to clone a
-repository from your GitLab server over HTTP.
+1. Edit `/etc/default/gitlab`:
+
+   ```shell
+   gitaly_enabled=false
+   ```
+
+1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source).
 
 ## TLS support
 
@@ -267,172 +329,163 @@ repository from your GitLab server over HTTP.
 
 Gitaly supports TLS encryption. To be able to communicate
 with a Gitaly instance that listens for secure connections you will need to use `tls://` url
-scheme in the `gitaly_address` of the corresponding storage entry in the gitlab configuration.
+scheme in the `gitaly_address` of the corresponding storage entry in the GitLab configuration.
 
-The admin needs to bring their own certificate as we do not provide that automatically.
-The certificate to be used needs to be installed on all Gitaly nodes and on all client nodes that communicate with it following procedures described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates).
+You will need to bring your own certificates as this isn't provided automatically.
+The certificate to be used needs to be installed on all Gitaly nodes and on all
+client nodes that communicate with it following the procedure described in
+[GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates).
 
-Note that it is possible to configure Gitaly servers with both an
+NOTE: **Note:**
+It is possible to configure Gitaly servers with both an
 unencrypted listening address `listen_addr` and an encrypted listening
 address `tls_listen_addr` at the same time. This allows you to do a
 gradual transition from unencrypted to encrypted traffic, if necessary.
 
-To observe what type of connections are actually being used in a
-production environment you can use the following Prometheus query:
+To configure Gitaly with TLS:
 
-```
-sum(rate(gitaly_connections_total[5m])) by (type)
-```
+**For Omnibus GitLab**
 
-### Example TLS configuration
+1. On the client nodes, edit `/etc/gitlab/gitlab.rb`:
 
-### Omnibus installations:
+   ```ruby
+   git_data_dirs({
+     'default' => { 'gitaly_address' => 'tls://gitaly.internal:9999' },
+     'storage1' => { 'gitaly_address' => 'tls://gitaly.internal:9999' },
+   })
 
-#### On client nodes:
+   gitlab_rails['gitaly_token'] = 'abc123secret'
+   ```
 
-```ruby
-# /etc/gitlab/gitlab.rb
-git_data_dirs({
-  'default' => { 'path' => '/mnt/gitlab/default', 'gitaly_address' => 'tls://gitaly.internal:9999' },
-  'storage1' => { 'path' => '/mnt/gitlab/storage1', 'gitaly_address' => 'tls://gitaly.internal:9999' },
-})
+1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
+1. On the Gitaly server nodes, edit `/etc/gitlab/gitlab.rb`:
 
-gitlab_rails['gitaly_token'] = 'abc123secret'
-```
+   ```ruby
+   gitaly['tls_listen_addr'] = "0.0.0.0:9999"
+   gitaly['certificate_path'] = "path/to/cert.pem"
+   gitaly['key_path'] = "path/to/key.pem"
+   ```
 
-#### On Gitaly server nodes:
+1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
 
-```ruby
-gitaly['tls_listen_addr'] = "0.0.0.0:9999"
-gitaly['certificate_path'] = "path/to/cert.pem"
-gitaly['key_path'] = "path/to/key.pem"
-```
+**For installations from source**
 
-### Source installations:
+1. On the client nodes, edit `/home/git/gitlab/config/gitlab.yml`:
 
-#### On client nodes:
+   ```yaml
+   gitlab:
+     repositories:
+       storages:
+         default:
+           gitaly_address: tls://gitaly.internal:9999
+         storage1:
+           gitaly_address: tls://gitaly.internal:9999
 
-```yaml
-# /home/git/gitlab/config/gitlab.yml
-gitlab:
-  repositories:
-    storages:
-      default:
-        path: /mnt/gitlab/default/repositories
-        gitaly_address: tls://gitaly.internal:9999
-      storage1:
-        path: /mnt/gitlab/storage1/repositories
-        gitaly_address: tls://gitaly.internal:9999
+     gitaly:
+       token: 'abc123secret'
+   ```
 
-  gitaly:
-    token: 'abc123secret'
-```
+   NOTE: **Note:**
+   In some cases, you'll have to set `path` for each of the `storages` in the
+   format `path: /mnt/gitlab/<storage name>/repositories`.
+
+1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source).
+1. On the Gitaly server nodes, edit `/home/git/gitaly/config.toml`:
 
-#### On Gitaly server nodes:
+   ```toml
+   tls_listen_addr = '0.0.0.0:9999'
 
-```toml
-# /home/git/gitaly/config.toml
-tls_listen_addr = '0.0.0.0:9999'
+   [tls]
+   certificate_path = '/path/to/cert.pem'
+   key_path = '/path/to/key.pem'
+   ```
 
-[tls]
-certificate_path = '/path/to/cert.pem'
-key_path = '/path/to/key.pem'
+1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source).
+
+To observe what type of connections are actually being used in a
+production environment you can use the following Prometheus query:
+
+```
+sum(rate(gitaly_connections_total[5m])) by (type)
 ```
 
-## Gitaly-ruby
+## `gitaly-ruby`
 
-Gitaly was developed to replace Ruby application code in gitlab-ce/ee.
+Gitaly was developed to replace the Ruby application code in GitLab.
 In order to save time and/or avoid the risk of rewriting existing
 application logic, in some cases we chose to copy some application code
-from gitlab-ce into Gitaly almost as-is. To be able to run that code, we
-made gitaly-ruby, which is a sidecar process for the main Gitaly Go
-process. Some examples of things that are implemented in gitaly-ruby are
-RPC's that deal with wiki's, and RPC's that create commits on behalf of
+from GitLab into Gitaly almost as-is. To be able to run that code,
+`gitaly-ruby` was created, which is a "sidecar" process for the main Gitaly Go
+process. Some examples of things that are implemented in `gitaly-ruby` are
+RPCs that deal with wikis, and RPCs that create commits on behalf of
 a user, such as merge commits.
 
-### Number of gitaly-ruby workers
+### Number of `gitaly-ruby` workers
 
-Gitaly-ruby has much less capacity than Gitaly itself. If your Gitaly
-server has to handle a lot of request, the default setting of having
-just 1 active gitaly-ruby sidecar might not be enough. If you see
-ResourceExhausted errors from Gitaly it's very likely that you have not
-enough gitaly-ruby capacity.
+`gitaly-ruby` has much less capacity than Gitaly itself. If your Gitaly
+server has to handle a lot of requests, the default setting of having
+just one active `gitaly-ruby` sidecar might not be enough. If you see
+`ResourceExhausted` errors from Gitaly, it's very likely that you have not
+enough `gitaly-ruby` capacity.
 
-You can increase the number of gitaly-ruby processes on your Gitaly
+You can increase the number of `gitaly-ruby` processes on your Gitaly
 server with the following settings.
 
-Omnibus:
+**For Omnibus GitLab**
 
-```ruby
-# /etc/gitlab/gitlab.rb
-# Default is 2 workers. The minimum is 2; 1 worker is always reserved as
-# a passive stand-by.
-gitaly['ruby_num_workers'] = 4
-```
+1. Edit `/etc/gitlab/gitlab.rb`:
 
-Source:
+   ```ruby
+   # Default is 2 workers. The minimum is 2; 1 worker is always reserved as
+   # a passive stand-by.
+   gitaly['ruby_num_workers'] = 4
+   ```
 
-```toml
-# /home/git/gitaly/config.toml
-[gitaly-ruby]
-num_workers = 4
-```
+1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
 
-### Observing gitaly-ruby traffic
+**For installations from source**
 
-Gitaly-ruby is a somewhat hidden, internal implementation detail of
-Gitaly. There is not that much visibility into what goes on inside
-gitaly-ruby processes.
+1. Edit `/home/git/gitaly/config.toml`:
 
-If you have Prometheus set up to scrape your Gitaly process, you can see
-request rates and error codes for individual RPC's in gitaly-ruby by
-querying `grpc_client_handled_total`. Strictly speaking this metric does
-not differentiate between gitaly-ruby and other RPC's, but in practice
-(as of GitLab 11.9), all gRPC calls made by Gitaly itself are internal
-calls from the main Gitaly process to one of its gitaly-ruby sidecars.
-
-Assuming your `grpc_client_handled_total` counter only observes Gitaly,
-the following query shows you RPC's are (most likely) internally
-implemented as calls to gitaly-ruby.
-
-```
-sum(rate(grpc_client_handled_total[5m])) by (grpc_method) > 0
-```
+   ```toml
+   [gitaly-ruby]
+   num_workers = 4
+   ```
 
-## Disabling or enabling the Gitaly service in a cluster environment
+1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source).
 
-If you are running Gitaly [as a remote
-service](#running-gitaly-on-its-own-server) you may want to disable
-the local Gitaly service that runs on your GitLab server by default.
+## Eliminating NFS altogether
 
-> 'Disabling Gitaly' only makes sense when you run GitLab in a custom
-cluster configuration, where different services run on different
-machines. Disabling Gitaly on all machines in the cluster is not a
-valid configuration.
+If you are planning to use Gitaly without NFS for your storage needs
+and want to eliminate NFS from your environment altogether, there are
+a few things that you need to do:
 
-If you are setting up a GitLab cluster where Gitaly does not need to
-run on all machines, you can disable the Gitaly service in your
-Omnibus installation, add the following line to `/etc/gitlab/gitlab.rb`:
+1. Make sure the [`git` user home directory](https://docs.gitlab.com/omnibus/settings/configuration.html#moving-the-home-directory-for-a-user) is on local disk.
+1. Configure [database lookup of SSH keys](../operations/fast_ssh_key_lookup.md)
+   to eliminate the need for a shared authorized_keys file.
+1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage)
+   including [live tracing](../job_traces.md#new-live-trace-architecture).
+1. Configure [object storage for LFS objects](../../workflow/lfs/lfs_administration.md#storing-lfs-objects-in-remote-object-storage).
+1. Configure [object storage for uploads](../uploads.md#using-object-storage-core-only).
 
-```ruby
-gitaly['enable'] = false
-```
+NOTE: **Note:**
+One current feature of GitLab that still requires a shared directory (NFS) is
+[GitLab Pages](../../user/project/pages/index.md).
+There is [work in progress](https://gitlab.com/gitlab-org/gitlab-pages/issues/196)
+to eliminate the need for NFS to support GitLab Pages.
 
-When you run `gitlab-ctl reconfigure` the Gitaly service will be
-disabled.
+## Troubleshooting Gitaly
 
-To disable the Gitaly service in a GitLab cluster where you installed
-GitLab from source, add the following to `/etc/default/gitlab` on the
-machine where you want to disable Gitaly.
+### Commits, pushes, and clones return a 401
 
-```shell
-gitaly_enabled=false
+```
+remote: GitLab: 401 Unauthorized
 ```
 
-When you run `service gitlab restart` Gitaly will be disabled on this
-particular machine.
+You will need to sync your `gitlab-secrets.json` file with your GitLab
+app nodes.
 
-## Troubleshooting Gitaly in production
+### `gitaly-debug`
 
 Since GitLab 11.6, Gitaly comes with a command-line tool called
 `gitaly-debug` that can be run on a Gitaly server to aid in
@@ -442,3 +495,123 @@ Git clone speed for a specific repository on the server.
 
 For an up to date list of sub-commands see [the gitaly-debug
 README](https://gitlab.com/gitlab-org/gitaly/blob/master/cmd/gitaly-debug/README.md).
+
+### Client side GRPC logs
+
+Gitaly uses the [gRPC](https://grpc.io/) RPC framework. The Ruby gRPC
+client has its own log file which may contain useful information when
+you are seeing Gitaly errors. You can control the log level of the
+gRPC client with the `GRPC_LOG_LEVEL` environment variable. The
+default level is `WARN`.
+
+### Observing `gitaly-ruby` traffic
+
+[`gitaly-ruby`](#gitaly-ruby) is an internal implementation detail of Gitaly,
+so, there's not that much visibility into what goes on inside
+`gitaly-ruby` processes.
+
+If you have Prometheus set up to scrape your Gitaly process, you can see
+request rates and error codes for individual RPCs in `gitaly-ruby` by
+querying `grpc_client_handled_total`. Strictly speaking, this metric does
+not differentiate between `gitaly-ruby` and other RPCs, but in practice
+(as of GitLab 11.9), all gRPC calls made by Gitaly itself are internal
+calls from the main Gitaly process to one of its `gitaly-ruby` sidecars.
+
+Assuming your `grpc_client_handled_total` counter only observes Gitaly,
+the following query shows you RPCs are (most likely) internally
+implemented as calls to `gitaly-ruby`:
+
+```
+sum(rate(grpc_client_handled_total[5m])) by (grpc_method) > 0
+```
+
+### Repository changes fail with a `401 Unauthorized` error
+
+If you're running Gitaly on its own server and notice that users can
+successfully clone and fetch repositories (via both SSH and HTTPS), but can't
+push to them or make changes to the repository in the web UI without getting a
+`401 Unauthorized` message, then it's possible Gitaly is failing to authenticate
+with the other nodes due to having the [wrong secrets file](#3-gitaly-server-configuration).
+
+Confirm the following are all true:
+
+- When any user performs a `git push` to any repository on this Gitaly node, it
+  fails with the following error (note the `401 Unauthorized`):
+
+  ```sh
+  remote: GitLab: 401 Unauthorized
+  To <REMOTE_URL>
+  ! [remote rejected] branch-name -> branch-name (pre-receive hook declined)
+  error: failed to push some refs to '<REMOTE_URL>'
+  ```
+
+- When any user adds or modifies a file from the repository using the GitLab
+  UI, it immediatley fails with a red `401 Unauthorized` banner.
+- Creating a new project and [initializing it with a README](../../gitlab-basics/create-project.md#blank-projects)
+  successfully creates the project but doesn't create the README.
+- When [tailing the logs](https://docs.gitlab.com/omnibus/settings/logs.md#tail-logs-in-a-console-on-the-server) on an app node and reproducing the error, you get `401` errors
+  when reaching the `/api/v4/internal/allowed` endpoint:
+
+  ```sh
+  # api_json.log
+  {
+    "time": "2019-07-18T00:30:14.967Z",
+    "severity": "INFO",
+    "duration": 0.57,
+    "db": 0,
+    "view": 0.57,
+    "status": 401,
+    "method": "POST",
+    "path": "\/api\/v4\/internal\/allowed",
+    "params": [
+      {
+        "key": "action",
+        "value": "git-receive-pack"
+      },
+      {
+        "key": "changes",
+        "value": "REDACTED"
+      },
+      {
+        "key": "gl_repository",
+        "value": "REDACTED"
+      },
+      {
+        "key": "project",
+        "value": "\/path\/to\/project.git"
+      },
+      {
+        "key": "protocol",
+        "value": "web"
+      },
+      {
+        "key": "env",
+        "value": "{\"GIT_ALTERNATE_OBJECT_DIRECTORIES\":[],\"GIT_ALTERNATE_OBJECT_DIRECTORIES_RELATIVE\":[],\"GIT_OBJECT_DIRECTORY\":null,\"GIT_OBJECT_DIRECTORY_RELATIVE\":null}"
+      },
+      {
+        "key": "user_id",
+        "value": "2"
+      },
+      {
+        "key": "secret_token",
+        "value": "[FILTERED]"
+      }
+    ],
+    "host": "gitlab.example.com",
+    "ip": "REDACTED",
+    "ua": "Ruby",
+    "route": "\/api\/:version\/internal\/allowed",
+    "queue_duration": 4.24,
+    "gitaly_calls": 0,
+    "gitaly_duration": 0,
+    "correlation_id": "XPUZqTukaP3"
+  }
+
+  # nginx_access.log
+  [IP] - - [18/Jul/2019:00:30:14 +0000] "POST /api/v4/internal/allowed HTTP/1.1" 401 30 "" "Ruby"
+  ```
+
+To fix this problem, confirm that your [`gitlab-secrets.json` file](#3-gitaly-server-configuration)
+on the Gitaly node matches the one on all other nodes. If it doesn't match,
+update the secrets file on the Gitaly node to match the others, then
+[reconfigure the node](../restart_gitlab.md#omnibus-gitlab-reconfigure).
diff --git a/doc/administration/high_availability/README.md b/doc/administration/high_availability/README.md
index d9c80b1ec59..56665ba8b9a 100644
--- a/doc/administration/high_availability/README.md
+++ b/doc/administration/high_availability/README.md
@@ -1,3 +1,7 @@
+---
+type: reference, concepts
+---
+
 # Scaling and High Availability
 
 GitLab supports several different types of clustering and high-availability.
@@ -65,6 +69,7 @@ larger one.
 - 1 Redis node
 - 1 NFS/Gitaly storage server
 - 2 or more GitLab application nodes (Unicorn, Workhorse, Sidekiq)
+- 1 Monitoring node (Prometheus, Grafana)
 
 #### Installation Instructions
 
@@ -76,6 +81,7 @@ you can continue with the next step.
 1. [Redis](redis.md#redis-in-a-scaled-environment)
 1. [Gitaly](gitaly.md) (recommended) or [NFS](nfs.md)
 1. [GitLab application nodes](gitlab.md)
+1. [Monitoring node (Prometheus and Grafana)](monitoring_node.md)
 
 ### Full Scaling
 
@@ -90,6 +96,7 @@ in size, indicating that there is contention or not enough resources.
 - 2 or more NFS/Gitaly storage servers
 - 2 or more Sidekiq nodes
 - 2 or more GitLab application nodes (Unicorn, Workhorse)
+- 1 Monitoring node (Prometheus, Grafana)
 
 ## High Availability Architecture Examples
 
@@ -133,6 +140,7 @@ the contention.
 - 3 Consul/Sentinel nodes
 - 2 or more GitLab application nodes (Unicorn, Workhorse, Sidekiq, PGBouncer)
 - 1 NFS/Gitaly server
+- 1 Monitoring node (Prometheus, Grafana)
 
 ![Horizontal architecture diagram](img/horizontal.png)
 
@@ -156,25 +164,24 @@ contention due to certain workloads.
 
 #### Reference Architecture
 
-- **Status:** Work-in-progress
 - **Supported Users (approximate):** 10,000
-- **Related Issues:** [gitlab-com/support/support-team-meta#1513](https://gitlab.com/gitlab-com/support/support-team-meta/issues/1513), 
- [gitlab-org/quality/team-tasks#110](https://gitlab.com/gitlab-org/quality/team-tasks/issues/110)
-
-The Support and Quality teams are in the process of building and performance testing
-an environment that will support about 10,000 users. The specifications below
-are a work-in-progress representation of the work so far. Quality will be 
-certifying this environment in FY20-Q2. The specifications may be adjusted 
-prior to certification based on performance testing. 
-
-- 3 PostgreSQL - 4 CPU, 8GB RAM
-- 1 PgBouncer - 2 CPU, 4GB RAM
-- 2 Redis - 2 CPU, 8GB RAM
-- 3 Consul/Sentinel - 2 CPU, 2GB RAM
-- 4 Sidekiq - 4 CPU, 8GB RAM
-- 5 GitLab application nodes - 20 CPU, 64GB RAM
-- 1 Gitaly - 20 CPU, 64GB RAM
-- 1 Monitoring node - 4 CPU, 8GB RAM
+- **Known Issues:** While validating the reference architecture, slow endpoints were discovered and are being investigated. [gitlab-org/gitlab-ce/issues/64335](https://gitlab.com/gitlab-org/gitlab-ce/issues/64335)
+
+The Support and Quality teams built, performance tested, and validated an
+environment that supports about 10,000 users. The specifications below are a
+representation of the work so far. The specifications may be adjusted in the
+future based on additional testing and iteration.
+
+NOTE: **Note:** The specifications here were performance tested against a specific coded workload. Your exact needs may be more, depending on your workload. Your workload is influenced by factors such as - but not limited to - how active your users are, how much automation you use, mirroring, and repo/change size.
+
+- 3 PostgreSQL - 4 CPU, 16GiB memory per node
+- 1 PgBouncer - 2 CPU, 4GiB memory
+- 2 Redis - 2 CPU, 8GiB memory per node
+- 3 Consul/Sentinel - 2 CPU, 2GiB memory per node
+- 4 Sidekiq - 4 CPU, 16GiB memory per node
+- 5 GitLab application nodes - 16 CPU, 64GiB memory per node
+- 1 Gitaly - 16 CPU, 64GiB memory
+- 1 Monitoring node - 2 CPU, 8GiB memory, 100GiB local storage
 
 ### Fully Distributed
 
@@ -192,6 +199,7 @@ with the added complexity of many more nodes to configure, manage and monitor.
 - 2 or more API nodes (All requests to `/api`)
 - 2 or more Web nodes (All other web requests)
 - 2 or more NFS/Gitaly servers
+- 1 Monitoring node (Prometheus, Grafana)
 
 ![Fully Distributed architecture diagram](img/fully-distributed.png)
 
@@ -205,4 +213,4 @@ separately:
    1. [NFS Client and Host setup](nfs_host_client_setup.md)
 1. [Configure the GitLab application servers](gitlab.md)
 1. [Configure the load balancers](load_balancer.md)
-
+1. [Monitoring node (Prometheus and Grafana)](monitoring_node.md)
diff --git a/doc/administration/high_availability/alpha_database.md b/doc/administration/high_availability/alpha_database.md
index 7bf20be60e6..7afd739f44c 100644
--- a/doc/administration/high_availability/alpha_database.md
+++ b/doc/administration/high_availability/alpha_database.md
@@ -2,5 +2,4 @@
 redirect_to: 'database.md'
 ---
 
-This documentation has been moved to the main
-[database documentation](database.md#configure_using_omnibus_for_high_availability).
+This document was moved to [another location](database.md).
diff --git a/doc/administration/high_availability/consul.md b/doc/administration/high_availability/consul.md
index 056b7fc15d9..b02a61b9256 100644
--- a/doc/administration/high_availability/consul.md
+++ b/doc/administration/high_availability/consul.md
@@ -1,16 +1,85 @@
-# Working with the bundled Consul service **[PREMIUM ONLY]**
+---
+type: reference
+---
 
-## Overview
+# Working with the bundled Consul service **(PREMIUM ONLY)**
 
-As part of its High Availability stack, GitLab Premium includes a bundled version of [Consul](http://consul.io) that can be managed through `/etc/gitlab/gitlab.rb`.
+As part of its High Availability stack, GitLab Premium includes a bundled version of [Consul](https://www.consul.io/) that can be managed through `/etc/gitlab/gitlab.rb`.
 
 A Consul cluster consists of multiple server agents, as well as client agents that run on other nodes which need to talk to the consul cluster.
 
+## Prerequisites
+
+First, make sure to [download/install](https://about.gitlab.com/install/)
+GitLab Omnibus **on each node**.
+
+Choose an installation method, then make sure you complete steps:
+
+1. Install and configure the necessary dependencies.
+1. Add the GitLab package repository and install the package.
+
+When installing the GitLab package, do not supply `EXTERNAL_URL` value.
+
+## Configuring the Consul nodes
+
+On each Consul node perform the following:
+
+1. Make sure you collect [`CONSUL_SERVER_NODES`](database.md#consul-information), which are the IP addresses or DNS records of the Consul server nodes, for the next step, before executing the next step.
+
+1. Edit `/etc/gitlab/gitlab.rb` replacing values noted in the `# START user configuration` section:
+
+   ```ruby
+   # Disable all components except Consul
+   roles ['consul_role']
+
+   # START user configuration
+   # Replace placeholders:
+   #
+   # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z
+   # with the addresses gathered for CONSUL_SERVER_NODES
+   consul['configuration'] = {
+     server: true,
+     retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z)
+   }
+
+   # Disable auto migrations
+   gitlab_rails['auto_migrate'] = false
+   #
+   # END user configuration
+   ```
+
+   > `consul_role` was introduced with GitLab 10.3
+
+1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes
+   to take effect.
+
+### Consul checkpoint
+
+Before moving on, make sure Consul is configured correctly. Run the following
+command to verify all server nodes are communicating:
+
+```sh
+/opt/gitlab/embedded/bin/consul members
+```
+
+The output should be similar to:
+
+```
+Node                 Address               Status  Type    Build  Protocol  DC
+CONSUL_NODE_ONE      XXX.XXX.XXX.YYY:8301  alive   server  0.9.2  2         gitlab_consul
+CONSUL_NODE_TWO      XXX.XXX.XXX.YYY:8301  alive   server  0.9.2  2         gitlab_consul
+CONSUL_NODE_THREE    XXX.XXX.XXX.YYY:8301  alive   server  0.9.2  2         gitlab_consul
+```
+
+If any of the nodes isn't `alive` or if any of the three nodes are missing,
+check the [Troubleshooting section](#troubleshooting) before proceeding.
+
 ## Operations
 
 ### Checking cluster membership
 
 To see which nodes are part of the cluster, run the following on any member in the cluster
+
 ```
 # /opt/gitlab/embedded/bin/consul members
 Node            Address               Status  Type    Build  Protocol  DC
@@ -46,18 +115,18 @@ You will see messages like the following in `gitlab-ctl tail consul` output if y
 2017-09-25_19:53:41.74356     2017/09/25 19:53:41 [ERR] agent: failed to sync remote state: No cluster leader
 ```
 
-
 To fix this:
 
 1. Pick an address on each node that all of the other nodes can reach this node through.
 1. Update your `/etc/gitlab/gitlab.rb`
 
-    ```ruby
-    consul['configuration'] = {
-      ...
-      bind_addr: 'IP ADDRESS'
-    }
-    ```
+   ```ruby
+   consul['configuration'] = {
+     ...
+     bind_addr: 'IP ADDRESS'
+   }
+   ```
+
 1. Run `gitlab-ctl reconfigure`
 
 If you still see the errors, you may have to [erase the consul database and reinitialize](#recreate-from-scratch) on the affected node.
@@ -78,12 +147,13 @@ To fix this:
 1. Pick an address on the node that all of the other nodes can reach this node through.
 1. Update your `/etc/gitlab/gitlab.rb`
 
-    ```ruby
-    consul['configuration'] = {
-      ...
-      bind_addr: 'IP ADDRESS'
-    }
-    ```
+   ```ruby
+   consul['configuration'] = {
+     ...
+     bind_addr: 'IP ADDRESS'
+   }
+   ```
+
 1. Run `gitlab-ctl reconfigure`
 
 ### Outage recovery
@@ -91,6 +161,7 @@ To fix this:
 If you lost enough server agents in the cluster to break quorum, then the cluster is considered failed, and it will not function without manual intervenetion.
 
 #### Recreate from scratch
+
 By default, GitLab does not store anything in the consul cluster that cannot be recreated. To erase the consul database and reinitialize
 
 ```
@@ -102,4 +173,5 @@ By default, GitLab does not store anything in the consul cluster that cannot be
 After this, the cluster should start back up, and the server agents rejoin. Shortly after that, the client agents should rejoin as well.
 
 #### Recover a failed cluster
+
 If you have taken advantage of consul to store other data, and want to restore the failed cluster, please follow the [Consul guide](https://www.consul.io/docs/guides/outage.html) to recover a failed cluster.
diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md
index 3b874e5d312..7c9e02d889e 100644
--- a/doc/administration/high_availability/database.md
+++ b/doc/administration/high_availability/database.md
@@ -1,6 +1,13 @@
+---
+type: reference
+---
+
 # Configuring PostgreSQL for Scaling and High Availability
 
-## Provide your own PostgreSQL instance **[CORE ONLY]**
+In this section, you'll be guided through configuring a PostgreSQL database
+to be used with GitLab in a highly available environment.
+
+## Provide your own PostgreSQL instance **(CORE ONLY)**
 
 If you're hosting GitLab on a cloud provider, you can optionally use a
 managed service for PostgreSQL. For example, AWS offers a managed Relational
@@ -21,27 +28,27 @@ This section is relevant for [Scaled Architecture](README.md#scalable-architectu
 environments including [Basic Scaling](README.md#basic-scaling) and
 [Full Scaling](README.md#full-scaling).
 
-### Provide your own PostgreSQL instance **[CORE ONLY]**
+### Provide your own PostgreSQL instance **(CORE ONLY)**
 
 If you want to use your own deployed PostgreSQL instance(s),
 see [Provide your own PostgreSQL instance](#provide-your-own-postgresql-instance-core-only)
 for more details. However, you can use the GitLab Omnibus package to easily
 deploy the bundled PostgreSQL.
 
-### Standalone PostgreSQL using GitLab Omnibus **[CORE ONLY]**
+### Standalone PostgreSQL using GitLab Omnibus **(CORE ONLY)**
 
 1. SSH into the PostgreSQL server.
-1. [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab
+1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab
    package you want using **steps 1 and 2** from the GitLab downloads page.
-     - Do not complete any other steps on the download page.
+   - Do not complete any other steps on the download page.
 1. Generate a password hash for PostgreSQL. This assumes you will use the default
    username of `gitlab` (recommended). The command will request a password
    and confirmation. Use the value that is output by this command in the next
    step as the value of `POSTGRESQL_PASSWORD_HASH`.
 
-    ```sh
-    sudo gitlab-ctl pg-password-md5 gitlab
-    ```
+   ```sh
+   sudo gitlab-ctl pg-password-md5 gitlab
+   ```
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the contents below, updating placeholder
    values appropriately.
@@ -51,37 +58,38 @@ deploy the bundled PostgreSQL.
      addresses of the GitLab application servers that will connect to the
      database. Example: `%w(123.123.123.123/32 123.123.123.234/32)`
 
-    ```ruby
-    # Disable all components except PostgreSQL
-    roles ['postgres_role']
-    repmgr['enable'] = false
-    consul['enable'] = false
-    prometheus['enable'] = false
-    alertmanager['enable'] = false
-    pgbouncer_exporter['enable'] = false
-    redis_exporter['enable'] = false
-    gitlab_monitor['enable'] = false
-
-    postgresql['listen_address'] = '0.0.0.0'
-    postgresql['port'] = 5432
-
-    # Replace POSTGRESQL_PASSWORD_HASH with a generated md5 value
-    postgresql['sql_user_password'] = 'POSTGRESQL_PASSWORD_HASH'
-
-    # Replace XXX.XXX.XXX.XXX/YY with Network Address
-    # ????
-    postgresql['trust_auth_cidr_addresses'] = %w(APPLICATION_SERVER_IP_BLOCKS)
-
-    # Disable automatic database migrations
-    gitlab_rails['auto_migrate'] = false
-    ```
+   ```ruby
+   # Disable all components except PostgreSQL
+   roles ['postgres_role']
+   repmgr['enable'] = false
+   consul['enable'] = false
+   prometheus['enable'] = false
+   alertmanager['enable'] = false
+   pgbouncer_exporter['enable'] = false
+   redis_exporter['enable'] = false
+   gitlab_monitor['enable'] = false
+
+   postgresql['listen_address'] = '0.0.0.0'
+   postgresql['port'] = 5432
+
+   # Replace POSTGRESQL_PASSWORD_HASH with a generated md5 value
+   postgresql['sql_user_password'] = 'POSTGRESQL_PASSWORD_HASH'
+
+   # Replace XXX.XXX.XXX.XXX/YY with Network Address
+   # ????
+   postgresql['trust_auth_cidr_addresses'] = %w(APPLICATION_SERVER_IP_BLOCKS)
+
+   # Disable automatic database migrations
+   gitlab_rails['auto_migrate'] = false
+   ```
 
-    NOTE: **Note:** The role `postgres_role` was introduced with GitLab 10.3
+   NOTE: **Note:** The role `postgres_role` was introduced with GitLab 10.3
 
 1. [Reconfigure GitLab] for the changes to take effect.
 1. Note the PostgreSQL node's IP address or hostname, port, and
    plain text password. These will be necessary when configuring the GitLab
    application servers later.
+1. [Enable monitoring](#enable-monitoring)
 
 Advanced configuration options are supported and can be added if
 needed.
@@ -96,14 +104,14 @@ environments including [Horizontal](README.md#horizontal),
 [Hybrid](README.md#hybrid), and
 [Fully Distributed](README.md#fully-distributed).
 
-### Provide your own PostgreSQL instance **[CORE ONLY]**
+### Provide your own PostgreSQL instance **(CORE ONLY)**
 
 If you want to use your own deployed PostgreSQL instance(s),
 see [Provide your own PostgreSQL instance](#provide-your-own-postgresql-instance-core-only)
 for more details. However, you can use the GitLab Omnibus package to easily
 deploy the bundled PostgreSQL.
 
-### High Availability with GitLab Omnibus **[PREMIUM ONLY]**
+### High Availability with GitLab Omnibus **(PREMIUM ONLY)**
 
 > Important notes:
 >
@@ -111,7 +119,7 @@ deploy the bundled PostgreSQL.
 > - If you are a Community Edition or Starter user, consider using a cloud hosted solution.
 > - This document will not cover installations from source.
 >
-> - If HA setup is not what you were looking for, see the [database configuration document](http://docs.gitlab.com/omnibus/settings/database.html)
+> - If HA setup is not what you were looking for, see the [database configuration document](https://docs.gitlab.com/omnibus/settings/database.html)
 >   for the Omnibus GitLab packages.
 >
 > Please read this document fully before attempting to configure PostgreSQL HA
@@ -193,9 +201,9 @@ When using default setup, minimum configuration requires:
 - `CONSUL_PASSWORD_HASH`. This is a hash generated out of consul username/password pair.
    Can be generated with:
 
-    ```sh
-    sudo gitlab-ctl pg-password-md5 CONSUL_USERNAME
-    ```
+   ```sh
+   sudo gitlab-ctl pg-password-md5 CONSUL_USERNAME
+   ```
 
 - `CONSUL_SERVER_NODES`. The IP addresses or DNS records of the Consul server nodes.
 
@@ -203,9 +211,9 @@ Few notes on the service itself:
 
 - The service runs under a system account, by default `gitlab-consul`.
   - If you are using a different username, you will have to specify it. We
-will refer to it with `CONSUL_USERNAME`,
+    will refer to it with `CONSUL_USERNAME`,
 - There will be a database user created with read only access to the repmgr
-database
+  database
 - Passwords will be stored in the following locations:
   - `/etc/gitlab/gitlab.rb`: hashed
   - `/var/opt/gitlab/pgbouncer/pg_auth`: hashed
@@ -236,9 +244,9 @@ We will need the following password information for the application's database u
 - `POSTGRESQL_PASSWORD_HASH`. This is a hash generated out of the username/password pair.
   Can be generated with:
 
-    ```sh
-    sudo gitlab-ctl pg-password-md5 POSTGRESQL_USERNAME
-    ```
+  ```sh
+  sudo gitlab-ctl pg-password-md5 POSTGRESQL_USERNAME
+  ```
 
 ##### Pgbouncer information
 
@@ -249,9 +257,9 @@ When using default setup, minimum configuration requires:
 - `PGBOUNCER_PASSWORD_HASH`. This is a hash generated out of pgbouncer username/password pair.
   Can be generated with:
 
-    ```sh
-    sudo gitlab-ctl pg-password-md5 PGBOUNCER_USERNAME
-    ```
+  ```sh
+  sudo gitlab-ctl pg-password-md5 PGBOUNCER_USERNAME
+  ```
 
 - `PGBOUNCER_NODE`, is the IP address or a FQDN of the node running Pgbouncer.
 
@@ -280,125 +288,76 @@ Few notes on the service itself:
 
 #### Installing Omnibus GitLab
 
-First, make sure to [download/install](https://about.gitlab.com/installation)
+First, make sure to [download/install](https://about.gitlab.com/install/)
 GitLab Omnibus **on each node**.
 
 Make sure you install the necessary dependencies from step 1,
 add GitLab package repository from step 2.
 When installing the GitLab package, do not supply `EXTERNAL_URL` value.
 
-#### Configuring the Consul nodes
-
-On each Consul node perform the following:
-
-1. Make sure you collect [`CONSUL_SERVER_NODES`](#consul-information) before executing the next step.
-
-1. Edit `/etc/gitlab/gitlab.rb` replacing values noted in the `# START user configuration` section:
-
-    ```ruby
-    # Disable all components except Consul
-    roles ['consul_role']
-
-    # START user configuration
-    # Replace placeholders:
-    #
-    # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z
-    # with the addresses gathered for CONSUL_SERVER_NODES
-    consul['configuration'] = {
-      server: true,
-      retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z)
-    }
-
-    # Disable auto migrations
-    gitlab_rails['auto_migrate'] = false
-    #
-    # END user configuration
-    ```
-
-    > `consul_role` was introduced with GitLab 10.3
-
-1. [Reconfigure GitLab] for the changes to take effect.
-
-##### Consul Checkpoint
-
-Before moving on, make sure Consul is configured correctly. Run the following
-command to verify all server nodes are communicating:
-
-```sh
-/opt/gitlab/embedded/bin/consul members
-```
-
-The output should be similar to:
-
-```
-Node                 Address               Status  Type    Build  Protocol  DC
-CONSUL_NODE_ONE      XXX.XXX.XXX.YYY:8301  alive   server  0.9.2  2         gitlab_consul
-CONSUL_NODE_TWO      XXX.XXX.XXX.YYY:8301  alive   server  0.9.2  2         gitlab_consul
-CONSUL_NODE_THREE    XXX.XXX.XXX.YYY:8301  alive   server  0.9.2  2         gitlab_consul
-```
-
-If any of the nodes isn't `alive` or if any of the three nodes are missing,
-check the [Troubleshooting section](#troubleshooting) before proceeding.
-
 #### Configuring the Database nodes
 
+1. Make sure to [configure the Consul nodes](consul.md).
 1. Make sure you collect [`CONSUL_SERVER_NODES`](#consul-information), [`PGBOUNCER_PASSWORD_HASH`](#pgbouncer-information), [`POSTGRESQL_PASSWORD_HASH`](#postgresql-information), the [number of db nodes](#postgresql-information), and the [network address](#network-information) before executing the next step.
 
 1. On the master database node, edit `/etc/gitlab/gitlab.rb` replacing values noted in the `# START user configuration` section:
 
-    ```ruby
-    # Disable all components except PostgreSQL and Repmgr and Consul
-    roles ['postgres_role']
-
-    # PostgreSQL configuration
-    postgresql['listen_address'] = '0.0.0.0'
-    postgresql['hot_standby'] = 'on'
-    postgresql['wal_level'] = 'replica'
-    postgresql['shared_preload_libraries'] = 'repmgr_funcs'
-
-    # Disable automatic database migrations
-    gitlab_rails['auto_migrate'] = false
-
-    # Configure the consul agent
-    consul['services'] = %w(postgresql)
-
-    # START user configuration
-    # Please set the real values as explained in Required Information section
-    #
-    # Replace PGBOUNCER_PASSWORD_HASH with a generated md5 value
-    postgresql['pgbouncer_user_password'] = 'PGBOUNCER_PASSWORD_HASH'
-    # Replace POSTGRESQL_PASSWORD_HASH with a generated md5 value
-    postgresql['sql_user_password'] = 'POSTGRESQL_PASSWORD_HASH'
-    # Replace X with value of number of db nodes + 1
-    postgresql['max_wal_senders'] = X
-
-    # Replace XXX.XXX.XXX.XXX/YY with Network Address
-    postgresql['trust_auth_cidr_addresses'] = %w(XXX.XXX.XXX.XXX/YY)
-    repmgr['trust_auth_cidr_addresses'] = %w(127.0.0.1/32 XXX.XXX.XXX.XXX/YY)
-
-    # Replace placeholders:
-    #
-    # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z
-    # with the addresses gathered for CONSUL_SERVER_NODES
-    consul['configuration'] = {
-      retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z)
-    }
-    #
-    # END user configuration
-    ```
-
-    > `postgres_role` was introduced with GitLab 10.3
+   ```ruby
+   # Disable all components except PostgreSQL and Repmgr and Consul
+   roles ['postgres_role']
+
+   # PostgreSQL configuration
+   postgresql['listen_address'] = '0.0.0.0'
+   postgresql['hot_standby'] = 'on'
+   postgresql['wal_level'] = 'replica'
+   postgresql['shared_preload_libraries'] = 'repmgr_funcs'
+
+   # Disable automatic database migrations
+   gitlab_rails['auto_migrate'] = false
+
+   # Configure the consul agent
+   consul['services'] = %w(postgresql)
+
+   # START user configuration
+   # Please set the real values as explained in Required Information section
+   #
+   # Replace PGBOUNCER_PASSWORD_HASH with a generated md5 value
+   postgresql['pgbouncer_user_password'] = 'PGBOUNCER_PASSWORD_HASH'
+   # Replace POSTGRESQL_PASSWORD_HASH with a generated md5 value
+   postgresql['sql_user_password'] = 'POSTGRESQL_PASSWORD_HASH'
+   # Replace X with value of number of db nodes + 1
+   postgresql['max_wal_senders'] = X
+   postgresql['max_replication_slots'] = X
+
+   # Replace XXX.XXX.XXX.XXX/YY with Network Address
+   postgresql['trust_auth_cidr_addresses'] = %w(XXX.XXX.XXX.XXX/YY)
+   repmgr['trust_auth_cidr_addresses'] = %w(127.0.0.1/32 XXX.XXX.XXX.XXX/YY)
+
+   # Replace placeholders:
+   #
+   # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z
+   # with the addresses gathered for CONSUL_SERVER_NODES
+   consul['configuration'] = {
+     retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z)
+   }
+   #
+   # END user configuration
+   ```
+
+   > `postgres_role` was introduced with GitLab 10.3
 
 1. On secondary nodes, add all the configuration specified above for primary node
    to `/etc/gitlab/gitlab.rb`. In addition, append the following configuration
    to inform gitlab-ctl that they are standby nodes initially and it need not
    attempt to register them as primary node
+
    ```
    # HA setting to specify if a node should attempt to be master on initialization
    repmgr['master_on_initialization'] = false
    ```
 
 1. [Reconfigure GitLab] for the changes to take effect.
+1. [Enable Monitoring](#enable-monitoring)
 
 > Please note:
 >
@@ -416,31 +375,31 @@ Select one node as a primary node.
 
 1. Open a database prompt:
 
-    ```sh
-    gitlab-psql -d gitlabhq_production
-    ```
+   ```sh
+   gitlab-psql -d gitlabhq_production
+   ```
 
 1. Enable the `pg_trgm` extension:
 
-    ```sh
-    CREATE EXTENSION pg_trgm;
-    ```
+   ```sh
+   CREATE EXTENSION pg_trgm;
+   ```
 
 1. Exit the database prompt by typing `\q` and Enter.
 
 1. Verify the cluster is initialized with one node:
 
-    ```sh
-    gitlab-ctl repmgr cluster show
-    ```
+   ```sh
+   gitlab-ctl repmgr cluster show
+   ```
 
-    The output should be similar to the following:
+   The output should be similar to the following:
 
-    ```
-    Role      | Name     | Upstream | Connection String
-    ----------+----------|----------|----------------------------------------
-    * master  | HOSTNAME |          | host=HOSTNAME user=gitlab_repmgr dbname=gitlab_repmgr
-    ```
+   ```
+   Role      | Name     | Upstream | Connection String
+   ----------+----------|----------|----------------------------------------
+   * master  | HOSTNAME |          | host=HOSTNAME user=gitlab_repmgr dbname=gitlab_repmgr
+   ```
 
 1. Note down the hostname/ip in the connection string: `host=HOSTNAME`. We will
    refer to the hostname in the next section as `MASTER_NODE_NAME`. If the value
@@ -451,43 +410,43 @@ Select one node as a primary node.
 
 1. Set up the repmgr standby:
 
-    ```sh
-    gitlab-ctl repmgr standby setup MASTER_NODE_NAME
-    ```
-
-    Do note that this will remove the existing data on the node. The command
-    has a wait time.
-
-    The output should be similar to the following:
-
-    ```console
-    # gitlab-ctl repmgr standby setup MASTER_NODE_NAME
-    Doing this will delete the entire contents of /var/opt/gitlab/postgresql/data
-    If this is not what you want, hit Ctrl-C now to exit
-    To skip waiting, rerun with the -w option
-    Sleeping for 30 seconds
-    Stopping the database
-    Removing the data
-    Cloning the data
-    Starting the database
-    Registering the node with the cluster
-    ok: run: repmgrd: (pid 19068) 0s
-    ```
+   ```sh
+   gitlab-ctl repmgr standby setup MASTER_NODE_NAME
+   ```
+
+   Do note that this will remove the existing data on the node. The command
+   has a wait time.
+
+   The output should be similar to the following:
+
+   ```console
+   # gitlab-ctl repmgr standby setup MASTER_NODE_NAME
+   Doing this will delete the entire contents of /var/opt/gitlab/postgresql/data
+   If this is not what you want, hit Ctrl-C now to exit
+   To skip waiting, rerun with the -w option
+   Sleeping for 30 seconds
+   Stopping the database
+   Removing the data
+   Cloning the data
+   Starting the database
+   Registering the node with the cluster
+   ok: run: repmgrd: (pid 19068) 0s
+   ```
 
 1. Verify the node now appears in the cluster:
 
-    ```sh
-    gitlab-ctl repmgr cluster show
-    ```
+   ```sh
+   gitlab-ctl repmgr cluster show
+   ```
 
-    The output should be similar to the following:
+   The output should be similar to the following:
 
-    ```
-    Role      | Name    | Upstream  | Connection String
-    ----------+---------|-----------|------------------------------------------------
-    * master  | MASTER  |           | host=MASTER_NODE_NAME user=gitlab_repmgr dbname=gitlab_repmgr
-      standby | STANDBY | MASTER    | host=STANDBY_HOSTNAME user=gitlab_repmgr dbname=gitlab_repmgr
-    ```
+   ```
+   Role      | Name    | Upstream  | Connection String
+   ----------+---------|-----------|------------------------------------------------
+   * master  | MASTER  |           | host=MASTER_NODE_NAME user=gitlab_repmgr dbname=gitlab_repmgr
+     standby | STANDBY | MASTER    | host=STANDBY_HOSTNAME user=gitlab_repmgr dbname=gitlab_repmgr
+   ```
 
 Repeat the above steps on all secondary nodes.
 
@@ -527,88 +486,7 @@ Check the [Troubleshooting section](#troubleshooting) before proceeding.
 
 #### Configuring the Pgbouncer node
 
-1. Make sure you collect [`CONSUL_SERVER_NODES`](#consul-information), [`CONSUL_PASSWORD_HASH`](#consul-information), and [`PGBOUNCER_PASSWORD_HASH`](#pgbouncer-information) before executing the next step.
-
-1. Edit `/etc/gitlab/gitlab.rb` replacing values noted in the `# START user configuration` section:
-
-    ```ruby
-    # Disable all components except Pgbouncer and Consul agent
-    roles ['pgbouncer_role']
-
-    # Configure Pgbouncer
-    pgbouncer['admin_users'] = %w(pgbouncer gitlab-consul)
-
-    # Configure Consul agent
-    consul['watchers'] = %w(postgresql)
-
-    # START user configuration
-    # Please set the real values as explained in Required Information section
-    # Replace CONSUL_PASSWORD_HASH with with a generated md5 value
-    # Replace PGBOUNCER_PASSWORD_HASH with with a generated md5 value
-    pgbouncer['users'] = {
-      'gitlab-consul': {
-        password: 'CONSUL_PASSWORD_HASH'
-      },
-      'pgbouncer': {
-        password: 'PGBOUNCER_PASSWORD_HASH'
-      }
-    }
-    # Replace placeholders:
-    #
-    # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z
-    # with the addresses gathered for CONSUL_SERVER_NODES
-    consul['configuration'] = {
-      retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z)
-    }
-    #
-    # END user configuration
-    ```
-
-    > `pgbouncer_role` was introduced with GitLab 10.3
-
-1. [Reconfigure GitLab] for the changes to take effect.
-
-1. Create a `.pgpass` file so Consule is able to
-   reload pgbouncer. Enter the `PGBOUNCER_PASSWORD` twice when asked:
-
-    ```sh
-    gitlab-ctl write-pgpass --host 127.0.0.1 --database pgbouncer --user pgbouncer --hostuser gitlab-consul
-    ```
-
-##### PGBouncer Checkpoint
-
-1. Ensure the node is talking to the current master:
-
-    ```sh
-    gitlab-ctl pgb-console # You will be prompted for PGBOUNCER_PASSWORD
-    ```
-
-    If there is an error `psql: ERROR:  Auth failed` after typing in the
-    password, ensure you previously generated the MD5 password hashes with the correct
-    format. The correct format is to concatenate the password and the username:
-    `PASSWORDUSERNAME`. For example, `Sup3rS3cr3tpgbouncer` would be the text
-    needed to generate an MD5 password hash for the `pgbouncer` user.
-
-1. Once the console prompt is available, run the following queries:
-
-    ```sh
-    show databases ; show clients ;
-    ```
-
-    The output should be similar to the following:
-
-    ```
-            name         |  host       | port |      database       | force_user | pool_size | reserve_pool | pool_mode | max_connections | current_connections
-    ---------------------+-------------+------+---------------------+------------+-----------+--------------+-----------+-----------------+---------------------
-     gitlabhq_production | MASTER_HOST | 5432 | gitlabhq_production |            |        20 |            0 |           |               0 |                   0
-     pgbouncer           |             | 6432 | pgbouncer           | pgbouncer  |         2 |            0 | statement |               0 |                   0
-    (2 rows)
-
-     type |   user    |      database       |  state  |   addr         | port  | local_addr | local_port |    connect_time     |    request_time     |    ptr    | link | remote_pid | tls
-    ------+-----------+---------------------+---------+----------------+-------+------------+------------+---------------------+---------------------+-----------+------+------------+-----
-     C    | pgbouncer | pgbouncer           | active  | 127.0.0.1      | 56846 | 127.0.0.1  |       6432 | 2017-08-21 18:09:59 | 2017-08-21 18:10:48 | 0x22b3880 |      |          0 |
-    (2 rows)
-    ```
+See our [documentation for Pgbouncer](pgbouncer.md) for information on running Pgbouncer as part of an HA setup.
 
 #### Configuring the Application nodes
 
@@ -617,15 +495,15 @@ attributes set, but the following need to be set.
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    # Disable PostgreSQL on the application node
-    postgresql['enable'] = false
+   ```ruby
+   # Disable PostgreSQL on the application node
+   postgresql['enable'] = false
 
-    gitlab_rails['db_host'] = 'PGBOUNCER_NODE'
-    gitlab_rails['db_port'] = 6432
-    gitlab_rails['db_password'] = 'POSTGRESQL_USER_PASSWORD'
-    gitlab_rails['auto_migrate'] = false
-    ```
+   gitlab_rails['db_host'] = 'PGBOUNCER_NODE'
+   gitlab_rails['db_port'] = 6432
+   gitlab_rails['db_password'] = 'POSTGRESQL_USER_PASSWORD'
+   gitlab_rails['auto_migrate'] = false
+   ```
 
 1. [Reconfigure GitLab] for the changes to take effect.
 
@@ -785,45 +663,45 @@ After deploying the configuration follow these steps:
 
 1. On `10.6.0.21`, our primary database
 
-    Enable the `pg_trgm` extension
+   Enable the `pg_trgm` extension
 
-    ```sh
-    gitlab-psql -d gitlabhq_production
-    ```
+   ```sh
+   gitlab-psql -d gitlabhq_production
+   ```
 
-    ```
-    CREATE EXTENSION pg_trgm;
-    ```
+   ```
+   CREATE EXTENSION pg_trgm;
+   ```
 
 1. On `10.6.0.22`, our first standby database
 
-    Make this node a standby of the primary
+   Make this node a standby of the primary
 
-    ```sh
-    gitlab-ctl repmgr standby setup 10.6.0.21
-    ```
+   ```sh
+   gitlab-ctl repmgr standby setup 10.6.0.21
+   ```
 
 1. On `10.6.0.23`, our second standby database
 
-    Make this node a standby of the primary
+   Make this node a standby of the primary
 
-    ```sh
-    gitlab-ctl repmgr standby setup 10.6.0.21
-    ```
+   ```sh
+   gitlab-ctl repmgr standby setup 10.6.0.21
+   ```
 
 1. On `10.6.0.31`, our application server
 
-    Set gitlab-consul's pgbouncer password to `toomanysecrets`
+   Set gitlab-consul's pgbouncer password to `toomanysecrets`
 
-    ```sh
-    gitlab-ctl write-pgpass --host 127.0.0.1 --database pgbouncer --user pgbouncer --hostuser gitlab-consul
-    ```
+   ```sh
+   gitlab-ctl write-pgpass --host 127.0.0.1 --database pgbouncer --user pgbouncer --hostuser gitlab-consul
+   ```
 
-    Run database migrations
+   Run database migrations
 
-    ```sh
-    gitlab-rake gitlab:db:configure
-    ```
+   ```sh
+   gitlab-rake gitlab:db:configure
+   ```
 
 #### Example minimal setup
 
@@ -960,16 +838,16 @@ standby nodes.
 1. Ensure the old master node is not still active.
 1. Login to the server that should become the new master and run:
 
-    ```sh
-    gitlab-ctl repmgr standby promote
-    ```
+   ```sh
+   gitlab-ctl repmgr standby promote
+   ```
 
 1. If there are any other standby servers in the cluster, have them follow
    the new master server:
 
-    ```sh
-    gitlab-ctl repmgr standby follow NEW_MASTER
-    ```
+   ```sh
+   gitlab-ctl repmgr standby follow NEW_MASTER
+   ```
 
 #### Restore procedure
 
@@ -979,42 +857,42 @@ after it has been restored to service.
 - If you want to remove the node from the cluster, on any other node in the
   cluster, run:
 
-    ```sh
-    gitlab-ctl repmgr standby unregister --node=X
-    ```
+  ```sh
+  gitlab-ctl repmgr standby unregister --node=X
+  ```
 
-    where X is the value of node in `repmgr.conf` on the old server.
+  where X is the value of node in `repmgr.conf` on the old server.
 
-    To find this, you can use:
+  To find this, you can use:
 
-    ```sh
-    awk -F = '$1 == "node" { print $2 }' /var/opt/gitlab/postgresql/repmgr.conf
-    ```
+  ```sh
+  awk -F = '$1 == "node" { print $2 }' /var/opt/gitlab/postgresql/repmgr.conf
+  ```
 
-    It will output something like:
+  It will output something like:
 
-    ```
-    959789412
-    ```
+  ```
+  959789412
+  ```
 
-    Then you will use this id to unregister the node:
+  Then you will use this id to unregister the node:
 
-    ```sh
-    gitlab-ctl repmgr standby unregister --node=959789412
-    ```
+  ```sh
+  gitlab-ctl repmgr standby unregister --node=959789412
+  ```
 
 - To add the node as a standby server:
 
-    ```sh
-    gitlab-ctl repmgr standby follow NEW_MASTER
-    gitlab-ctl restart repmgrd
-    ```
+  ```sh
+  gitlab-ctl repmgr standby follow NEW_MASTER
+  gitlab-ctl restart repmgrd
+  ```
 
-    CAUTION: **Warning:** When the server is brought back online, and before
-    you switch it to a standby node, repmgr will report that there are two masters.
-    If there are any clients that are still attempting to write to the old master,
-    this will cause a split, and the old master will need to be resynced from
-    scratch by performing a `gitlab-ctl repmgr standby setup NEW_MASTER`.
+  CAUTION: **Warning:** When the server is brought back online, and before
+  you switch it to a standby node, repmgr will report that there are two masters.
+  If there are any clients that are still attempting to write to the old master,
+  this will cause a split, and the old master will need to be resynced from
+  scratch by performing a `gitlab-ctl repmgr standby setup NEW_MASTER`.
 
 #### Alternate configurations
 
@@ -1057,13 +935,13 @@ the previous section:
 1. On the current master node, create a password for the `gitlab` and
    `gitlab_repmgr` user:
 
-    ```sh
-    gitlab-psql -d template1
-    template1=# \password gitlab_repmgr
-    Enter password: ****
-    Confirm password: ****
-    template1=# \password gitlab
-    ```
+   ```sh
+   gitlab-psql -d template1
+   template1=# \password gitlab_repmgr
+   Enter password: ****
+   Confirm password: ****
+   template1=# \password gitlab
+   ```
 
 1. On each database node:
 
@@ -1077,18 +955,37 @@ the previous section:
    1. Create a `.pgpass` file. Enter the `gitlab_repmgr` password twice to
       when asked:
 
-        ```sh
-        gitlab-ctl write-pgpass --user gitlab_repmgr --hostuser gitlab-psql --database '*'
-        ```
+      ```sh
+      gitlab-ctl write-pgpass --user gitlab_repmgr --hostuser gitlab-psql --database '*'
+      ```
 
 1. On each pgbouncer node, edit `/etc/gitlab/gitlab.rb`:
    1. Ensure `gitlab_rails['db_password']` is set to the plaintext password for
       the `gitlab` database user
    1. [Reconfigure GitLab] for the changes to take effect
 
+## Enable Monitoring
+
+> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3786) in GitLab 12.0.
+
+If you enable Monitoring, it must be enabled on **all** database servers.
+
+1. Create/edit `/etc/gitlab/gitlab.rb` and add the following configuration:
+
+   ```ruby
+   # Enable service discovery for Prometheus
+   consul['monitoring_service_discovery'] = true
+
+   # Set the network addresses that the exporters will listen on
+   node_exporter['listen_address'] = '0.0.0.0:9100'
+   postgres_exporter['listen_address'] = '0.0.0.0:9187'
+   ```
+
+1. Run `sudo gitlab-ctl reconfigure` to compile the configuration.
+
 ## Troubleshooting
 
-#### Consul and PostgreSQL changes not taking effect.
+### Consul and PostgreSQL changes not taking effect
 
 Due to the potential impacts, `gitlab-ctl reconfigure` only reloads Consul and PostgreSQL, it will not restart the services. However, not all changes can be activated by reloading.
 
@@ -1098,7 +995,7 @@ For PostgreSQL, it is usually safe to restart the master node by default. Automa
 
 On the consul server nodes, it is important to restart the consul service in a controlled fashion. Read our [consul documentation](consul.md#restarting-the-server-cluster) for instructions on how to restart the service.
 
-#### `gitlab-ctl repmgr-check-master` command produces errors
+### `gitlab-ctl repmgr-check-master` command produces errors
 
 If this command displays errors about database permissions it is likely that something failed during
 install, resulting in the `gitlab-consul` database user getting incorrect permissions. Follow these
@@ -1113,7 +1010,7 @@ steps to fix the problem:
 
 Now there should not be errors. If errors still occur then there is another problem.
 
-#### PGBouncer error `ERROR: pgbouncer cannot connect to server`
+### PGBouncer error `ERROR: pgbouncer cannot connect to server`
 
 You may get this error when running `gitlab-rake gitlab:db:configure` or you
 may see the error in the PGBouncer log file.
@@ -1141,12 +1038,12 @@ postgresql['trust_auth_cidr_addresses'] = %w(123.123.123.123/32 <other_cidrs>)
 
 [Reconfigure GitLab] for the changes to take effect.
 
-#### Issues with other components
+### Issues with other components
 
 If you're running into an issue with a component not outlined here, be sure to check the troubleshooting section of their specific documentation page.
 
 - [Consul](consul.md#troubleshooting)
-- [PostgreSQL](http://docs.gitlab.com/omnibus/settings/database.html#troubleshooting)
+- [PostgreSQL](https://docs.gitlab.com/omnibus/settings/database.html#troubleshooting)
 - [GitLab application](gitlab.md#troubleshooting)
 
 ## Configure using Omnibus
diff --git a/doc/administration/high_availability/gitaly.md b/doc/administration/high_availability/gitaly.md
index 1d8e6c999cb..739d1ae35fb 100644
--- a/doc/administration/high_availability/gitaly.md
+++ b/doc/administration/high_availability/gitaly.md
@@ -1,14 +1,18 @@
+---
+type: reference
+---
+
 # Configuring Gitaly for Scaled and High Availability
 
 Gitaly does not yet support full high availability. However, Gitaly is quite
 stable and is in use on GitLab.com. Scaled and highly available GitLab environments
-should consider using Gitaly on a separate node. 
+should consider using Gitaly on a separate node.
 
-See the [Gitaly HA Epic](https://gitlab.com/groups/gitlab-org/-/epics/289) to 
-track plans and progress toward high availability support. 
+See the [Gitaly HA Epic](https://gitlab.com/groups/gitlab-org/-/epics/289) to
+track plans and progress toward high availability support.
 
 This document is relevant for [Scaled Architecture](README.md#scalable-architecture-examples)
-environments and [High Availability Architecture](README.md#high-availability-architecture-examples). 
+environments and [High Availability Architecture](README.md#high-availability-architecture-examples).
 
 ## Running Gitaly on its own server
 
@@ -19,3 +23,42 @@ Continue configuration of other components by going back to:
 
 - [Scaled Architectures](README.md#scalable-architecture-examples)
 - [High Availability Architectures](README.md#high-availability-architecture-examples)
+
+## Enable Monitoring
+
+> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3786) in GitLab 12.0.
+
+1. Make sure to collect [`CONSUL_SERVER_NODES`](database.md#consul-information), which are the IP addresses or DNS records of the Consul server nodes, for the next step. Note they are presented as `Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z`
+
+1. Create/edit `/etc/gitlab/gitlab.rb` and add the following configuration:
+
+   ```ruby
+   # Enable service discovery for Prometheus
+   consul['enable'] = true
+   consul['monitoring_service_discovery'] =  true
+
+   # Replace placeholders
+   # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z
+   # with the addresses of the Consul server nodes
+   consul['configuration'] = {
+      retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z),
+   }
+
+   # Set the network addresses that the exporters will listen on
+   node_exporter['listen_address'] = '0.0.0.0:9100'
+   gitaly['prometheus_listen_addr'] = "0.0.0.0:9236"
+   ```
+
+1. Run `sudo gitlab-ctl reconfigure` to compile the configuration.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md
index 888426ece5c..8818a9606de 100644
--- a/doc/administration/high_availability/gitlab.md
+++ b/doc/administration/high_availability/gitlab.md
@@ -1,4 +1,8 @@
-# Configuring GitLab Scaling and High Availability
+---
+type: reference
+---
+
+# Configuring GitLab for Scaling and High Availability
 
 > **Note:** There is some additional configuration near the bottom for
   additional GitLab application servers. It's important to read and understand
@@ -7,33 +11,33 @@
 1. If necessary, install the NFS client utility packages using the following
    commands:
 
-    ```
-    # Ubuntu/Debian
-    apt-get install nfs-common
+   ```
+   # Ubuntu/Debian
+   apt-get install nfs-common
 
-    # CentOS/Red Hat
-    yum install nfs-utils nfs-utils-lib
-    ```
+   # CentOS/Red Hat
+   yum install nfs-utils nfs-utils-lib
+   ```
 
 1. Specify the necessary NFS shares. Mounts are specified in
    `/etc/fstab`. The exact contents of `/etc/fstab` will depend on how you chose
    to configure your NFS server. See [NFS documentation](nfs.md) for the various
    options. Here is an example snippet to add to `/etc/fstab`:
 
-    ```
-    10.1.0.1:/var/opt/gitlab/.ssh /var/opt/gitlab/.ssh nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2
-    10.1.0.1:/var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/uploads nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2
-    10.1.0.1:/var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-rails/shared nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2
-    10.1.0.1:/var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/gitlab-ci/builds nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2
-    10.1.0.1:/var/opt/gitlab/git-data /var/opt/gitlab/git-data nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2
-    ```
+   ```
+   10.1.0.1:/var/opt/gitlab/.ssh /var/opt/gitlab/.ssh nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2
+   10.1.0.1:/var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/uploads nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2
+   10.1.0.1:/var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-rails/shared nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2
+   10.1.0.1:/var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/gitlab-ci/builds nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2
+   10.1.0.1:/var/opt/gitlab/git-data /var/opt/gitlab/git-data nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2
+   ```
 
 1. Create the shared directories. These may be different depending on your NFS
    mount locations.
 
-    ```
-    mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data
-    ```
+   ```
+   mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data
+   ```
 
 1. Download/install GitLab Omnibus using **steps 1 and 2** from
    [GitLab downloads](https://about.gitlab.com/downloads). Do not complete other
@@ -46,49 +50,52 @@
    added NFS mounts in the default data locations. Additionally the UID and GIDs
    given are just examples and you should configure with your preferred values.
 
-    ```ruby
-    external_url 'https://gitlab.example.com'
-
-    # Prevent GitLab from starting if NFS data mounts are not available
-    high_availability['mountpoint'] = '/var/opt/gitlab/git-data'
-
-    # Disable components that will not be on the GitLab application server
-    roles ['application_role']
-    nginx['enable'] = true
-
-    # PostgreSQL connection details
-    gitlab_rails['db_adapter'] = 'postgresql'
-    gitlab_rails['db_encoding'] = 'unicode'
-    gitlab_rails['db_host'] = '10.1.0.5' # IP/hostname of database server
-    gitlab_rails['db_password'] = 'DB password'
-
-    # Redis connection details
-    gitlab_rails['redis_port'] = '6379'
-    gitlab_rails['redis_host'] = '10.1.0.6' # IP/hostname of Redis server
-    gitlab_rails['redis_password'] = 'Redis Password'
-    
-    # Ensure UIDs and GIDs match between servers for permissions via NFS
-    user['uid'] = 9000
-    user['gid'] = 9000
-    web_server['uid'] = 9001
-    web_server['gid'] = 9001
-    registry['uid'] = 9002
-    registry['gid'] = 9002
-    ```
-
-    > **Note:** To maintain uniformity of links across HA clusters, the `external_url`
-    on the first application server as well as the additional application
-    servers should point to the external url that users will use to access GitLab.
-    In a typical HA setup, this will be the url of the load balancer which will
-    route traffic to all GitLab application servers in the HA cluster.
-    > 
-    > **Note:** When you specify `https` in the `external_url`, as in the example
-    above, GitLab assumes you have SSL certificates in `/etc/gitlab/ssl/`. If
-    certificates are not present, Nginx will fail to start. See
-    [Nginx documentation](http://docs.gitlab.com/omnibus/settings/nginx.html#enable-https)
-    for more information.
-    >
-    > **Note:** It is best to set the `uid` and `gid`s prior to the initial reconfigure of GitLab. Omnibus will not recursively `chown` directories if set after the initial reconfigure.
+   ```ruby
+   external_url 'https://gitlab.example.com'
+
+   # Prevent GitLab from starting if NFS data mounts are not available
+   high_availability['mountpoint'] = '/var/opt/gitlab/git-data'
+
+   # Disable components that will not be on the GitLab application server
+   roles ['application_role']
+   nginx['enable'] = true
+
+   # PostgreSQL connection details
+   gitlab_rails['db_adapter'] = 'postgresql'
+   gitlab_rails['db_encoding'] = 'unicode'
+   gitlab_rails['db_host'] = '10.1.0.5' # IP/hostname of database server
+   gitlab_rails['db_password'] = 'DB password'
+
+   # Redis connection details
+   gitlab_rails['redis_port'] = '6379'
+   gitlab_rails['redis_host'] = '10.1.0.6' # IP/hostname of Redis server
+   gitlab_rails['redis_password'] = 'Redis Password'
+
+   # Ensure UIDs and GIDs match between servers for permissions via NFS
+   user['uid'] = 9000
+   user['gid'] = 9000
+   web_server['uid'] = 9001
+   web_server['gid'] = 9001
+   registry['uid'] = 9002
+   registry['gid'] = 9002
+   ```
+
+1. [Enable monitoring](#enable-monitoring)
+
+   > **Note:** To maintain uniformity of links across HA clusters, the `external_url`
+   on the first application server as well as the additional application
+   servers should point to the external url that users will use to access GitLab.
+   In a typical HA setup, this will be the url of the load balancer which will
+   route traffic to all GitLab application servers in the HA cluster.
+   >
+   > **Note:** When you specify `https` in the `external_url`, as in the example
+   above, GitLab assumes you have SSL certificates in `/etc/gitlab/ssl/`. If
+   certificates are not present, Nginx will fail to start. See
+   [Nginx documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https)
+   for more information.
+   >
+   > **Note:** It is best to set the `uid` and `gid`s prior to the initial reconfigure
+   of GitLab. Omnibus will not recursively `chown` directories if set after the initial reconfigure.
 
 ## First GitLab application server
 
@@ -111,24 +118,65 @@ need some extra configuration.
    secondary servers **prior to** running the first `reconfigure` in the steps
    above.
 
-    ```ruby
-    gitlab_shell['secret_token'] = 'fbfb19c355066a9afb030992231c4a363357f77345edd0f2e772359e5be59b02538e1fa6cae8f93f7d23355341cea2b93600dab6d6c3edcdced558fc6d739860'
-    gitlab_rails['otp_key_base'] = 'b719fe119132c7810908bba18315259ed12888d4f5ee5430c42a776d840a396799b0a5ef0a801348c8a357f07aa72bbd58e25a84b8f247a25c72f539c7a6c5fa'
-    gitlab_rails['secret_key_base'] = '6e657410d57c71b4fc3ed0d694e7842b1895a8b401d812c17fe61caf95b48a6d703cb53c112bc01ebd197a85da81b18e29682040e99b4f26594772a4a2c98c6d'
-    gitlab_rails['db_key_base'] = 'bf2e47b68d6cafaef1d767e628b619365becf27571e10f196f98dc85e7771042b9203199d39aff91fcb6837c8ed83f2a912b278da50999bb11a2fbc0fba52964'
-    ```
+   ```ruby
+   gitlab_shell['secret_token'] = 'fbfb19c355066a9afb030992231c4a363357f77345edd0f2e772359e5be59b02538e1fa6cae8f93f7d23355341cea2b93600dab6d6c3edcdced558fc6d739860'
+   gitlab_rails['otp_key_base'] = 'b719fe119132c7810908bba18315259ed12888d4f5ee5430c42a776d840a396799b0a5ef0a801348c8a357f07aa72bbd58e25a84b8f247a25c72f539c7a6c5fa'
+   gitlab_rails['secret_key_base'] = '6e657410d57c71b4fc3ed0d694e7842b1895a8b401d812c17fe61caf95b48a6d703cb53c112bc01ebd197a85da81b18e29682040e99b4f26594772a4a2c98c6d'
+   gitlab_rails['db_key_base'] = 'bf2e47b68d6cafaef1d767e628b619365becf27571e10f196f98dc85e7771042b9203199d39aff91fcb6837c8ed83f2a912b278da50999bb11a2fbc0fba52964'
+   ```
 
 1. Run `touch /etc/gitlab/skip-auto-reconfigure` to prevent database migrations
    from running on upgrade. Only the primary GitLab application server should
    handle migrations.
 
-1. **Optional** Configure host keys. Copy all contents(primary and public keys) inside `/etc/ssh/` on
+1. **Recommended** Configure host keys. Copy the contents (primary and public keys) of `/etc/ssh/` on
    the primary application server to `/etc/ssh` on all secondary servers. This
    prevents false man-in-the-middle-attack alerts when accessing servers in your
    High Availability cluster behind a load balancer.
 
 1. Run `sudo gitlab-ctl reconfigure` to compile the configuration.
 
+## Enable Monitoring
+
+> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3786) in GitLab 12.0.
+
+If you enable Monitoring, it must be enabled on **all** GitLab servers.
+
+1. Make sure to collect [`CONSUL_SERVER_NODES`](database.md#consul-information), which are the IP addresses or DNS records of the Consul server nodes, for the next step. Note they are presented as `Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z`
+
+1. Create/edit `/etc/gitlab/gitlab.rb` and add the following configuration:
+
+   ```ruby
+   # Enable service discovery for Prometheus
+   consul['enable'] = true
+   consul['monitoring_service_discovery'] =  true
+
+   # Replace placeholders
+   # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z
+   # with the addresses of the Consul server nodes
+   consul['configuration'] = {
+      retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z),
+   }
+
+   # Set the network addresses that the exporters will listen on
+   node_exporter['listen_address'] = '0.0.0.0:9100'
+   gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229'
+   sidekiq['listen_address'] = "0.0.0.0"
+   unicorn['listen'] = '0.0.0.0'
+
+   # Add the monitoring node's IP address to the monitoring whitelist and allow it to
+   # scrape the NGINX metrics. Replace placeholder `monitoring.gitlab.example.com` with
+   # the address and/or subnets gathered from the monitoring node(s).
+   gitlab_rails['monitoring_whitelist'] = ['monitoring.gitlab.example.com', '127.0.0.0/8']
+   nginx['status']['options']['allow'] = ['monitoring.gitlab.example.com', '127.0.0.0/8']
+   ```
+
+1. Run `sudo gitlab-ctl reconfigure` to compile the configuration.
+
+> **Warning:** After changing `unicorn['listen']` in `gitlab.rb`, and running `sudo gitlab-ctl reconfigure`,
+  it can take an extended period of time for unicorn to complete reloading after receiving a `HUP`.
+  For more information, see the [issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/4401).
+
 ## Troubleshooting
 
 - `mount: wrong fs type, bad option, bad superblock on`
diff --git a/doc/administration/high_availability/img/fully-distributed.png b/doc/administration/high_availability/img/fully-distributed.png
index ad23207134e..c3cd2bf24f0 100644
--- a/doc/administration/high_availability/img/fully-distributed.png
+++ b/doc/administration/high_availability/img/fully-distributed.png
diff --git a/doc/administration/high_availability/img/horizontal.png b/doc/administration/high_availability/img/horizontal.png
index c3bd489d96f..75d08e1097a 100644
--- a/doc/administration/high_availability/img/horizontal.png
+++ b/doc/administration/high_availability/img/horizontal.png
diff --git a/doc/administration/high_availability/img/hybrid.png b/doc/administration/high_availability/img/hybrid.png
index 7d4a56bf0ea..8dd9923e597 100644
--- a/doc/administration/high_availability/img/hybrid.png
+++ b/doc/administration/high_availability/img/hybrid.png
diff --git a/doc/administration/high_availability/load_balancer.md b/doc/administration/high_availability/load_balancer.md
index 28b226cacd5..9e9f604317a 100644
--- a/doc/administration/high_availability/load_balancer.md
+++ b/doc/administration/high_availability/load_balancer.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Load Balancer for GitLab HA
 
 In an active/active GitLab configuration, you will need a load balancer to route
@@ -114,3 +118,15 @@ Read more on high-availability configuration:
       if SSL was terminated at the load balancer.
 
 [gitlab-pages]: ../pages/index.md
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/high_availability/monitoring_node.md b/doc/administration/high_availability/monitoring_node.md
new file mode 100644
index 00000000000..b2750603c74
--- /dev/null
+++ b/doc/administration/high_availability/monitoring_node.md
@@ -0,0 +1,87 @@
+---
+type: reference
+---
+
+# Configuring a Monitoring node for Scaling and High Availability
+
+> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3786) in GitLab 12.0.
+
+You can configure a Prometheus node to monitor GitLab.
+
+## Standalone Monitoring node using GitLab Omnibus
+
+The GitLab Omnibus package can be used to configure a standalone Monitoring node running [Prometheus](../monitoring/prometheus/index.md) and [Grafana](../monitoring/performance/grafana_configuration.md).
+The monitoring node is not highly available. See [Scaling and High Availability](README.md)
+for an overview of GitLab scaling and high availability options.
+
+The steps below are the minimum necessary to configure a Monitoring node running Prometheus and Grafana with
+Omnibus:
+
+1. SSH into the Monitoring node.
+1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab
+   package you want using **steps 1 and 2** from the GitLab downloads page.
+   - Do not complete any other steps on the download page.
+
+1. Make sure to collect [`CONSUL_SERVER_NODES`](database.md#consul-information), which are the IP addresses or DNS records of the Consul server nodes, for the next step. Note they are presented as `Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z`
+
+1. Edit `/etc/gitlab/gitlab.rb` and add the contents:
+
+   ```ruby
+   external_url 'http://gitlab.example.com'
+
+   # Enable Prometheus
+   prometheus['enable'] = true
+   prometheus['listen_address'] = '0.0.0.0:9090'
+   prometheus['monitor_kubernetes'] = false
+
+   # Enable Grafana
+   grafana['enable'] = true
+   grafana['admin_password'] = 'toomanysecrets'
+
+   # Enable service discovery for Prometheus
+   consul['enable'] = true
+   consul['monitoring_service_discovery'] =  true
+
+   # Replace placeholders
+   # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z
+   # with the addresses of the Consul server nodes
+   consul['configuration'] = {
+      retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z),
+   }
+
+   # Disable all other services
+   gitlab_rails['auto_migrate'] = false
+   alertmanager['enable'] = false
+   gitaly['enable'] = false
+   gitlab_monitor['enable'] = false
+   gitlab_workhorse['enable'] = false
+   nginx['enable'] = true
+   postgres_exporter['enable'] = false
+   postgresql['enable'] = false
+   redis['enable'] = false
+   redis_exporter['enable'] = false
+   sidekiq['enable'] = false
+   unicorn['enable'] = false
+   node_exporter['enable'] = false
+   ```
+
+1. Run `sudo gitlab-ctl reconfigure` to compile the configuration.
+
+## Migrating to Service Discovery
+
+Once monitoring using Service Discovery is enabled with `consul['monitoring_service_discovery'] =  true`,
+ensure that `prometheus['scrape_configs']` is not set  in `/etc/gitlab/gitlab.rb`. Setting both
+`consul['monitoring_service_discovery'] =  true` and `prometheus['scrape_configs']` in `/etc/gitlab/gitlab.rb`
+will result in errors.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md
index 3013ce63bd5..274bd32299b 100644
--- a/doc/administration/high_availability/nfs.md
+++ b/doc/administration/high_availability/nfs.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # NFS
 
 You can view information and options set for each of the mounted NFS file
@@ -42,34 +46,20 @@ maintaining ID mapping without LDAP, in most cases you should enable numeric UID
 and GIDs (which is off by default in some cases) for simplified permission
 management between systems:
 
-  - [NetApp instructions](https://library.netapp.com/ecmdocs/ECMP1401220/html/GUID-24367A9F-E17B-4725-ADC1-02D86F56F78E.html)
-  - For non-NetApp devices, disable NFSv4 `idmapping` by performing opposite of [enable NFSv4 idmapper](https://wiki.archlinux.org/index.php/NFS#Enabling_NFSv4_idmapping)
+- [NetApp instructions](https://library.netapp.com/ecmdocs/ECMP1401220/html/GUID-24367A9F-E17B-4725-ADC1-02D86F56F78E.html)
+- For non-NetApp devices, disable NFSv4 `idmapping` by performing opposite of [enable NFSv4 idmapper](https://wiki.archlinux.org/index.php/NFS#Enabling_NFSv4_idmapping)
 
 ### Improving NFS performance with GitLab
 
-NOTE: **Note:** This is only available starting in certain versions of GitLab: 11.5.11,
-11.6.11, 11.7.12, 11.8.8, 11.9.0 and up (e.g. 11.10, 11.11, etc.)
+NOTE: **Note:** From GitLab 12.1, it will automatically be detected if Rugged can and should be used per storage.
 
-If you are using NFS to share Git data, we recommend that you enable a
-number of feature flags that will allow GitLab application processes to
-access Git data directly instead of going through the [Gitaly
-service](../gitaly/index.md). Depending on your workload and disk
-performance, these flags may help improve performance. See [the
-issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/57317) for more
-details.
-
-To do this, run the Rake task:
+If you previously enabled Rugged using the feature flag, you will need to unset the feature flag by using:
 
 ```sh
-sudo gitlab-rake gitlab:features:enable_rugged
+sudo gitlab-rake gitlab:features:unset_rugged
 ```
 
-If you need to undo this setting for some reason such as switching to [Gitaly without NFS](gitaly.md)
-(recommended), run:
-
-```sh
-sudo gitlab-rake gitlab:features:disable_rugged
-```
+If the Rugged feature flag is explicitly set to either true or false, GitLab will use the value explicitly set.
 
 ### Known issues
 
@@ -81,16 +71,21 @@ bug](https://bugzilla.redhat.com/show_bug.cgi?id=1552203) that may be fixed in
 [more recent kernels with this
 commit](https://github.com/torvalds/linux/commit/95da1b3a5aded124dd1bda1e3cdb876184813140).
 
+NOTE: **Note** Red Hat Enterprise 7 [shipped a kernel
+update](https://access.redhat.com/errata/RHSA-2019:2029) on August 6,
+2019 that may have resolved this problem. The following instructions may
+not be needed if the latest kernel is updated properly.
+
 GitLab recommends all NFS users disable the NFS server
 delegation feature. To disable NFS server delegations
 on an Linux NFS server, do the following:
 
 1. On the NFS server, run:
 
-    ```sh
-    echo 0 > /proc/sys/fs/leases-enable
-    sysctl -w fs.leases-enable=0
-    ```
+   ```sh
+   echo 0 > /proc/sys/fs/leases-enable
+   sysctl -w fs.leases-enable=0
+   ```
 
 1. Restart the NFS server process. For example, on CentOS run `service nfs restart`.
 
@@ -235,4 +230,16 @@ Read more on high-availability configuration:
 1. [Configure the GitLab application servers](gitlab.md)
 1. [Configure the load balancers](load_balancer.md)
 
-[udp-log-shipping]: http://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only "UDP log shipping"
+[udp-log-shipping]: https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only "UDP log shipping"
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/high_availability/nfs_host_client_setup.md b/doc/administration/high_availability/nfs_host_client_setup.md
index a8d69b9ab0a..9b0e085fe25 100644
--- a/doc/administration/high_availability/nfs_host_client_setup.md
+++ b/doc/administration/high_availability/nfs_host_client_setup.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Configuring NFS for GitLab HA
 
 Setting up NFS for a GitLab HA setup allows all applications nodes in a cluster
@@ -133,3 +137,15 @@ client with the command below.
 ```sh
 sudo ufw allow from <client-ip-address> to any port nfs
 ```
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/high_availability/pgbouncer.md b/doc/administration/high_availability/pgbouncer.md
index 762179cf756..b99724d12a2 100644
--- a/doc/administration/high_availability/pgbouncer.md
+++ b/doc/administration/high_availability/pgbouncer.md
@@ -1,6 +1,8 @@
-# Working with the bundle Pgbouncer service
+---
+type: reference
+---
 
-## Overview
+# Working with the bundle Pgbouncer service
 
 As part of its High Availability stack, GitLab Premium includes a bundled version of [Pgbouncer](https://pgbouncer.github.io/) that can be managed through `/etc/gitlab/gitlab.rb`.
 
@@ -14,7 +16,89 @@ It is recommended to run pgbouncer alongside the `gitlab-rails` service, or on i
 
 ### Running Pgbouncer as part of an HA GitLab installation
 
-See our [HA documentation for PostgreSQL](database.md) for information on running pgbouncer as part of a HA setup
+1. Make sure you collect [`CONSUL_SERVER_NODES`](database.md#consul-information), [`CONSUL_PASSWORD_HASH`](database.md#consul-information), and [`PGBOUNCER_PASSWORD_HASH`](database.md#pgbouncer-information) before executing the next step.
+
+1. Edit `/etc/gitlab/gitlab.rb` replacing values noted in the `# START user configuration` section:
+
+   ```ruby
+   # Disable all components except Pgbouncer and Consul agent
+   roles ['pgbouncer_role']
+
+   # Configure Pgbouncer
+   pgbouncer['admin_users'] = %w(pgbouncer gitlab-consul)
+
+   # Configure Consul agent
+   consul['watchers'] = %w(postgresql)
+
+   # START user configuration
+   # Please set the real values as explained in Required Information section
+   # Replace CONSUL_PASSWORD_HASH with with a generated md5 value
+   # Replace PGBOUNCER_PASSWORD_HASH with with a generated md5 value
+   pgbouncer['users'] = {
+     'gitlab-consul': {
+       password: 'CONSUL_PASSWORD_HASH'
+     },
+     'pgbouncer': {
+       password: 'PGBOUNCER_PASSWORD_HASH'
+     }
+   }
+   # Replace placeholders:
+   #
+   # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z
+   # with the addresses gathered for CONSUL_SERVER_NODES
+   consul['configuration'] = {
+     retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z)
+   }
+   #
+   # END user configuration
+   ```
+
+   NOTE: **Note:**
+   `pgbouncer_role` was introduced with GitLab 10.3.
+
+1. Run `gitlab-ctl reconfigure`
+
+1. Create a `.pgpass` file so Consul is able to
+   reload pgbouncer. Enter the `PGBOUNCER_PASSWORD` twice when asked:
+
+   ```sh
+   gitlab-ctl write-pgpass --host 127.0.0.1 --database pgbouncer --user pgbouncer --hostuser gitlab-consul
+   ```
+
+#### PGBouncer Checkpoint
+
+1. Ensure the node is talking to the current master:
+
+   ```sh
+   gitlab-ctl pgb-console # You will be prompted for PGBOUNCER_PASSWORD
+   ```
+
+   If there is an error `psql: ERROR:  Auth failed` after typing in the
+   password, ensure you previously generated the MD5 password hashes with the correct
+   format. The correct format is to concatenate the password and the username:
+   `PASSWORDUSERNAME`. For example, `Sup3rS3cr3tpgbouncer` would be the text
+   needed to generate an MD5 password hash for the `pgbouncer` user.
+
+1. Once the console prompt is available, run the following queries:
+
+   ```sh
+   show databases ; show clients ;
+   ```
+
+   The output should be similar to the following:
+
+   ```
+           name         |  host       | port |      database       | force_user | pool_size | reserve_pool | pool_mode | max_connections | current_connections
+   ---------------------+-------------+------+---------------------+------------+-----------+--------------+-----------+-----------------+---------------------
+    gitlabhq_production | MASTER_HOST | 5432 | gitlabhq_production |            |        20 |            0 |           |               0 |                   0
+    pgbouncer           |             | 6432 | pgbouncer           | pgbouncer  |         2 |            0 | statement |               0 |                   0
+   (2 rows)
+
+    type |   user    |      database       |  state  |   addr         | port  | local_addr | local_port |    connect_time     |    request_time     |    ptr    | link | remote_pid | tls
+   ------+-----------+---------------------+---------+----------------+-------+------------+------------+---------------------+---------------------+-----------+------+------------+-----
+    C    | pgbouncer | pgbouncer           | active  | 127.0.0.1      | 56846 | 127.0.0.1  |       6432 | 2017-08-21 18:09:59 | 2017-08-21 18:10:48 | 0x22b3880 |      |          0 |
+   (2 rows)
+   ```
 
 ### Running Pgbouncer as part of a non-HA GitLab installation
 
@@ -24,44 +108,71 @@ See our [HA documentation for PostgreSQL](database.md) for information on runnin
 
 1. On your database node, ensure the following is set in your `/etc/gitlab/gitlab.rb`
 
-    ```ruby
-    postgresql['pgbouncer_user_password'] = 'PGBOUNCER_USER_PASSWORD_HASH'
-    postgresql['sql_user_password'] = 'SQL_USER_PASSWORD_HASH'
-    postgresql['listen_address'] = 'XX.XX.XX.Y' # Where XX.XX.XX.Y is the ip address on the node postgresql should listen on
-    postgresql['md5_auth_cidr_addresses'] = %w(AA.AA.AA.B/32) # Where AA.AA.AA.B is the IP address of the pgbouncer node
-    ```
+   ```ruby
+   postgresql['pgbouncer_user_password'] = 'PGBOUNCER_USER_PASSWORD_HASH'
+   postgresql['sql_user_password'] = 'SQL_USER_PASSWORD_HASH'
+   postgresql['listen_address'] = 'XX.XX.XX.Y' # Where XX.XX.XX.Y is the ip address on the node postgresql should listen on
+   postgresql['md5_auth_cidr_addresses'] = %w(AA.AA.AA.B/32) # Where AA.AA.AA.B is the IP address of the pgbouncer node
+   ```
 
 1. Run `gitlab-ctl reconfigure`
 
-    **Note:** If the database was already running, it will need to be restarted after reconfigure by running `gitlab-ctl restart postgresql`.
+   **Note:** If the database was already running, it will need to be restarted after reconfigure by running `gitlab-ctl restart postgresql`.
 
 1. On the node you are running pgbouncer on, make sure the following is set in `/etc/gitlab/gitlab.rb`
 
-    ```ruby
-    pgbouncer['enable'] = true
-    pgbouncer['databases'] = {
-      gitlabhq_production: {
-        host: 'DATABASE_HOST',
-        user: 'pgbouncer',
-        password: 'PGBOUNCER_USER_PASSWORD_HASH'
-      }
-    }
-    ```
+   ```ruby
+   pgbouncer['enable'] = true
+   pgbouncer['databases'] = {
+     gitlabhq_production: {
+       host: 'DATABASE_HOST',
+       user: 'pgbouncer',
+       password: 'PGBOUNCER_USER_PASSWORD_HASH'
+     }
+   }
+   ```
 
 1. Run `gitlab-ctl reconfigure`
 
 1. On the node running unicorn, make sure the following is set in `/etc/gitlab/gitlab.rb`
 
-    ```ruby
-    gitlab_rails['db_host'] = 'PGBOUNCER_HOST'
-    gitlab_rails['db_port'] = '6432'
-    gitlab_rails['db_password'] = 'SQL_USER_PASSWORD'
-    ```
+   ```ruby
+   gitlab_rails['db_host'] = 'PGBOUNCER_HOST'
+   gitlab_rails['db_port'] = '6432'
+   gitlab_rails['db_password'] = 'SQL_USER_PASSWORD'
+   ```
 
 1. Run `gitlab-ctl reconfigure`
 
 1. At this point, your instance should connect to the database through pgbouncer. If you are having issues, see the [Troubleshooting](#troubleshooting) section
 
+## Enable Monitoring
+
+> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3786) in GitLab 12.0.
+
+If you enable Monitoring, it must be enabled on **all** pgbouncer servers.
+
+1. Create/edit `/etc/gitlab/gitlab.rb` and add the following configuration:
+
+   ```ruby
+   # Enable service discovery for Prometheus
+   consul['enable'] = true
+   consul['monitoring_service_discovery'] =  true
+
+   # Replace placeholders
+   # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z
+   # with the addresses of the Consul server nodes
+   consul['configuration'] = {
+      retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z),
+   }
+
+   # Set the network addresses that the exporters will listen on
+   node_exporter['listen_address'] = '0.0.0.0:9100'
+   pgbouncer_exporter['listen_address'] = '0.0.0.0:9188'
+   ```
+
+1. Run `sudo gitlab-ctl reconfigure` to compile the configuration.
+
 ### Interacting with pgbouncer
 
 #### Administrative console
@@ -82,6 +193,7 @@ pgbouncer=#
 The password you will be prompted for is the PGBOUNCER_USER_PASSWORD
 
 To get some basic information about the instance, run
+
 ```shell
 pgbouncer=# show databases; show clients; show servers;
         name         |   host    | port |      database       | force_user | pool_size | reserve_pool | pool_mode | max_connections | current_connections
diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 1aaa709fc8f..1b79dde9476 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -1,6 +1,10 @@
+---
+type: reference
+---
+
 # Configuring Redis for Scaling and High Availability
 
-## Provide your own Redis instance **[CORE ONLY]**
+## Provide your own Redis instance **(CORE ONLY)**
 
 The following are the requirements for providing your own Redis instance:
 
@@ -20,14 +24,14 @@ This section is relevant for [Scaled Architecture](README.md#scalable-architectu
 environments including [Basic Scaling](README.md#basic-scaling) and
 [Full Scaling](README.md#full-scaling).
 
-### Provide your own Redis instance **[CORE ONLY]**
+### Provide your own Redis instance **(CORE ONLY)**
 
-If you want to use your own deployed Redis instance(s), 
-see [Provide your own Redis instance](#provide-your-own-redis-instance-core-only) 
-for more details. However, you can use the GitLab Omnibus package to easily 
-deploy the bundled Redis.  
+If you want to use your own deployed Redis instance(s),
+see [Provide your own Redis instance](#provide-your-own-redis-instance-core-only)
+for more details. However, you can use the GitLab Omnibus package to easily
+deploy the bundled Redis.
 
-### Standalone Redis using GitLab Omnibus **[CORE ONLY]**
+### Standalone Redis using GitLab Omnibus **(CORE ONLY)**
 
 The GitLab Omnibus package can be used to configure a standalone Redis server.
 In this configuration Redis is not highly available, and represents a single
@@ -41,39 +45,40 @@ The steps below are the minimum necessary to configure a Redis server with
 Omnibus:
 
 1. SSH into the Redis server.
-1. [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab
+1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab
    package you want using **steps 1 and 2** from the GitLab downloads page.
      - Do not complete any other steps on the download page.
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the contents:
 
-    ```ruby
-    ## Enable Redis
-    redis['enable'] = true
-
-    ## Disable all other services
-    sidekiq['enable'] = false
-    gitlab_workhorse['enable'] = false
-    unicorn['enable'] = false
-    postgresql['enable'] = false
-    nginx['enable'] = false
-    prometheus['enable'] = false
-    alertmanager['enable'] = false
-    pgbouncer_exporter['enable'] = false
-    gitlab_monitor['enable'] = false
-    gitaly['enable'] = false
- 
-    redis['bind'] = '0.0.0.0'
-    redis['port'] = '6379'
-    redis['password'] = 'SECRET_PASSWORD_HERE'
- 
-    gitlab_rails['auto_migrate'] = false
-    ```
+   ```ruby
+   ## Enable Redis
+   redis['enable'] = true
+
+   ## Disable all other services
+   sidekiq['enable'] = false
+   gitlab_workhorse['enable'] = false
+   unicorn['enable'] = false
+   postgresql['enable'] = false
+   nginx['enable'] = false
+   prometheus['enable'] = false
+   alertmanager['enable'] = false
+   pgbouncer_exporter['enable'] = false
+   gitlab_monitor['enable'] = false
+   gitaly['enable'] = false
+
+   redis['bind'] = '0.0.0.0'
+   redis['port'] = '6379'
+   redis['password'] = 'SECRET_PASSWORD_HERE'
+
+   gitlab_rails['auto_migrate'] = false
+   ```
 
 1. [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 1. Note the Redis node's IP address or hostname, port, and
    Redis password. These will be necessary when configuring the GitLab
    application servers later.
+1. [Enable Monitoring](#enable-monitoring)
 
 Advanced configuration options are supported and can be added if
 needed.
@@ -88,14 +93,14 @@ environments including [Horizontal](README.md#horizontal),
 [Hybrid](README.md#hybrid), and
 [Fully Distributed](README.md#fully-distributed).
 
-### Provide your own Redis instance **[CORE ONLY]**
+### Provide your own Redis instance **(CORE ONLY)**
 
-If you want to use your own deployed Redis instance(s), 
-see [Provide your own Redis instance](#provide-your-own-redis-instance-core-only) 
-for more details. However, you can use the GitLab Omnibus package to easily 
-deploy the bundled Redis.  
+If you want to use your own deployed Redis instance(s),
+see [Provide your own Redis instance](#provide-your-own-redis-instance-core-only)
+for more details. However, you can use the GitLab Omnibus package to easily
+deploy the bundled Redis.
 
-### High Availability with GitLab Omnibus **[PREMIUM ONLY]**
+### High Availability with GitLab Omnibus **(PREMIUM ONLY)**
 
 > Experimental Redis Sentinel support was [introduced in GitLab 8.11][ce-1877].
 Starting with 8.14, Redis Sentinel is no longer experimental.
@@ -356,95 +361,94 @@ The prerequisites for a HA Redis setup are the following:
 ### Step 1. Configuring the master Redis instance
 
 1. SSH into the **master** Redis server.
-1. [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab
+1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab
    package you want using **steps 1 and 2** from the GitLab downloads page.
-     - Make sure you select the correct Omnibus package, with the same version
-       and type (Community, Enterprise editions) of your current install.
-     - Do not complete any other steps on the download page.
+   - Make sure you select the correct Omnibus package, with the same version
+     and type (Community, Enterprise editions) of your current install.
+   - Do not complete any other steps on the download page.
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the contents:
 
-    ```ruby
-    # Specify server role as 'redis_master_role'
-    roles ['redis_master_role']
-    
-    # IP address pointing to a local IP that the other machines can reach to.
-    # You can also set bind to '0.0.0.0' which listen in all interfaces.
-    # If you really need to bind to an external accessible IP, make
-    # sure you add extra firewall rules to prevent unauthorized access.
-    redis['bind'] = '10.0.0.1'
-
-    # Define a port so Redis can listen for TCP requests which will allow other
-    # machines to connect to it.
-    redis['port'] = 6379
-
-    # Set up password authentication for Redis (use the same password in all nodes).
-    redis['password'] = 'redis-password-goes-here'
-    ```
-    
+   ```ruby
+   # Specify server role as 'redis_master_role'
+   roles ['redis_master_role']
+
+   # IP address pointing to a local IP that the other machines can reach to.
+   # You can also set bind to '0.0.0.0' which listen in all interfaces.
+   # If you really need to bind to an external accessible IP, make
+   # sure you add extra firewall rules to prevent unauthorized access.
+   redis['bind'] = '10.0.0.1'
+
+   # Define a port so Redis can listen for TCP requests which will allow other
+   # machines to connect to it.
+   redis['port'] = 6379
+
+   # Set up password authentication for Redis (use the same password in all nodes).
+   redis['password'] = 'redis-password-goes-here'
+   ```
 
 1. Only the primary GitLab application server should handle migrations. To
    prevent database migrations from running on upgrade, add the following
    configuration to your `/etc/gitlab/gitlab.rb` file:
 
-    ```
-    gitlab_rails['auto_migrate'] = false
-    ```
+   ```
+   gitlab_rails['auto_migrate'] = false
+   ```
 
 1. [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 
-> Note: You can specify multiple roles like sentinel and redis as: 
-> roles ['redis_sentinel_role', 'redis_master_role']. Read more about high 
-> availability roles at https://docs.gitlab.com/omnibus/roles/
+> Note: You can specify multiple roles like sentinel and redis as:
+> `roles ['redis_sentinel_role', 'redis_master_role']`. Read more about high
+> availability roles at <https://docs.gitlab.com/omnibus/roles/>.
 
 ### Step 2. Configuring the slave Redis instances
 
 1. SSH into the **slave** Redis server.
-1. [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab
+1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab
    package you want using **steps 1 and 2** from the GitLab downloads page.
-     - Make sure you select the correct Omnibus package, with the same version
-       and type (Community, Enterprise editions) of your current install.
-     - Do not complete any other steps on the download page.
+   - Make sure you select the correct Omnibus package, with the same version
+     and type (Community, Enterprise editions) of your current install.
+   - Do not complete any other steps on the download page.
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the contents:
 
-    ```ruby
-    # Specify server role as 'redis_slave_role'
-    roles ['redis_slave_role']
-    
-    # IP address pointing to a local IP that the other machines can reach to.
-    # You can also set bind to '0.0.0.0' which listen in all interfaces.
-    # If you really need to bind to an external accessible IP, make
-    # sure you add extra firewall rules to prevent unauthorized access.
-    redis['bind'] = '10.0.0.2'
+   ```ruby
+   # Specify server role as 'redis_slave_role'
+   roles ['redis_slave_role']
+
+   # IP address pointing to a local IP that the other machines can reach to.
+   # You can also set bind to '0.0.0.0' which listen in all interfaces.
+   # If you really need to bind to an external accessible IP, make
+   # sure you add extra firewall rules to prevent unauthorized access.
+   redis['bind'] = '10.0.0.2'
 
-    # Define a port so Redis can listen for TCP requests which will allow other
-    # machines to connect to it.
-    redis['port'] = 6379
+   # Define a port so Redis can listen for TCP requests which will allow other
+   # machines to connect to it.
+   redis['port'] = 6379
 
-    # The same password for Redis authentication you set up for the master node.
-    redis['password'] = 'redis-password-goes-here'
+   # The same password for Redis authentication you set up for the master node.
+   redis['password'] = 'redis-password-goes-here'
 
-    # The IP of the master Redis node.
-    redis['master_ip'] = '10.0.0.1'
+   # The IP of the master Redis node.
+   redis['master_ip'] = '10.0.0.1'
 
-    # Port of master Redis server, uncomment to change to non default. Defaults
-    # to `6379`.
-    #redis['master_port'] = 6379
-    ```
+   # Port of master Redis server, uncomment to change to non default. Defaults
+   # to `6379`.
+   #redis['master_port'] = 6379
+   ```
 
 1. To prevent reconfigure from running automatically on upgrade, run:
 
-    ```
-    sudo touch /etc/gitlab/skip-auto-reconfigure
-    ```
+   ```
+   sudo touch /etc/gitlab/skip-auto-reconfigure
+   ```
 
 1. [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 1. Go through the steps again for all the other slave nodes.
 
-> Note: You can specify multiple roles like sentinel and redis as: 
-> roles ['redis_sentinel_role', 'redis_slave_role']. Read more about high 
-> availability roles at https://docs.gitlab.com/omnibus/roles/
+> Note: You can specify multiple roles like sentinel and redis as:
+> `roles ['redis_sentinel_role', 'redis_slave_role']`. Read more about high
+> availability roles at <https://docs.gitlab.com/omnibus/roles/>.
 
 ---
 
@@ -487,89 +491,89 @@ multiple machines with the Sentinel daemon.
 1. **You can omit this step if the Sentinels will be hosted in the same node as
    the other Redis instances.**
 
-     [Download/install](https://about.gitlab.com/downloads-ee) the
-     Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the
-     GitLab downloads page.
-     - Make sure you select the correct Omnibus package, with the same version
-       the GitLab application is running.
-     - Do not complete any other steps on the download page.
+   [Download/install](https://about.gitlab.com/downloads-ee) the
+   Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the
+   GitLab downloads page.
+   - Make sure you select the correct Omnibus package, with the same version
+     the GitLab application is running.
+   - Do not complete any other steps on the download page.
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the contents (if you are installing the
    Sentinels in the same node as the other Redis instances, some values might
    be duplicate below):
 
-    ```ruby
-    roles ['redis_sentinel_role']
-
-    # Must be the same in every sentinel node
-    redis['master_name'] = 'gitlab-redis'
-
-    # The same password for Redis authentication you set up for the master node.
-    redis['master_password'] = 'redis-password-goes-here'
-
-    # The IP of the master Redis node.
-    redis['master_ip'] = '10.0.0.1'
-
-    # Define a port so Redis can listen for TCP requests which will allow other
-    # machines to connect to it.
-    redis['port'] = 6379
-
-    # Port of master Redis server, uncomment to change to non default. Defaults
-    # to `6379`.
-    #redis['master_port'] = 6379
-
-    ## Configure Sentinel
-    sentinel['bind'] = '10.0.0.1'
-
-    # Port that Sentinel listens on, uncomment to change to non default. Defaults
-    # to `26379`.
-    # sentinel['port'] = 26379
-
-    ## Quorum must reflect the amount of voting sentinels it take to start a failover.
-    ## Value must NOT be greater then the amount of sentinels.
-    ##
-    ## The quorum can be used to tune Sentinel in two ways:
-    ## 1. If a the quorum is set to a value smaller than the majority of Sentinels
-    ##    we deploy, we are basically making Sentinel more sensible to master failures,
-    ##    triggering a failover as soon as even just a minority of Sentinels is no longer
-    ##    able to talk with the master.
-    ## 1. If a quorum is set to a value greater than the majority of Sentinels, we are
-    ##    making Sentinel able to failover only when there are a very large number (larger
-    ##    than majority) of well connected Sentinels which agree about the master being down.s
-    sentinel['quorum'] = 2
-
-    ## Consider unresponsive server down after x amount of ms.
-    # sentinel['down_after_milliseconds'] = 10000
-
-    ## Specifies the failover timeout in milliseconds. It is used in many ways:
-    ##
-    ## - The time needed to re-start a failover after a previous failover was
-    ##   already tried against the same master by a given Sentinel, is two
-    ##   times the failover timeout.
-    ##
-    ## - The time needed for a slave replicating to a wrong master according
-    ##   to a Sentinel current configuration, to be forced to replicate
-    ##   with the right master, is exactly the failover timeout (counting since
-    ##   the moment a Sentinel detected the misconfiguration).
-    ##
-    ## - The time needed to cancel a failover that is already in progress but
-    ##   did not produced any configuration change (SLAVEOF NO ONE yet not
-    ##   acknowledged by the promoted slave).
-    ##
-    ## - The maximum time a failover in progress waits for all the slaves to be
-    ##   reconfigured as slaves of the new master. However even after this time
-    ##   the slaves will be reconfigured by the Sentinels anyway, but not with
-    ##   the exact parallel-syncs progression as specified.
-    # sentinel['failover_timeout'] = 60000
-    ```
+   ```ruby
+   roles ['redis_sentinel_role']
+
+   # Must be the same in every sentinel node
+   redis['master_name'] = 'gitlab-redis'
+
+   # The same password for Redis authentication you set up for the master node.
+   redis['master_password'] = 'redis-password-goes-here'
+
+   # The IP of the master Redis node.
+   redis['master_ip'] = '10.0.0.1'
+
+   # Define a port so Redis can listen for TCP requests which will allow other
+   # machines to connect to it.
+   redis['port'] = 6379
+
+   # Port of master Redis server, uncomment to change to non default. Defaults
+   # to `6379`.
+   #redis['master_port'] = 6379
+
+   ## Configure Sentinel
+   sentinel['bind'] = '10.0.0.1'
+
+   # Port that Sentinel listens on, uncomment to change to non default. Defaults
+   # to `26379`.
+   # sentinel['port'] = 26379
+
+   ## Quorum must reflect the amount of voting sentinels it take to start a failover.
+   ## Value must NOT be greater then the amount of sentinels.
+   ##
+   ## The quorum can be used to tune Sentinel in two ways:
+   ## 1. If a the quorum is set to a value smaller than the majority of Sentinels
+   ##    we deploy, we are basically making Sentinel more sensible to master failures,
+   ##    triggering a failover as soon as even just a minority of Sentinels is no longer
+   ##    able to talk with the master.
+   ## 1. If a quorum is set to a value greater than the majority of Sentinels, we are
+   ##    making Sentinel able to failover only when there are a very large number (larger
+   ##    than majority) of well connected Sentinels which agree about the master being down.s
+   sentinel['quorum'] = 2
+
+   ## Consider unresponsive server down after x amount of ms.
+   # sentinel['down_after_milliseconds'] = 10000
+
+   ## Specifies the failover timeout in milliseconds. It is used in many ways:
+   ##
+   ## - The time needed to re-start a failover after a previous failover was
+   ##   already tried against the same master by a given Sentinel, is two
+   ##   times the failover timeout.
+   ##
+   ## - The time needed for a slave replicating to a wrong master according
+   ##   to a Sentinel current configuration, to be forced to replicate
+   ##   with the right master, is exactly the failover timeout (counting since
+   ##   the moment a Sentinel detected the misconfiguration).
+   ##
+   ## - The time needed to cancel a failover that is already in progress but
+   ##   did not produced any configuration change (SLAVEOF NO ONE yet not
+   ##   acknowledged by the promoted slave).
+   ##
+   ## - The maximum time a failover in progress waits for all the slaves to be
+   ##   reconfigured as slaves of the new master. However even after this time
+   ##   the slaves will be reconfigured by the Sentinels anyway, but not with
+   ##   the exact parallel-syncs progression as specified.
+   # sentinel['failover_timeout'] = 60000
+   ```
 
 1. To prevent database migrations from running on upgrade, run:
 
-    ```
-    sudo touch /etc/gitlab/skip-auto-reconfigure
-    ```
+   ```
+   sudo touch /etc/gitlab/skip-auto-reconfigure
+   ```
 
-    Only the primary GitLab application server should handle migrations.
+   Only the primary GitLab application server should handle migrations.
 
 1. [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 1. Go through the steps again for all the other Sentinel nodes.
@@ -593,20 +597,20 @@ which ideally should not have Redis or Sentinels on it for a HA setup.
 1. SSH into the server where the GitLab application is installed.
 1. Edit `/etc/gitlab/gitlab.rb` and add/change the following lines:
 
-    ```
-    ## Must be the same in every sentinel node
-    redis['master_name'] = 'gitlab-redis'
+   ```ruby
+   ## Must be the same in every sentinel node
+   redis['master_name'] = 'gitlab-redis'
 
-    ## The same password for Redis authentication you set up for the master node.
-    redis['master_password'] = 'redis-password-goes-here'
+   ## The same password for Redis authentication you set up for the master node.
+   redis['master_password'] = 'redis-password-goes-here'
 
-    ## A list of sentinels with `host` and `port`
-    gitlab_rails['redis_sentinels'] = [
-      {'host' => '10.0.0.1', 'port' => 26379},
-      {'host' => '10.0.0.2', 'port' => 26379},
-      {'host' => '10.0.0.3', 'port' => 26379}
-    ]
-    ```
+   ## A list of sentinels with `host` and `port`
+   gitlab_rails['redis_sentinels'] = [
+     {'host' => '10.0.0.1', 'port' => 26379},
+     {'host' => '10.0.0.2', 'port' => 26379},
+     {'host' => '10.0.0.3', 'port' => 26379}
+   ]
+   ```
 
 1. [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 
@@ -749,6 +753,35 @@ gitlab_rails['redis_sentinels'] = [
 
 [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 
+## Enable Monitoring
+
+> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3786) in GitLab 12.0.
+
+If you enable Monitoring, it must be enabled on **all** Redis servers.
+
+1. Make sure to collect [`CONSUL_SERVER_NODES`](database.md#consul-information), which are the IP addresses or DNS records of the Consul server nodes, for the next step. Note they are presented as `Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z`
+
+1. Create/edit `/etc/gitlab/gitlab.rb` and add the following configuration:
+
+   ```ruby
+   # Enable service discovery for Prometheus
+   consul['enable'] = true
+   consul['monitoring_service_discovery'] =  true
+
+   # Replace placeholders
+   # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z
+   # with the addresses of the Consul server nodes
+   consul['configuration'] = {
+      retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z),
+   }
+
+   # Set the network addresses that the exporters will listen on
+   node_exporter['listen_address'] = '0.0.0.0:9100'
+   redis_exporter['listen_address'] = '0.0.0.0:9121'
+   ```
+
+1. Run `sudo gitlab-ctl reconfigure` to compile the configuration.
+
 ## Advanced configuration
 
 Omnibus GitLab configures some things behind the curtains to make the sysadmins'
@@ -762,31 +795,34 @@ cache, queues, and shared_state. To make this work with Sentinel:
 
 1. Set the appropriate variable in `/etc/gitlab/gitlab.rb` for each instance you are using:
 
-    ```ruby
-    gitlab_rails['redis_cache_instance'] = REDIS_CACHE_URL
-    gitlab_rails['redis_queues_instance'] = REDIS_QUEUES_URL
-    gitlab_rails['redis_shared_state_instance'] = REDIS_SHARED_STATE_URL
-    ```
+   ```ruby
+   gitlab_rails['redis_cache_instance'] = REDIS_CACHE_URL
+   gitlab_rails['redis_queues_instance'] = REDIS_QUEUES_URL
+   gitlab_rails['redis_shared_state_instance'] = REDIS_SHARED_STATE_URL
+   ```
+
     **Note**: Redis URLs should be in the format: `redis://:PASSWORD@SENTINEL_MASTER_NAME`
 
-    1. PASSWORD is the plaintext password for the Redis instance
-    1. SENTINEL_MASTER_NAME is the Sentinel master name (e.g. `gitlab-redis-cache`)
+   1. PASSWORD is the plaintext password for the Redis instance
+   1. SENTINEL_MASTER_NAME is the Sentinel master name (e.g. `gitlab-redis-cache`)
+
 1. Include an array of hashes with host/port combinations, such as the following:
 
-    ```ruby
-    gitlab_rails['redis_cache_sentinels'] = [
-      { host: REDIS_CACHE_SENTINEL_HOST, port: PORT1 },
-      { host: REDIS_CACHE_SENTINEL_HOST2, port: PORT2 }
-    ]
-    gitlab_rails['redis_queues_sentinels'] = [
-      { host: REDIS_QUEUES_SENTINEL_HOST, port: PORT1 },
-      { host: REDIS_QUEUES_SENTINEL_HOST2, port: PORT2 }
-    ]
-    gitlab_rails['redis_shared_state_sentinels'] = [
-      { host: SHARED_STATE_SENTINEL_HOST, port: PORT1 },
-      { host: SHARED_STATE_SENTINEL_HOST2, port: PORT2 }
-    ]
-    ```
+   ```ruby
+   gitlab_rails['redis_cache_sentinels'] = [
+     { host: REDIS_CACHE_SENTINEL_HOST, port: PORT1 },
+     { host: REDIS_CACHE_SENTINEL_HOST2, port: PORT2 }
+   ]
+   gitlab_rails['redis_queues_sentinels'] = [
+     { host: REDIS_QUEUES_SENTINEL_HOST, port: PORT1 },
+     { host: REDIS_QUEUES_SENTINEL_HOST2, port: PORT2 }
+   ]
+   gitlab_rails['redis_shared_state_sentinels'] = [
+     { host: SHARED_STATE_SENTINEL_HOST, port: PORT1 },
+     { host: SHARED_STATE_SENTINEL_HOST2, port: PORT2 }
+   ]
+   ```
+
 1. Note that for each persistence class, GitLab will default to using the
    configuration specified in `gitlab_rails['redis_sentinels']` unless
    overridden by the settings above.
@@ -850,12 +886,12 @@ in order for the HA setup to work as expected.
 Before proceeding with the troubleshooting below, check your firewall rules:
 
 - Redis machines
-   - Accept TCP connection in `6379`
-   - Connect to the other Redis machines via TCP in `6379`
+  - Accept TCP connection in `6379`
+  - Connect to the other Redis machines via TCP in `6379`
 - Sentinel machines
-   - Accept TCP connection in `26379`
-   - Connect to other Sentinel machines via TCP in `26379`
-   - Connect to the Redis machines via TCP in `6379`
+  - Accept TCP connection in `26379`
+  - Connect to other Sentinel machines via TCP in `26379`
+  - Connect to the Redis machines via TCP in `6379`
 
 ### Troubleshooting Redis replication
 
@@ -923,38 +959,38 @@ To make sure your configuration is correct:
 1. SSH into your GitLab application server
 1. Enter the Rails console:
 
-    ```
-    # For Omnibus installations
-    sudo gitlab-rails console
+   ```
+   # For Omnibus installations
+   sudo gitlab-rails console
 
-    # For source installations
-    sudo -u git rails console production
-    ```
+   # For source installations
+   sudo -u git rails console production
+   ```
 
 1. Run in the console:
 
-    ```ruby
-    redis = Redis.new(Gitlab::Redis::SharedState.params)
-    redis.info
-    ```
+   ```ruby
+   redis = Redis.new(Gitlab::Redis::SharedState.params)
+   redis.info
+   ```
 
-    Keep this screen open and try to simulate a failover below.
+   Keep this screen open and try to simulate a failover below.
 
 1. To simulate a failover on master Redis, SSH into the Redis server and run:
 
-    ```bash
-    # port must match your master redis port, and the sleep time must be a few seconds bigger than defined one
-     redis-cli -h localhost -p 6379 DEBUG sleep 20
-    ```
+   ```bash
+   # port must match your master redis port, and the sleep time must be a few seconds bigger than defined one
+    redis-cli -h localhost -p 6379 DEBUG sleep 20
+   ```
 
 1. Then back in the Rails console from the first step, run:
 
-    ```
-    redis.info
-    ```
+   ```
+   redis.info
+   ```
 
-    You should see a different port after a few seconds delay
-    (the failover/reconnect time).
+   You should see a different port after a few seconds delay
+   (the failover/reconnect time).
 
 ## Changelog
 
diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md
index be6b547372a..63915e5d96c 100644
--- a/doc/administration/high_availability/redis_source.md
+++ b/doc/administration/high_availability/redis_source.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Configuring non-Omnibus Redis for GitLab HA
 
 This is the documentation for configuring a Highly Available Redis setup when
@@ -49,22 +53,22 @@ Assuming that the Redis master instance IP is `10.0.0.1`:
 1. [Install Redis](../../install/installation.md#7-redis).
 1. Edit `/etc/redis/redis.conf`:
 
-    ```conf
-    ## Define a `bind` address pointing to a local IP that your other machines
-    ## can reach you. If you really need to bind to an external accessible IP, make
-    ## sure you add extra firewall rules to prevent unauthorized access:
-    bind 10.0.0.1
+   ```conf
+   ## Define a `bind` address pointing to a local IP that your other machines
+   ## can reach you. If you really need to bind to an external accessible IP, make
+   ## sure you add extra firewall rules to prevent unauthorized access:
+   bind 10.0.0.1
 
-    ## Define a `port` to force redis to listen on TCP so other machines can
-    ## connect to it (default port is `6379`).
-    port 6379
+   ## Define a `port` to force redis to listen on TCP so other machines can
+   ## connect to it (default port is `6379`).
+   port 6379
 
-    ## Set up password authentication (use the same password in all nodes).
-    ## The password should be defined equal for both `requirepass` and `masterauth`
-    ## when setting up Redis to use with Sentinel.
-    requirepass redis-password-goes-here
-    masterauth redis-password-goes-here
-    ```
+   ## Set up password authentication (use the same password in all nodes).
+   ## The password should be defined equal for both `requirepass` and `masterauth`
+   ## when setting up Redis to use with Sentinel.
+   requirepass redis-password-goes-here
+   masterauth redis-password-goes-here
+   ```
 
 1. Restart the Redis service for the changes to take effect.
 
@@ -75,25 +79,25 @@ Assuming that the Redis slave instance IP is `10.0.0.2`:
 1. [Install Redis](../../install/installation.md#7-redis).
 1. Edit `/etc/redis/redis.conf`:
 
-    ```conf
-    ## Define a `bind` address pointing to a local IP that your other machines
-    ## can reach you. If you really need to bind to an external accessible IP, make
-    ## sure you add extra firewall rules to prevent unauthorized access:
-    bind 10.0.0.2
+   ```conf
+   ## Define a `bind` address pointing to a local IP that your other machines
+   ## can reach you. If you really need to bind to an external accessible IP, make
+   ## sure you add extra firewall rules to prevent unauthorized access:
+   bind 10.0.0.2
 
-    ## Define a `port` to force redis to listen on TCP so other machines can
-    ## connect to it (default port is `6379`).
-    port 6379
+   ## Define a `port` to force redis to listen on TCP so other machines can
+   ## connect to it (default port is `6379`).
+   port 6379
 
-    ## Set up password authentication (use the same password in all nodes).
-    ## The password should be defined equal for both `requirepass` and `masterauth`
-    ## when setting up Redis to use with Sentinel.
-    requirepass redis-password-goes-here
-    masterauth redis-password-goes-here
+   ## Set up password authentication (use the same password in all nodes).
+   ## The password should be defined equal for both `requirepass` and `masterauth`
+   ## when setting up Redis to use with Sentinel.
+   requirepass redis-password-goes-here
+   masterauth redis-password-goes-here
 
-    ## Define `slaveof` pointing to the Redis master instance with IP and port.
-    slaveof 10.0.0.1 6379
-    ```
+   ## Define `slaveof` pointing to the Redis master instance with IP and port.
+   slaveof 10.0.0.1 6379
+   ```
 
 1. Restart the Redis service for the changes to take effect.
 1. Go through the steps again for all the other slave nodes.
@@ -110,56 +114,57 @@ master with IP `10.0.0.1` (some settings might overlap with the master):
 1. [Install Redis Sentinel](https://redis.io/topics/sentinel)
 1. Edit `/etc/redis/sentinel.conf`:
 
-    ```conf
-    ## Define a `bind` address pointing to a local IP that your other machines
-    ## can reach you. If you really need to bind to an external accessible IP, make
-    ## sure you add extra firewall rules to prevent unauthorized access:
-    bind 10.0.0.1
-
-    ## Define a `port` to force Sentinel to listen on TCP so other machines can
-    ## connect to it (default port is `6379`).
-    port 26379
-
-    ## Set up password authentication (use the same password in all nodes).
-    ## The password should be defined equal for both `requirepass` and `masterauth`
-    ## when setting up Redis to use with Sentinel.
-    requirepass redis-password-goes-here
-    masterauth redis-password-goes-here
-
-    ## Define with `sentinel auth-pass` the same shared password you have
-    ## defined for both Redis master and slaves instances.
-    sentinel auth-pass gitlab-redis redis-password-goes-here
-
-    ## Define with `sentinel monitor` the IP and port of the Redis
-    ## master node, and the quorum required to start a failover.
-    sentinel monitor gitlab-redis 10.0.0.1 6379 2
-
-    ## Define with `sentinel down-after-milliseconds` the time in `ms`
-    ## that an unresponsive server will be considered down.
-    sentinel down-after-milliseconds gitlab-redis 10000
-
-    ## Define a value for `sentinel failover_timeout` in `ms`. This has multiple
-    ## meanings:
-    ##
-    ## * The time needed to re-start a failover after a previous failover was
-    ##   already tried against the same master by a given Sentinel, is two
-    ##   times the failover timeout.
-    ##
-    ## * The time needed for a slave replicating to a wrong master according
-    ##   to a Sentinel current configuration, to be forced to replicate
-    ##   with the right master, is exactly the failover timeout (counting since
-    ##   the moment a Sentinel detected the misconfiguration).
-    ##
-    ## * The time needed to cancel a failover that is already in progress but
-    ##   did not produced any configuration change (SLAVEOF NO ONE yet not
-    ##   acknowledged by the promoted slave).
-    ##
-    ## * The maximum time a failover in progress waits for all the slaves to be
-    ##   reconfigured as slaves of the new master. However even after this time
-    ##   the slaves will be reconfigured by the Sentinels anyway, but not with
-    ##   the exact parallel-syncs progression as specified.
-    sentinel failover_timeout 30000
-    ```
+   ```conf
+   ## Define a `bind` address pointing to a local IP that your other machines
+   ## can reach you. If you really need to bind to an external accessible IP, make
+   ## sure you add extra firewall rules to prevent unauthorized access:
+   bind 10.0.0.1
+
+   ## Define a `port` to force Sentinel to listen on TCP so other machines can
+   ## connect to it (default port is `6379`).
+   port 26379
+
+   ## Set up password authentication (use the same password in all nodes).
+   ## The password should be defined equal for both `requirepass` and `masterauth`
+   ## when setting up Redis to use with Sentinel.
+   requirepass redis-password-goes-here
+   masterauth redis-password-goes-here
+
+   ## Define with `sentinel auth-pass` the same shared password you have
+   ## defined for both Redis master and slaves instances.
+   sentinel auth-pass gitlab-redis redis-password-goes-here
+
+   ## Define with `sentinel monitor` the IP and port of the Redis
+   ## master node, and the quorum required to start a failover.
+   sentinel monitor gitlab-redis 10.0.0.1 6379 2
+
+   ## Define with `sentinel down-after-milliseconds` the time in `ms`
+   ## that an unresponsive server will be considered down.
+   sentinel down-after-milliseconds gitlab-redis 10000
+
+   ## Define a value for `sentinel failover_timeout` in `ms`. This has multiple
+   ## meanings:
+   ##
+   ## * The time needed to re-start a failover after a previous failover was
+   ##   already tried against the same master by a given Sentinel, is two
+   ##   times the failover timeout.
+   ##
+   ## * The time needed for a slave replicating to a wrong master according
+   ##   to a Sentinel current configuration, to be forced to replicate
+   ##   with the right master, is exactly the failover timeout (counting since
+   ##   the moment a Sentinel detected the misconfiguration).
+   ##
+   ## * The time needed to cancel a failover that is already in progress but
+   ##   did not produced any configuration change (SLAVEOF NO ONE yet not
+   ##   acknowledged by the promoted slave).
+   ##
+   ## * The maximum time a failover in progress waits for all the slaves to be
+   ##   reconfigured as slaves of the new master. However even after this time
+   ##   the slaves will be reconfigured by the Sentinels anyway, but not with
+   ##   the exact parallel-syncs progression as specified.
+   sentinel failover_timeout 30000
+   ```
+
 1. Restart the Redis service for the changes to take effect.
 1. Go through the steps again for all the other Sentinel nodes.
 
@@ -180,21 +185,21 @@ setup:
    [resque.yml.example][resque], and uncomment the Sentinel lines, pointing to
    the correct server credentials:
 
-    ```yaml
-    # resque.yaml
-    production:
-      url: redis://:redi-password-goes-here@gitlab-redis/
-      sentinels:
-        -
-          host: 10.0.0.1
-          port: 26379 # point to sentinel, not to redis port
-        -
-          host: 10.0.0.2
-          port: 26379 # point to sentinel, not to redis port
-        -
-          host: 10.0.0.3
-          port: 26379 # point to sentinel, not to redis port
-    ```
+   ```yaml
+   # resque.yaml
+   production:
+     url: redis://:redi-password-goes-here@gitlab-redis/
+     sentinels:
+       -
+         host: 10.0.0.1
+         port: 26379 # point to sentinel, not to redis port
+       -
+         host: 10.0.0.2
+         port: 26379 # point to sentinel, not to redis port
+       -
+         host: 10.0.0.3
+         port: 26379 # point to sentinel, not to redis port
+   ```
 
 1. [Restart GitLab][restart] for the changes to take effect.
 
@@ -232,23 +237,23 @@ or a failover promotes a different **Master** node.
 
 1. In `/etc/redis/redis.conf`:
 
-    ```conf
-    bind 10.0.0.1
-    port 6379
-    requirepass redis-password-goes-here
-    masterauth redis-password-goes-here
-    ```
+   ```conf
+   bind 10.0.0.1
+   port 6379
+   requirepass redis-password-goes-here
+   masterauth redis-password-goes-here
+   ```
 
 1. In `/etc/redis/sentinel.conf`:
 
-    ```conf
-    bind 10.0.0.1
-    port 26379
-    sentinel auth-pass gitlab-redis redis-password-goes-here
-    sentinel monitor gitlab-redis 10.0.0.1 6379 2
-    sentinel down-after-milliseconds gitlab-redis 10000
-    sentinel failover_timeout 30000
-    ```
+   ```conf
+   bind 10.0.0.1
+   port 26379
+   sentinel auth-pass gitlab-redis redis-password-goes-here
+   sentinel monitor gitlab-redis 10.0.0.1 6379 2
+   sentinel down-after-milliseconds gitlab-redis 10000
+   sentinel failover_timeout 30000
+   ```
 
 1. Restart the Redis service for the changes to take effect.
 
@@ -256,24 +261,24 @@ or a failover promotes a different **Master** node.
 
 1. In `/etc/redis/redis.conf`:
 
-    ```conf
-    bind 10.0.0.2
-    port 6379
-    requirepass redis-password-goes-here
-    masterauth redis-password-goes-here
-    slaveof 10.0.0.1 6379
-    ```
+   ```conf
+   bind 10.0.0.2
+   port 6379
+   requirepass redis-password-goes-here
+   masterauth redis-password-goes-here
+   slaveof 10.0.0.1 6379
+   ```
 
 1. In `/etc/redis/sentinel.conf`:
 
-    ```conf
-    bind 10.0.0.2
-    port 26379
-    sentinel auth-pass gitlab-redis redis-password-goes-here
-    sentinel monitor gitlab-redis 10.0.0.1 6379 2
-    sentinel down-after-milliseconds gitlab-redis 10000
-    sentinel failover_timeout 30000
-    ```
+   ```conf
+   bind 10.0.0.2
+   port 26379
+   sentinel auth-pass gitlab-redis redis-password-goes-here
+   sentinel monitor gitlab-redis 10.0.0.1 6379 2
+   sentinel down-after-milliseconds gitlab-redis 10000
+   sentinel failover_timeout 30000
+   ```
 
 1. Restart the Redis service for the changes to take effect.
 
@@ -281,24 +286,24 @@ or a failover promotes a different **Master** node.
 
 1. In `/etc/redis/redis.conf`:
 
-    ```conf
-    bind 10.0.0.3
-    port 6379
-    requirepass redis-password-goes-here
-    masterauth redis-password-goes-here
-    slaveof 10.0.0.1 6379
-    ```
+   ```conf
+   bind 10.0.0.3
+   port 6379
+   requirepass redis-password-goes-here
+   masterauth redis-password-goes-here
+   slaveof 10.0.0.1 6379
+   ```
 
 1. In `/etc/redis/sentinel.conf`:
 
-    ```conf
-    bind 10.0.0.3
-    port 26379
-    sentinel auth-pass gitlab-redis redis-password-goes-here
-    sentinel monitor gitlab-redis 10.0.0.1 6379 2
-    sentinel down-after-milliseconds gitlab-redis 10000
-    sentinel failover_timeout 30000
-    ```
+   ```conf
+   bind 10.0.0.3
+   port 26379
+   sentinel auth-pass gitlab-redis redis-password-goes-here
+   sentinel monitor gitlab-redis 10.0.0.1 6379 2
+   sentinel down-after-milliseconds gitlab-redis 10000
+   sentinel failover_timeout 30000
+   ```
 
 1. Restart the Redis service for the changes to take effect.
 
@@ -306,20 +311,20 @@ or a failover promotes a different **Master** node.
 
 1. Edit `/home/git/gitlab/config/resque.yml`:
 
-    ```yaml
-    production:
-      url: redis://:redi-password-goes-here@gitlab-redis/
-      sentinels:
-        -
-          host: 10.0.0.1
-          port: 26379 # point to sentinel, not to redis port
-        -
-          host: 10.0.0.2
-          port: 26379 # point to sentinel, not to redis port
-        -
-          host: 10.0.0.3
-          port: 26379 # point to sentinel, not to redis port
-    ```
+   ```yaml
+   production:
+     url: redis://:redi-password-goes-here@gitlab-redis/
+     sentinels:
+       -
+         host: 10.0.0.1
+         port: 26379 # point to sentinel, not to redis port
+       -
+         host: 10.0.0.2
+         port: 26379 # point to sentinel, not to redis port
+       -
+         host: 10.0.0.3
+         port: 26379 # point to sentinel, not to redis port
+   ```
 
 1. [Restart GitLab][restart] for the changes to take effect.
 
diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md
index 1b01419e062..abe39d188aa 100644
--- a/doc/administration/housekeeping.md
+++ b/doc/administration/housekeeping.md
@@ -2,7 +2,6 @@
 
 > [Introduced][ce-2371] in GitLab 8.4.
 
----
 ## Automatic housekeeping
 
 GitLab automatically runs `git gc` and `git repack` on repositories
@@ -32,8 +31,6 @@ the `pushes_since_gc` value is 200 a `git gc` will be run.
 
 You can find this option under your project's **Settings > General > Advanced**.
 
----
-
 ![Housekeeping settings](img/housekeeping_settings.png)
 
 [ce-2371]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2371 "Housekeeping merge request"
diff --git a/doc/administration/audit_log.png b/doc/administration/img/audit_log.png
index d4f4c2abf38..d4f4c2abf38 100644
--- a/doc/administration/audit_log.png
+++ b/doc/administration/img/audit_log.png
diff --git a/doc/administration/auditor_access_form.png b/doc/administration/img/auditor_access_form.png
index c179a7d3b0a..c179a7d3b0a 100644
--- a/doc/administration/auditor_access_form.png
+++ b/doc/administration/img/auditor_access_form.png
diff --git a/doc/administration/img/custom_hooks_error_msg.png b/doc/administration/img/custom_hooks_error_msg.png
index 4f25c471908..e7d5c157d08 100644
--- a/doc/administration/img/custom_hooks_error_msg.png
+++ b/doc/administration/img/custom_hooks_error_msg.png
diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md
index 8271c579f5b..73a39a6dd35 100644
--- a/doc/administration/incoming_email.md
+++ b/doc/administration/incoming_email.md
@@ -4,14 +4,14 @@ 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):
+- [New issue by email](../user/project/issues/managing_issues.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.
 - [Service Desk](../user/project/service_desk.md): provide e-mail support to
-  your customers through GitLab. **[PREMIUM]**
+  your customers through GitLab. **(PREMIUM)**
 
 ## Requirements
 
@@ -102,16 +102,16 @@ for a real-world example of this exploit.
 
 1. Reconfigure GitLab for the changes to take effect:
 
-    ```sh
-    sudo gitlab-ctl reconfigure
-    sudo gitlab-ctl restart
-    ```
+   ```sh
+   sudo gitlab-ctl reconfigure
+   sudo gitlab-ctl restart
+   ```
 
 1. Verify that everything is configured correctly:
 
-    ```sh
-    sudo gitlab-rake gitlab:incoming_email:check
-    ```
+   ```sh
+   sudo gitlab-rake gitlab:incoming_email:check
+   ```
 
 Reply by email should now be working.
 
@@ -119,31 +119,31 @@ Reply by email should now be working.
 
 1. Go to the GitLab installation directory:
 
-    ```sh
-    cd /home/git/gitlab
-    ```
+   ```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 (see [examples](#config-examples) below).
 
 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
-    ```
+   ```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
-    ```
+   ```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
-    ```
+   ```sh
+   sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
+   ```
 
 Reply by email should now be working.
 
diff --git a/doc/administration/index.md b/doc/administration/index.md
index 06d900b152d..2b25e8efd23 100644
--- a/doc/administration/index.md
+++ b/doc/administration/index.md
@@ -2,7 +2,7 @@
 description: 'Learn how to install, configure, update, and maintain your GitLab instance.'
 ---
 
-# Administrator documentation **[CORE ONLY]**
+# Administrator Docs **(CORE ONLY)**
 
 Learn how to administer your self-managed GitLab instance.
 
@@ -11,7 +11,7 @@ GitLab has two product distributions available through [different subscriptions]
 - The open source [GitLab Community Edition (CE)](https://gitlab.com/gitlab-org/gitlab-ce).
 - The open core [GitLab Enterprise Edition (EE)](https://gitlab.com/gitlab-org/gitlab-ee).
 
-You can [install either GitLab CE or GitLab EE](https://about.gitlab.com/installation/ce-or-ee/).
+You can [install either GitLab CE or GitLab EE](https://about.gitlab.com/install/ce-or-ee/).
 However, the features you'll have access to depend on the subscription you choose
 (Core, Starter, Premium, or Ultimate).
 
@@ -32,15 +32,14 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 ### Installing GitLab
 
 - [Install](../install/README.md): Requirements, directory structures, and installation methods.
-  - [Database load balancing](database_load_balancing.md): Distribute database queries among multiple database servers. **[STARTER ONLY]**
-  - [Omnibus support for external MySQL DB](https://docs.gitlab.com/omnibus/settings/database.html#using-a-mysql-database-management-server-enterprise-edition-only): Omnibus package supports configuring an external MySQL database. **[STARTER ONLY]**
-  - [Omnibus support for log forwarding](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only) **[STARTER ONLY]**
+  - [Database load balancing](database_load_balancing.md): Distribute database queries among multiple database servers. **(STARTER ONLY)**
+  - [Omnibus support for log forwarding](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only) **(STARTER ONLY)**
 - [High Availability](high_availability/README.md): Configure multiple servers for scaling or high availability.
   - [Installing GitLab HA on Amazon Web Services (AWS)](../install/aws/index.md): Set up GitLab High Availability on Amazon AWS.
-- [Geo](geo/replication/index.md): Replicate your GitLab instance to other geographic locations as a read-only fully operational version. **[PREMIUM ONLY]**
-- [Disaster Recovery](geo/disaster_recovery/index.md): Quickly fail-over to a different site with minimal effort in a disaster situation. **[PREMIUM ONLY]**
-- [Pivotal Tile](../install/pivotal/index.md): Deploy GitLab as a pre-configured appliance using Ops Manager (BOSH) for Pivotal Cloud Foundry. **[PREMIUM ONLY]**
-- [Add License](../user/admin_area/license.md): Upload a license at install time to unlock features that are in paid tiers of GitLab. **[STARTER ONLY]**
+- [Geo](geo/replication/index.md): Replicate your GitLab instance to other geographic locations as a read-only fully operational version. **(PREMIUM ONLY)**
+- [Disaster Recovery](geo/disaster_recovery/index.md): Quickly fail-over to a different site with minimal effort in a disaster situation. **(PREMIUM ONLY)**
+- [Pivotal Tile](../install/pivotal/index.md): Deploy GitLab as a pre-configured appliance using Ops Manager (BOSH) for Pivotal Cloud Foundry. **(PREMIUM ONLY)**
+- [Add License](../user/admin_area/license.md): Upload a license at install time to unlock features that are in paid tiers of GitLab. **(STARTER ONLY)**
 
 ### Configuring GitLab
 
@@ -61,9 +60,9 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 - [Diff limits](../user/admin_area/diff_limits.md): Configure the diff rendering size limits of branch comparison pages.
 - [Merge request diffs storage](merge_request_diffs.md): Configure merge requests diffs external storage.
 - [Broadcast Messages](../user/admin_area/broadcast_messages.md): Send messages to GitLab users through the UI.
-- [Elasticsearch](../integration/elasticsearch.md): Enable Elasticsearch to empower GitLab's Advanced Global Search. Useful when you deal with a huge amount of data. **[STARTER ONLY]**
-- [External Classification Policy Authorization](../user/admin_area/settings/external_authorization.md) **[PREMIUM ONLY]**
-- [Upload a license](../user/admin_area/license.md): Upload a license to unlock features that are in paid tiers of GitLab. **[STARTER ONLY]**
+- [Elasticsearch](../integration/elasticsearch.md): Enable Elasticsearch to empower GitLab's Advanced Global Search. Useful when you deal with a huge amount of data. **(STARTER ONLY)**
+- [External Classification Policy Authorization](../user/admin_area/settings/external_authorization.md) **(PREMIUM ONLY)**
+- [Upload a license](../user/admin_area/license.md): Upload a license to unlock features that are in paid tiers of GitLab. **(STARTER ONLY)**
 - [Admin Area](../user/admin_area/index.md): for self-managed instance-wide configuration and maintenance.
 
 #### Customizing GitLab's appearance
@@ -73,7 +72,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 - [Branded login page](../customization/branded_login_page.md): Customize the login page with your own logo, title, and description.
 - [Welcome message](../customization/welcome_message.md): Add a custom welcome message to the sign-in page.
 - ["New Project" page](../customization/new_project_page.md): Customize the text to be displayed on the page that opens whenever your users create a new project.
-- [Additional custom email text](../user/admin_area/settings/email.md#custom-additional-text-premium-only): Add additional custom text to emails sent from GitLab. **[PREMIUM ONLY]**
+- [Additional custom email text](../user/admin_area/settings/email.md#custom-additional-text-premium-only): Add additional custom text to emails sent from GitLab. **(PREMIUM ONLY)**
 
 ### Maintaining GitLab
 
@@ -108,17 +107,17 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 - [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 and Authorization](auth/README.md): Configure external authentication with LDAP, SAML, CAS and additional providers.
-  - [Sync LDAP](auth/ldap-ee.md) **[STARTER ONLY]**
-  - [Kerberos authentication](../integration/kerberos.md) **[STARTER ONLY]**
+  - [Sync LDAP](auth/ldap-ee.md) **(STARTER ONLY)**
+  - [Kerberos authentication](../integration/kerberos.md) **(STARTER ONLY)**
   - See also other [authentication](../topics/authentication/index.md#gitlab-administrators) topics (for example, enforcing 2FA).
-- [Email users](../tools/email.md): Email GitLab users from within GitLab. **[STARTER ONLY]**
+- [Email users](../tools/email.md): Email GitLab users from within GitLab. **(STARTER ONLY)**
 - [User Cohorts](../user/admin_area/user_cohorts.md): Display the monthly cohorts of new users and their activities over time.
 - [Audit logs and events](audit_events.md): View the changes made within the GitLab server for:
-  - Groups and projects. **[STARTER]**
-  - Instances. **[PREMIUM ONLY]**
-- [Auditor users](auditor_users.md): Users with read-only access to all projects, groups, and other resources on the GitLab instance. **[PREMIUM ONLY]**
+  - Groups and projects. **(STARTER)**
+  - Instances. **(PREMIUM ONLY)**
+- [Auditor users](auditor_users.md): Users with read-only access to all projects, groups, and other resources on the GitLab instance. **(PREMIUM ONLY)**
 - [Incoming email](incoming_email.md): Configure incoming emails to allow
-  users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/create_new_issue.md#new-issue-via-email) and
+  users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/managing_issues.md#new-issue-via-email) and
   [merge requests by email](../user/project/merge_requests/index.md#create-new-merge-requests-by-email), and to enable [Service Desk](../user/project/service_desk.md).
   - [Postfix for incoming email](reply_by_email_postfix_setup.md): Set up a
   basic Postfix mail server with IMAP authentication on Ubuntu for incoming
@@ -132,15 +131,15 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 - [Gitaly](gitaly/index.md): Configuring Gitaly, GitLab's Git repository storage service.
 - [Default labels](../user/admin_area/labels.md): Create labels that will be automatically added to every new project.
 - [Restrict the use of public or internal projects](../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects): Restrict the use of visibility levels for users when they create a project or a snippet.
-- [Custom project templates](../user/admin_area/custom_project_templates.md): Configure a set of projects to be used as custom templates when creating a new project. **[PREMIUM ONLY]**
-- [Packages](packages.md): Enable GitLab to act as a Maven repository or NPM registry. **[PREMIUM ONLY]**
+- [Custom project templates](../user/admin_area/custom_project_templates.md): Configure a set of projects to be used as custom templates when creating a new project. **(PREMIUM ONLY)**
+- [Packages](packages.md): Enable GitLab to act as a Maven repository or NPM registry. **(PREMIUM ONLY)**
 
 ### Repository settings
 
 - [Repository checks](repository_checks.md): Periodic Git repository checks.
 - [Repository storage paths](repository_storage_paths.md): Manage the paths used to store repositories.
 - [Repository storage rake tasks](raketasks/storage.md): A collection of rake tasks to list and migrate existing projects and attachments associated with it from Legacy storage to Hashed storage.
-- [Limit repository size](../user/admin_area/settings/account_and_limit_settings.md): Set a hard limit for your repositories' size. **[STARTER ONLY]**
+- [Limit repository size](../user/admin_area/settings/account_and_limit_settings.md): Set a hard limit for your repositories' size. **(STARTER ONLY)**
 
 ## Continuous Integration settings
 
@@ -149,7 +148,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 - [Job artifacts](job_artifacts.md): Enable, disable, and configure job artifacts (a set of files and directories which are outputted by a job when it completes successfully).
 - [Job traces](job_traces.md): Information about the job traces (logs).
 - [Register Shared and specific Runners](../ci/runners/README.md#registering-a-shared-runner): Learn how to register and configure Shared and specific Runners to your own instance.
-- [Shared Runners pipelines quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota-starter-only): Limit the usage of pipeline minutes for Shared Runners. **[STARTER ONLY]**
+- [Shared Runners pipelines quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota-starter-only): Limit the usage of pipeline minutes for Shared Runners. **(STARTER ONLY)**
 - [Enable/disable Auto DevOps](../topics/autodevops/index.md#enablingdisabling-auto-devops): Enable or disable Auto DevOps for your instance.
 
 ## Git configuration options
@@ -179,10 +178,20 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 
 ## Analytics
 
-- [Pseudonymizer](pseudonymizer.md): Export data from GitLab's database to CSV files in a secure way. **[ULTIMATE]**
+- [Pseudonymizer](pseudonymizer.md): Export data from GitLab's database to CSV files in a secure way. **(ULTIMATE)**
 
 ## Troubleshooting
 
 - [Debugging tips](troubleshooting/debug.md): Tips to debug problems when things go wrong
 - [Log system](logs.md): Where to look for logs.
 - [Sidekiq Troubleshooting](troubleshooting/sidekiq.md): Debug when Sidekiq appears hung and is not processing jobs.
+- Useful [diagnostics tools](troubleshooting/diagnostics_tools.md) that are sometimes used by the GitLab
+  Support team.
+- [Troubleshooting ElasticSearch](troubleshooting/elasticsearch.md): Tips to troubleshoot ElasticSearch.
+- [Kubernetes troubleshooting](troubleshooting/kubernetes_cheat_sheet.md): Commands and tips useful
+  for troubleshooting Kubernetes-related issues.
+- Useful links from the Support Team:
+  - [GitLab Developer Docs](https://docs.gitlab.com/ee/development/README.html).
+  - [Repairing and recovering broken git repositories](https://git.seveas.net/repairing-and-recovering-broken-git-repositories.html).
+  - [Testing with OpenSSL](https://www.feistyduck.com/library/openssl-cookbook/online/ch-testing-with-openssl.html).
+  - [Strace zine](https://wizardzines.com/zines/strace/).
diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md
index b1244f44e95..ab6a4646a71 100644
--- a/doc/administration/instance_review.md
+++ b/doc/administration/instance_review.md
@@ -1,4 +1,4 @@
-# Instance Review **[CORE ONLY]**
+# Instance Review **(CORE ONLY)**
 
 > [Introduced][6995] in [GitLab Core][ee] 11.3.
 
diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md
index 82e0c14ffc2..16a193550a1 100644
--- a/doc/administration/integration/plantuml.md
+++ b/doc/administration/integration/plantuml.md
@@ -1,6 +1,7 @@
 # PlantUML & GitLab
 
-> [Introduced][ce-8537] in GitLab 8.16.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8537) in
+> GitLab 8.16.
 
 When [PlantUML](http://plantuml.com) integration is enabled and configured in
 GitLab we are able to create simple diagrams in AsciiDoc and Markdown documents
@@ -15,7 +16,9 @@ server that will generate the diagrams.
 
 With Docker, you can just run a container like this:
 
-`docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat`
+```sh
+docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat
+```
 
 The **PlantUML URL** will be the hostname of the server running the container.
 
@@ -26,7 +29,7 @@ own PlantUML server is easy in Debian/Ubuntu distributions using Tomcat.
 
 First you need to create a `plantuml.war` file from the source code:
 
-```
+```sh
 sudo apt-get install graphviz openjdk-8-jdk git-core maven
 git clone https://github.com/plantuml/plantuml-server.git
 cd plantuml-server
@@ -36,7 +39,7 @@ mvn package
 The above sequence of commands will generate a WAR file that can be deployed
 using Tomcat:
 
-```
+```sh
 sudo apt-get install tomcat7
 sudo cp target/plantuml.war /var/lib/tomcat7/webapps/plantuml.war
 sudo chown tomcat7:tomcat7 /var/lib/tomcat7/webapps/plantuml.war
@@ -46,7 +49,7 @@ sudo service tomcat7 restart
 Once the Tomcat service restarts the PlantUML service will be ready and
 listening for requests on port 8080:
 
-```
+```text
 http://localhost:8080/plantuml
 ```
 
@@ -57,9 +60,10 @@ you can change these defaults by editing the `/etc/tomcat7/server.xml` file.
 You need to enable PlantUML integration from Settings under Admin Area. To do
 that, login with an Admin account and do following:
 
- - in GitLab go to **Admin Area**->**Settings**->**Integrations**->**PlantUML**
- - check **Enable PlantUML** checkbox
- - set the PlantUML instance as **PlantUML URL**
+- In GitLab, go to **Admin Area > Settings > Integrations**.
+- Expand the **PlantUML** section.
+- Check **Enable PlantUML** checkbox.
+- Set the PlantUML instance as **PlantUML URL**.
 
 ## Creating Diagrams
 
@@ -68,33 +72,34 @@ our AsciiDoc snippets, wikis and repos using delimited blocks:
 
 - **Markdown**
 
-    <pre>
-    ```plantuml
-    Bob -> Alice : hello
-    Alice -> Bob : Go Away
-    ```</pre>
+  ~~~markdown
+  ```plantuml
+  Bob -> Alice : hello
+  Alice -> Bob : Go Away
+  ```
+  ~~~
 
 - **AsciiDoc**
 
-    ```
-    [plantuml, format="png", id="myDiagram", width="200px"]
-    ----
-    Bob->Alice : hello
-    Alice -> Bob : Go Away
-    ----
-    ```
+  ```text
+  [plantuml, format="png", id="myDiagram", width="200px"]
+  ----
+  Bob->Alice : hello
+  Alice -> Bob : Go Away
+  ----
+  ```
 
 - **reStructuredText**
 
-    ```
-    .. plantuml::
-       :caption: Caption with **bold** and *italic*
+  ```text
+  .. plantuml::
+     :caption: Caption with **bold** and *italic*
 
-       Bob -> Alice: hello
-       Alice -> Bob: Go Away
-    ```
+     Bob -> Alice: hello
+     Alice -> Bob: Go Away
+  ```
 
-    You can also use the `uml::` directive for compatibility with [sphinxcontrib-plantuml](https://pypi.python.org/pypi/sphinxcontrib-plantuml), but please note that we currently only support the `caption` option.
+   You can also use the `uml::` directive for compatibility with [sphinxcontrib-plantuml](https://pypi.org/project/sphinxcontrib-plantuml/), but please note that we currently only support the `caption` option.
 
 The above blocks will be converted to an HTML img tag with source pointing to the
 PlantUML instance. If the PlantUML server is correctly configured, this should
@@ -111,12 +116,10 @@ diagram delimiters `@startuml`/`@enduml` as these are replaced by the AsciiDoc `
 
 Some parameters can be added to the AsciiDoc block definition:
 
- - *format*: Can be either `png` or `svg`. Note that `svg` is not supported by
-   all browsers so use with care. The default is `png`.
- - *id*: A CSS id added to the diagram HTML tag.
- - *width*: Width attribute added to the img tag.
- - *height*: Height attribute added to the img tag.
+- *format*: Can be either `png` or `svg`. Note that `svg` is not supported by
+  all browsers so use with care. The default is `png`.
+- *id*: A CSS id added to the diagram HTML tag.
+- *width*: Width attribute added to the img tag.
+- *height*: Height attribute added to the img tag.
 
 Markdown does not support any parameters and will always use PNG format.
-
-[ce-8537]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8537
diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md
index c34858cd0db..24c9cc0bea9 100644
--- a/doc/administration/integration/terminal.md
+++ b/doc/administration/integration/terminal.md
@@ -41,9 +41,9 @@ detail below.
 - Every session URL that is created has an authorization header that needs to be sent, to establish a `wss` connection.
 - The session URL is not exposed to the users in any way. GitLab holds all the state internally and proxies accordingly.
 
-##  Enabling and disabling terminal support
+## Enabling and disabling terminal support
 
-NOTE: **Note:** AWS Elastic Load Balancers (ELBs) do not support web sockets. 
+NOTE: **Note:** AWS Elastic Load Balancers (ELBs) do not support web sockets.
 AWS Application Load Balancers (ALBs) must be used if you want web terminals
 to work. See [AWS Elastic Load Balancing Product Comparison](https://aws.amazon.com/elasticloadbalancing/features/#compare)
 for more information.
diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md
index 160da47c780..e1bbabb2878 100644
--- a/doc/administration/issue_closing_pattern.md
+++ b/doc/administration/issue_closing_pattern.md
@@ -1,4 +1,4 @@
-# Issue closing pattern
+# Issue closing pattern **(CORE ONLY)**
 
 >**Note:**
 This is the administration documentation.
@@ -27,9 +27,10 @@ Because Rubular doesn't understand `%{issue_ref}`, you can replace this by
 1. Change the value of `gitlab_rails['gitlab_issue_closing_pattern']` to a regular
    expression of your liking:
 
-    ```ruby
-    gitlab_rails['gitlab_issue_closing_pattern'] = "\b((?:[Cc]los(?:e[sd]|ing)|\b[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)"
-    ```
+   ```ruby
+   gitlab_rails['gitlab_issue_closing_pattern'] = "\b((?:[Cc]los(?:e[sd]|ing)|\b[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)"
+   ```
+
 1. [Reconfigure] GitLab for the changes to take effect.
 
 **For installations from source**
@@ -37,13 +38,13 @@ Because Rubular doesn't understand `%{issue_ref}`, you can replace this by
 1. Open `gitlab.yml` with your editor.
 1. Change the value of `issue_closing_pattern`:
 
-    ```yaml
-    issue_closing_pattern: "\b((?:[Cc]los(?:e[sd]|ing)|\b[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)"
-    ```
+   ```yaml
+   issue_closing_pattern: "\b((?:[Cc]los(?:e[sd]|ing)|\b[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)"
+   ```
 
 1. [Restart] GitLab for the changes to take effect.
 
 [gitlab.yml.example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example
 [reconfigure]: restart_gitlab.md#omnibus-gitlab-reconfigure
 [restart]: restart_gitlab.md#installations-from-source
-[user documentation]: ../user/project/issues/automatic_issue_closing.md
+[user documentation]: ../user/project/issues/managing_issues.md#closing-issues-automatically
diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md
index 05e15fc303b..2b624f8de77 100644
--- a/doc/administration/job_artifacts.md
+++ b/doc/administration/job_artifacts.md
@@ -1,7 +1,5 @@
 # Jobs artifacts administration
 
-> **Notes:**
->
 > - Introduced in GitLab 8.2 and GitLab Runner 0.7.0.
 > - Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format changed to `ZIP`.
 > - Starting with GitLab 8.17, builds are renamed to jobs.
@@ -15,28 +13,24 @@ if you want to know how to disable it.
 
 To disable artifacts site-wide, follow the steps below.
 
----
-
 **In Omnibus installations:**
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
-    ```ruby
-    gitlab_rails['artifacts_enabled'] = false
-    ```
+   ```ruby
+   gitlab_rails['artifacts_enabled'] = false
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **In installations from source:**
 
 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
 
-    ```yaml
-    artifacts:
-      enabled: false
-    ```
+   ```yaml
+   artifacts:
+     enabled: false
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -51,8 +45,6 @@ this is done when the job succeeds, but can also be done on failure, or always,
 To change the location where the artifacts are stored locally, follow the steps
 below.
 
----
-
 **In Omnibus installations:**
 
 _The artifacts are stored by default in
@@ -61,14 +53,12 @@ _The artifacts are stored by default in
 1. To change the storage path for example to `/mnt/storage/artifacts`, edit
    `/etc/gitlab/gitlab.rb` and add the following line:
 
-    ```ruby
-    gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts"
-    ```
+   ```ruby
+   gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts"
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **In installations from source:**
 
 _The artifacts are stored by default in
@@ -77,18 +67,16 @@ _The artifacts are stored by default in
 1. To change the storage path for example to `/mnt/storage/artifacts`, edit
    `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
 
-    ```yaml
-    artifacts:
-      enabled: true
-      path: /mnt/storage/artifacts
-    ```
+   ```yaml
+   artifacts:
+     enabled: true
+     path: /mnt/storage/artifacts
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
 ### Using object storage
 
-> **Notes:**
->
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1762) in
 >   [GitLab Premium](https://about.gitlab.com/pricing/) 9.4.
 > - Since version 9.5, artifacts are [browsable](../user/project/pipelines/job_artifacts.md#browsing-artifacts),
@@ -127,6 +115,7 @@ The connection settings match those provided by [Fog](https://github.com/fog), a
 | `aws_access_key_id` | AWS credentials, or compatible | |
 | `aws_secret_access_key` | AWS credentials, or compatible | |
 | `aws_signature_version` | AWS signature version to use. 2 or 4 are valid options. Digital Ocean Spaces and other providers may need 2. | 4 |
+| `enable_signature_v4_streaming` | Set to true to enable HTTP chunked transfers with AWS v4 signatures (https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be false | true
 | `region` | AWS region | us-east-1 |
 | `host` | S3 compatible host for when not using AWS, e.g. `localhost` or `storage.example.com` | s3.amazonaws.com |
 | `endpoint` | Can be used when configuring an S3 compatible service such as [Minio](https://www.minio.io), by entering a URL such as `http://127.0.0.1:9000` | (optional) |
@@ -141,37 +130,35 @@ _The artifacts are stored by default in
 1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with
    the values you want:
 
-    ```ruby
-    gitlab_rails['artifacts_enabled'] = true
-    gitlab_rails['artifacts_object_store_enabled'] = true
-    gitlab_rails['artifacts_object_store_remote_directory'] = "artifacts"
-    gitlab_rails['artifacts_object_store_connection'] = {
-      'provider' => 'AWS',
-      'region' => 'eu-central-1',
-      'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
-      'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
-    }
-    ```
-
-    NOTE: For GitLab 9.4+, if you are using AWS IAM profiles, be sure to omit the
-    AWS access key and secret access key/value pairs. For example:
-
-    ```ruby
-    gitlab_rails['artifacts_object_store_connection'] = {
-      'provider' => 'AWS',
-      'region' => 'eu-central-1',
-      'use_iam_profile' => true
-    }
-    ```
+   ```ruby
+   gitlab_rails['artifacts_enabled'] = true
+   gitlab_rails['artifacts_object_store_enabled'] = true
+   gitlab_rails['artifacts_object_store_remote_directory'] = "artifacts"
+   gitlab_rails['artifacts_object_store_connection'] = {
+     'provider' => 'AWS',
+     'region' => 'eu-central-1',
+     'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
+     'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
+   }
+   ```
+
+   NOTE: For GitLab 9.4+, if you are using AWS IAM profiles, be sure to omit the
+   AWS access key and secret access key/value pairs. For example:
+
+   ```ruby
+   gitlab_rails['artifacts_object_store_connection'] = {
+     'provider' => 'AWS',
+     'region' => 'eu-central-1',
+     'use_iam_profile' => true
+   }
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 1. Migrate any existing local artifacts to the object storage:
 
-    ```bash
-    gitlab-rake gitlab:artifacts:migrate
-    ```
-
----
+   ```bash
+   gitlab-rake gitlab:artifacts:migrate
+   ```
 
 **In installations from source:**
 
@@ -181,25 +168,25 @@ _The artifacts are stored by default in
 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
    lines:
 
-    ```yaml
-    artifacts:
-      enabled: true
-      object_store:
-        enabled: true
-        remote_directory: "artifacts" # The bucket name
-        connection:
-          provider: AWS # Only AWS supported at the moment
-          aws_access_key_id: AWS_ACCESS_KEY_ID
-          aws_secret_access_key: AWS_SECRET_ACCESS_KEY
-          region: eu-central-1
-    ```
+   ```yaml
+   artifacts:
+     enabled: true
+     object_store:
+       enabled: true
+       remote_directory: "artifacts" # The bucket name
+       connection:
+         provider: AWS # Only AWS supported at the moment
+         aws_access_key_id: AWS_ACCESS_KEY_ID
+         aws_secret_access_key: AWS_SECRET_ACCESS_KEY
+         region: eu-central-1
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 1. Migrate any existing local artifacts to the object storage:
 
-    ```bash
-    sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production
-    ```
+   ```bash
+   sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production
+   ```
 
 ## Expiring artifacts
 
@@ -211,29 +198,25 @@ right after that date passes. Artifacts are cleaned up by the
 To change the default schedule on which the artifacts are expired, follow the
 steps below.
 
----
-
 **In Omnibus installations:**
 
 1. Edit `/etc/gitlab/gitlab.rb` and comment out or add the following line
 
-    ```ruby
-    gitlab_rails['expire_build_artifacts_worker_cron'] = "50 * * * *"
-    ```
+   ```ruby
+   gitlab_rails['expire_build_artifacts_worker_cron'] = "50 * * * *"
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **In installations from source:**
 
 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
    lines:
 
-    ```yaml
-    expire_build_artifacts_worker:
-      cron: "50 * * * *"
-    ```
+   ```yaml
+   expire_build_artifacts_worker:
+     cron: "50 * * * *"
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -244,38 +227,34 @@ steps below.
 To disable [the dependencies validation](../ci/yaml/README.md#when-a-dependent-job-will-fail),
 you can flip the feature flag from a Rails console.
 
----
-
 **In Omnibus installations:**
 
 1. Enter the Rails console:
 
-    ```sh
-    sudo gitlab-rails console
-    ```
+   ```sh
+   sudo gitlab-rails console
+   ```
 
 1. Flip the switch and disable it:
 
-    ```ruby
-    Feature.enable('ci_disable_validates_dependencies')
-    ```
-
----
+   ```ruby
+   Feature.enable('ci_disable_validates_dependencies')
+   ```
 
 **In installations from source:**
 
 1. Enter the Rails console:
 
-    ```sh
-    cd /home/git/gitlab
-    RAILS_ENV=production sudo -u git -H bundle exec rails console
-    ```
+   ```sh
+   cd /home/git/gitlab
+   RAILS_ENV=production sudo -u git -H bundle exec rails console
+   ```
 
 1. Flip the switch and disable it:
 
-    ```ruby
-    Feature.enable('ci_disable_validates_dependencies')
-    ```
+   ```ruby
+   Feature.enable('ci_disable_validates_dependencies')
+   ```
 
 ## Set the maximum file size of the artifacts
 
diff --git a/doc/administration/job_traces.md b/doc/administration/job_traces.md
index aa9d87562a3..6a06eb240de 100644
--- a/doc/administration/job_traces.md
+++ b/doc/administration/job_traces.md
@@ -25,11 +25,11 @@ To change the location where the job logs will be stored, follow the steps below
 
 **In Omnibus installations:**
 
-1.  Edit `/etc/gitlab/gitlab.rb` and add or amend the following line:
+1. Edit `/etc/gitlab/gitlab.rb` and add or amend the following line:
 
-    ```
-    gitlab_ci['builds_directory'] = '/mnt/to/gitlab-ci/builds'
-    ```
+   ```ruby
+   gitlab_ci['builds_directory'] = '/mnt/to/gitlab-ci/builds'
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -39,12 +39,12 @@ To change the location where the job logs will be stored, follow the steps below
 
 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
 
-    ```yaml
-    gitlab_ci:
-      # The location where build traces are stored (default: builds/).
-      # Relative paths are relative to Rails.root.
-      builds_path: path/to/builds/
-    ```
+   ```yaml
+   gitlab_ci:
+     # The location where build traces are stored (default: builds/).
+     # Relative paths are relative to Rails.root.
+     builds_path: path/to/builds/
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -67,24 +67,24 @@ To archive those legacy job traces, please follow the instruction below.
 
 1. Execute the following command
 
-    ```bash
-    gitlab-rake gitlab:traces:archive
-    ```
+   ```bash
+   gitlab-rake gitlab:traces:archive
+   ```
 
-    After you executed this task, GitLab instance queues up Sidekiq jobs (asynchronous processes)
-    for migrating job trace files from local storage to object storage. 
-    It could take time to complete the all migration jobs. You can check the progress by the following command
+   After you executed this task, GitLab instance queues up Sidekiq jobs (asynchronous processes)
+   for migrating job trace files from local storage to object storage.
+   It could take time to complete the all migration jobs. You can check the progress by the following command
 
-    ```bash
-    sudo gitlab-rails console
-    ```
+   ```bash
+   sudo gitlab-rails console
+   ```
 
-    ```bash
-    [1] pry(main)> Sidekiq::Stats.new.queues['pipeline_background:archive_trace']
-    => 100
-    ```
+   ```bash
+   [1] pry(main)> Sidekiq::Stats.new.queues['pipeline_background:archive_trace']
+   => 100
+   ```
 
-    If the count becomes zero, the archiving processes are done
+   If the count becomes zero, the archiving processes are done
 
 ## How to migrate archived job traces to object storage
 
@@ -95,9 +95,9 @@ If job traces have already been archived into local storage, and you want to mig
 1. Ensure [Object storage integration for Job Artifacts](job_artifacts.md#object-storage-settings) is enabled
 1. Execute the following command
 
-    ```bash
-    gitlab-rake gitlab:traces:migrate
-    ```
+   ```bash
+   gitlab-rake gitlab:traces:migrate
+   ```
 
 ## How to remove job traces
 
diff --git a/doc/administration/logs.md b/doc/administration/logs.md
index c5cfb8d5016..9030c941cad 100644
--- a/doc/administration/logs.md
+++ b/doc/administration/logs.md
@@ -4,7 +4,7 @@ GitLab has an advanced log system where everything is logged so that you
 can analyze your instance using various system log files. In addition to
 system log files, GitLab Enterprise Edition comes with Audit Events.
 Find more about them [in Audit Events
-documentation](http://docs.gitlab.com/ee/administration/audit_events.html)
+documentation](audit_events.md)
 
 System log files are typically plain text in a standard log file format.
 This guide talks about how to read and use these system log files.
@@ -88,7 +88,7 @@ Introduced in GitLab 10.0, this file lives in
 It helps you see requests made directly to the API. For example:
 
 ```json
-{"time":"2018-10-29T12:49:42.123Z","severity":"INFO","duration":709.08,"db":14.59,"view":694.49,"status":200,"method":"GET","path":"/api/v4/projects","params":[{"key":"action","value":"git-upload-pack"},{"key":"changes","value":"_any"},{"key":"key_id","value":"secret"},{"key":"secret_token","value":"[FILTERED]"}],"host":"localhost","ip":"::1","ua":"Ruby","route":"/api/:version/projects","user_id":1,"username":"root","queue_duration":100.31,"gitaly_calls":30,"gitaly_duration":5.36}
+{"time":"2018-10-29T12:49:42.123Z","severity":"INFO","duration":709.08,"db":14.59,"view":694.49,"status":200,"method":"GET","path":"/api/v4/projects","params":[{"key":"action","value":"git-upload-pack"},{"key":"changes","value":"_any"},{"key":"key_id","value":"secret"},{"key":"secret_token","value":"[FILTERED]"}],"host":"localhost","remote_ip":"::1","ua":"Ruby","route":"/api/:version/projects","user_id":1,"username":"root","queue_duration":100.31,"gitaly_calls":30,"gitaly_duration":5.36}
 ```
 
 This entry above shows an access to an internal endpoint to check whether an
@@ -125,7 +125,7 @@ This file lives in `/var/log/gitlab/gitlab-rails/integrations_json.log` for
 Omnibus GitLab packages or in `/home/git/gitlab/log/integrations_json.log` for
 installations from source.
 
-It contains information about [integrations](../user/project/integrations/project_services.md) activities such as JIRA, Asana and Irker services. It uses JSON format like the example below:
+It contains information about [integrations](../user/project/integrations/project_services.md) activities such as Jira, Asana and Irker services. It uses JSON format like the example below:
 
 ``` json
 {"severity":"ERROR","time":"2018-09-06T14:56:20.439Z","service_class":"JiraService","project_id":8,"project_path":"h5bp/html5-boilerplate","message":"Error sending message","client_url":"http://jira.gitlap.com:8080","error":"execution expired"}
@@ -151,22 +151,29 @@ etc. For example:
 {"severity":"ERROR","time":"2018-11-23T15:42:11.647Z","exception":"Kubeclient::HttpError","error_code":null,"service":"Clusters::Applications::InstallService","app_id":2,"project_ids":[19],"group_ids":[],"message":"SSL_connect returned=1 errno=0 state=error: certificate verify failed (unable to get local issuer certificate)"}
 ```
 
-## `githost.log`
+## `git_json.log`
 
-This file lives in `/var/log/gitlab/gitlab-rails/githost.log` for
-Omnibus GitLab packages or in `/home/git/gitlab/log/githost.log` for
+This file lives in `/var/log/gitlab/gitlab-rails/git_json.log` for
+Omnibus GitLab packages or in `/home/git/gitlab/log/git_json.log` for
 installations from source.
 
+NOTE: **Note:**
+After 12.2, this file was renamed from `githost.log` to
+`git_json.log` and stored in JSON format.
+
 GitLab has to interact with Git repositories but in some rare cases
 something can go wrong and in this case you will know what exactly
 happened. This log file contains all failed requests from GitLab to Git
 repositories. In the majority of cases this file will be useful for developers
 only. For example:
 
-```
-December 03, 2014 13:20 -> ERROR -> Command failed [1]: /usr/bin/git --git-dir=/Users/vsizov/gitlab-development-kit/gitlab/tmp/tests/gitlab-satellites/group184/gitlabhq/.git --work-tree=/Users/vsizov/gitlab-development-kit/gitlab/tmp/tests/gitlab-satellites/group184/gitlabhq merge --no-ff -mMerge branch 'feature_conflict' into 'feature' source/feature_conflict
-
-error: failed to push some refs to '/Users/vsizov/gitlab-development-kit/repositories/gitlabhq/gitlab_git.git'
+```json
+{
+   "severity":"ERROR",
+   "time":"2019-07-19T22:16:12.528Z",
+   "correlation_id":"FeGxww5Hj64",
+   "message":"Command failed [1]: /usr/bin/git --git-dir=/Users/vsizov/gitlab-development-kit/gitlab/tmp/tests/gitlab-satellites/group184/gitlabhq/.git --work-tree=/Users/vsizov/gitlab-development-kit/gitlab/tmp/tests/gitlab-satellites/group184/gitlabhq merge --no-ff -mMerge branch 'feature_conflict' into 'feature' source/feature_conflict\n\nerror: failed to push some refs to '/Users/vsizov/gitlab-development-kit/repositories/gitlabhq/gitlab_git.git'"
+}
 ```
 
 ## `audit_json.log`
@@ -236,7 +243,7 @@ I, [2015-02-13T06:17:00.679433 #9291]  INFO -- : Moving existing hooks directory
 
 User clone/fetch activity using ssh transport appears in this log as `executing git command <gitaly-upload-pack...`.
 
-## `unicorn\_stderr.log`
+## `unicorn_stderr.log`
 
 This file lives in `/var/log/gitlab/unicorn/unicorn_stderr.log` for
 Omnibus GitLab packages or in `/home/git/gitlab/log/unicorn_stderr.log` for
@@ -277,16 +284,19 @@ Introduced in GitLab 11.3. This file lives in `/var/log/gitlab/gitlab-rails/impo
 Omnibus GitLab packages or in `/home/git/gitlab/log/importer.log` for
 installations from source.
 
-Currently it logs the progress of project imports from the Bitbucket Server
-importer. Future importers may use this file.
-
-## `auth.log`
+## `auth.log`
 
 Introduced in GitLab 12.0. This file lives in `/var/log/gitlab/gitlab-rails/auth.log` for
 Omnibus GitLab packages or in `/home/git/gitlab/log/auth.log` for
 installations from source.
 
-It logs information whenever [Rack Attack] registers an abusive request.
+This log records:
+
+- Information whenever [Rack Attack] registers an abusive request.
+- Requests over the [Rate Limit] on raw endpoints.
+
+NOTE: **Note:**
+From [%12.1](https://gitlab.com/gitlab-org/gitlab-ce/issues/62756), user id and username are available on this log.
 
 ## `graphql_json.log`
 
@@ -302,6 +312,12 @@ GraphQL queries are recorded in that file. For example:
 {"query_string":"query IntrospectionQuery{__schema {queryType { name },mutationType { name }}}...(etc)","variables":{"a":1,"b":2},"complexity":181,"depth":1,"duration":7}
 ```
 
+## `migrations.log`
+
+Introduced in GitLab 12.3. This file lives in `/var/log/gitlab/gitlab-rails/migrations.log` for
+Omnibus GitLab packages or in `/home/git/gitlab/log/migrations.log` for
+installations from source.
+
 ## Reconfigure Logs
 
 Reconfigure log files live in `/var/log/gitlab/reconfigure` for Omnibus GitLab
@@ -321,3 +337,4 @@ installations from source.
 
 [repocheck]: repository_checks.md
 [Rack Attack]: ../security/rack_attack.md
+[Rate Limit]: ../user/admin_area/settings/rate_limits_on_raw_endpoints.md
diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md
index 5e9ba4f640f..0b065082ded 100644
--- a/doc/administration/merge_request_diffs.md
+++ b/doc/administration/merge_request_diffs.md
@@ -1,4 +1,4 @@
-# Merge request diffs storage **[CORE ONLY]**
+# Merge request diffs storage **(CORE ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/52568) in GitLab 11.8.
 
@@ -10,7 +10,7 @@ By default, merge request diffs are stored in the database, in a table named
 `merge_request_diff_files`. Larger installations may find this table grows too
 large, in which case, switching to external storage is recommended.
 
-### Using external storage
+## Using external storage
 
 Merge request diffs can be stored on disk, or in object storage. In general, it
 is better to store the diffs in the database than on disk.
@@ -21,18 +21,18 @@ To enable external storage of merge request diffs, follow the instructions below
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
-    ```ruby
-    gitlab_rails['external_diffs_enabled'] = true
-    ```
+   ```ruby
+   gitlab_rails['external_diffs_enabled'] = true
+   ```
 
 1. _The external diffs will be stored in in
    `/var/opt/gitlab/gitlab-rails/shared/external-diffs`._ To change the path,
    for example, to `/mnt/storage/external-diffs`, edit `/etc/gitlab/gitlab.rb`
    and add the following line:
 
-    ```ruby
-    gitlab_rails['external_diffs_storage_path'] = "/mnt/storage/external-diffs"
-    ```
+   ```ruby
+   gitlab_rails['external_diffs_storage_path'] = "/mnt/storage/external-diffs"
+   ```
 
 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -41,31 +41,31 @@ To enable external storage of merge request diffs, follow the instructions below
 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
    lines:
 
-    ```yaml
-    external_diffs:
-      enabled: true
-    ```
+   ```yaml
+   external_diffs:
+     enabled: true
+   ```
 
-1. _The external diffs will be stored in 
+1. _The external diffs will be stored in
    `/home/git/gitlab/shared/external-diffs`._ To change the path, for example,
    to `/mnt/storage/external-diffs`, edit `/home/git/gitlab/config/gitlab.yml`
    and add or amend the following lines:
 
-    ```yaml
-    external_diffs:
-      enabled: true
-      storage_path: /mnt/storage/external-diffs
-    ```
+   ```yaml
+   external_diffs:
+     enabled: true
+     storage_path: /mnt/storage/external-diffs
+   ```
 
 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
 
-### Using object storage
+## Using object storage
 
 Instead of storing the external diffs on disk, we recommended the use of an object
 store like AWS S3 instead. This configuration relies on valid AWS credentials to
 be configured already.
 
-### Object Storage Settings
+## Object Storage Settings
 
 For source installations, these settings are nested under `external_diffs:` and
 then `object_store:`. On Omnibus installations, they are prefixed by
@@ -80,7 +80,7 @@ then `object_store:`. On Omnibus installations, they are prefixed by
 | `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` |
 | `connection` | Various connection options described below | |
 
-#### S3 compatible connection settings
+### S3 compatible connection settings
 
 The connection settings match those provided by [Fog](https://github.com/fog), and are as follows:
 
@@ -90,6 +90,7 @@ The connection settings match those provided by [Fog](https://github.com/fog), a
 | `aws_access_key_id` | AWS credentials, or compatible | |
 | `aws_secret_access_key` | AWS credentials, or compatible | |
 | `aws_signature_version` | AWS signature version to use. 2 or 4 are valid options. Digital Ocean Spaces and other providers may need 2. | 4 |
+| `enable_signature_v4_streaming` | Set to true to enable HTTP chunked transfers with AWS v4 signatures (https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be false | true
 | `region` | AWS region | us-east-1 |
 | `host` | S3 compatible host for when not using AWS, e.g. `localhost` or `storage.example.com` | s3.amazonaws.com |
 | `endpoint` | Can be used when configuring an S3 compatible service such as [Minio](https://www.minio.io), by entering a URL such as `http://127.0.0.1:9000` | (optional) |
@@ -101,28 +102,28 @@ The connection settings match those provided by [Fog](https://github.com/fog), a
 1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with
    the values you want:
 
-    ```ruby
-    gitlab_rails['external_diffs_enabled'] = true
-    gitlab_rails['external_diffs_object_store_enabled'] = true
-    gitlab_rails['external_diffs_object_store_remote_directory'] = "external-diffs"
-    gitlab_rails['external_diffs_object_store_connection'] = {
-      'provider' => 'AWS',
-      'region' => 'eu-central-1',
-      'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
-      'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
-    }
-    ```
-
-    Note that, if you are using AWS IAM profiles, be sure to omit the
-    AWS access key and secret access key/value pairs. For example:
-
-    ```ruby
-    gitlab_rails['external_diffs_object_store_connection'] = {
-      'provider' => 'AWS',
-      'region' => 'eu-central-1',
-      'use_iam_profile' => true
-    }
-    ```
+   ```ruby
+   gitlab_rails['external_diffs_enabled'] = true
+   gitlab_rails['external_diffs_object_store_enabled'] = true
+   gitlab_rails['external_diffs_object_store_remote_directory'] = "external-diffs"
+   gitlab_rails['external_diffs_object_store_connection'] = {
+     'provider' => 'AWS',
+     'region' => 'eu-central-1',
+     'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
+     'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
+   }
+   ```
+
+   Note that, if you are using AWS IAM profiles, be sure to omit the
+   AWS access key and secret access key/value pairs. For example:
+
+   ```ruby
+   gitlab_rails['external_diffs_object_store_connection'] = {
+     'provider' => 'AWS',
+     'region' => 'eu-central-1',
+     'use_iam_profile' => true
+   }
+   ```
 
 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -131,22 +132,22 @@ The connection settings match those provided by [Fog](https://github.com/fog), a
 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
    lines:
 
-    ```yaml
-    external_diffs:
-      enabled: true
-      object_store:
-        enabled: true
-        remote_directory: "external-diffs" # The bucket name
-        connection:
-          provider: AWS # Only AWS supported at the moment
-          aws_access_key_id: AWS_ACCESS_KEY_ID
-          aws_secret_access_key: AWS_SECRET_ACCESS_KEY
-          region: eu-central-1
-    ```
+   ```yaml
+   external_diffs:
+     enabled: true
+     object_store:
+       enabled: true
+       remote_directory: "external-diffs" # The bucket name
+       connection:
+         provider: AWS # Only AWS supported at the moment
+         aws_access_key_id: AWS_ACCESS_KEY_ID
+         aws_secret_access_key: AWS_SECRET_ACCESS_KEY
+         region: eu-central-1
+   ```
 
 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
 
-### Alternative in-database storage
+## Alternative in-database storage
 
 Enabling external diffs may reduce the performance of merge requests, as they
 must be retrieved in a separate operation to other data. A compromise may be
@@ -157,11 +158,11 @@ To enable this feature, perform the following steps:
 
 **In Omnibus installations:**
 
-1.  Edit `/etc/gitlab/gitlab.rb` and add the following line:
+1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
-    ```ruby
-    gitlab_rails['external_diffs_when'] = 'outdated'
-    ```
+   ```ruby
+   gitlab_rails['external_diffs_when'] = 'outdated'
+   ```
 
 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -170,11 +171,11 @@ To enable this feature, perform the following steps:
 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
    lines:
 
-    ```yaml
-    external_diffs:
-      enabled: true
-      when: outdated
-    ```
+   ```yaml
+   external_diffs:
+     enabled: true
+     when: outdated
+   ```
 
 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
 
diff --git a/doc/administration/monitoring/gitlab_instance_administration_project/index.md b/doc/administration/monitoring/gitlab_instance_administration_project/index.md
new file mode 100644
index 00000000000..8e33cea6217
--- /dev/null
+++ b/doc/administration/monitoring/gitlab_instance_administration_project/index.md
@@ -0,0 +1,36 @@
+# GitLab instance administration project
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/56883) in GitLab 12.2.
+
+GitLab has been adding the ability for administrators to see insights into the health of
+their GitLab instance. In order to surface this experience in a native way, similar to how
+you would interact with an application deployed via GitLab, a base project called
+"GitLab Instance Administration" with
+[internal visibility](../../../public_access/public_access.md#internal-projects) will be
+added under a group called "GitLab Instance Administrators" specifically created for
+visualizing and configuring the monitoring of your GitLab instance.
+
+All administrators at the time of creation of the project and group will be added
+as maintainers of the group and project, and as an admin, you'll be able to add new
+members to the group in order to give them maintainer access to the project.
+
+This project will be used for self-monitoring your GitLab instance.
+
+## Connection to Prometheus
+
+The project will be automatically configured to connect to the
+[internal Prometheus](../prometheus/index.md) instance if the Prometheus
+instance is present (should be the case if GitLab was installed via Omnibus
+and you haven't disabled it).
+
+If that's not the case or if you have an external Prometheus instance or an HA setup,
+you should
+[configure it manually](../../../user/project/integrations/prometheus.md#manual-configuration-of-prometheus).
+
+## Taking action on Prometheus alerts **[ULTIMATE]**
+
+You can [add a webhook](../../../user/project/integrations/prometheus.md#external-prometheus-instances)
+to the Prometheus config in order for GitLab to receive notifications of any alerts.
+
+Once the webhook is setup, you can
+[take action on incoming alerts](../../../user/project/integrations/prometheus.md#taking-action-on-incidents-ultimate).
diff --git a/doc/administration/monitoring/index.md b/doc/administration/monitoring/index.md
index fa0459b24ff..2b3daec42bd 100644
--- a/doc/administration/monitoring/index.md
+++ b/doc/administration/monitoring/index.md
@@ -2,6 +2,9 @@
 
 Explore our features to monitor your GitLab instance:
 
+- [GitLab self-monitoring](gitlab_instance_administration_project/index.md): The
+  GitLab instance administration project helps to monitor the GitLab instance and
+  take action on alerts.
 - [Performance monitoring](performance/index.md): GitLab Performance Monitoring makes it possible to measure a wide variety of statistics of your instance.
 - [Prometheus](prometheus/index.md): Prometheus is a powerful time-series monitoring service, providing a flexible platform for monitoring GitLab and other software products.
 - [GitHub imports](github_imports.md): Monitor the health and progress of GitLab's GitHub importer with various Prometheus metrics.
diff --git a/doc/administration/monitoring/ip_whitelist.md b/doc/administration/monitoring/ip_whitelist.md
index ad2773de132..6bb2fe81b2c 100644
--- a/doc/administration/monitoring/ip_whitelist.md
+++ b/doc/administration/monitoring/ip_whitelist.md
@@ -12,9 +12,9 @@ hosts or use IP ranges:
 
 1. Open `/etc/gitlab/gitlab.rb` and add or uncomment the following:
 
-    ```ruby
-    gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', '192.168.0.1']
-    ```
+   ```ruby
+   gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', '192.168.0.1']
+   ```
 
 1. Save the file and [reconfigure] GitLab for the changes to take effect.
 
@@ -24,13 +24,13 @@ hosts or use IP ranges:
 
 1. Edit `config/gitlab.yml`:
 
-    ```yaml
-    monitoring:
-      # by default only local IPs are allowed to access monitoring resources
-      ip_whitelist:
-        - 127.0.0.0/8
-        - 192.168.0.1
-    ```
+   ```yaml
+   monitoring:
+     # by default only local IPs are allowed to access monitoring resources
+     ip_whitelist:
+       - 127.0.0.0/8
+       - 192.168.0.1
+   ```
 
 1. Save the file and [restart] GitLab for the changes to take effect.
 
diff --git a/doc/administration/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md
index 771584268d9..9a25cc04ee7 100644
--- a/doc/administration/monitoring/performance/gitlab_configuration.md
+++ b/doc/administration/monitoring/performance/gitlab_configuration.md
@@ -8,12 +8,8 @@ The minimum required settings you need to set are the InfluxDB host and port.
 Make sure _Enable InfluxDB Metrics_ is checked and hit **Save** to save the
 changes.
 
----
-
 ![GitLab Performance Monitoring Admin Settings](img/metrics_gitlab_configuration_settings.png)
 
----
-
 Finally, a restart of all GitLab processes is required for the changes to take
 effect:
 
@@ -30,8 +26,6 @@ sudo service gitlab restart
 When any migrations are pending, the metrics are disabled until the migrations
 have been performed.
 
----
-
 Read more on:
 
 - [Introduction to GitLab Performance Monitoring](introduction.md)
diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md
index 187fb2f73a1..95be0d5fd88 100644
--- a/doc/administration/monitoring/performance/grafana_configuration.md
+++ b/doc/administration/monitoring/performance/grafana_configuration.md
@@ -1,6 +1,6 @@
 # Grafana Configuration
 
-[Grafana](http://grafana.org/) is a tool that allows you to visualize time
+[Grafana](https://grafana.com/) is a tool that allows you to visualize time
 series metrics through graphs and dashboards. It supports several backend
 data stores, including InfluxDB. GitLab writes performance data to InfluxDB
 and Grafana will allow you to query to display useful graphs.
@@ -13,7 +13,7 @@ services.
 
 [GitLab Omnibus can help you install Grafana (recommended)](https://docs.gitlab.com/omnibus/settings/grafana.html)
 or Grafana supplies package repositories (Yum/Apt) for easy installation.
-See [Grafana installation documentation](http://docs.grafana.org/installation/)
+See [Grafana installation documentation](https://grafana.com/docs/installation/)
 for detailed steps.
 
 NOTE: **Note:**
@@ -103,6 +103,51 @@ repository for more information on this process.
 
 [grafana-dashboards]: https://gitlab.com/gitlab-org/grafana-dashboards
 
+## Integration with GitLab UI
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/61005) in GitLab 12.1.
+
+If you have set up Grafana, you can enable a link to access it easily from the sidebar:
+
+1. Go to the admin area under **Settings > Metrics and profiling**
+   and expand "Metrics - Grafana".
+1. Check the "Enable access to Grafana" checkbox.
+1. If Grafana is enabled through Omnibus GitLab and on the same server,
+   leave "Grafana URL" unchanged. In any other case, enter the full URL
+   path of the Grafana instance.
+1. Click **Save changes**.
+1. The new link will be available in the admin area under **Monitoring > Metrics Dashboard**.
+
+## Security Update
+
+Users running GitLab version 12.0 or later should immediately upgrade to one of the following security releases due to a known vulnerability with the embedded Grafana dashboard:
+
+- 12.0.6
+- 12.1.6
+
+After upgrading, the Grafana dashboard will be disabled and the location of your existing Grafana data will be changed from `/var/opt/gitlab/grafana/data/` to `/var/opt/gitlab/grafana/data.bak.#{Date.today}/`.
+
+To prevent the data from being relocated, you can run the following command prior to upgrading:
+
+```sh
+echo "0" > /var/opt/gitlab/grafana/CVE_reset_status
+```
+
+To reinstate your old data, move it back into its original location:
+
+```
+sudo mv /var/opt/gitlab/grafana/data.bak.xxxx/ /var/opt/gitlab/grafana/data/
+```
+
+However, you should **not** reinstate your old data _except_ under one of the following conditions:
+
+1. If you are certain that you changed your default admin password when you enabled Grafana
+1. If you run GitLab in a private network, accessed only by trusted users, and your Grafana login page has not been exposed to the internet
+
+If you require access to your old Grafana data but do not meet one of these criteria, you may consider reinstating it temporarily, [exporting the dashboards](https://grafana.com/docs/reference/export_import/#exporting-a-dashboard) you need, then refreshing the data and [re-importing your dashboards](https://grafana.com/docs/reference/export_import/#importing-a-dashboard). Note that this poses a temporary vulnerability while your old Grafana data is in use, and the decision to do so should be weighed carefully with your need to access existing data and dashboards.
+
+For more information and further mitigation details, please refer to our [blog post on the security release](https://about.gitlab.com/2019/08/12/critical-security-release-gitlab-12-dot-1-dot-6-released/).
+
 ---
 
 Read more on:
diff --git a/doc/administration/monitoring/performance/img/performance_bar.png b/doc/administration/monitoring/performance/img/performance_bar.png
index 2bf686f9017..d1187fd879a 100644
--- a/doc/administration/monitoring/performance/img/performance_bar.png
+++ b/doc/administration/monitoring/performance/img/performance_bar.png
diff --git a/doc/administration/monitoring/performance/img/performance_bar_gitaly_calls.png b/doc/administration/monitoring/performance/img/performance_bar_gitaly_calls.png
index 7af6d401d1d..2c43201cbd0 100644
--- a/doc/administration/monitoring/performance/img/performance_bar_gitaly_calls.png
+++ b/doc/administration/monitoring/performance/img/performance_bar_gitaly_calls.png
diff --git a/doc/administration/monitoring/performance/img/performance_bar_line_profiling.png b/doc/administration/monitoring/performance/img/performance_bar_line_profiling.png
deleted file mode 100644
index a55ce753101..00000000000
--- a/doc/administration/monitoring/performance/img/performance_bar_line_profiling.png
+++ /dev/null
diff --git a/doc/administration/monitoring/performance/img/performance_bar_redis_calls.png b/doc/administration/monitoring/performance/img/performance_bar_redis_calls.png
new file mode 100644
index 00000000000..ecb2dffbf8d
--- /dev/null
+++ b/doc/administration/monitoring/performance/img/performance_bar_redis_calls.png
diff --git a/doc/administration/monitoring/performance/img/performance_bar_rugged_calls.png b/doc/administration/monitoring/performance/img/performance_bar_rugged_calls.png
new file mode 100644
index 00000000000..210f80a713d
--- /dev/null
+++ b/doc/administration/monitoring/performance/img/performance_bar_rugged_calls.png
diff --git a/doc/administration/monitoring/performance/img/performance_bar_sql_queries.png b/doc/administration/monitoring/performance/img/performance_bar_sql_queries.png
index b3219b4fa94..6b571f4e85c 100644
--- a/doc/administration/monitoring/performance/img/performance_bar_sql_queries.png
+++ b/doc/administration/monitoring/performance/img/performance_bar_sql_queries.png
diff --git a/doc/administration/monitoring/performance/img/request_profile_result.png b/doc/administration/monitoring/performance/img/request_profile_result.png
index 1b06e240fa0..9176a0b49fd 100644
--- a/doc/administration/monitoring/performance/img/request_profile_result.png
+++ b/doc/administration/monitoring/performance/img/request_profile_result.png
diff --git a/doc/administration/monitoring/performance/influxdb_configuration.md b/doc/administration/monitoring/performance/influxdb_configuration.md
index fa281f47ed8..cf6728510fe 100644
--- a/doc/administration/monitoring/performance/influxdb_configuration.md
+++ b/doc/administration/monitoring/performance/influxdb_configuration.md
@@ -187,7 +187,7 @@ Read more on:
 [influxdb documentation]: https://docs.influxdata.com/influxdb/v0.9/
 [influxdb cli]: https://docs.influxdata.com/influxdb/v0.9/tools/shell/
 [udp]: https://docs.influxdata.com/influxdb/v0.9/write_protocols/udp/
-[influxdb]: https://influxdata.com/time-series-platform/influxdb/
+[influxdb]: https://www.influxdata.com/products/influxdb-overview/
 [tsm tree]: https://influxdata.com/blog/new-storage-engine-time-structured-merge-tree/
 [tsm1-commit]: https://github.com/influxdata/influxdb/commit/15d723dc77651bac83e09e2b1c94be480966cb0d
 [influx-admin]: https://docs.influxdata.com/influxdb/v0.9/administration/authentication_and_authorization/#create-a-new-admin-user
diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md
index 95f497a1470..02f4b78bd60 100644
--- a/doc/administration/monitoring/performance/performance_bar.md
+++ b/doc/administration/monitoring/performance/performance_bar.md
@@ -8,16 +8,14 @@ activated, it looks as follows:
 It allows you to see (from left to right):
 
 - the current host serving the page
-- the timing of the page (backend, frontend)
 - time taken and number of DB queries, click through for details of these queries
   ![SQL profiling using the Performance Bar](img/performance_bar_sql_queries.png)
 - time taken and number of [Gitaly] calls, click through for details of these calls
   ![Gitaly profiling using the Performance Bar](img/performance_bar_gitaly_calls.png)
-- profile of the code used to generate the page, line by line. In the profile view, the numbers in the left panel represent wall time, cpu time, and number of calls (based on [rblineprof](https://github.com/tmm1/rblineprof)).
-  ![Line profiling using the Performance Bar](img/performance_bar_line_profiling.png)
-- time taken and number of calls to Redis
-- time taken and number of background jobs created by Sidekiq
-- time taken and number of Ruby GC calls
+- time taken and number of [Rugged] calls, click through for details of these calls
+  ![Rugged profiling using the Performance Bar](img/performance_bar_rugged_calls.png)
+- time taken and number of Redis calls, click through for details of these calls
+  ![Redis profiling using the Performance Bar](img/performance_bar_redis_calls.png)
 
 On the far right is a request selector that allows you to view the same metrics
 (excluding the page timing and line profiler) for any requests made while the
@@ -40,10 +38,7 @@ display it.
 
 You can toggle the Bar using the same shortcut.
 
----
-
 ![GitLab Performance Bar Admin Settings](img/performance_bar_configuration_settings.png)
 
----
-
 [Gitaly]: ../../gitaly/index.md
+[Rugged]: ../../high_availability/nfs.md#improving-nfs-performance-with-gitlab
diff --git a/doc/administration/monitoring/performance/request_profiling.md b/doc/administration/monitoring/performance/request_profiling.md
index 726882fbb87..9f671e0db11 100644
--- a/doc/administration/monitoring/performance/request_profiling.md
+++ b/doc/administration/monitoring/performance/request_profiling.md
@@ -5,9 +5,9 @@
 1. Grab the profiling token from **Monitoring > Requests Profiles** admin page
   (highlighted in a blue in the image below).
   ![Profile token](img/request_profiling_token.png)
-1. Pass the header `X-Profile-Token: <token>` to the request you want to profile. You can use:
+1. Pass the header `X-Profile-Token: <token>` and `X-Profile-Mode: <mode>`(where <mode> can be `execution` or `memory`) to the request you want to profile. You can use:
     - Browser extensions. For example, [ModHeader](https://chrome.google.com/webstore/detail/modheader/idgpnmonknjnojddfkpgkljpfnnfcklj) Chrome extension.
-    - `curl`. For example, `curl --header 'X-Profile-Token: <token>' https://gitlab.example.com/group/project`.
+    - `curl`. For example, `curl --header 'X-Profile-Token: <token>' --header 'X-Profile-Mode: <mode>' https://gitlab.example.com/group/project`.
 1. Once request is finished (which will take a little longer than usual), you can
   view the profiling output from **Monitoring > Requests Profiles** admin page.
   ![Profiling output](img/request_profile_result.png)
diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md
index 84b71ae6f1c..ec26c0b2e7e 100644
--- a/doc/administration/monitoring/prometheus/gitlab_metrics.md
+++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md
@@ -34,6 +34,9 @@ The following metrics are available:
 | filesystem_writable               | Gauge     | 9.4   | Whether or not the filesystem is writable |
 | filesystem_read_latency_seconds   | Gauge     | 9.4   | Read latency of a specific filesystem |
 | filesystem_readable               | Gauge     | 9.4   | Whether or not the filesystem is readable |
+| gitlab_cache_misses_total         | Counter   | 10.2  | Cache read miss |
+| gitlab_cache_operation_duration_seconds | Histogram   | 10.2  | Cache access time |
+| gitlab_cache_operations_total     | Counter   | 12.2  | Cache operations by controller/action |
 | http_requests_total               | Counter   | 9.4   | Rack request count |
 | http_request_duration_seconds     | Histogram | 9.4   | HTTP response time from rack middleware |
 | pipelines_created_total           | Counter   | 9.4   | Counter of pipelines created |
@@ -49,7 +52,7 @@ The following metrics are available:
 | unicorn_queued_connections        | Gauge     | 11.0  | The number of queued Unicorn connections |
 | unicorn_workers                   | Gauge     | 12.0  | The number of Unicorn workers |
 
-## Sidekiq Metrics available for Geo **[PREMIUM]**
+## Sidekiq Metrics available for Geo **(PREMIUM)**
 
 Sidekiq jobs may also gather metrics, and these metrics can be accessed if the Sidekiq exporter is enabled (e.g. via
 the `monitoring.sidekiq_exporter` configuration option in `gitlab.yml`.
@@ -104,11 +107,11 @@ Some basic Ruby runtime metrics are available:
 | ruby_process_cpu_seconds_total         | Gauge     | 12.0  | Total amount of CPU time per process |
 | ruby_process_max_fds                   | Gauge     | 12.0  | Maximum number of open file descriptors per process |
 | ruby_process_resident_memory_bytes     | Gauge     | 12.0  | Memory usage by process, measured in bytes |
-| ruby_process_start_time_seconds        | Gauge     | 12.0  | The elapsed time between system boot and the process started, measured in seconds |
+| ruby_process_start_time_seconds        | Gauge     | 12.0  | UNIX timestamp of process start time |
 
 [GC.stat]: https://ruby-doc.org/core-2.3.0/GC.html#method-c-stat
 
-## Puma Metrics **[EXPERIMENTAL]**
+## Puma Metrics **(EXPERIMENTAL)**
 
 When Puma is used instead of Unicorn, following metrics are available:
 
@@ -117,7 +120,6 @@ When Puma is used instead of Unicorn, following metrics are available:
 | puma_workers                                 | Gauge   | 12.0  | Total number of workers |
 | puma_running_workers                         | Gauge   | 12.0  | Number of booted workers |
 | puma_stale_workers                           | Gauge   | 12.0  | Number of old workers |
-| puma_phase                                   | Gauge   | 12.0  | Phase number (increased during phased restarts) |
 | puma_running                                 | Gauge   | 12.0  | Number of running threads |
 | puma_queued_connections                      | Gauge   | 12.0  | Number of connections in that worker's "todo" set waiting for a worker thread |
 | puma_active_connections                      | Gauge   | 12.0  | Number of threads processing a request |
diff --git a/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md b/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md
index f68b03d1ade..9aa4dfa5ab7 100644
--- a/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md
+++ b/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md
@@ -12,9 +12,9 @@ To enable the GitLab monitor exporter:
 1. Edit `/etc/gitlab/gitlab.rb`
 1. Add or find and uncomment the following line, making sure it's set to `true`:
 
-    ```ruby
-    gitlab_monitor['enable'] = true
-    ```
+   ```ruby
+   gitlab_monitor['enable'] = true
+   ```
 
 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to
    take effect
diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md
index ce65d77274b..c8968c51393 100644
--- a/doc/administration/monitoring/prometheus/index.md
+++ b/doc/administration/monitoring/prometheus/index.md
@@ -39,9 +39,9 @@ To disable Prometheus and all of its exporters, as well as any added in the futu
 1. Edit `/etc/gitlab/gitlab.rb`
 1. Add or find and uncomment the following line, making sure it's set to `false`:
 
-    ```ruby
-    prometheus_monitoring['enable'] = false
-    ```
+   ```ruby
+   prometheus_monitoring['enable'] = false
+   ```
 
 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to
    take effect.
@@ -61,19 +61,19 @@ To change the address/port that Prometheus listens on:
 1. Edit `/etc/gitlab/gitlab.rb`
 1. Add or find and uncomment the following line:
 
-    ```ruby
-    prometheus['listen_address'] = 'localhost:9090'
-    ```
+   ```ruby
+   prometheus['listen_address'] = 'localhost:9090'
+   ```
 
-    Replace `localhost:9090` with the address/port you want Prometheus to
-    listen on. If you would like to allow access to Prometheus to hosts other
-    than `localhost`, leave out the host, or use `0.0.0.0` to allow public access:
+   Replace `localhost:9090` with the address/port you want Prometheus to
+   listen on. If you would like to allow access to Prometheus to hosts other
+   than `localhost`, leave out the host, or use `0.0.0.0` to allow public access:
 
-    ```ruby
-    prometheus['listen_address'] = ':9090'
-    # or
-    prometheus['listen_address'] = '0.0.0.0:9090'
-    ```
+   ```ruby
+   prometheus['listen_address'] = ':9090'
+   # or
+   prometheus['listen_address'] = '0.0.0.0:9090'
+   ```
 
 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to
    take effect
@@ -90,22 +90,22 @@ To use an external Prometheus server:
 1. Edit `/etc/gitlab/gitlab.rb`.
 1. Disable the bundled Prometheus:
 
-    ```ruby
-    prometheus['enable'] = false
-    ```
+   ```ruby
+   prometheus['enable'] = false
+   ```
 
 1. Set each bundled service's [exporter](#bundled-software-metrics) to listen on a network address, for example:
 
-    ```ruby
-     gitlab_monitor['listen_address'] = '0.0.0.0'
-     sidekiq['listen_address'] = '0.0.0.0'
-     gitlab_monitor['listen_port'] = '9168'
-     node_exporter['listen_address'] = '0.0.0.0:9100'
-     redis_exporter['listen_address'] = '0.0.0.0:9121'
-     postgres_exporter['listen_address'] = '0.0.0.0:9187'
-     gitaly['prometheus_listen_addr'] = "0.0.0.0:9236"
-     gitlab_workhorse['prometheus_listen_addr'] = "0.0.0.0:9229"
-     ```
+   ```ruby
+   gitlab_monitor['listen_address'] = '0.0.0.0'
+   sidekiq['listen_address'] = '0.0.0.0'
+   gitlab_monitor['listen_port'] = '9168'
+   node_exporter['listen_address'] = '0.0.0.0:9100'
+   redis_exporter['listen_address'] = '0.0.0.0:9121'
+   postgres_exporter['listen_address'] = '0.0.0.0:9187'
+   gitaly['prometheus_listen_addr'] = "0.0.0.0:9236"
+   gitlab_workhorse['prometheus_listen_addr'] = "0.0.0.0:9229"
+   ```
 
 1. Install and set up a dedicated Prometheus instance, if necessary, using the [official installation instructions](https://prometheus.io/docs/prometheus/latest/installation/).
 1. Add the Prometheus server IP address to the [monitoring IP whitelist](../ip_whitelist.html). For example:
@@ -117,14 +117,14 @@ To use an external Prometheus server:
 1. To scrape nginx metrics, you'll also need to configure nginx to allow the Prometheus server
    IP. For example:
 
-    ```ruby
-    nginx['status']['options'] = {
-          "server_tokens" => "off",
-          "access_log" => "off",
-          "allow" => "192.168.0.1",
-          "deny" => "all",
-    }
-    ```
+   ```ruby
+   nginx['status']['options'] = {
+         "server_tokens" => "off",
+         "access_log" => "off",
+         "allow" => "192.168.0.1",
+         "deny" => "all",
+   }
+   ```
 
 1. [Reconfigure GitLab][reconfigure] to apply the changes
 1. Edit the Prometheus server's configuration file.
@@ -132,19 +132,59 @@ To use an external Prometheus server:
    [scrape target configuration](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#%3Cscrape_config%3E).
    For example, a sample snippet using `static_configs`:
 
-    ```yaml
-    scrape_configs:
-    - job_name: 'gitlab_exporters'
-      static_configs:
-      - targets: ['1.1.1.1:9168', '1.1.1.1:9236', '1.1.1.1:9236', '1.1.1.1:9100', '1.1.1.1:9121', '1.1.1.1:9187']
-
-    - job_name: 'gitlab_metrics'
-      metrics_path: /-/metrics
-      static_configs:
-      - targets: ['1.1.1.1:443']
-    ```
-
-1. Restart the Prometheus server.
+   ```yaml
+   scrape_configs:
+   - job_name: nginx
+     static_configs:
+     - targets:
+       - 1.1.1.1:8060
+   - job_name: redis
+     static_configs:
+     - targets:
+       - 1.1.1.1:9121
+   - job_name: postgres
+     static_configs:
+     - targets:
+       - 1.1.1.1:9187
+   - job_name: node
+     static_configs:
+     - targets:
+       - 1.1.1.1:9100
+   - job_name: gitlab-workhorse
+     static_configs:
+     - targets:
+       - 1.1.1.1:9229
+   - job_name: gitlab-rails
+     metrics_path: "/-/metrics"
+     static_configs:
+     - targets:
+       - 1.1.1.1:8080
+   - job_name: gitlab-sidekiq
+     static_configs:
+     - targets:
+       - 1.1.1.1:8082
+   - job_name: gitlab_monitor_database
+     metrics_path: "/database"
+     static_configs:
+     - targets:
+       - 1.1.1.1:9168
+   - job_name: gitlab_monitor_sidekiq
+     metrics_path: "/sidekiq"
+     static_configs:
+     - targets:
+       - 1.1.1.1:9168
+   - job_name: gitlab_monitor_process
+     metrics_path: "/process"
+     static_configs:
+     - targets:
+       - 1.1.1.1:9168
+   - job_name: gitaly
+     static_configs:
+     - targets:
+       - 1.1.1.1:9236
+   ```
+
+1. Reload the Prometheus server.
 
 ## Viewing performance metrics
 
@@ -241,9 +281,9 @@ To disable the monitoring of Kubernetes:
 1. Edit `/etc/gitlab/gitlab.rb`.
 1. Add or find and uncomment the following line and set it to `false`:
 
-    ```ruby
-    prometheus['monitor_kubernetes'] = false
-    ```
+   ```ruby
+   prometheus['monitor_kubernetes'] = false
+   ```
 
 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to
    take effect.
diff --git a/doc/administration/monitoring/prometheus/node_exporter.md b/doc/administration/monitoring/prometheus/node_exporter.md
index aef7758a88f..bcacfaa3be5 100644
--- a/doc/administration/monitoring/prometheus/node_exporter.md
+++ b/doc/administration/monitoring/prometheus/node_exporter.md
@@ -13,9 +13,9 @@ To enable the node exporter:
 1. Edit `/etc/gitlab/gitlab.rb`
 1. Add or find and uncomment the following line, making sure it's set to `true`:
 
-    ```ruby
-    node_exporter['enable'] = true
-    ```
+   ```ruby
+   node_exporter['enable'] = true
+   ```
 
 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to
    take effect
diff --git a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md
index d76834fdbea..6183594c69c 100644
--- a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md
+++ b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md
@@ -12,9 +12,9 @@ To enable the PgBouncer exporter:
 1. Edit `/etc/gitlab/gitlab.rb`
 1. Add or find and uncomment the following line, making sure it's set to `true`:
 
-    ```ruby
-    pgbouncer_exporter['enable'] = true
-    ```
+   ```ruby
+   pgbouncer_exporter['enable'] = true
+   ```
 
 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to
    take effect.
diff --git a/doc/administration/monitoring/prometheus/postgres_exporter.md b/doc/administration/monitoring/prometheus/postgres_exporter.md
index 8e2d3162f88..3ad15b65497 100644
--- a/doc/administration/monitoring/prometheus/postgres_exporter.md
+++ b/doc/administration/monitoring/prometheus/postgres_exporter.md
@@ -12,9 +12,9 @@ To enable the postgres exporter:
 1. Edit `/etc/gitlab/gitlab.rb`
 1. Add or find and uncomment the following line, making sure it's set to `true`:
 
-    ```ruby
-    postgres_exporter['enable'] = true
-    ```
+   ```ruby
+   postgres_exporter['enable'] = true
+   ```
 
 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to
    take effect
diff --git a/doc/administration/monitoring/prometheus/redis_exporter.md b/doc/administration/monitoring/prometheus/redis_exporter.md
index d54d409dbb6..1520115a38d 100644
--- a/doc/administration/monitoring/prometheus/redis_exporter.md
+++ b/doc/administration/monitoring/prometheus/redis_exporter.md
@@ -13,9 +13,9 @@ To enable the Redis exporter:
 1. Edit `/etc/gitlab/gitlab.rb`
 1. Add or find and uncomment the following line, making sure it's set to `true`:
 
-    ```ruby
-    redis_exporter['enable'] = true
-    ```
+   ```ruby
+   redis_exporter['enable'] = true
+   ```
 
 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to
    take effect
diff --git a/doc/administration/operations/extra_sidekiq_processes.md b/doc/administration/operations/extra_sidekiq_processes.md
index 286b99aceb5..a16cd5166b7 100644
--- a/doc/administration/operations/extra_sidekiq_processes.md
+++ b/doc/administration/operations/extra_sidekiq_processes.md
@@ -1,70 +1,132 @@
-# Extra Sidekiq processes **[STARTER ONLY]**
+# Extra Sidekiq processes **(STARTER ONLY)**
 
-GitLab Enterprise Edition allows one to start an extra set of Sidekiq processes
+NOTE: **Note:**
+The information in this page applies only to Omnibus GitLab.
+
+GitLab Starter allows one to start an extra set of Sidekiq processes
 besides the default one. These processes can be used to consume a dedicated set
 of queues. This can be used to ensure certain queues always have dedicated
 workers, no matter the number of jobs that need to be processed.
 
-## Starting extra processes via Omnibus GitLab
+## Available Sidekiq queues
 
-To enable `sidekiq-cluster`, you must apply the `sidekiq_cluster['enable'] = true`
-setting `/etc/gitlab/gitlab.rb`:
+For a list of the existing Sidekiq queues, check the following files:
 
-```ruby
-sidekiq_cluster['enable'] = true
-```
+- [Queues for both GitLab Community and Enterprise Editions](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/app/workers/all_queues.yml)
+- [Queues for GitLab Enterprise Editions only](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/app/workers/all_queues.yml)
 
-You will then specify how many additional processes to create via `sidekiq-cluster`
-as well as which queues for them to handle. This is done via the 
-`sidekiq_cluster['queue_groups']` setting. This is an array whose items contain
-which queues to process. Each item in the array will equate to one additional
-sidekiq process.
+Each entry in the above files represents a queue on which extra Sidekiq processes
+can be started.
 
-As an example, to make additional sidekiq processes that process the 
-`elastic_indexer` and `mailers` queues, you would apply the following:
+## Starting extra processes
 
-```ruby
-sidekiq_cluster['queue_groups'] = [
-  "elastic_indexer",
-  "mailers"
-]
-```
+To start extra Sidekiq processes, you must enable `sidekiq-cluster`:
 
-To have an additional sidekiq process handle multiple queues, you simply put a
-comma after the first queue name and then put the next queue name:
+1. Edit `/etc/gitlab/gitlab.rb` and add:
 
-```ruby
-sidekiq_cluster['queue_groups'] = [
-  "elastic_indexer,elastic_commit_indexer",
-  "mailers"
-]
-```
+   ```ruby
+   sidekiq_cluster['enable'] = true
+   ```
 
-Keep in mind, all changes must be followed by reconfiguring your GitLab
-application via `sudo gitlab-ctl reconfigure`.
+1. You will then need to specify how many additional processes to create via `sidekiq-cluster`
+   and which queue they should handle via the `sidekiq_cluster['queue_groups']`
+   array setting. Each item in the array equates to one additional Sidekiq
+   process, and values in each item determine the queues it works on.
 
-### Monitoring
+   For example, the following setting adds additional Sidekiq processes to two
+   queues, one to `elastic_indexer` and one to `mailers`:
 
-Once the Sidekiq processes are added, you can visit the "Background Jobs"
+   ```ruby
+   sidekiq_cluster['queue_groups'] = [
+     "elastic_indexer",
+     "mailers"
+   ]
+   ```
+
+   To have an additional Sidekiq process handle multiple queues, add multiple
+   queue names to its item delimited by commas. For example:
+
+   ```ruby
+   sidekiq_cluster['queue_groups'] = [
+     "elastic_indexer, elastic_commit_indexer",
+     "mailers"
+   ]
+   ```
+
+1. Save the file and reconfigure GitLab for the changes to take effect:
+
+   ```sh
+   sudo gitlab-ctl reconfigure
+   ```
+
+Once the extra Sidekiq processes are added, you can visit the "Background Jobs"
 section under the admin area in GitLab (`/admin/background_jobs`).
 
-![Extra sidekiq processes](img/sidekiq-cluster.png)
+![Extra Sidekiq processes](img/sidekiq-cluster.png)
 
-### All queues with exceptions
+## Negating settings
 
-To have the additional sidekiq processes work on every queue EXCEPT the ones
+To have the additional Sidekiq processes work on every queue **except** the ones
 you list:
 
+1. After you follow the steps for [starting extra processes](#starting-extra-processes),
+   edit `/etc/gitlab/gitlab.rb` and add:
+
+   ```ruby
+   sidekiq_cluster['negate'] = true
+   ```
+
+1. Save the file and reconfigure GitLab for the changes to take effect:
+
+   ```sh
+   sudo gitlab-ctl reconfigure
+   ```
+
+## Ignore all GitHub import queues
+
+When [importing from GitHub](../../user/project/import/github.md), Sidekiq might
+use all of its resources to perform those operations. To set up a separate
+`sidekiq-cluster` process to ignore all GitHub import-related queues:
+
 1. Edit `/etc/gitlab/gitlab.rb` and add:
 
    ```ruby
+   sidekiq_cluster['enable'] = true
    sidekiq_cluster['negate'] = true
+   sidekiq_cluster['queue_groups'] = [
+     "github_import_advance_stage",
+     "github_importer:github_import_import_diff_note",
+     "github_importer:github_import_import_issue",
+     "github_importer:github_import_import_note",
+     "github_importer:github_import_import_lfs_object",
+     "github_importer:github_import_import_pull_request",
+     "github_importer:github_import_refresh_import_jid",
+     "github_importer:github_import_stage_finish_import",
+     "github_importer:github_import_stage_import_base_data",
+     "github_importer:github_import_stage_import_issues_and_diff_notes",
+     "github_importer:github_import_stage_import_notes",
+     "github_importer:github_import_stage_import_lfs_objects",
+     "github_importer:github_import_stage_import_pull_requests",
+     "github_importer:github_import_stage_import_repository"
+   ]
    ```
 
-1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
+1. Save the file and reconfigure GitLab for the changes to take effect:
 
+   ```sh
+   sudo gitlab-ctl reconfigure
+   ```
 
-### Limiting concurrency
+## Number of threads
+
+Each process defined under `sidekiq_cluster` starts with a
+number of threads that equals the number of queues, plus one spare thread.
+For example, a process that handles the `process_commit` and `post_receive`
+queues will use three threads in total.
+
+## Limiting concurrency
+
+To limit the concurrency of the Sidekiq processes:
 
 1. Edit `/etc/gitlab/gitlab.rb` and add:
 
@@ -72,11 +134,22 @@ you list:
    sidekiq_cluster['concurrency'] = 25
    ```
 
-1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
+1. Save the file and reconfigure GitLab for the changes to take effect:
 
-Keep in mind, this normally would not exceed the number of CPU cores available.
+   ```sh
+   sudo gitlab-ctl reconfigure
+   ```
 
-### Modifying the check interval
+For each queue group, the concurrency factor will be set to `min(number of queues, N)`.
+Setting the value to 0 will disable the limit. Keep in mind this normally would
+not exceed the number of CPU cores available.
+
+Each thread requires a Redis connection, so adding threads may
+increase Redis latency and potentially cause client timeouts. See the [Sidekiq
+documentation about Redis](https://github.com/mperham/sidekiq/wiki/Using-Redis)
+for more details.
+
+## Modifying the check interval
 
 To modify the check interval for the additional Sidekiq processes:
 
@@ -90,9 +163,14 @@ To modify the check interval for the additional Sidekiq processes:
 
 This tells the additional processes how often to check for enqueued jobs.
 
-## Starting extra processes via command line
+## Troubleshooting using the CLI
 
-Starting extra Sidekiq processes can be done using the command
+CAUTION: **Warning:**
+It's recommended to use `/etc/gitlab/gitlab.rb` to configure the Sidekiq processes.
+If you experience a problem, you should contact GitLab support. Use the command
+line at your own risk.
+
+For debugging purposes, you can start extra Sidekiq processes by using the command
 `/opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster`. This command
 takes arguments using the following syntax:
 
@@ -111,29 +189,29 @@ see the relevant section in the
 [Sidekiq style guide](../../development/sidekiq_style_guide.md#queue-namespaces).
 
 For example, say you want to start 2 extra processes: one to process the
-"process_commit" queue, and one to process the "post_receive" queue. This can be
+`process_commit` queue, and one to process the `post_receive` queue. This can be
 done as follows:
 
 ```bash
 /opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster process_commit post_receive
 ```
 
-If you instead want to start one process processing both queues you'd use the
+If you instead want to start one process processing both queues, you'd use the
 following syntax:
 
 ```bash
 /opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster process_commit,post_receive
 ```
 
-If you want to have one Sidekiq process process the "process_commit" and
-"post_receive" queues, and one process to process the "gitlab_shell" queue,
+If you want to have one Sidekiq process dealing with the `process_commit` and
+`post_receive` queues, and one process to process the `gitlab_shell` queue,
 you'd use the following:
 
 ```bash
 /opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster process_commit,post_receive gitlab_shell
 ```
 
-### Monitoring
+### Monitoring the `sidekiq-cluster` command
 
 The `sidekiq-cluster` command will not terminate once it has started the desired
 amount of Sidekiq processes. Instead, the process will continue running and
@@ -172,24 +250,24 @@ command and not the PID(s) of the started Sidekiq processes.
 
 The Rails environment can be set by passing the `--environment` flag to the
 `sidekiq-cluster` command, or by setting `RAILS_ENV` to a non-empty value. The
-default value is "development".
+default value can be found in `/opt/gitlab/etc/gitlab-rails/env/RAILS_ENV`.
 
-### All queues with exceptions
+### Using negation
 
 You're able to run all queues in `sidekiq_queues.yml` file on a single or
 multiple processes with exceptions using the `--negate` flag.
 
 For example, say you want to run a single process for all queues,
-except "process_commit" and "post_receive". You can do so by executing:
+except `process_commit` and `post_receive`:
 
 ```bash
-sidekiq-cluster process_commit,post_receive --negate
+/opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster process_commit,post_receive --negate
 ```
 
-For multiple processes of all queues (except "process_commit" and "post_receive"):
+For multiple processes of all queues (except `process_commit` and `post_receive`):
 
 ```bash
-sidekiq-cluster process_commit,post_receive process_commit,post_receive --negate
+/opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster process_commit,post_receive process_commit,post_receive --negate
 ```
 
 ### Limiting concurrency
@@ -201,18 +279,3 @@ the `-m N` option. For example, this would cap the maximum number of threads to
 ```bash
 /opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster process_commit,post_receive -m 1
 ```
-
-For each queue group, the concurrency factor will be set to min(number of
-queues, N). Setting the value to 0 will disable the limit.
-
-Note that each thread requires a Redis connection, so adding threads may
-increase Redis latency and potentially cause client timeouts. See the [Sidekiq
-documentation about Redis](https://github.com/mperham/sidekiq/wiki/Using-Redis)
-for more details.
-
-## Number of threads
-
-Each process started using `sidekiq-cluster` (whether it be via command line or
-via the gitlab.rb file) starts with a number of threads that equals the number
-of queues, plus one spare thread. For example, a process that handles the
-"process_commit" and "post_receive" queues will use 3 threads in total.
diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md
index 3631ea0822f..e787af798bc 100644
--- a/doc/administration/operations/fast_ssh_key_lookup.md
+++ b/doc/administration/operations/fast_ssh_key_lookup.md
@@ -6,7 +6,7 @@ using [ssh certificates](ssh_certificates.md), they are even faster,
 but are not a drop-in replacement.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1631) in
-> [GitLab Starter](https://about.gitlab.com/gitlab-ee) 9.3.
+> [GitLab Starter](https://about.gitlab.com/pricing/) 9.3.
 >
 > [Available in](https://gitlab.com/gitlab-org/gitlab-ee/issues/3953) GitLab
 > Community Edition 10.4.
@@ -30,7 +30,7 @@ instructions will break installations using older versions of OpenSSH, such as
 those included with CentOS 6 as of September 2017. If you want to use this
 feature for CentOS 6, follow [the instructions on how to build and install a custom OpenSSH package](#compiling-a-custom-version-of-openssh-for-centos-6) before continuing.
 
-## Fast lookup is required for Geo **[PREMIUM]**
+## Fast lookup is required for Geo **(PREMIUM)**
 
 By default, GitLab manages an `authorized_keys` file, which contains all the
 public SSH keys for users allowed to access GitLab. However, to maintain a
@@ -71,10 +71,10 @@ sudo service sshd reload
 Confirm that SSH is working by removing your user's SSH key in the UI, adding a
 new one, and attempting to pull a repo.
 
-> **Note:** For Omnibus Docker, `AuthorizedKeysCommand` is setup by default in
+NOTE: **Note:** For Omnibus Docker, `AuthorizedKeysCommand` is setup by default in
 GitLab 11.11 and later.
 
-> **Warning:** Do not disable writes until SSH is confirmed to be working
+CAUTION: **Caution:** Do not disable writes until SSH is confirmed to be working
 perfectly, because the file will quickly become out-of-date.
 
 In the case of lookup failures (which are common), the `authorized_keys`
@@ -117,81 +117,81 @@ the database. The following instructions can be used to build OpenSSH 7.5:
 
 1. First, download the package and install the required packages:
 
-    ```
-    sudo su -
-    cd /tmp
-    curl --remote-name https://mirrors.evowise.com/pub/OpenBSD/OpenSSH/portable/openssh-7.5p1.tar.gz
-    tar xzvf openssh-7.5p1.tar.gz
-    yum install rpm-build gcc make wget openssl-devel krb5-devel pam-devel libX11-devel xmkmf libXt-devel
-    ```
+   ```
+   sudo su -
+   cd /tmp
+   curl --remote-name https://mirrors.evowise.com/pub/OpenBSD/OpenSSH/portable/openssh-7.5p1.tar.gz
+   tar xzvf openssh-7.5p1.tar.gz
+   yum install rpm-build gcc make wget openssl-devel krb5-devel pam-devel libX11-devel xmkmf libXt-devel
+   ```
 
 1. Prepare the build by copying files to the right place:
 
-    ```
-    mkdir -p /root/rpmbuild/{SOURCES,SPECS}
-    cp ./openssh-7.5p1/contrib/redhat/openssh.spec /root/rpmbuild/SPECS/
-    cp openssh-7.5p1.tar.gz /root/rpmbuild/SOURCES/
-    cd /root/rpmbuild/SPECS
-    ```
+   ```
+   mkdir -p /root/rpmbuild/{SOURCES,SPECS}
+   cp ./openssh-7.5p1/contrib/redhat/openssh.spec /root/rpmbuild/SPECS/
+   cp openssh-7.5p1.tar.gz /root/rpmbuild/SOURCES/
+   cd /root/rpmbuild/SPECS
+   ```
 
 1. Next, set the spec settings properly:
 
-    ```
-    sed -i -e "s/%define no_gnome_askpass 0/%define no_gnome_askpass 1/g" openssh.spec
-    sed -i -e "s/%define no_x11_askpass 0/%define no_x11_askpass 1/g" openssh.spec
-    sed -i -e "s/BuildPreReq/BuildRequires/g" openssh.spec
-    ```
+   ```
+   sed -i -e "s/%define no_gnome_askpass 0/%define no_gnome_askpass 1/g" openssh.spec
+   sed -i -e "s/%define no_x11_askpass 0/%define no_x11_askpass 1/g" openssh.spec
+   sed -i -e "s/BuildPreReq/BuildRequires/g" openssh.spec
+   ```
 
 1. Build the RPMs:
 
-    ```
-    rpmbuild -bb openssh.spec
-    ```
+   ```
+   rpmbuild -bb openssh.spec
+   ```
 
 1. Ensure the RPMs were built:
 
-    ```
-    ls -al /root/rpmbuild/RPMS/x86_64/
-    ```
+   ```
+   ls -al /root/rpmbuild/RPMS/x86_64/
+   ```
 
-    You should see something as the following:
+   You should see something as the following:
 
-    ```
-    total 1324
-    drwxr-xr-x. 2 root root   4096 Jun 20 19:37 .
-    drwxr-xr-x. 3 root root     19 Jun 20 19:37 ..
-    -rw-r--r--. 1 root root 470828 Jun 20 19:37 openssh-7.5p1-1.x86_64.rpm
-    -rw-r--r--. 1 root root 490716 Jun 20 19:37 openssh-clients-7.5p1-1.x86_64.rpm
-    -rw-r--r--. 1 root root  17020 Jun 20 19:37 openssh-debuginfo-7.5p1-1.x86_64.rpm
-    -rw-r--r--. 1 root root 367516 Jun 20 19:37 openssh-server-7.5p1-1.x86_64.rpm
-    ```
+   ```
+   total 1324
+   drwxr-xr-x. 2 root root   4096 Jun 20 19:37 .
+   drwxr-xr-x. 3 root root     19 Jun 20 19:37 ..
+   -rw-r--r--. 1 root root 470828 Jun 20 19:37 openssh-7.5p1-1.x86_64.rpm
+   -rw-r--r--. 1 root root 490716 Jun 20 19:37 openssh-clients-7.5p1-1.x86_64.rpm
+   -rw-r--r--. 1 root root  17020 Jun 20 19:37 openssh-debuginfo-7.5p1-1.x86_64.rpm
+   -rw-r--r--. 1 root root 367516 Jun 20 19:37 openssh-server-7.5p1-1.x86_64.rpm
+   ```
 
 1. Install the packages. OpenSSH packages will replace `/etc/pam.d/sshd`
    with its own version, which may prevent users from logging in, so be sure
    that the file is backed up and restored after installation:
 
-    ```
-    timestamp=$(date +%s)
-    cp /etc/pam.d/sshd pam-ssh-conf-$timestamp
-    rpm -Uvh /root/rpmbuild/RPMS/x86_64/*.rpm
-    yes | cp pam-ssh-conf-$timestamp /etc/pam.d/sshd
-    ```
+   ```
+   timestamp=$(date +%s)
+   cp /etc/pam.d/sshd pam-ssh-conf-$timestamp
+   rpm -Uvh /root/rpmbuild/RPMS/x86_64/*.rpm
+   yes | cp pam-ssh-conf-$timestamp /etc/pam.d/sshd
+   ```
 
 1. Verify the installed version. In another window, attempt to login to the server:
 
-    ```
-    ssh -v <your-centos-machine>
-    ```
+   ```
+   ssh -v <your-centos-machine>
+   ```
 
-    You should see a line that reads: "debug1: Remote protocol version 2.0, remote software version OpenSSH_7.5"
+   You should see a line that reads: "debug1: Remote protocol version 2.0, remote software version OpenSSH_7.5"
 
-    If not, you may need to restart sshd (e.g. `systemctl restart sshd.service`).
+   If not, you may need to restart sshd (e.g. `systemctl restart sshd.service`).
 
-1.  *IMPORTANT!* Open a new SSH session to your server before exiting to make
-    sure everything is working! If you need to downgrade, simple install the
-    older package:
+1. *IMPORTANT!* Open a new SSH session to your server before exiting to make
+   sure everything is working! If you need to downgrade, simple install the
+   older package:
 
-    ```
-    # Only run this if you run into a problem logging in
-    yum downgrade openssh-server openssh openssh-clients
-    ```
+   ```
+   # Only run this if you run into a problem logging in
+   yum downgrade openssh-server openssh openssh-clients
+   ```
diff --git a/doc/administration/operations/filesystem_benchmarking.md b/doc/administration/operations/filesystem_benchmarking.md
index c0c242733a2..b5922d9d99d 100644
--- a/doc/administration/operations/filesystem_benchmarking.md
+++ b/doc/administration/operations/filesystem_benchmarking.md
@@ -78,34 +78,37 @@ executed, and then read the same 1,000 files.
    [repository storage path](../repository_storage_paths.md).
 1. Create a temporary directory for the test so it's easy to remove the files later:
 
-    ```sh
-    mkdir test; cd test
-    ```
+   ```sh
+   mkdir test; cd test
+   ```
+
 1. Run the command:
 
-    ```sh
-    time for i in {0..1000}; do echo 'test' > "test${i}.txt"; done
-    ```
-1. To benchmark read performance, run the command:
+   ```sh
+   time for i in {0..1000}; do echo 'test' > "test${i}.txt"; done
+   ```
 
-    ```sh
-    time for i in {0..1000}; do cat "test${i}.txt" > /dev/null; done
-    ```
-1. Remove the test files:
+1. To benchmark read performance, run the command:
 
    ```sh
-   cd ../; rm -rf test
+   time for i in {0..1000}; do cat "test${i}.txt" > /dev/null; done
    ```
 
+1. Remove the test files:
+
+  ```sh
+  cd ../; rm -rf test
+  ```
+
 The output of the `time for ...` commands will look similar to the following. The
 important metric is the `real` time.
 
 ```sh
 $ time for i in {0..1000}; do echo 'test' > "test${i}.txt"; done
 
-real	0m0.116s
-user	0m0.025s
-sys	0m0.091s
+real    0m0.116s
+user    0m0.025s
+sys     0m0.091s
 
 $ time for i in {0..1000}; do cat "test${i}.txt" > /dev/null; done
 
diff --git a/doc/administration/operations/img/sidekiq-cluster.png b/doc/administration/operations/img/sidekiq-cluster.png
index 4eb1849010e..3899385eb8f 100644
--- a/doc/administration/operations/img/sidekiq-cluster.png
+++ b/doc/administration/operations/img/sidekiq-cluster.png
diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md
index df795a48169..df208b3f427 100644
--- a/doc/administration/operations/index.md
+++ b/doc/administration/operations/index.md
@@ -11,7 +11,7 @@ Keep your GitLab instance up and running smoothly.
   by GitLab to another file system or another server.
 - [Sidekiq MemoryKiller](sidekiq_memory_killer.md): Configure Sidekiq MemoryKiller
   to restart Sidekiq.
-- [Extra Sidekiq operations](extra_sidekiq_processes.md): Configure an extra set of Sidekiq processes to ensure certain queues always have dedicated workers, no matter the amount of jobs that need to be processed. **[STARTER ONLY]**
+- [Extra Sidekiq operations](extra_sidekiq_processes.md): Configure an extra set of Sidekiq processes to ensure certain queues always have dedicated workers, no matter the amount of jobs that need to be processed. **(STARTER ONLY)**
 - [Unicorn](unicorn.md): Understand Unicorn and unicorn-worker-killer.
 - Speed up SSH operations by [Authorizing SSH users via a fast,
   indexed lookup to the GitLab database](fast_ssh_key_lookup.md), and/or
diff --git a/doc/administration/operations/unicorn.md b/doc/administration/operations/unicorn.md
index 0e2079cb093..8178cb243f3 100644
--- a/doc/administration/operations/unicorn.md
+++ b/doc/administration/operations/unicorn.md
@@ -2,7 +2,7 @@
 
 ## Unicorn
 
-GitLab uses [Unicorn](http://unicorn.bogomips.org/), a pre-forking Ruby web
+GitLab uses [Unicorn](https://bogomips.org/unicorn/), a pre-forking Ruby web
 server, to handle web requests (web browsers and Git HTTP clients). Unicorn is
 a daemon written in Ruby and C that can load and run a Ruby on Rails
 application; in our case the Rails application is GitLab Community Edition or
@@ -69,7 +69,7 @@ unicorn['worker_memory_limit_min'] = "400 * 1 << 20"
 unicorn['worker_memory_limit_max'] = "650 * 1 << 20"
 ```
 
-Otherwise, you can set the `GITLAB_UNICORN_MEMORY_MIN` and `GITLAB_UNICORN_MEMORY_MIN`
+Otherwise, you can set the `GITLAB_UNICORN_MEMORY_MIN` and `GITLAB_UNICORN_MEMORY_MAX`
 [environment variables](../environment_variables.md).
 
 This is what a Unicorn worker memory restart looks like in unicorn_stderr.log.
diff --git a/doc/administration/packages.md b/doc/administration/packages.md
index 0d5f784b71e..c0f8777a8c0 100644
--- a/doc/administration/packages.md
+++ b/doc/administration/packages.md
@@ -1,4 +1,4 @@
-# GitLab Packages administration **[PREMIUM ONLY]**
+# GitLab Packages administration **(PREMIUM ONLY)**
 
 GitLab Packages allows organizations to utilize GitLab as a private repository
 for a variety of common package managers. Users are able to build and publish
@@ -11,7 +11,7 @@ The Packages feature allows GitLab to act as a repository for the following:
 | [Maven Repository](../user/project/packages/maven_repository.md) | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | 11.3+ |
 | [NPM Registry](../user/project/packages/npm_registry.md)   | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | 11.7+ |
 
-Don't you see your package management system supported yet? 
+Don't you see your package management system supported yet?
 Please consider contributing
 to GitLab. This [development documentation](../development/packages.md) will guide you through the process.
 
@@ -28,9 +28,9 @@ To enable the Packages feature:
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
-    ```ruby
-    gitlab_rails['packages_enabled'] = true
-    ```
+   ```ruby
+   gitlab_rails['packages_enabled'] = true
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -39,10 +39,11 @@ To enable the Packages feature:
 1. After the installation is complete, you will have to configure the `packages`
    section in `config/gitlab.yml`. Set to `true` to enable it:
 
-      ```yaml
-      packages:
-        enabled: true
-      ```
+   ```yaml
+   packages:
+     enabled: true
+   ```
+
 1. [Restart GitLab] for the changes to take effect.
 
 ## Changing the storage path
@@ -61,9 +62,9 @@ To change the local storage path:
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
-    ```ruby
-    gitlab_rails['packages_storage_path'] = "/mnt/packages"
-    ```
+   ```ruby
+   gitlab_rails['packages_storage_path'] = "/mnt/packages"
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -71,11 +72,12 @@ To change the local storage path:
 
 1. Edit the `packages` section in `config/gitlab.yml`:
 
-      ```yaml
-      packages:
-        enabled: true
-        storage_path: shared/packages
-      ```
+   ```yaml
+   packages:
+     enabled: true
+     storage_path: shared/packages
+   ```
+
 1. [Restart GitLab] for the changes to take effect.
 
 ### Using object storage
@@ -88,31 +90,31 @@ upload packages:
 1. Edit `/etc/gitlab/gitlab.rb` and add the following lines (uncomment where
    necessary):
 
-    ```ruby
-    gitlab_rails['packages_enabled'] = true
-    gitlab_rails['packages_storage_path'] = "/var/opt/gitlab/gitlab-rails/shared/packages"
-    gitlab_rails['packages_object_store_enabled'] = true
-    gitlab_rails['packages_object_store_remote_directory'] = "packages" # The bucket name.
-    gitlab_rails['packages_object_store_direct_upload'] = false         # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
-    gitlab_rails['packages_object_store_background_upload'] = true      # Temporary option to limit automatic upload (Default: true).
-    gitlab_rails['packages_object_store_proxy_download'] = false        # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
-    gitlab_rails['packages_object_store_connection'] = {
-      ##
-      ## If the provider is AWS S3, uncomment the following
-      ##
-      #'provider' => 'AWS',
-      #'region' => 'eu-west-1',
-      #'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
-      #'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY',
-      ##
-      ## If the provider is other than AWS (an S3-compatible one), uncomment the following
-      ##
-      #'host' => 's3.amazonaws.com',
-      #'aws_signature_version' => 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
-      #'endpoint' => 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
-      #'path_style' => false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
-    }
-    ```
+   ```ruby
+   gitlab_rails['packages_enabled'] = true
+   gitlab_rails['packages_storage_path'] = "/var/opt/gitlab/gitlab-rails/shared/packages"
+   gitlab_rails['packages_object_store_enabled'] = true
+   gitlab_rails['packages_object_store_remote_directory'] = "packages" # The bucket name.
+   gitlab_rails['packages_object_store_direct_upload'] = false         # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
+   gitlab_rails['packages_object_store_background_upload'] = true      # Temporary option to limit automatic upload (Default: true).
+   gitlab_rails['packages_object_store_proxy_download'] = false        # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
+   gitlab_rails['packages_object_store_connection'] = {
+     ##
+     ## If the provider is AWS S3, uncomment the following
+     ##
+     #'provider' => 'AWS',
+     #'region' => 'eu-west-1',
+     #'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
+     #'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY',
+     ##
+     ## If the provider is other than AWS (an S3-compatible one), uncomment the following
+     ##
+     #'host' => 's3.amazonaws.com',
+     #'aws_signature_version' => 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
+     #'endpoint' => 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
+     #'path_style' => false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
+   }
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -120,35 +122,35 @@ upload packages:
 
 1. Edit the `packages` section in `config/gitlab.yml` (uncomment where necessary):
 
-    ```yaml
-      packages:
-        enabled: true
-        ##
-        ## The location where build packages are stored (default: shared/packages).
-        ##
-        #storage_path: shared/packages
-        object_store:
-          enabled: false
-          remote_directory: packages # The bucket name.
-          #direct_upload: false      # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
-          #background_upload: true   # Temporary option to limit automatic upload (Default: true).
-          #proxy_download: false     # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
-          connection:
-            ##
-            ## If the provider is AWS S3, uncomment the following
-            ##
-            #provider: AWS
-            #region: us-east-1
-            #aws_access_key_id: AWS_ACCESS_KEY_ID
-            #aws_secret_access_key: AWS_SECRET_ACCESS_KEY
-            ##
-            ## If the provider is other than AWS (an S3-compatible one), uncomment the following
-            ##
-            #host: 's3.amazonaws.com'             # default: s3.amazonaws.com.
-            #aws_signature_version: 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
-            #endpoint: 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
-            #path_style: false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
-    ```
+   ```yaml
+     packages:
+       enabled: true
+       ##
+       ## The location where build packages are stored (default: shared/packages).
+       ##
+       #storage_path: shared/packages
+       object_store:
+         enabled: false
+         remote_directory: packages # The bucket name.
+         #direct_upload: false      # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
+         #background_upload: true   # Temporary option to limit automatic upload (Default: true).
+         #proxy_download: false     # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
+         connection:
+           ##
+           ## If the provider is AWS S3, uncomment the following
+           ##
+           #provider: AWS
+           #region: us-east-1
+           #aws_access_key_id: AWS_ACCESS_KEY_ID
+           #aws_secret_access_key: AWS_SECRET_ACCESS_KEY
+           ##
+           ## If the provider is other than AWS (an S3-compatible one), uncomment the following
+           ##
+           #host: 's3.amazonaws.com'             # default: s3.amazonaws.com.
+           #aws_signature_version: 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
+           #endpoint: 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
+           #path_style: false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
+   ```
 
 1. [Restart GitLab] for the changes to take effect.
 
diff --git a/doc/administration/pages/img/lets_encrypt_integration_v12_1.png b/doc/administration/pages/img/lets_encrypt_integration_v12_1.png
new file mode 100644
index 00000000000..0f3ca25ce55
--- /dev/null
+++ b/doc/administration/pages/img/lets_encrypt_integration_v12_1.png
diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md
index 3a7ca517d56..774e7056845 100644
--- a/doc/administration/pages/index.md
+++ b/doc/administration/pages/index.md
@@ -4,21 +4,24 @@ description: 'Learn how to administer GitLab Pages.'
 
 # GitLab Pages administration
 
-> **Notes:**
->
 > - [Introduced][ee-80] in GitLab EE 8.3.
 > - Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5.
-> - GitLab Pages [were ported][ce-14605] to Community Edition in GitLab 8.17.
-> - This guide is for Omnibus GitLab installations. If you have installed
->   GitLab from source, follow the [Pages source installation document](source.md).
-> - To learn how to use GitLab Pages, read the [user documentation][pages-userguide].
-> - Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8.
-
-This document describes how to set up the _latest_ GitLab Pages feature. Make
-sure to read the [changelog](#changelog) if you are upgrading to a new GitLab
+> - GitLab Pages [was ported][ce-14605] to Community Edition in GitLab 8.17.
+> - Support for subgroup project's websites was
+>   [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8.
+
+GitLab Pages allows for hosting of static sites. It must be configured by an
+administrator. Separate [user documentation][pages-userguide] is available.
+
+Read the [changelog](#changelog) if you are upgrading to a new GitLab
 version as it may include new features and changes needed to be made in your
 configuration.
 
+NOTE: **Note:**
+This guide is for Omnibus GitLab installations. If you have installed
+GitLab from source, see
+[GitLab Pages administration for source installations](source.md).
+
 ## Overview
 
 GitLab Pages makes use of the [GitLab Pages daemon], a simple HTTP server
@@ -121,9 +124,9 @@ The Pages daemon doesn't listen to the outside world.
 
 1. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`:
 
-    ```shell
-    pages_external_url 'http://example.io'
-    ```
+   ```shell
+   pages_external_url 'http://example.io'
+   ```
 
 1. [Reconfigure GitLab][reconfigure].
 
@@ -146,16 +149,16 @@ outside world.
 1. Place the certificate and key inside `/etc/gitlab/ssl`
 1. In `/etc/gitlab/gitlab.rb` specify the following configuration:
 
-    ```shell
-    pages_external_url 'https://example.io'
+   ```shell
+   pages_external_url 'https://example.io'
 
-    pages_nginx['redirect_http_to_https'] = true
-    pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/pages-nginx.crt"
-    pages_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/pages-nginx.key"
-    ```
+   pages_nginx['redirect_http_to_https'] = true
+   pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/pages-nginx.crt"
+   pages_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/pages-nginx.key"
+   ```
 
-    where `pages-nginx.crt` and `pages-nginx.key` are the SSL cert and key,
-    respectively.
+   where `pages-nginx.crt` and `pages-nginx.key` are the SSL cert and key,
+   respectively.
 
 1. [Reconfigure GitLab][reconfigure].
 
@@ -168,9 +171,9 @@ behavior:
 1. Edit `/etc/gitlab/gitlab.rb`.
 1. Set the `inplace_chroot` to `true` for GitLab Pages:
 
-    ```shell
-    gitlab_pages['inplace_chroot'] = true
-    ```
+   ```shell
+   gitlab_pages['inplace_chroot'] = true
+   ```
 
 1. [Reconfigure GitLab][reconfigure].
 
@@ -203,16 +206,16 @@ world. Custom domains are supported, but no TLS.
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```shell
-    pages_external_url "http://example.io"
-    nginx['listen_addresses'] = ['192.0.2.1']
-    pages_nginx['enable'] = false
-    gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001::2]:80']
-    ```
+   ```shell
+   pages_external_url "http://example.io"
+   nginx['listen_addresses'] = ['192.0.2.1']
+   pages_nginx['enable'] = false
+   gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001::2]:80']
+   ```
 
-    where `192.0.2.1` is the primary IP address that GitLab is listening to and
-    `192.0.2.2` and `2001::2` are the secondary IPs the GitLab Pages daemon
-    listens on. If you don't have IPv6, you can omit the IPv6 address.
+   where `192.0.2.1` is the primary IP address that GitLab is listening to and
+   `192.0.2.2` and `2001::2` are the secondary IPs the GitLab Pages daemon
+   listens on. If you don't have IPv6, you can omit the IPv6 address.
 
 1. [Reconfigure GitLab][reconfigure].
 
@@ -234,26 +237,26 @@ world. Custom domains and TLS are supported.
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```shell
-    pages_external_url "https://example.io"
-    nginx['listen_addresses'] = ['192.0.2.1']
-    pages_nginx['enable'] = false
-    gitlab_pages['cert'] = "/etc/gitlab/ssl/example.io.crt"
-    gitlab_pages['cert_key'] = "/etc/gitlab/ssl/example.io.key"
-    gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001::2]:80']
-    gitlab_pages['external_https'] = ['192.0.2.2:443', '[2001::2]:443']
-    ```
+   ```shell
+   pages_external_url "https://example.io"
+   nginx['listen_addresses'] = ['192.0.2.1']
+   pages_nginx['enable'] = false
+   gitlab_pages['cert'] = "/etc/gitlab/ssl/example.io.crt"
+   gitlab_pages['cert_key'] = "/etc/gitlab/ssl/example.io.key"
+   gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001::2]:80']
+   gitlab_pages['external_https'] = ['192.0.2.2:443', '[2001::2]:443']
+   ```
 
-    where `192.0.2.1` is the primary IP address that GitLab is listening to and
-    `192.0.2.2` and `2001::2` are the secondary IPs where the GitLab Pages daemon
-    listens on. If you don't have IPv6, you can omit the IPv6 address.
+   where `192.0.2.1` is the primary IP address that GitLab is listening to and
+   `192.0.2.2` and `2001::2` are the secondary IPs where the GitLab Pages daemon
+   listens on. If you don't have IPv6, you can omit the IPv6 address.
 
 1. [Reconfigure GitLab][reconfigure].
 
 ### Custom domain verification
 
 To prevent malicious users from hijacking domains that don't belong to them,
-GitLab supports [custom domain verification](../../user/project/pages/getting_started_part_three.md#dns-txt-record).
+GitLab supports [custom domain verification](../../user/project/pages/custom_domains_ssl_tls_certification/index.md#steps).
 When adding a custom domain, users will be required to prove they own it by
 adding a GitLab-controlled verification code to the DNS records for that domain.
 
@@ -262,6 +265,23 @@ verification requirement. Navigate to `Admin area ➔ Settings` and uncheck
 **Require users to prove ownership of custom domains** in the Pages section.
 This setting is enabled by default.
 
+### Let's Encrypt integration
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28996) in GitLab 12.1.
+
+[GitLab Pages' Let's Encrypt integration](../../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md)
+allows users to add Let's Encrypt SSL certificates for GitLab Pages
+sites served under a custom domain.
+
+To enable it, you'll need to:
+
+1. Choose an email on which you will recieve notifications about expiring domains.
+1. Navigate to your instance's **Admin Area > Settings > Preferences** and expand **Pages** settings.
+1. Enter the email for receiving notifications and accept Let's Encrypt's Terms of Service as shown below.
+1. Click **Save changes**.
+
+![Let's Encrypt settings](img/lets_encrypt_integration_v12_1.png)
+
 ### Access control
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5.
@@ -284,9 +304,9 @@ Pages access control is disabled by default. To enable it:
 
 1. Enable it in `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_pages['access_control'] = true
-    ```
+   ```ruby
+   gitlab_pages['access_control'] = true
+   ```
 
 1. [Reconfigure GitLab][reconfigure].
 1. Users can now configure it in their [projects' settings](../../user/project/pages/introduction.md#gitlab-pages-access-control-core-only).
@@ -299,9 +319,9 @@ pages:
 
 1. Configure in `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_pages['http_proxy'] = 'http://example:8080'
-    ```
+   ```ruby
+   gitlab_pages['http_proxy'] = 'http://example:8080'
+   ```
 
 1. [Reconfigure Gitlab][reconfigure] for the changes to take effect.
 
@@ -316,9 +336,9 @@ Follow the steps below to configure verbose logging of GitLab Pages daemon.
    If you wish to make it log events with level `DEBUG` you must configure this in
    `/etc/gitlab/gitlab.rb`:
 
-    ```shell
-    gitlab_pages['log_verbose'] = true
-    ```
+   ```shell
+   gitlab_pages['log_verbose'] = true
+   ```
 
 1. [Reconfigure GitLab][reconfigure].
 
@@ -331,9 +351,9 @@ are stored.
    If you wish to store them in another location you must set it up in
    `/etc/gitlab/gitlab.rb`:
 
-    ```shell
-    gitlab_rails['pages_path'] = "/mnt/storage/pages"
-    ```
+   ```shell
+   gitlab_rails['pages_path'] = "/mnt/storage/pages"
+   ```
 
 1. [Reconfigure GitLab][reconfigure].
 
@@ -344,19 +364,19 @@ Omnibus GitLab 11.1.
 
 1. By default the listener is configured to listen for requests on `localhost:8090`.
 
-    If you wish to disable it you must configure this in
-    `/etc/gitlab/gitlab.rb`:
+   If you wish to disable it you must configure this in
+   `/etc/gitlab/gitlab.rb`:
 
-    ```shell
-    gitlab_pages['listen_proxy'] = nil
-    ```
+   ```shell
+   gitlab_pages['listen_proxy'] = nil
+   ```
 
-    If you wish to make it listen on a different port you must configure this also in
-    `/etc/gitlab/gitlab.rb`:
+   If you wish to make it listen on a different port you must configure this also in
+   `/etc/gitlab/gitlab.rb`:
 
-    ```shell
-    gitlab_pages['listen_proxy'] = "localhost:10080"
-    ```
+   ```shell
+   gitlab_pages['listen_proxy'] = "localhost:10080"
+   ```
 
 1. [Reconfigure GitLab][reconfigure].
 
@@ -378,28 +398,29 @@ Follow the steps below to configure GitLab Pages in a separate server.
 
 1. On `app2` install GitLab omnibus and modify `/etc/gitlab/gitlab.rb` this way:
 
-    ```shell
-    external_url 'http://<ip-address-of-the-server>'
-    pages_external_url "http://<your-pages-domain>"
-    postgresql['enable'] = false
-    redis['enable'] = false
-    prometheus['enable'] = false
-    unicorn['enable'] = false
-    sidekiq['enable'] = false
-    gitlab_workhorse['enable'] = false
-    gitaly['enable'] = false
-    alertmanager['enable'] = false
-    node_exporter['enable'] = false
-    gitlab_rails['auto_migrate'] = false
-    ```
+   ```shell
+   external_url 'http://<ip-address-of-the-server>'
+   pages_external_url "http://<your-pages-domain>"
+   postgresql['enable'] = false
+   redis['enable'] = false
+   prometheus['enable'] = false
+   unicorn['enable'] = false
+   sidekiq['enable'] = false
+   gitlab_workhorse['enable'] = false
+   gitaly['enable'] = false
+   alertmanager['enable'] = false
+   node_exporter['enable'] = false
+   gitlab_rails['auto_migrate'] = false
+   ```
+
 1. Run `sudo gitlab-ctl reconfigure`.
 1. On `app1` apply the following changes to `/etc/gitlab/gitlab.rb`:
 
-    ```shell
-    gitlab_pages['enable'] = false
-    pages_external_url "http://<your-pages-domain>"
-    gitlab_rails['pages_path'] = "/mnt/pages"
-    ```
+   ```shell
+   gitlab_pages['enable'] = false
+   pages_external_url "http://<your-pages-domain>"
+   gitlab_rails['pages_path'] = "/mnt/pages"
+   ```
 
 1. Run `sudo gitlab-ctl reconfigure`.
 
diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md
index 2100f7cd707..c77a1a9638f 100644
--- a/doc/administration/pages/source.md
+++ b/doc/administration/pages/source.md
@@ -24,8 +24,6 @@ SNI and exposes pages using HTTP2 by default.
 You are encouraged to read its [README][pages-readme] to fully understand how
 it works.
 
----
-
 In the case of [custom domains](#custom-domains) (but not
 [wildcard domains](#wildcard-domains)), the Pages daemon needs to listen on
 ports `80` and/or `443`. For that reason, there is some flexibility in the way
@@ -92,8 +90,6 @@ since that is needed in all configurations.
 
 - [Wildcard DNS setup](#dns-configuration)
 
----
-
 URL scheme: `http://page.example.io`
 
 This is the minimum setup that you can use Pages with. It is the base for all
@@ -102,90 +98,89 @@ The Pages daemon doesn't listen to the outside world.
 
 1. Install the Pages daemon:
 
-    ```
-    cd /home/git
-    sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
-    cd gitlab-pages
-    sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
-    sudo -u git -H make
-    ```
+   ```
+   cd /home/git
+   sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
+   cd gitlab-pages
+   sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
+   sudo -u git -H make
+   ```
 
 1. Go to the GitLab installation directory:
 
-    ```bash
-    cd /home/git/gitlab
-    ```
+   ```bash
+   cd /home/git/gitlab
+   ```
 
 1. Edit `gitlab.yml` and under the `pages` setting, set `enabled` to `true` and
    the `host` to the FQDN under which GitLab Pages will be served:
 
-    ```yaml
-    ## GitLab Pages
-    pages:
-      enabled: true
-      # The location where pages are stored (default: shared/pages).
-      # path: shared/pages
+   ```yaml
+   ## GitLab Pages
+   pages:
+     enabled: true
+     # The location where pages are stored (default: shared/pages).
+     # path: shared/pages
 
-      host: example.io
-      port: 80
-      https: false
-    ```
+     host: example.io
+     port: 80
+     https: false
+   ```
 
 1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in
    order to enable the pages daemon. In `gitlab_pages_options` the
    `-pages-domain` must match the `host` setting that you set above.
 
-    ```
-    gitlab_pages_enabled=true
-    gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090"
-    ```
+   ```
+   gitlab_pages_enabled=true
+   gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090"
+   ```
 
 1. Copy the `gitlab-pages` Nginx configuration file:
 
-    ```bash
-    sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf
-    sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf
-    ```
+   ```bash
+   sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf
+   sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf
+   ```
 
 1. Restart NGINX
 1. [Restart GitLab][restart]
 
 ### Wildcard domains with TLS support
 
-> **Requirements:**
-> - [Wildcard DNS setup](#dns-configuration)
-> - Wildcard TLS certificate
->
-> ---
->
-> URL scheme: `https://page.example.io`
+**Requirements:**
+
+- [Wildcard DNS setup](#dns-configuration)
+- Wildcard TLS certificate
+
+URL scheme: `https://page.example.io`
 
 Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the
 outside world.
 
 1. Install the Pages daemon:
 
-    ```
-    cd /home/git
-    sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
-    cd gitlab-pages
-    sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
-    sudo -u git -H make
-    ```
+   ```
+   cd /home/git
+   sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
+   cd gitlab-pages
+   sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
+   sudo -u git -H make
+   ```
 
 1. In `gitlab.yml`, set the port to `443` and https to `true`:
 
-    ```bash
-    ## GitLab Pages
-    pages:
-      enabled: true
-      # The location where pages are stored (default: shared/pages).
-      # path: shared/pages
+   ```bash
+   ## GitLab Pages
+   pages:
+     enabled: true
+     # The location where pages are stored (default: shared/pages).
+     # path: shared/pages
 
-      host: example.io
-      port: 443
-      https: true
-    ```
+     host: example.io
+     port: 443
+     https: true
+   ```
 
 1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in
    order to enable the pages daemon. In `gitlab_pages_options` the
@@ -193,17 +188,17 @@ outside world.
    The `-root-cert` and `-root-key` settings are the wildcard TLS certificates
    of the `example.io` domain:
 
-    ```
-    gitlab_pages_enabled=true
-    gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key
-    ```
+   ```
+   gitlab_pages_enabled=true
+   gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key
+   ```
 
 1. Copy the `gitlab-pages-ssl` Nginx configuration file:
 
-    ```bash
-    sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf
-    sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf
-    ```
+   ```bash
+   sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf
+   sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf
+   ```
 
 1. Restart NGINX
 1. [Restart GitLab][restart]
@@ -217,13 +212,12 @@ that without TLS certificates.
 
 ### Custom domains
 
-> **Requirements:**
-> - [Wildcard DNS setup](#dns-configuration)
-> - Secondary IP
->
-> ---
->
-> URL scheme: `http://page.example.io` and `http://domain.com`
+**Requirements:**
+
+- [Wildcard DNS setup](#dns-configuration)
+- Secondary IP
+
+URL scheme: `http://page.example.io` and `http://domain.com`
 
 In that case, the pages daemon is running, Nginx still proxies requests to
 the daemon but the daemon is also able to receive requests from the outside
@@ -231,48 +225,48 @@ world. Custom domains are supported, but no TLS.
 
 1. Install the Pages daemon:
 
-    ```
-    cd /home/git
-    sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
-    cd gitlab-pages
-    sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
-    sudo -u git -H make
-    ```
+   ```
+   cd /home/git
+   sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
+   cd gitlab-pages
+   sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
+   sudo -u git -H make
+   ```
 
 1. Edit `gitlab.yml` to look like the example below. You need to change the
    `host` to the FQDN under which GitLab Pages will be served. Set
    `external_http` to the secondary IP on which the pages daemon will listen
    for connections:
 
-    ```yaml
-    pages:
-      enabled: true
-      # The location where pages are stored (default: shared/pages).
-      # path: shared/pages
+   ```yaml
+   pages:
+     enabled: true
+     # The location where pages are stored (default: shared/pages).
+     # path: shared/pages
 
-      host: example.io
-      port: 80
-      https: false
+     host: example.io
+     port: 80
+     https: false
 
-      external_http: 192.0.2.2:80
-    ```
+     external_http: 192.0.2.2:80
+   ```
 
 1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in
    order to enable the pages daemon. In `gitlab_pages_options` the
    `-pages-domain` and `-listen-http` must match the `host` and `external_http`
    settings that you set above respectively:
 
-    ```
-    gitlab_pages_enabled=true
-    gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -listen-http 192.0.2.2:80"
-    ```
+   ```
+   gitlab_pages_enabled=true
+   gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -listen-http 192.0.2.2:80"
+   ```
 
 1. Copy the `gitlab-pages-ssl` Nginx configuration file:
 
-    ```bash
-    sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf
-    sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf
-    ```
+   ```bash
+   sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf
+   sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf
+   ```
 
 1. Edit all GitLab related configs in `/etc/nginx/site-available/` and replace
    `0.0.0.0` with `192.0.2.1`, where `192.0.2.1` the primary IP where GitLab
@@ -282,14 +276,13 @@ world. Custom domains are supported, but no TLS.
 
 ### Custom domains with TLS support
 
-> **Requirements:**
-> - [Wildcard DNS setup](#dns-configuration)
-> - Wildcard TLS certificate
-> - Secondary IP
->
-> ---
->
-> URL scheme: `https://page.example.io` and `https://domain.com`
+**Requirements:**
+
+- [Wildcard DNS setup](#dns-configuration)
+- Wildcard TLS certificate
+- Secondary IP
+
+URL scheme: `https://page.example.io` and `https://domain.com`
 
 In that case, the pages daemon is running, Nginx still proxies requests to
 the daemon but the daemon is also able to receive requests from the outside
@@ -297,33 +290,33 @@ world. Custom domains and TLS are supported.
 
 1. Install the Pages daemon:
 
-    ```
-    cd /home/git
-    sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
-    cd gitlab-pages
-    sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
-    sudo -u git -H make
-    ```
+   ```
+   cd /home/git
+   sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
+   cd gitlab-pages
+   sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
+   sudo -u git -H make
+   ```
 
 1. Edit `gitlab.yml` to look like the example below. You need to change the
    `host` to the FQDN under which GitLab Pages will be served. Set
    `external_http` and `external_https` to the secondary IP on which the pages
    daemon will listen for connections:
 
-    ```yaml
-    ## GitLab Pages
-    pages:
-      enabled: true
-      # The location where pages are stored (default: shared/pages).
-      # path: shared/pages
+   ```yaml
+   ## GitLab Pages
+   pages:
+     enabled: true
+     # The location where pages are stored (default: shared/pages).
+     # path: shared/pages
 
-      host: example.io
-      port: 443
-      https: true
+     host: example.io
+     port: 443
+     https: true
 
-      external_http: 192.0.2.2:80
-      external_https: 192.0.2.2:443
-    ```
+     external_http: 192.0.2.2:80
+     external_https: 192.0.2.2:443
+   ```
 
 1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in
    order to enable the pages daemon. In `gitlab_pages_options` the
@@ -332,17 +325,17 @@ world. Custom domains and TLS are supported.
    The `-root-cert` and `-root-key` settings are the wildcard TLS certificates
    of the `example.io` domain:
 
-    ```
-    gitlab_pages_enabled=true
-    gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -listen-http 192.0.2.2:80 -listen-https 192.0.2.2:443 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key
-    ```
+   ```
+   gitlab_pages_enabled=true
+   gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -listen-http 192.0.2.2:80 -listen-https 192.0.2.2:443 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key
+   ```
 
 1. Copy the `gitlab-pages-ssl` Nginx configuration file:
 
-    ```bash
-    sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf
-    sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf
-    ```
+   ```bash
+   sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf
+   sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf
+   ```
 
 1. Edit all GitLab related configs in `/etc/nginx/site-available/` and replace
    `0.0.0.0` with `192.0.2.1`, where `192.0.2.1` the primary IP where GitLab
@@ -359,9 +352,9 @@ are stored.
    If you wish to store them in another location you must set it up in
    `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['pages_path'] = "/mnt/storage/pages"
-    ```
+   ```ruby
+   gitlab_rails['pages_path'] = "/mnt/storage/pages"
+   ```
 
 1. [Reconfigure GitLab][reconfigure]
 
@@ -414,10 +407,10 @@ Pages access control is disabled by default. To enable it:
 
 1. Modify your `config/gitlab.yml` file:
 
-    ```yaml
-    pages:
-      access_control: true
-    ```
+   ```yaml
+   pages:
+     access_control: true
+   ```
 
 1. [Restart GitLab][restart].
 1. Create a new [system OAuth application](../../integration/oauth_provider.md#adding-an-application-through-the-profile).
@@ -426,12 +419,12 @@ Pages access control is disabled by default. To enable it:
    application, but it does need the "api" scope.
 1. Start the Pages daemon with the following additional arguments:
 
-    ```shell
-      -auth-client-secret <OAuth code generated by GitLab> \
-      -auth-redirect-uri http://projects.example.io/auth \
-      -auth-secret <40 random hex characters> \
-      -auth-server <URL of the GitLab instance>
-    ```
+   ```shell
+     -auth-client-secret <OAuth code generated by GitLab> \
+     -auth-redirect-uri http://projects.example.io/auth \
+     -auth-secret <40 random hex characters> \
+     -auth-server <URL of the GitLab instance>
+   ```
 
 1. Users can now configure it in their [projects' settings](../../user/project/pages/introduction.md#gitlab-pages-access-control-core-only).
 
@@ -444,12 +437,12 @@ are stored.
    If you wish to store them in another location you must set it up in
    `gitlab.yml` under the `pages` section:
 
-    ```yaml
-    pages:
-      enabled: true
-      # The location where pages are stored (default: shared/pages).
-      path: /mnt/storage/pages
-    ```
+   ```yaml
+   pages:
+     enabled: true
+     # The location where pages are stored (default: shared/pages).
+     path: /mnt/storage/pages
+   ```
 
 1. [Restart GitLab][restart]
 
diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md
index 4302667caf5..4cf3c607dae 100644
--- a/doc/administration/plugins.md
+++ b/doc/administration/plugins.md
@@ -52,7 +52,37 @@ as appropriate. The 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`.
+message will be logged to:
+
+- `gitlab-rails/plugin.log` in an Omnibus installation.
+- `log/plugin.log` in a source installation.
+
+## Creating plugins
+
+Below is an example that will only response on the event `project_create` and
+will inform the admins from the GitLab instance that a new project has been created.
+
+```ruby
+# By using the embedded ruby version we eliminate the possibility that our chosen language
+# would be unavailable from
+#!/opt/gitlab/embedded/bin/ruby
+require 'json'
+require 'mail'
+
+# The incoming variables are in JSON format so we need to parse it first.
+ARGS = JSON.parse(STDIN.read)
+
+# We only want to trigger this plugin on the event project_create
+return unless ARGS['event_name'] == 'project_create'
+
+# We will inform our admins of our gitlab instance that a new project is created
+Mail.deliver do
+  from    'info@gitlab_instance.com'
+  to      'admin@gitlab_instance.com'
+  subject "new project " + ARGS['name']
+  body    ARGS['owner_name'] + 'created project ' + ARGS['name']
+end
+```
 
 ## Validation
 
diff --git a/doc/administration/pseudonymizer.md b/doc/administration/pseudonymizer.md
index 036e1d3fe61..716a4259a64 100644
--- a/doc/administration/pseudonymizer.md
+++ b/doc/administration/pseudonymizer.md
@@ -1,4 +1,4 @@
-# Pseudonymizer **[ULTIMATE]**
+# Pseudonymizer **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5532) in [GitLab Ultimate][ee] 11.1.
 
@@ -22,36 +22,36 @@ To configure the pseudonymizer, you need to:
 
 - Provide a manifest file that describes which fields should be included or
   pseudonymized ([example `manifest.yml` file](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/config/pseudonymizer.yml)).
-  A default manifest is provided with the GitLab installation. Using a relative file path will be resolved from the Rails root. 
+  A default manifest is provided with the GitLab installation. Using a relative file path will be resolved from the Rails root.
   Alternatively, you can use an absolute file path.
-- Use an object storage and specify the connection parameters in the `pseudonymizer.upload.connection` configuration option. 
+- Use an object storage and specify the connection parameters in the `pseudonymizer.upload.connection` configuration option.
 
 **For Omnibus installations:**
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with
    the values you want:
 
-    ```ruby
-    gitlab_rails['pseudonymizer_manifest'] = 'config/pseudonymizer.yml'
-    gitlab_rails['pseudonymizer_upload_remote_directory'] = 'gitlab-elt' # bucket name
-    gitlab_rails['pseudonymizer_upload_connection'] = {
-      'provider' => 'AWS',
-      'region' => 'eu-central-1',
-      'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
-      'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
-    }
-    ```
-
-    NOTE: **Note:**
-    If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.
-
-    ```ruby
-    gitlab_rails['pseudonymizer_upload_connection'] = {
-      'provider' => 'AWS',
-      'region' => 'eu-central-1',
-      'use_iam_profile' => true
-    }
-    ```
+   ```ruby
+   gitlab_rails['pseudonymizer_manifest'] = 'config/pseudonymizer.yml'
+   gitlab_rails['pseudonymizer_upload_remote_directory'] = 'gitlab-elt' # bucket name
+   gitlab_rails['pseudonymizer_upload_connection'] = {
+     'provider' => 'AWS',
+     'region' => 'eu-central-1',
+     'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
+     'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
+   }
+   ```
+
+   NOTE: **Note:**
+   If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.
+
+   ```ruby
+   gitlab_rails['pseudonymizer_upload_connection'] = {
+     'provider' => 'AWS',
+     'region' => 'eu-central-1',
+     'use_iam_profile' => true
+   }
+   ```
 
 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure)
    for the changes to take effect.
@@ -63,17 +63,17 @@ To configure the pseudonymizer, you need to:
 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
    lines:
 
-    ```yaml
-    pseudonymizer:
-	  manifest: config/pseudonymizer.yml
-	  upload:
-        remote_directory: 'gitlab-elt' # bucket name
-        connection:
-          provider: AWS
-          aws_access_key_id: AWS_ACCESS_KEY_ID
-          aws_secret_access_key: AWS_SECRET_ACCESS_KEY
-          region: eu-central-1
-    ```
+   ```yaml
+   pseudonymizer:
+     manifest: config/pseudonymizer.yml
+     upload:
+       remote_directory: 'gitlab-elt' # bucket name
+       connection:
+         provider: AWS
+         aws_access_key_id: AWS_ACCESS_KEY_ID
+         aws_secret_access_key: AWS_SECRET_ACCESS_KEY
+         region: eu-central-1
+   ```
 
 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source)
    for the changes to take effect.
diff --git a/doc/administration/raketasks/geo.md b/doc/administration/raketasks/geo.md
index 9f3b31442f3..691d34ab7fa 100644
--- a/doc/administration/raketasks/geo.md
+++ b/doc/administration/raketasks/geo.md
@@ -1,8 +1,8 @@
-# Geo Rake Tasks **[PREMIUM ONLY]**
+# Geo Rake Tasks **(PREMIUM ONLY)**
 
 ## Git housekeeping
 
-There are few tasks you can run to schedule a git housekeeping to start at the 
+There are few tasks you can run to schedule a git housekeeping to start at the
 next repository sync in a **Secondary node**:
 
 ### Incremental Repack
@@ -23,7 +23,7 @@ sudo -u git -H bundle exec rake geo:git:housekeeping:incremental_repack RAILS_EN
 
 ### Full Repack
 
-This is equivalent of running `git repack -d -A --pack-kept-objects` on a 
+This is equivalent of running `git repack -d -A --pack-kept-objects` on a
 _bare_ repository which will optionally, write a reachability bitmap index
 when this is enabled in GitLab.
 
diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md
index 91fc0133d56..e880d76e756 100644
--- a/doc/administration/raketasks/ldap.md
+++ b/doc/administration/raketasks/ldap.md
@@ -28,6 +28,31 @@ limit by passing a number to the check task:
 rake gitlab:ldap:check[50]
 ```
 
+## Run a Group Sync
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/14735) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3.
+
+The following task will run a [group sync](../auth/ldap-ee.md#group-sync) immediately. This is valuable
+when you'd like to update all configured group memberships against LDAP without
+waiting for the next scheduled group sync to be run.
+
+NOTE: **NOTE:**
+If you'd like to change the frequency at which a group sync is performed,
+[adjust the cron schedule](../auth/ldap-ee.md#adjusting-ldap-group-sync-schedule)
+instead.
+
+**Omnibus Installation**
+
+```
+sudo gitlab-rake gitlab:ldap:group_sync
+```
+
+**Source Installation**
+
+```bash
+bundle exec rake gitlab:ldap:group_sync
+```
+
 ## Rename a provider
 
 If you change the LDAP server ID in `gitlab.yml` or `gitlab.rb` you will need
diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md
index 0b4c1ae15d6..8d0b5b42515 100644
--- a/doc/administration/raketasks/maintenance.md
+++ b/doc/administration/raketasks/maintenance.md
@@ -61,8 +61,8 @@ It will check that each component was set up according to the installation guide
 
 You may also have a look at our Troubleshooting Guides:
 
-- [Troubleshooting Guide (GitLab)](http://docs.gitlab.com/ee/README.html#troubleshooting)
-- [Troubleshooting Guide (Omnibus Gitlab)](http://docs.gitlab.com/omnibus/README.html#troubleshooting)
+- [Troubleshooting Guide (GitLab)](../index.md#troubleshooting)
+- [Troubleshooting Guide (Omnibus Gitlab)](https://docs.gitlab.com/omnibus/README.html#troubleshooting)
 
 **Omnibus Installation**
 
@@ -251,3 +251,22 @@ sudo gitlab-rake gitlab:exclusive_lease:clear[project_housekeeping:*]
 # to clear a lease for repository garbage collection in a specific project: (id=4)
 sudo gitlab-rake gitlab:exclusive_lease:clear[project_housekeeping:4]
 ```
+
+## Display status of database migrations
+
+To check the status of migrations, you can use the following rake task:
+
+```bash
+sudo gitlab-rake db:migrate:status
+```
+
+This will output a table with a `Status` of `up` or `down` for 
+each Migration ID.
+
+```bash
+database: gitlabhq_production
+
+ Status   Migration ID    Migration Name
+--------------------------------------------------
+   up     migration_id    migration_name
+```
\ No newline at end of file
diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md
index 6ca23aabdec..138db4dfbb1 100644
--- a/doc/administration/raketasks/project_import_export.md
+++ b/doc/administration/raketasks/project_import_export.md
@@ -1,15 +1,15 @@
-# Project import/export administration **[CORE ONLY]**
+# Project import/export administration **(CORE ONLY)**
 
 >**Note:**
 >
->  - [Introduced][ce-3050] in GitLab 8.9.
->  - Importing will not be possible if the import instance version is lower
->    than that of the exporter.
->  - For existing installations, the project import option has to be enabled in
->    application settings (`/admin/application_settings`) under 'Import sources'.
->  - The exports are stored in a temporary [shared directory][tmp] and are deleted
->    every 24 hours by a specific worker.
->  - ImportExport can use object storage automatically starting from GitLab 11.3 
+> - [Introduced][ce-3050] in GitLab 8.9.
+> - Importing will not be possible if the import instance version is lower
+>   than that of the exporter.
+> - For existing installations, the project import option has to be enabled in
+>   application settings (`/admin/application_settings`) under 'Import sources'.
+> - The exports are stored in a temporary [shared directory][tmp] and are deleted
+>   every 24 hours by a specific worker.
+> - ImportExport can use object storage automatically starting from GitLab 11.3
 
 The GitLab Import/Export version can be checked by using:
 
diff --git a/doc/administration/raketasks/storage.md b/doc/administration/raketasks/storage.md
index 42a1a1c2e60..1198f3414c5 100644
--- a/doc/administration/raketasks/storage.md
+++ b/doc/administration/raketasks/storage.md
@@ -1,17 +1,17 @@
 # Repository Storage Rake Tasks
 
-This is a collection of rake tasks you can use to help you list and migrate 
-existing projects and attachments associated with it from Legacy storage to 
+This is a collection of rake tasks you can use to help you list and migrate
+existing projects and attachments associated with it from Legacy storage to
 the new Hashed storage type.
 
 You can read more about the storage types [here][storage-types].
 
 ## Migrate existing projects to Hashed storage
 
-Before migrating your existing projects, you should 
+Before migrating your existing projects, you should
 [enable hashed storage][storage-migration] for the new projects as well.
 
-This task will schedule all your existing projects and attachments associated with it to be migrated to the 
+This task will schedule all your existing projects and attachments associated with it to be migrated to the
 **Hashed** storage type:
 
 **Omnibus Installation**
@@ -30,15 +30,15 @@ They both also accept a range as environment variable:
 
 ```bash
 # to migrate any non migrated project from ID 20 to 50.
-export ID_FROM=20 
+export ID_FROM=20
 export ID_TO=50
 ```
 
 You can monitor the progress in the **Admin Area > Monitoring > Background Jobs** page.
-There is a specific Queue you can watch to see how long it will take to finish: 
+There is a specific Queue you can watch to see how long it will take to finish:
 `hashed_storage:hashed_storage_project_migrate`
 
-After it reaches zero, you can confirm every project has been migrated by running the commands bellow. 
+After it reaches zero, you can confirm every project has been migrated by running the commands bellow.
 If you find it necessary, you can run this migration script again to schedule missing projects.
 
 Any error or warning will be logged in Sidekiq's log file.
@@ -55,7 +55,7 @@ If you need to rollback the storage migration for any reason, you can follow the
 
 NOTE: **Note:** Hashed Storage will be required in future version of GitLab.
 
-To prevent new projects from being created in the Hashed storage, 
+To prevent new projects from being created in the Hashed storage,
 you need to undo the [enable hashed storage][storage-migration] changes.
 
 This task will schedule all your existing projects and associated attachments to be rolled back to the
@@ -77,15 +77,14 @@ Both commands accept a range as environment variable:
 
 ```bash
 # to rollback any migrated project from ID 20 to 50.
-export ID_FROM=20 
+export ID_FROM=20
 export ID_TO=50
 ```
 
 You can monitor the progress in the **Admin Area > Monitoring > Background Jobs** page.
 On the **Queues** tab, you can watch the `hashed_storage:hashed_storage_project_rollback` queue to see how long the process will take to finish.
 
-
-After it reaches zero, you can confirm every project has been rolled back by running the commands bellow. 
+After it reaches zero, you can confirm every project has been rolled back by running the commands bellow.
 If some projects weren't rolled back, you can run this rollback script again to schedule further rollbacks.
 
 Any error or warning will be logged in Sidekiq's log file.
@@ -106,8 +105,6 @@ sudo gitlab-rake gitlab:storage:legacy_projects
 sudo -u git -H bundle exec rake gitlab:storage:legacy_projects RAILS_ENV=production
 ```
 
-------
-
 To list projects using **Legacy** storage:
 
 **Omnibus Installation**
@@ -139,8 +136,6 @@ sudo gitlab-rake gitlab:storage:hashed_projects
 sudo -u git -H bundle exec rake gitlab:storage:hashed_projects RAILS_ENV=production
 ```
 
-------
-
 To list projects using **Hashed** storage:
 
 **Omnibus Installation**
@@ -171,8 +166,6 @@ sudo gitlab-rake gitlab:storage:legacy_attachments
 sudo -u git -H bundle exec rake gitlab:storage:legacy_attachments RAILS_ENV=production
 ```
 
-------
-
 To list project attachments using **Legacy** storage:
 
 **Omnibus Installation**
@@ -203,8 +196,6 @@ sudo gitlab-rake gitlab:storage:hashed_attachments
 sudo -u git -H bundle exec rake gitlab:storage:hashed_attachments RAILS_ENV=production
 ```
 
-------
-
 To list project attachments using **Hashed** storage:
 
 **Omnibus Installation**
diff --git a/doc/administration/raketasks/uploads/migrate.md b/doc/administration/raketasks/uploads/migrate.md
index fd8ea8d3162..86e8b763f51 100644
--- a/doc/administration/raketasks/uploads/migrate.md
+++ b/doc/administration/raketasks/uploads/migrate.md
@@ -103,3 +103,13 @@ sudo -u git -H bundle exec rake "gitlab:uploads:migrate[NamespaceFileUploader, S
 sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, MergeRequest]"
 
 ```
+
+## Migrate legacy uploads out of deprecated paths
+
+> Introduced in GitLab 12.3.
+
+To migrate all uploads created by legacy uploaders, run: 
+
+```shell
+bundle exec rake gitlab:uploads:legacy:migrate
+```
diff --git a/doc/administration/raketasks/uploads/sanitize.md b/doc/administration/raketasks/uploads/sanitize.md
index 54a423b9571..ae5ccfb9e37 100644
--- a/doc/administration/raketasks/uploads/sanitize.md
+++ b/doc/administration/raketasks/uploads/sanitize.md
@@ -4,16 +4,16 @@
 
 You need `exiftool` installed on your system. If you installed GitLab:
 
--   Using the Omnibus package, you're all set.
--   From source, make sure `exiftool` is installed:
+- Using the Omnibus package, you're all set.
+- From source, make sure `exiftool` is installed:
 
-    ```sh
-    # Debian/Ubuntu
-    sudo apt-get install libimage-exiftool-perl
+  ```sh
+  # Debian/Ubuntu
+  sudo apt-get install libimage-exiftool-perl
 
-    # RHEL/CentOS
-    sudo yum install perl-Image-ExifTool
-    ```
+  # RHEL/CentOS
+  sudo yum install perl-Image-ExifTool
+  ```
 
 ## Remove EXIF data from existing uploads
 
diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md
index d57fc67c83e..406f7e8a034 100644
--- a/doc/administration/reply_by_email_postfix_setup.md
+++ b/doc/administration/reply_by_email_postfix_setup.md
@@ -14,109 +14,109 @@ The instructions make the assumption that you will be using the email address `i
 
 1. Install the `postfix` package if it is not installed already:
 
-    ```sh
-    sudo apt-get install postfix
-    ```
+   ```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`.
+   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
-    ```
+   ```sh
+   sudo apt-get install mailutils
+   ```
 
 ## Create user
 
 1. Create a user for incoming email.
 
-    ```sh
-    sudo useradd -m -s /bin/bash incoming
-    ```
+   ```sh
+   sudo useradd -m -s /bin/bash incoming
+   ```
 
 1. Set a password for this user.
 
-    ```sh
-    sudo passwd incoming
-    ```
+   ```sh
+   sudo passwd incoming
+   ```
 
-    Be sure not to forget this, you'll need it later.
+   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
-    ```
+   ```sh
+   telnet localhost 25
+   ```
 
-    You should see a prompt like this:
+   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)
-    ```
+   ```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:
+   If you get a `Connection refused` error instead, verify that `postfix` is running:
 
-    ```sh
-    sudo postfix status
-    ```
+   ```sh
+   sudo postfix status
+   ```
 
-    If it is not, start it:
+   If it is not, start it:
 
-    ```sh
-    sudo postfix start
-    ```
+   ```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
+   ```
+   ehlo localhost
+   mail from: root@localhost
+   rcpt to: incoming@localhost
+   data
+   Subject: Re: Some issue
 
-    Sounds good!
-    .
-    quit
-    ```
+   Sounds good!
+   .
+   quit
+   ```
 
-    _**Note:** The `.` is a literal period on its own line._
+   _**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)._
+   _**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
-    ```
+   ```sh
+   su - incoming
+   mail
+   ```
 
-    You should see output like this:
+   You should see output like this:
 
-    ```
-    "/var/mail/incoming": 1 message 1 unread
-    >U   1 root@localhost                           59/2842  Re: Some issue
-    ```
+   ```
+   "/var/mail/incoming": 1 message 1 unread
+   >U   1 root@localhost                           59/2842  Re: Some issue
+   ```
 
-    Quit the mail app:
+   Quit the mail app:
 
-    ```sh
-    q
-    ```
+   ```sh
+   q
+   ```
 
 1. Log out of the `incoming` account and go back to being `root`:
 
-    ```sh
-    logout
-    ```
+   ```sh
+   logout
+   ```
 
 ## Configure Postfix to use Maildir-style mailboxes
 
@@ -124,208 +124,212 @@ Courier, which we will install later to add IMAP authentication, requires mailbo
 
 1. Configure Postfix to use Maildir-style mailboxes:
 
-    ```sh
-    sudo postconf -e "home_mailbox = Maildir/"
-    ```
+   ```sh
+   sudo postconf -e "home_mailbox = Maildir/"
+   ```
 
 1. Restart Postfix:
 
-    ```sh
-    sudo /etc/init.d/postfix restart
-    ```
+   ```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:
+   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
-        ```
+      ```sh
+      su - incoming
+      MAIL=/home/incoming/Maildir
+      mail
+      ```
 
-        You should see output like this:
+      You should see output like this:
 
-        ```
-        "/home/incoming/Maildir": 1 message 1 unread
-        >U   1 root@localhost                           59/2842  Re: Some issue
-        ```
+      ```
+      "/home/incoming/Maildir": 1 message 1 unread
+      >U   1 root@localhost                           59/2842  Re: Some issue
+      ```
 
-        Quit the mail app:
+      Quit the mail app:
 
-        ```sh
-        q
-        ```
+      ```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._
+   _**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
-    ```
+   ```sh
+   logout
+   ```
 
 ## Install the Courier IMAP server
 
 1. Install the `courier-imap` package:
 
-    ```sh
-    sudo apt-get install courier-imap
-    ```
+   ```sh
+   sudo apt-get install courier-imap
+   ```
 
-    And start `imapd`:
-    ```sh
-    imapd start
-    ```
+   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
-    ```
-    You can also configure courier-authdaemon to start on boot:
-    ```sh
-    sudo systemctl enable courier-authdaemon
-    ```
+
+   ```sh
+   sudo service courier-authdaemon start
+   ```
+
+   You can also configure courier-authdaemon to start on boot:
+
+   ```sh
+   sudo systemctl enable courier-authdaemon
+   ```
 
 ## 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"
-    ```
+   ```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.
+   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"
-    ```
+   ```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"
-    ```
+   ```sh
+   sudo postconf -e "inet_interfaces = all"
+   ```
 
 1. Configure Postfix to use the `+` delimiter for sub-addressing:
 
-    ```sh
-    sudo postconf -e "recipient_delimiter = +"
-    ```
+   ```sh
+   sudo postconf -e "recipient_delimiter = +"
+   ```
 
 1. Restart Postfix:
 
-    ```sh
-    sudo service postfix restart
-    ```
+   ```sh
+   sudo service postfix restart
+   ```
 
 ## Test the final setup
 
 1. Test SMTP under the new setup:
 
-    1. Connect to the SMTP server:
+   1. Connect to the SMTP server:
 
-        ```sh
-        telnet gitlab.example.com 25
-        ```
+      ```sh
+      telnet gitlab.example.com 25
+      ```
 
-        You should see a prompt like this:
+      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)
-        ```
+      ```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 set up to allow inbound traffic on port 25.
+      If you get a `Connection refused` error instead, make sure your firewall is set up 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:
+   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
+      ```
+      ehlo gitlab.example.com
+      mail from: root@gitlab.example.com
+      rcpt to: incoming@gitlab.example.com
+      data
+      Subject: Re: Some issue
 
-        Sounds good!
-        .
-        quit
-        ```
+      Sounds good!
+      .
+      quit
+      ```
 
-        (Note: The `.` is a literal period on its own line)
+      (Note: The `.` is a literal period on its own line)
 
-    1. Check if the `incoming` user received the email:
+   1. Check if the `incoming` user received the email:
 
-        ```sh
-        su - incoming
-        MAIL=/home/incoming/Maildir
-        mail
-        ```
+      ```sh
+      su - incoming
+      MAIL=/home/incoming/Maildir
+      mail
+      ```
 
-        You should see output like this:
+      You should see output like this:
 
-        ```
-        "/home/incoming/Maildir": 1 message 1 unread
-        >U   1 root@gitlab.example.com                           59/2842  Re: Some issue
-        ```
+      ```
+      "/home/incoming/Maildir": 1 message 1 unread
+      >U   1 root@gitlab.example.com                           59/2842  Re: Some issue
+      ```
 
-        Quit the mail app:
+      Quit the mail app:
 
-        ```sh
-        q
-        ```
+      ```sh
+      q
+      ```
 
-    1. Log out of the `incoming` account and go back to being `root`:
+   1. Log out of the `incoming` account and go back to being `root`:
 
-        ```sh
-        logout
-        ```
+      ```sh
+      logout
+      ```
 
 1. Test IMAP under the new setup:
 
-    1. Connect to the IMAP server:
+   1. Connect to the IMAP server:
 
-        ```sh
-        telnet gitlab.example.com 143
-        ```
+      ```sh
+      telnet gitlab.example.com 143
+      ```
 
-        You should see a prompt like this:
+      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.
-        ```
+      ```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:
+   1. Sign in as the `incoming` user to test IMAP, by entering the following into the IMAP prompt:
 
-        ```
-        a login incoming PASSWORD
-        ```
+      ```
+      a login incoming PASSWORD
+      ```
 
-        Replace PASSWORD with the password you set on the `incoming` user earlier.
+      Replace PASSWORD with the password you set on the `incoming` user earlier.
 
-        You should see output like this:
+      You should see output like this:
 
-        ```
-        a OK LOGIN Ok.
-        ```
+      ```
+      a OK LOGIN Ok.
+      ```
 
-    1. Disconnect from the IMAP server:
+   1. Disconnect from the IMAP server:
 
-        ```sh
-        a logout
-        ```
+      ```sh
+      a logout
+      ```
 
 ## Done!
 
diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md
index 7cf8f20a9dc..05a7cb006a3 100644
--- a/doc/administration/repository_checks.md
+++ b/doc/administration/repository_checks.md
@@ -33,8 +33,8 @@ in `repocheck.log`:
 
 - in the [admin panel](logs.md#repochecklog)
 - or on disk, see:
-    - `/var/log/gitlab/gitlab-rails` for Omnibus installations
-    - `/home/git/gitlab/log` for installations from source
+  - `/var/log/gitlab/gitlab-rails` for Omnibus installations
+  - `/home/git/gitlab/log` for installations from source
 
 If for some reason the periodic repository check caused a lot of false
 alarms you can choose to clear *all* repository check states by
diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md
index 4aafc06cfdc..b1a870210a8 100644
--- a/doc/administration/repository_storage_paths.md
+++ b/doc/administration/repository_storage_paths.md
@@ -55,31 +55,29 @@ storage2:
 > don't specify the full repository path but the parent path), but not for source
 > installations.
 
----
-
 Now that you've read that big fat warning above, let's edit the configuration
 files and add the full paths of the alternative repository storage paths. In
-the example below, we add two more mountpoints that are named `nfs` and `cephfs`
+the example below, we add two more mountpoints that are named `nfs_1` and `nfs_2`
 respectively.
 
-NOTE: **Note:** This example uses NFS and CephFS. We do not recommend using EFS for storage as it may impact GitLab's performance. See the [relevant documentation](high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs) for more details.
+NOTE: **Note:** This example uses NFS. We do not recommend using EFS for storage as it may impact GitLab's performance. See the [relevant documentation](high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs) for more details.
 
 **For installations from source**
 
 1. Edit `gitlab.yml` and add the storage paths:
 
-    ```yaml
-    repositories:
-      # Paths where repositories can be stored. Give the canonicalized absolute pathname.
-      # NOTE: REPOS PATHS MUST NOT CONTAIN ANY SYMLINK!!!
-      storages: # You must have at least a 'default' storage path.
-        default:
-          path: /home/git/repositories
-        nfs:
-          path: /mnt/nfs/repositories
-        cephfs:
-          path: /mnt/cephfs/repositories
-    ```
+   ```yaml
+   repositories:
+     # Paths where repositories can be stored. Give the canonicalized absolute pathname.
+     # NOTE: REPOS PATHS MUST NOT CONTAIN ANY SYMLINK!!!
+     storages: # You must have at least a 'default' storage path.
+       default:
+         path: /home/git/repositories
+       nfs_1:
+         path: /mnt/nfs1/repositories
+       nfs_2:
+         path: /mnt/nfs2/repositories
+   ```
 
 1. [Restart GitLab][restart-gitlab] for the changes to take effect.
 
@@ -90,23 +88,21 @@ are upgrading from a version prior to 8.10, make sure to add the configuration
 as described in the step above. After you make the changes and confirm they are
 working, you can remove the `repos_path` line.
 
----
-
 **For Omnibus installations**
 
 1. Edit `/etc/gitlab/gitlab.rb` by appending the rest of the paths to the
    default one:
 
-    ```ruby
-    git_data_dirs({
-      "default" => { "path" => "/var/opt/gitlab/git-data" },
-      "nfs" => { "path" => "/mnt/nfs/git-data" },
-      "cephfs" => { "path" => "/mnt/cephfs/git-data" }
-    })
-    ```
+   ```ruby
+   git_data_dirs({
+     "default" => { "path" => "/var/opt/gitlab/git-data" },
+     "nfs_1" => { "path" => "/mnt/nfs1/git-data" },
+     "nfs_2" => { "path" => "/mnt/nfs2/git-data" }
+   })
+   ```
 
-    Note that Omnibus stores the repositories in a `repositories` subdirectory
-    of the `git-data` directory.
+   Note that Omnibus stores the repositories in a `repositories` subdirectory
+   of the `git-data` directory.
 
 ## Choose where new project repositories will be stored
 
diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md
index 38842693d73..1669f8b128c 100644
--- a/doc/administration/repository_storage_types.md
+++ b/doc/administration/repository_storage_types.md
@@ -6,19 +6,19 @@ Two different storage layouts can be used
 to store the repositories on disk and their characteristics.
 
 GitLab can be configured to use one or multiple repository shard locations
-that can be: 
+that can be:
 
 - Mounted to the local disk
 - Exposed as an NFS shared volume
 - Acessed via [gitaly] on its own machine.
 
 In GitLab, this is configured in `/etc/gitlab/gitlab.rb` by the `git_data_dirs({})`
-configuration hash. The storage layouts discussed here will apply to any shard 
+configuration hash. The storage layouts discussed here will apply to any shard
 defined in it.
 
 The `default` repository shard that is available in any installations
 that haven't customized it, points to the local folder: `/var/opt/gitlab/git-data`.
-Anything discussed below is expected to be part of that folder. 
+Anything discussed below is expected to be part of that folder.
 
 ## Legacy Storage
 
@@ -47,18 +47,12 @@ Any change in the URL will need to be reflected on disk (when groups / users or
 projects are renamed). This can add a lot of load in big installations,
 especially if using any type of network based filesystem.
 
-CAUTION: **Caution:**
-For Geo in particular: Geo does work with legacy storage, but in some
-edge cases due to race conditions it can lead to errors when a project is
-renamed multiple times in short succession, or a project is deleted and
-recreated under the same name very quickly. We expect these race events to be
-rare, and we have not observed a race condition side-effect happening yet.
-This pattern also exists in other objects stored in GitLab, like issue
-Attachments, GitLab Pages artifacts, Docker Containers for the integrated
-Registry, etc. Hashed storage is a requirement for Geo. 
-
 ## Hashed Storage
 
+CAUTION: **Important:**
+Geo requires Hashed Storage since 12.0. If you haven't migrated yet,
+check the [migration instructions](#how-to-migrate-to-hashed-storage) ASAP.
+
 Hashed Storage is the new storage behavior we rolled out with 10.0. Instead
 of coupling project URL and the folder structure where the repository will be
 stored on disk, we are coupling a hash, based on the project's ID. This makes
@@ -86,25 +80,20 @@ by another folder with the next 2 characters. They are both stored in a special
 
 ### Hashed object pools
 
-CAUTION: **Beta:**
-Hashed objects pools are considered beta, and are not ready for production use.
-Follow [gitaly#1548](https://gitlab.com/gitlab-org/gitaly/issues/1548) for
-updates.
+> [Introduced](https://gitlab.com/gitlab-org/gitaly/issues/1606) in GitLab 12.1.
 
-For deduplication of public forks and their parent repository, objects are pooled
-in an object pool. These object pools are a third repository where shared objects
-are stored.
+Forks of public projects are deduplicated by creating a third repository, the object pool, containing the objects from the source project. Using `objects/info/alternates`, the source project and forks use the object pool for shared objects. Objects are moved from the source project to the object pool when housekeeping is run on the source project.
 
 ```ruby
 # object pool paths
 "@pools/#{hash[0..1]}/#{hash[2..3]}/#{hash}.git"
 ```
 
-The object pool feature is behind the `object_pools` feature flag, and can be
-enabled for individual projects by executing
-`Feature.enable(:object_pools, Project.find(<id>))`. Note that the project has to
-be on hashed storage, should not be a fork itself, and hashed storage should be
-enabled for all new projects.
+Object pools can be disabled using the `object_pools` feature flag, and can be
+disabled for individual projects by executing
+`Feature.disable(:object_pools, Project.find(<id>))`. Disabling object pools
+will not change existing deduplicated forks, but will prevent new forks from
+being deduplicated.
 
 DANGER: **Danger:**
 Do not run `git prune` or `git gc` in pool repositories! This can
@@ -114,9 +103,9 @@ question.
 ### How to migrate to Hashed Storage
 
 To start a migration, enable Hashed Storage for new projects:
- 
+
 1. Go to **Admin > Settings > Repository** and expand the **Repository Storage** section.
-2. Select the **Use hashed storage paths for newly created and renamed projects** checkbox.
+1. Select the **Use hashed storage paths for newly created and renamed projects** checkbox.
 
 Check if the change breaks any existing integration you may have that
 either runs on the same machine as your repositories are located, or may login to that machine
@@ -135,7 +124,7 @@ an Omnibus Gitlab installation:
 sudo gitlab-rake gitlab:storage:migrate_to_hashed ID_FROM=50 ID_TO=100
 ```
 
-Check the [documentation][rake/migrate-to-hashed] for additional information and instructions for 
+Check the [documentation][rake/migrate-to-hashed] for additional information and instructions for
 source-based installation.
 
 #### Rollback
@@ -144,14 +133,14 @@ Similar to the migration, to disable Hashed Storage for new
 projects:
 
 1. Go to **Admin > Settings > Repository** and expand the **Repository Storage** section.
-2. Uncheck the **Use hashed storage paths for newly created and renamed projects** checkbox.
+1. Uncheck the **Use hashed storage paths for newly created and renamed projects** checkbox.
 
-To schedule a complete rollback, see the 
+To schedule a complete rollback, see the
 [rake task documentation for storage rollback](raketasks/storage.md#rollback-from-hashed-storage-to-legacy-storage) for instructions.
 
 The rollback task also supports specifying a range of Project IDs. Here is an example
 of limiting the rollout to Project IDs 50 to 100, in an Omnibus Gitlab installation:
- 
+
 ```bash
 sudo gitlab-rake gitlab:storage:rollback_to_legacy ID_FROM=50 ID_TO=100
 ```
diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md
index cbc3fbd9473..e23f2052d04 100644
--- a/doc/administration/restart_gitlab.md
+++ b/doc/administration/restart_gitlab.md
@@ -137,9 +137,9 @@ If you are using other init systems, like systemd, you can check the
 [GitLab Recipes][gl-recipes] repository for some unofficial services. These are
 **not** officially supported so use them at your own risk.
 
-[omnibus-dl]: https://about.gitlab.com/downloads/ "Download the Omnibus packages"
+[omnibus-dl]: https://about.gitlab.com/install/ "Download the Omnibus packages"
 [install]: ../install/installation.md "Documentation to install GitLab from source"
 [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"
+[chef]: https://www.chef.io/products/chef-infra/ "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/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md
index 8f7280d5128..604dff5983d 100644
--- a/doc/administration/troubleshooting/debug.md
+++ b/doc/administration/troubleshooting/debug.md
@@ -10,43 +10,43 @@ an SMTP server, but you're not seeing mail delivered. Here's how to check the se
 
 1. Run a Rails console:
 
-    ```sh
-    sudo gitlab-rails console production
-    ```
+   ```sh
+   sudo gitlab-rails console production
+   ```
 
-    or for source installs:
+   or for source installs:
 
-    ```sh
-    bundle exec rails console production
-    ```
+   ```sh
+   bundle exec rails console production
+   ```
 
 1. Look at the ActionMailer `delivery_method` to make sure it matches what you
    intended. If you configured SMTP, it should say `:smtp`. If you're using
    Sendmail, it should say `:sendmail`:
 
-    ```ruby
-    irb(main):001:0> ActionMailer::Base.delivery_method
-    => :smtp
-    ```
+   ```ruby
+   irb(main):001:0> ActionMailer::Base.delivery_method
+   => :smtp
+   ```
 
 1. If you're using SMTP, check the mail settings:
 
-    ```ruby
-    irb(main):002:0> ActionMailer::Base.smtp_settings
-    => {:address=>"localhost", :port=>25, :domain=>"localhost.localdomain", :user_name=>nil, :password=>nil, :authentication=>nil, :enable_starttls_auto=>true}```
-    ```
+   ```ruby
+   irb(main):002:0> ActionMailer::Base.smtp_settings
+   => {:address=>"localhost", :port=>25, :domain=>"localhost.localdomain", :user_name=>nil, :password=>nil, :authentication=>nil, :enable_starttls_auto=>true}```
+   ```
 
-    In the example above, the SMTP server is configured for the local machine. If this is intended, you may need to check your local mail
-    logs (e.g. `/var/log/mail.log`) for more details.
+   In the example above, the SMTP server is configured for the local machine. If this is intended, you may need to check your local mail
+   logs (e.g. `/var/log/mail.log`) for more details.
 
-1.  Send a test message via the console.
+1. Send a test message via the console.
 
-    ```ruby
-    irb(main):003:0> Notify.test_email('youremail@email.com', 'Hello World', 'This is a test message').deliver_now
-    ```
+   ```ruby
+   irb(main):003:0> Notify.test_email('youremail@email.com', 'Hello World', 'This is a test message').deliver_now
+   ```
 
-    If you do not receive an e-mail and/or see an error message, then check
-    your mail server settings.
+   If you do not receive an e-mail and/or see an error message, then check
+   your mail server settings.
 
 ## Advanced Issues
 
@@ -103,37 +103,37 @@ downtime. Otherwise skip to the next section.
 1. Run `sudo gdb -p <PID>` to attach to the unicorn process.
 1. In the gdb window, type:
 
-    ```
-    call (void) rb_backtrace()
-    ```
+   ```
+   call (void) rb_backtrace()
+   ```
 
 1. This forces the process to generate a Ruby backtrace. Check
    `/var/log/gitlab/unicorn/unicorn_stderr.log` for the backtace. For example, you may see:
 
-    ```ruby
-    from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:33:in `block in start'
-    from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:33:in `loop'
-    from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:36:in `block (2 levels) in start'
-    from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:44:in `sample'
-    from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:68:in `sample_objects'
-    from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:68:in `each_with_object'
-    from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:68:in `each'
-    from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:69:in `block in sample_objects'
-    from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:69:in `name'
-    ```
+   ```ruby
+   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:33:in `block in start'
+   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:33:in `loop'
+   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:36:in `block (2 levels) in start'
+   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:44:in `sample'
+   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:68:in `sample_objects'
+   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:68:in `each_with_object'
+   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:68:in `each'
+   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:69:in `block in sample_objects'
+   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:69:in `name'
+   ```
 
 1. To see the current threads, run:
 
-    ```
-    thread apply all bt
-    ```
+   ```
+   thread apply all bt
+   ```
 
 1. Once you're done debugging with `gdb`, be sure to detach from the process and exit:
 
-    ```
-    detach
-    exit
-    ```
+   ```
+   detach
+   exit
+   ```
 
 Note that if the unicorn process terminates before you are able to run these
 commands, gdb will report an error. To buy more time, you can always raise the
@@ -162,21 +162,21 @@ separate Rails process to debug the issue:
 1. Create a Personal Access Token for your user (Profile Settings -> Access Tokens).
 1. Bring up the GitLab Rails console. For omnibus users, run:
 
-    ```
-    sudo gitlab-rails console
-    ```
+   ```
+   sudo gitlab-rails console
+   ```
 
 1. At the Rails console, run:
 
-    ```ruby
-    [1] pry(main)> app.get '<URL FROM STEP 2>/?private_token=<TOKEN FROM STEP 3>'
-    ```
+   ```ruby
+   [1] pry(main)> app.get '<URL FROM STEP 2>/?private_token=<TOKEN FROM STEP 3>'
+   ```
 
-    For example:
+   For example:
 
-    ```ruby
-    [1] pry(main)> app.get 'https://gitlab.com/gitlab-org/gitlab-ce/issues/1?private_token=123456'
-    ```
+   ```ruby
+   [1] pry(main)> app.get 'https://gitlab.com/gitlab-org/gitlab-ce/issues/1?private_token=123456'
+   ```
 
 1. In a new window, run `top`. It should show this ruby process using 100% CPU. Write down the PID.
 1. Follow step 2 from the previous section on using gdb.
@@ -209,7 +209,7 @@ ps auwx | grep unicorn | awk '{ print " -p " $2}' | xargs strace -tt -T -f -s 10
 
 The output in `/tmp/unicorn.txt` may help diagnose the root cause.
 
-# More information
+## More information
 
 - [Debugging Stuck Ruby Processes](https://blog.newrelic.com/2013/04/29/debugging-stuck-ruby-processes-what-to-do-before-you-kill-9/)
 - [Cheatsheet of using gdb and ruby processes](gdb-stuck-ruby.txt)
diff --git a/doc/administration/troubleshooting/diagnostics_tools.md b/doc/administration/troubleshooting/diagnostics_tools.md
new file mode 100644
index 00000000000..ab3b25f0e97
--- /dev/null
+++ b/doc/administration/troubleshooting/diagnostics_tools.md
@@ -0,0 +1,27 @@
+---
+type: reference
+---
+
+# Diagnostics tools
+
+These are some of the diagnostics tools the GitLab Support team uses during troubleshooting.
+They are listed here for transparency, and they may be useful for users with experience
+with troubleshooting GitLab. If you are currently having an issue with GitLab, you
+may want to check your [support options](https://about.gitlab.com/support/) first,
+before attempting to use these tools.
+
+## gitlabsos
+
+The [gitlabsos](https://gitlab.com/gitlab-com/support/toolbox/gitlabsos/) utility
+provides a unified method of gathering info and logs from GitLab and the system it's
+running on.
+
+## strace-parser
+
+[strace-parser](https://gitlab.com/wchandler/strace-parser) is a small tool to analyze
+and summarize raw strace data.
+
+## Pritaly
+
+[Pritaly](https://gitlab.com/wchandler/pritaly) takes Gitaly logs and colorizes output
+or converts the logs to JSON.
diff --git a/doc/administration/troubleshooting/elasticsearch.md b/doc/administration/troubleshooting/elasticsearch.md
new file mode 100644
index 00000000000..c4a7ba01fae
--- /dev/null
+++ b/doc/administration/troubleshooting/elasticsearch.md
@@ -0,0 +1,345 @@
+# Troubleshooting ElasticSearch
+
+Troubleshooting ElasticSearch requires:
+
+- Knowledge of common terms.
+- Establishing within which category the problem fits.
+
+## Common terminology
+
+- **Lucene**: A full-text search library written in Java.
+- **Near Realtime (NRT)**: Refers to the slight latency from the time to index a
+  document to the time when it becomes searchable.
+- **Cluster**: A collection of one or more nodes that work together to hold all
+  the data, providing indexing and search capabilities.
+- **Node**: A single server that works as part of a cluster.
+- **Index**: A collection of documents that have somewhat similar characteristics.
+- **Document**: A basic unit of information that can be indexed.
+- **Shards**: Fully-functional and independent subdivisions of indices. Each shard is actually
+  a Lucene index.
+- **Replicas**: Failover mechanisms that duplicate indices.
+
+## Troubleshooting workflows
+
+The type of problem will determine what steps to take. The possible troubleshooting workflows are for:
+
+- Search results.
+- Indexing.
+- Integration.
+- Performance.
+
+### Search Results workflow
+
+The following workflow is for ElasticSearch search results issues:
+
+```mermaid
+graph TD;
+  B --> |No| B1
+  B --> |Yes| B4
+  B1 --> B2
+  B2 --> B3
+  B4 --> B5
+  B5 --> |Yes| B6
+  B5 --> |No| B7
+  B7 --> B8
+  B{Is GitLab using<br>ElasticSearch for<br>searching?}
+  B1[Check Admin Area > Integrations<br>to ensure the settings are correct]
+  B2[Perform a search via<br>the rails console]
+  B3[If all settings are correct<br>and it still doesn't show ElasticSearch<br>doing the searches, escalate<br>to GitLab support.]
+  B4[Perform<br>the same search via the<br>ElasticSearch API]
+  B5{Are the results<br>the same?}
+  B6[This means it is working as intended.<br>Speak with GitLab support<br>to confirm if the issue lies with<br>the filters.]
+  B7[Check the index status of the project<br>containing the missing search<br>results.]
+  B8(Indexing Troubleshooting)
+```
+
+### Indexing workflow
+
+The following workflow is for ElasticSearch indexing issues:
+
+```mermaid
+graph TD;
+  C --> |Yes| C1
+  C1 --> |Yes| C2
+  C1 --> |No| C3
+  C3 --> |Yes| C4
+  C3 --> |No| C5
+  C --> |No| C6
+  C6 --> |No| C10
+  C7 --> |GitLab| C8
+  C7 --> |ElasticSearch| C9
+  C6 --> |Yes| C7
+  C10 --> |No| C12
+  C10 --> |Yes| C11
+  C12 --> |Yes| C13
+  C12 --> |No| C14
+  C14 --> |Yes| C15
+  C14 --> |No| C16
+  C{Is the problem with<br>creating an empty<br>index?}
+  C1{Does the gitlab-production<br>index exist on the<br>ElasticSearch instance?}
+  C2(Try to manually<br>delete the index on the<br>ElasticSearch instance and<br>retry creating an empty index.)
+  C3{Can indices be made<br>manually on the ElasticSearch<br>instance?}
+  C4(Retry the creation of an empty index)
+  C5(It is best to speak with an<br>ElasticSearch admin concerning the<br>instance's inability to create indices.)
+  C6{Is the indexer presenting<br>errors during indexing?}
+  C7{Is the error a GitLab<br>error or an ElasticSearch<br>error?}
+  C8[Escalate to<br>GitLab support]
+  C9[You will want<br>to speak with an<br>ElasticSearch admin.]
+  C10{Does the index status<br>show 100%?}
+  C11[Escalate to<br>GitLab support]
+  C12{Does re-indexing the project<br> present any GitLab errors?}
+  C13[Rectify the GitLab errors and<br>restart troubleshooting, or<br>escalate to GitLab support.]
+  C14{Does re-indexing the project<br>present errors on the <br>ElasticSearch instance?}
+  C15[It would be best<br>to speak with an<br>ElasticSearch admin.]
+  C16[This is likely a bug/issue<br>in GitLab and will require<br>deeper investigation. Escalate<br>to GitLab support.]
+```
+
+### Integration workflow
+
+The following workflow is for ElasticSearch integration issues:
+
+```mermaid
+graph TD;
+  D --> |No| D1
+  D --> |Yes| D2
+  D2 --> |No| D3
+  D2 --> |Yes| D4
+  D4 --> |No| D5
+  D4 --> |Yes| D6
+  D{Is the error concerning<br>the beta indexer?}
+  D1[It would be best<br>to speak with an<br>ElasticSearch admin.]
+  D2{Is the ICU development<br>package installed?}
+  D3>This package is required.<br>Install the package<br>and retry.]
+  D4{Is the error stemming<br>from the indexer?}
+  D5[This would indicate an OS level<br> issue. It would be best to<br>contact your sysadmin.]
+  D6[This is likely a bug/issue<br>in GitLab and will require<br>deeper investigation. Escalate<br>to GitLab support.]
+```
+
+### Performance workflow
+
+The following workflow is for ElasticSearch performance issues:
+
+```mermaid
+graph TD;
+  F --> |Yes| F1
+  F --> |No| F2
+  F2 --> |No| F3
+  F2 --> |Yes| F4
+  F4 --> F5
+  F5 --> |No| F6
+  F5 --> |Yes| F7
+  F{Is the ElasticSearch instance<br>running on the same server<br>as the GitLab instance?}
+  F1(This is not advised and will cause issues.<br>We recommend moving the ElasticSearch<br>instance to a different server.)
+  F2{Does the ElasticSearch<br>server have at least 8<br>GB of RAM and 2 CPU<br>cores?}
+  F3(According to ElasticSearch, a non-prod<br>server needs these as a base requirement.<br>Production often requires more. We recommend<br>you increase the server specifications.)
+  F4(Obtain the <br>cluster health information)
+  F5(Does it show the<br>status as green?)
+  F6(We recommend you speak with<br>an ElasticSearch admin<br>about implementing sharding.)
+  F7(Escalate to<br>GitLab support.)
+```
+
+## Troubleshooting walkthrough
+
+Most ElasticSearch troubleshooting can be broken down into 4 categories:
+
+- [Troubleshooting search results](#troubleshooting-search-results)
+- [Troubleshooting indexing](#troubleshooting-indexing)
+- [Troubleshooting integration](#troubleshooting-integration)
+- [Troubleshooting performance](#troubleshooting-performance)
+
+Generally speaking, if it does not fall into those four categories, it is either:
+
+- Something GitLab support needs to look into.
+- Not a true ElasticSearch issue.
+
+Exercise caution. Issues that appear to be ElasticSearch problems can be OS-level issues.
+
+### Troubleshooting search results
+
+Troubleshooting search result issues is rather straight forward on ElasticSearch.
+
+The first step is to confirm GitLab is using ElasticSearch for the search function.
+To do this:
+
+1. Confirm the integration is enabled in **Admin Area > Settings > Integrations**.
+1. Confirm searches utilize ElasticSearch by accessing the rails console
+   (`sudo gitlab-rails console`) and running the following commands:
+
+   ```rails
+   u = User.find_by_email('email_of_user_doing_search')
+   s = SearchService.new(u, {:search => 'search_term'})
+   pp s.search_objects.class.name
+   ```
+
+The ouput from the last command is the key here. If it shows:
+
+- `ActiveRecord::Relation`, **it is not** using ElasticSearch.
+- `Kaminari::PaginatableArray`, **it is** using ElasticSearch.
+
+| Not using ElasticSearch  | Using ElasticSearch          |
+|--------------------------|------------------------------|
+| `ActiveRecord::Relation` | `Kaminari::PaginatableArray` |
+
+If all the settings look correct and it is still not using ElasticSearch for the search function, it is best to escalate to GitLab support. This could be a bug/issue.
+
+Moving past that, it is best to attempt the same search using the [ElasticSearch Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html) and compare the results from what you see in GitLab.
+
+If the results:
+
+- Sync up, then there is not a technical "issue" per se. Instead, it might be a problem
+  with the ElasticSearch filters we are using. This can be complicated, so it is best to
+  escalate to GitLab support to check these and guide you on the potential on whether or
+  not a feature request is needed.
+- Do not match up, this indicates a problem with the documents generated from the
+  project. It is best to re-index that project and proceed with
+  [Troubleshooting indexing](#troubleshooting-indexing).
+
+### Troubleshooting indexing
+
+Troubleshooting indexing issues can be tricky. It can pretty quickly go to either GitLab
+support or your ElasticSearch admin.
+
+The best place to start is to determine if the issue is with creating an empty index.
+If it is, check on the ElasticSearch side to determine if the `gitlab-production` (the
+name for the GitLab index) exists. If it exists, manually delete it on the ElasticSearch
+side and attempt to recreate it from the
+[`create_empty_index`](../../integration/elasticsearch.md#gitlab-elasticsearch-rake-tasks)
+rake task.
+
+If you still encounter issues, try creating an index manually on the ElasticSearch
+instance. The details of the index aren't important here, as we want to test if indices
+can be made. If the indices:
+
+- Cannot be made, speak with your ElasticSearch admin.
+- Can be made, Escalate this to GitLab support.
+
+If the issue is not with creating an empty index, the next step is to check for errors
+during the indexing of projects. If errors do occur, they will either stem from the indexing:
+
+- On the GitLab side. You need to rectify those. If they are not
+  something you are familiar with, contact GitLab support for guidance.
+- Within the ElasticSearch instance itself. See if the error is [documented and has a fix](../../integration/elasticsearch.md#troubleshooting). If not, speak with your ElasticSearch admin.
+
+If the indexing process does not present errors, you will want to check the status of the indexed projects. You can do this via the following rake tasks:
+
+- [`sudo gitlab-rake gitlab:elastic:index_projects_status`](../../integration/elasticsearch.md#gitlab-elasticsearch-rake-tasks) (shows the overall status)
+- [`sudo gitlab-rake gitlab:elastic:projects_not_indexed`](../../integration/elasticsearch.md#gitlab-elasticsearch-rake-tasks) (shows specific projects that are not indexed)
+
+If:
+
+- Everything is showing at 100%, escalate to GitLab support. This could be a potential
+  bug/issue.
+- You do see something not at 100%, attempt to reindex that project. To do this,
+  run `sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=<project ID> ID_TO=<project ID>`.
+
+If reindexing the project shows:
+
+- Errors on the GitLab side, escalate those to GitLab support.
+- ElasticSearch errors or doesn't present any errors at all, reach out to your
+  ElasticSearch admin to check the instance.
+
+### Troubleshooting integration
+
+Troubleshooting integration tends to be pretty straight forward, as there really isn't
+much to "integrate" here.
+
+If the issue is:
+
+- Not concerning the beta indexer, it is almost always an
+  ElasticSearch-side issue. This means you should reach out to your ElasticSearch admin
+  regarding the error(s) you are seeing. If you are unsure here, it never hurts to reach
+  out to GitLab support.
+- With the beta indexer, check if the ICU development package is installed.
+  This is a required package so make sure you install it.
+
+Beyond that, you will want to review the error. If it is:
+
+- Specifically from the indexer, this could be a bug/issue and should be escalated to
+  GitLab support.
+- An OS issue, you will want to reach out to your systems administrator.
+
+### Troubleshooting performance
+
+Troubleshooting performance can be difficult on ElasticSearch. There is a ton of tuning
+that *can* be done, but the majority of this falls on shoulders of a skilled
+ElasticSearch administrator.
+
+Generally speaking, ensure:
+
+* The ElasticSearch server **is not** running on the same node as GitLab.
+* The ElasticSearch server have enough RAM and CPU cores.
+* That sharding **is** being used.
+
+Going into some more detail here, if ElasticSearch is running on the same server as GitLab, resource contention is **very** likely to occur. Ideally, ElasticSearch, which requires ample resources, should be running on its own server (maybe coupled with logstash and kibana).
+
+When it comes to ElasticSearch, RAM is the key resource. ElasticSearch themselves recommend:
+
+- **At least** 8 GB of RAM for a non-production instance.
+- **At least** 16 GB of RAM for a production instance.
+- Ideally, 64 GB of RAM.
+
+For CPU, ElasticSearch recommends at least 2 CPU cores, but ElasticSearch states common
+setups use up to 8 cores. For more details on server specs, check out
+[ElasticSearch's hardware guide](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html).
+
+Beyond the obvious, sharding comes into play. Sharding is a core part of ElasticSearch.
+It allows for horizontal scaling of indices, which is helpful when you are dealing with
+a large amount of data.
+
+With the way GitLab does indexing, there is a **huge** amount of documents being
+indexed. By utilizing sharding, you can speed up ElasticSearch's ability to locate
+data, since each shard is a Lucene index.
+
+If you are not using sharding, you are likely to hit issues when you start using
+ElasticSearch in a production environment.
+
+Keep in mind that an index with only one shard has **no scale factor** and will
+likely encounter issues when called upon with some frequency.
+
+If you need to know how many shards, read
+[ElasticSearch's documentation on capacity planning](https://www.elastic.co/guide/en/elasticsearch/guide/2.x/capacity-planning.html),
+as the answer is not straight forward.
+
+The easiest way to determine if sharding is in use is to check the output of the
+[ElasticSearch Health API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-health.html):
+
+- Red means the cluster is down.
+- Yellow means it is up with no sharding/replication.
+- Green means it is healthy (up, sharding, replicating).
+
+For production use, it should always be green.
+
+Beyond these steps, you get into some of the more complicated things to check,
+such as merges and caching. These can get complicated and it takes some time to
+learn them, so it is best to escalate/pair with an ElasticSearch expert if you need to
+dig further into these.
+
+Feel free to reach out to GitLab support, but this is likely to be something a skilled
+ElasticSearch admin has more experience with.
+
+## Common issues
+
+All common issues [should be documented](../../integration/elasticsearch.md#troubleshooting). If not,
+feel free to update that page with issues you encounter and solutions.
+
+## Replication
+
+Setting up ElasticSearch isn't too bad, but it can be a bit finnicky and time consuming.
+
+The eastiest method is to spin up a docker container with the required version and
+bind ports 9200/9300 so it can be used.
+
+The following is an example of running a docker container of ElasticSearch v7.2.0:
+
+```bash
+docker pull docker.elastic.co/elasticsearch/elasticsearch:7.2.0
+docker run -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:7.2.0
+```
+
+From here, you can:
+
+- Grab the IP of the docker container (use `docker inspect <container_id>`)
+- Use `<IP.add.re.ss:9200>` to communicate with it.
+
+This is a quick method to test out ElasticSearch, but by no means is this a
+production solution.
diff --git a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md
new file mode 100644
index 00000000000..95cdb1508fa
--- /dev/null
+++ b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md
@@ -0,0 +1,251 @@
+---
+type: reference
+---
+
+# Kubernetes, GitLab and You
+
+This is a list of useful information regarding Kubernetes that the GitLab Support
+Team sometimes uses while troubleshooting. GitLab is making this public, so that anyone
+can make use of the Support team's collected knowledge
+
+CAUTION: **Caution:**
+These commands **can alter or break** your Kubernetes components so use these at your own risk.
+
+If you are on a [paid tier](https://about.gitlab.com/pricing/) and are not sure how
+to use these commands, it is best to [contact Support](https://about.gitlab.com/support/)
+and they will assist you with any issues you are having.
+
+## Generic kubernetes commands
+
+- How to authorize to your GCP project (can be especially useful if you have projects
+  under different GCP accounts):
+
+  ```bash
+  gcloud auth login
+  ```
+
+- How to access Kubernetes dashboard:
+
+  ```bash
+  # for minikube:
+  minikube dashboard —url
+  # for non-local installations if access via kubectl is configured:
+  kubectl proxy
+  ```
+
+- How to ssh to a Kubernetes node and enter the container as root
+  <https://github.com/kubernetes/kubernetes/issues/30656>:
+
+  - For GCP, you may find the node name and run `gcloud compute ssh node-name`.
+  - List containers using `docker ps`.
+  - Enter container using `docker exec --user root -ti container-id bash`.
+
+- How to copy a file from local machine to a pod:
+
+  ```bash
+  kubectl cp file-name pod-name:./destination-path
+  ```
+
+- What to do with pods in `CrashLoopBackoff` status:
+
+  - Check logs via Kubernetes dashboard.
+  - Check logs via `kubectl`:
+
+    ```bash
+    kubectl logs <unicorn pod> -c dependencies
+    ```
+
+- How to tail all Kubernetes cluster events in real time:
+
+  ```bash
+  kubectl get events -w --all-namespaces
+  ```
+
+- How to get logs of the previously terminated pod instance:
+
+  ```bash
+  kubectl logs <pod-name> --previous
+  ```
+
+  NOTE: **Note:**
+  No logs are kept in the containers/pods themselves, everything is written to stdout.
+  This is the principle of Kubernetes, read [Twelve-factor app](https://12factor.net/)
+  for details.
+
+## Gitlab-specific kubernetes information
+
+- Minimal config that can be used to test a Kubernetes helm chart can be found
+  [here](https://gitlab.com/charts/gitlab/issues/620).
+
+- Tailing logs of a separate pod. An example for a unicorn pod:
+
+  ```bash
+  kubectl logs gitlab-unicorn-7656fdd6bf-jqzfs -c unicorn
+  ```
+
+- It is not possible to get all the logs via `kubectl` at once, like with `gitlab-ctl tail`,
+  but a number of third-party tools can be used to do it:
+
+  - [Kubetail](https://github.com/johanhaleby/kubetail)
+  - [kail: kubernetes tail](https://github.com/boz/kail)
+  - [stern](https://github.com/wercker/stern)
+
+- Check all events in the `gitlab` namespace (the namespace name can be different if you
+  specified a different one when deploying the helm chart):
+
+  ```bash
+  kubectl get events -w --namespace=gitlab
+  ```
+
+- Most of the useful GitLab tools (console, rake tasks, etc) are found in the task-runner
+  pod. You may enter it and run commands inside or run them from the outside:
+
+  ```bash
+  # find the pod
+  kubectl get pods | grep task-runner
+
+  # enter it
+  kubectl exec -it <task-runner-pod-name> bash
+
+  # open rails console
+  # rails console can be also called from other GitLab pods
+  /srv/gitlab/bin/rails console
+
+  # source-style commands should also work
+  /srv/gitlab && bundle exec rake gitlab:check RAILS_ENV=production
+
+  # run GitLab check. Note that the output can be confusing and invalid because of the specific structure of GitLab installed via helm chart
+  /usr/local/bin/gitlab-rake gitlab:check
+
+  # open console without entering pod
+  kubectl exec -it <task-runner-pod-name> /srv/gitlab/bin/rails console
+
+  # check the status of DB migrations
+  kubectl exec -it <task-runner-pod-name> /usr/local/bin/gitlab-rake db:migrate:status
+  ```
+
+  You can also use `gitlab-rake`, instead of `/usr/local/bin/gitlab-rake`.
+
+- Troubleshooting **Operations > Kubernetes** integration:
+
+  - Check the output of `kubectl get events -w --all-namespaces`.
+  - Check the logs of pods within `gitlab-managed-apps` namespace.
+  - On the side of GitLab check sidekiq log and kubernetes log. When GitLab is installed
+    via helm chart, kubernetes.log can be found inside the sidekiq pod.
+
+- How to get your initial admin password <https://docs.gitlab.com/charts/installation/deployment.html#initial-login>:
+
+  ```bash
+  # find the name of the secret containing the password
+  kubectl get secrets | grep initial-root
+  # decode it
+  kubectl get secret <secret-name> -ojsonpath={.data.password} | base64 --decode ; echo
+  ```
+
+- How to connect to a GitLab postgres database:
+
+  ```bash
+  kubectl exec -it <task-runner-pod-name> -- /srv/gitlab/bin/rails dbconsole -p
+  ```
+  
+- How to get info about helm installation status:
+
+  ```bash
+  helm status name-of-installation
+  ```
+
+- How to update GitLab installed using helm chart:
+
+  ```bash
+  helm repo upgrade
+
+  # get current values and redirect them to yaml file (analogue of gitlab.rb values)
+  helm get values <release name> > gitlab.yaml
+
+  # run upgrade itself
+  helm upgrade <release name> <chart path> -f gitlab.yaml
+  ```
+
+  After <https://canary.gitlab.com/charts/gitlab/issues/780> is fixed, it should
+  be possible to use [Updating GitLab using the Helm Chart](https://docs.gitlab.com/ee/install/kubernetes/gitlab_chart.html#updating-gitlab-using-the-helm-chart)
+  for upgrades.
+
+- How to apply changes to GitLab config:
+
+  - Modify the `gitlab.yaml` file.
+  - Run the following command to apply changes:
+
+    ```bash
+    helm upgrade <release name> <chart path> -f gitlab.yaml
+    ```
+
+## Installation of minimal GitLab config via minukube on macOS
+
+This section is based on [Developing for Kubernetes with Minikube](https://gitlab.com/charts/gitlab/blob/master/doc/minikube/index.md)
+and [Helm](https://gitlab.com/charts/gitlab/blob/master/doc/helm/index.md). Refer
+to those documents for details.
+
+- Install kubectl via Homebrew:
+
+  ```bash
+  brew install kubernetes-cli
+  ```
+
+- Install minikube via Homebrew:
+
+  ```bash
+  brew cask install minikube
+  ```
+
+- Start minikube and configure it. If minikube cannot start, try running `minikube delete && minikube start`
+  and repeat the steps:
+
+  ```bash
+  minikube start --cpus 3 --memory 8192 # minimum amount for GitLab to work
+  minikube addons enable ingress
+  minikube addons enable kube-dns
+  ```
+
+- Install helm via Homebrew and initialize it:
+
+  ```bash
+  brew install kubernetes-helm
+  helm init --service-account tiller
+  ```
+
+- Copy the file <https://gitlab.com/charts/gitlab/raw/master/examples/values-minikube-minimum.yaml>
+  to your workstation.
+
+- Find the IP address in the output of `minikube ip` and update the yaml file with
+  this IP address.
+
+- Install the GitLab helm chart:
+
+  ```bash
+  helm repo add gitlab https://charts.gitlab.io
+  helm install --name gitlab -f <path-to-yaml-file> gitlab/gitlab
+  ```
+
+  If you want to modify some GitLab settings, you can use the above-mentioned config
+  as a base and create your own yaml file.
+
+- Monitor the installation progress via `helm status gitlab` and `minikube dashboard`.
+  The installation could take up to 20-30 minutes depending on the amount of resources
+  on your workstation.
+
+- When all the pods show either a `Running` or `Completed` status, get the GitLab password as
+  described in [Initial login](https://docs.gitlab.com/ee/install/kubernetes/gitlab_chart.html#initial-login),
+  and log in to GitLab via the UI. It will be accessible via `https://gitlab.domain`
+  where `domain` is the value provided in the yaml file.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md
index 708b59a273b..99f1c386183 100644
--- a/doc/administration/uploads.md
+++ b/doc/administration/uploads.md
@@ -1,21 +1,18 @@
 # Uploads administration
 
->**Notes:**
 Uploads represent all user data that may be sent to GitLab as a single file. As an example, avatars and notes' attachments are uploads. Uploads are integral to GitLab functionality, and therefore cannot be disabled.
 
-### Using local storage
+## Using local storage
 
->**Notes:**
+NOTE: **Note:**
 This is the default configuration
 
 To change the location where the uploads are stored locally, follow the steps
 below.
 
----
-
 **In Omnibus installations:**
 
->**Notes:**
+NOTE: **Note:**
 For historical reasons, uploads are stored into a base directory, which by default is `uploads/-/system`. It is strongly discouraged to change this configuration option on an existing GitLab installation.
 
 _The uploads are stored by default in `/var/opt/gitlab/gitlab-rails/uploads`._
@@ -23,15 +20,13 @@ _The uploads are stored by default in `/var/opt/gitlab/gitlab-rails/uploads`._
 1. To change the storage path for example to `/mnt/storage/uploads`, edit
    `/etc/gitlab/gitlab.rb` and add the following line:
 
-    ```ruby
-    gitlab_rails['uploads_storage_path'] = "/mnt/storage/"
-	gitlab_rails['uploads_base_dir'] = "uploads"
-    ```
+   ```ruby
+   gitlab_rails['uploads_storage_path'] = "/mnt/storage/"
+   gitlab_rails['uploads_base_dir'] = "uploads"
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **In installations from source:**
 
 _The uploads are stored by default in
@@ -40,15 +35,15 @@ _The uploads are stored by default in
 1. To change the storage path for example to `/mnt/storage/uploads`, edit
    `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
 
-    ```yaml
-	uploads:
-	  storage_path: /mnt/storage
-	  base_dir: uploads
-    ```
+   ```yaml
+   uploads:
+     storage_path: /mnt/storage
+     base_dir: uploads
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
-### Using object storage **[CORE ONLY]**
+## Using object storage **(CORE ONLY)**
 
 > **Notes:**
 >
@@ -60,7 +55,7 @@ If you don't want to use the local disk where GitLab is installed to store the
 uploads, you can use an object storage provider like AWS S3 instead.
 This configuration relies on valid AWS credentials to be configured already.
 
-### Object Storage Settings
+## Object Storage Settings
 
 For source installations the following settings are nested under `uploads:` and then `object_store:`. On omnibus installs they are prefixed by `uploads_object_store_`.
 
@@ -73,7 +68,7 @@ For source installations the following settings are nested under `uploads:` and
 | `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` |
 | `connection` | Various connection options described below | |
 
-#### S3 compatible connection settings
+### S3 compatible connection settings
 
 The connection settings match those provided by [Fog](https://github.com/fog), and are as follows:
 
@@ -83,6 +78,7 @@ The connection settings match those provided by [Fog](https://github.com/fog), a
 | `aws_access_key_id` | AWS credentials, or compatible | |
 | `aws_secret_access_key` | AWS credentials, or compatible | |
 | `aws_signature_version` | AWS signature version to use. 2 or 4 are valid options. Digital Ocean Spaces and other providers may need 2. | 4 |
+| `enable_signature_v4_streaming` | Set to true to enable HTTP chunked transfers with AWS v4 signatures (https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be false | true
 | `region` | AWS region | us-east-1 |
 | `host` | S3 compatible host for when not using AWS, e.g. `localhost` or `storage.example.com` | s3.amazonaws.com |
 | `endpoint` | Can be used when configuring an S3 compatible service such as [Minio](https://www.minio.io), by entering a URL such as `http://127.0.0.1:9000` | (optional) |
@@ -97,27 +93,104 @@ _The uploads are stored by default in
 1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with
    the values you want:
 
-    ```ruby
-    gitlab_rails['uploads_object_store_enabled'] = true
-    gitlab_rails['uploads_object_store_remote_directory'] = "uploads"
-    gitlab_rails['uploads_object_store_connection'] = {
-      'provider' => 'AWS',
-      'region' => 'eu-central-1',
-      'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
-      'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
-    }
-    ```
-
-	>**Note:**
-	If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.
-
-    ```ruby
-    gitlab_rails['uploads_object_store_connection'] = {
-      'provider' => 'AWS',
-      'region' => 'eu-central-1',
-      'use_iam_profile' => true
-    }
-    ```
+   ```ruby
+   gitlab_rails['uploads_object_store_enabled'] = true
+   gitlab_rails['uploads_object_store_remote_directory'] = "uploads"
+   gitlab_rails['uploads_object_store_connection'] = {
+     'provider' => 'AWS',
+     'region' => 'eu-central-1',
+     'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
+     'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
+   }
+   ```
+
+   NOTE: **Note:**
+   If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.
+
+   ```ruby
+   gitlab_rails['uploads_object_store_connection'] = {
+     'provider' => 'AWS',
+     'region' => 'eu-central-1',
+     'use_iam_profile' => true
+   }
+   ```
+
+1. Save the file and [reconfigure GitLab][] for the changes to take effect.
+1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` rake task](raketasks/uploads/migrate.md).
+
+**In installations from source:**
+
+_The uploads are stored by default in
+`/home/git/gitlab/public/uploads/-/system`._
+
+1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
+   lines:
+
+   ```yaml
+   uploads:
+     object_store:
+       enabled: true
+       remote_directory: "uploads" # The bucket name
+       connection:
+         provider: AWS # Only AWS supported at the moment
+         aws_access_key_id: AWS_ACESS_KEY_ID
+         aws_secret_access_key: AWS_SECRET_ACCESS_KEY
+         region: eu-central-1
+   ```
+
+1. Save the file and [restart GitLab][] for the changes to take effect.
+1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` rake task](raketasks/uploads/migrate.md).
+
+### Oracle Cloud S3 connection settings
+
+Note that Oracle Cloud S3 must be sure to use the following settings:
+
+| Setting | Value |
+|---------|-------|
+| `enable_signature_v4_streaming` | false |
+| `path_style` | true |
+
+If `enable_signature_v4_streaming` is set to `true`, you may see the
+following error:
+
+```
+STREAMING-AWS4-HMAC-SHA256-PAYLOAD is not supported
+```
+
+### OpenStack compatible connection settings
+
+The connection settings match those provided by [Fog](https://github.com/fog), and are as follows:
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `provider` | Always `OpenStack` for compatible hosts | OpenStack |
+| `openstack_username` | OpenStack username | |
+| `openstack_api_key` | OpenStack api key  | |
+| `openstack_temp_url_key` | OpenStack key for generating temporary urls | |
+| `openstack_auth_url` | OpenStack authentication endpont | |
+| `openstack_region` | OpenStack region | |
+| `openstack_tenant` | OpenStack tenant ID |
+
+**In Omnibus installations:**
+
+_The uploads are stored by default in
+`/var/opt/gitlab/gitlab-rails/public/uploads/-/system`._
+
+1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with
+   the values you want:
+
+   ```ruby
+   gitlab_rails['uploads_object_store_remote_directory'] = "OPENSTACK_OBJECT_CONTAINER_NAME"
+   gitlab_rails['uploads_object_store_connection'] = {
+    'provider' => 'OpenStack',
+    'openstack_username' => 'OPENSTACK_USERNAME',
+    'openstack_api_key' => 'OPENSTACK_PASSWORD',
+    'openstack_temp_url_key' => 'OPENSTACK_TEMP_URL_KEY',
+    'openstack_auth_url' => 'https://auth.cloud.ovh.net/v2.0/',
+    'openstack_region' => 'DE1',
+    'openstack_tenant' => 'TENANT_ID',
+   }
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` rake task](raketasks/uploads/migrate.md).
@@ -132,19 +205,25 @@ _The uploads are stored by default in
 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
    lines:
 
-    ```yaml
-    uploads:
-      object_store:
-        enabled: true
-        remote_directory: "uploads" # The bucket name
-        connection:
-          provider: AWS # Only AWS supported at the moment
-          aws_access_key_id: AWS_ACESS_KEY_ID
-          aws_secret_access_key: AWS_SECRET_ACCESS_KEY
-          region: eu-central-1
-    ```
+   ```yaml
+   uploads:
+     object_store:
+       enabled: true
+       direct_upload: false
+       background_upload: true
+       proxy_download: false
+       remote_directory: OPENSTACK_OBJECT_CONTAINER_NAME
+       connection:
+         provider: OpenStack
+         openstack_username: OPENSTACK_USERNAME
+         openstack_api_key: OPENSTACK_PASSWORD
+         openstack_temp_url_key: OPENSTACK_TEMP_URL_KEY
+         openstack_auth_url: 'https://auth.cloud.ovh.net/v2.0/'
+         openstack_region: DE1
+         openstack_tenant: 'TENANT_ID' 
+   ```
 
-1. Save the file and [restart GitLab][] for the changes to take effect.
+1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` rake task](raketasks/uploads/migrate.md).
 
 [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab"
diff --git a/doc/api/README.md b/doc/api/README.md
index 3a1064b787e..9156d719e11 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -1,159 +1,25 @@
-# GitLab API
+# API Docs
 
 Automate GitLab via a simple and powerful API.
 
 The main GitLab API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. Therefore, documentation in this section assumes knowledge of REST concepts.
 
-## API resources
-
-Available API resources can be grouped in the following contexts:
-
-- [Projects](#project-resources).
-- [Groups](#group-resources).
-- [Standalone](#standalone-resources).
-
-See also:
-
-- [V3 to V4](v3_to_v4.md).
-- Adding [deploy keys for multiple projects](deploy_key_multiple_projects.md).
-
-### Project resources
-
-The following API resources are available in the project context:
-
-| Resource                                                            | Available endpoints                                                                                                                                                                                   |
-|:--------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [Access requests](access_requests.md)                               | `/projects/:id/access_requests` (also available for groups)                                                                                                                                           |
-| [Award emoji](award_emoji.md)                                       | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji`                                                                      |
-| [Branches](branches.md)                                             | `/projects/:id/repository/branches/`, `/projects/:id/repository/merged_branches`                                                                                                                      |
-| [Commits](commits.md)                                               | `/projects/:id/repository/commits`, `/projects/:id/statuses`                                                                                                                                          |
-| [Container Registry](container_registry.md)                         | `/projects/:id/registry/repositories`                                                                                                                                                                 |
-| [Custom attributes](custom_attributes.md)                           | `/projects/:id/custom_attributes` (also available for groups and users)                                                                                                                               |
-| [Deploy keys](deploy_keys.md)                                       | `/projects/:id/deploy_keys` (also available standalone)                                                                                                                                               |
-| [Deployments](deployments.md)                                       | `/projects/:id/deployments`                                                                                                                                                                           |
-| [Discussions](discussions.md) (threaded comments)                   | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` (also available for groups) |
-| [Environments](environments.md)                                     | `/projects/:id/environments`                                                                                                                                                                          |
-| [Events](events.md)                                                 | `/projects/:id/events` (also available for users and standalone)                                                                                                                                      |
-| [Issues](issues.md)                                                 | `/projects/:id/issues` (also available for groups and standalone)                                                                                                                                     |
-| [Issue boards](boards.md)                                           | `/projects/:id/boards`                                                                                                                                                                                |
-| [Issue links](issue_links.md) **[STARTER]**                         | `/projects/:id/issues/.../links`                                                                                                                                                                      |
-| [Jobs](jobs.md)                                                     | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs`                                                                                                                                              |
-| [Labels](labels.md)                                                 | `/projects/:id/labels`                                                                                                                                                                                |
-| [Managed licenses](managed_licenses.md) **[ULTIMATE]**              | `/projects/:id/managed_licenses`                                                                                                                                                                      |
-| [Members](members.md)                                               | `/projects/:id/members` (also available for groups)                                                                                                                                                   |
-| [Merge request approvals](merge_request_approvals.md) **[STARTER]** | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals`                                                                                                                               |
-| [Merge requests](merge_requests.md)                                 | `/projects/:id/merge_requests` (also available for groups and standalone)                                                                                                                             |
-| [Notes](notes.md) (comments)                                        | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` (also available for groups)                                                            |
-| [Notification settings](notification_settings.md)                   | `/projects/:id/notification_settings` (also available for groups and standalone)                                                                                                                      |
-| [Packages](packages.md) **[PREMIUM]**                               | `/projects/:id/packages`                                                                                                                                                                              |
-| [Pages domains](pages_domains.md)                                   | `/projects/:id/pages` (also available standalone)                                                                                                                                                     |
-| [Pipelines](pipelines.md)                                           | `/projects/:id/pipelines`                                                                                                                                                                             |
-| [Pipeline schedules](pipeline_schedules.md)                         | `/projects/:id/pipeline_schedules`                                                                                                                                                                    |
-| [Pipeline triggers](pipeline_triggers.md)                           | `/projects/:id/triggers`                                                                                                                                                                              |
-| [Projects](projects.md) including setting Webhooks                  | `/projects`, `/projects/:id/hooks` (also available for users)                                                                                                                                         |
-| [Project badges](project_badges.md)                                 | `/projects/:id/badges`                                                                                                                                                                                |
-| [Project clusters](project_clusters.md)                             | `/projects/:id/clusters`                                                                                                                                                                              |
-| [Project-level variables](project_level_variables.md)               | `/projects/:id/variables`                                                                                                                                                                             |
-| [Project import/export](project_import_export.md)                   | `/projects/:id/export`, `/projects/import`, `/projects/:id/import`                                                                                                                                    |
-| [Project milestones](milestones.md)                                 | `/projects/:id/milestones`                                                                                                                                                                            |
-| [Project snippets](project_snippets.md)                             | `/projects/:id/snippets`                                                                                                                                                                              |
-| [Project templates](project_templates.md)                           | `/projects/:id/templates`                                                                                                                                                                             |
-| [Protected branches](protected_branches.md)                         | `/projects/:id/protected_branches`                                                                                                                                                                    |
-| [Protected tags](protected_tags.md)                                 | `/projects/:id/protected_tags`                                                                                                                                                                        |
-| [Releases](releases/index.md)                                       | `/projects/:id/releases`                                                                                                                                                                              |
-| [Release links](releases/links.md)                                  | `/projects/:id/releases/.../assets/links`                                                                                                                                                             |
-| [Repositories](repositories.md)                                     | `/projects/:id/repository`                                                                                                                                                                            |
-| [Repository files](repository_files.md)                             | `/projects/:id/repository/files`                                                                                                                                                                      |
-| [Repository submodules](repository_submodules.md)                   | `/projects/:id/repository/submodules`                                                                                                                                                                 |
-| [Resource label events](resource_label_events.md)                   | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events` (also available for groups)                                                                |
-| [Runners](runners.md)                                               | `/projects/:id/runners` (also available standalone)                                                                                                                                                   |
-| [Search](search.md)                                                 | `/projects/:id/search` (also available for groups and standalone)                                                                                                                                     |
-| [Services](services.md)                                             | `/projects/:id/services`                                                                                                                                                                              |
-| [Tags](tags.md)                                                     | `/projects/:id/repository/tags`                                                                                                                                                                       |
-| [Vulnerabilities](vulnerabilities.md) **[ULTIMATE]**                | `/projects/:id/vulnerabilities` (also available for groups)                                                                                                                                           |
-| [Wikis](wikis.md)                                                   | `/projects/:id/wikis`                                                                                                                                                                                 |
-
-### Group resources
-
-The following API resources are available in the group context:
-
-| Resource                                                         | Available endpoints                                                              |
-|:-----------------------------------------------------------------|:---------------------------------------------------------------------------------|
-| [Access requests](access_requests.md)                            | `/groups/:id/access_requests/` (also available for projects)                     |
-| [Custom attributes](custom_attributes.md)                        | `/groups/:id/custom_attributes` (also available for projects and users)          |
-| [Discussions](discussions.md) (threaded comments) **[ULTIMATE]** | `/groups/:id/epics/.../discussions` (also available for projects)                |
-| [Epic issues](epic_issues.md) **[ULTIMATE]**                     | `/groups/:id/epics/.../issues`                                                   |
-| [Epic links](epic_links.md) **[ULTIMATE]**                       | `/groups/:id/epics/.../epics`                                                    |
-| [Epics](epics.md) **[ULTIMATE]**                                 | `/groups/:id/epics`                                                              |
-| [Groups](groups.md)                                              | `/groups`, `/groups/.../subgroups`                                               |
-| [Group badges](group_badges.md)                                  | `/groups/:id/badges`                                                             |
-| [Group issue boards](group_boards.md)                            | `/groups/:id/boards`                                                             |
-| [Group labels](group_labels.md)                                  | `/groups/:id/labels`                                                             |
-| [Group-level variables](group_level_variables.md)                | `/groups/:id/variables`                                                          |
-| [Group milestones](group_milestones.md)                          | `/groups/:id/milestones`                                                         |
-| [Issues](issues.md)                                              | `/groups/:id/issues` (also available for projects and standalone)                |
-| [Members](members.md)                                            | `/groups/:id/members` (also available for projects)                              |
-| [Merge requests](merge_requests.md)                              | `/groups/:id/merge_requests` (also available for projects and standalone)        |
-| [Notes](notes.md) (comments)                                     | `/groups/:id/epics/.../notes` (also available for projects)                      |
-| [Notification settings](notification_settings.md)                | `/groups/:id/notification_settings` (also available for projects and standalone) |
-| [Resource label events](resource_label_events.md)                | `/groups/:id/epics/.../resource_label_events` (also available for projects)      |
-| [Search](search.md)                                              | `/groups/:id/search` (also available for projects and standalone)                |
-
-### Standalone resources
-
-The following API resources are available outside of project and group contexts (including `/users`):
-
-| Resource                                          | Available endpoints                                                     |
-|:--------------------------------------------------|:------------------------------------------------------------------------|
-| [Applications](applications.md)                   | `/applications`                                                         |
-| [Avatar](avatar.md)                               | `/avatar`                                                               |
-| [Broadcast messages](broadcast_messages.md)       | `/broadcast_messages`                                                   |
-| [Code snippets](snippets.md)                      | `/snippets`                                                             |
-| [Custom attributes](custom_attributes.md)         | `/users/:id/custom_attributes` (also available for groups and projects) |
-| [Deploy keys](deploy_keys.md)                     | `/deploy_keys` (also available for projects)                            |
-| [Events](events.md)                               | `/events`, `/users/:id/events` (also available for projects)            |
-| [Feature flags](features.md)                      | `/features`                                                             |
-| [Geo Nodes](geo_nodes.md) **[PREMIUM ONLY]**      | `/geo_nodes`                                                            |
-| [Import repository from GitHub](import.md)        | `/import/github`                                                        |
-| [Issues](issues.md)                               | `/issues` (also available for groups and projects)                      |
-| [Keys](keys.md)                                   | `/keys`                                                                 |
-| [License](license.md) **[CORE ONLY]**             | `/license`                                                              |
-| [Markdown](markdown.md)                           | `/markdown`                                                             |
-| [Merge requests](merge_requests.md)               | `/merge_requests` (also available for groups and projects)              |
-| [Namespaces](namespaces.md)                       | `/namespaces`                                                           |
-| [Notification settings](notification_settings.md) | `/notification_settings` (also available for groups and projects)       |
-| [Pages domains](pages_domains.md)                 | `/pages/domains` (also available for projects)                          |
-| [Projects](projects.md)                           | `/users/:id/projects` (also available for projects)                     |
-| [Runners](runners.md)                             | `/runners` (also available for projects)                                |
-| [Search](search.md)                               | `/search` (also available for groups and projects)                      |
-| [Settings](settings.md)                           | `/application/settings`                                                 |
-| [Sidekiq metrics](sidekiq_metrics.md)             | `/sidekiq`                                                              |
-| [Suggestions](suggestions.md)                     | `/suggestions`                                                          |
-| [System hooks](system_hooks.md)                   | `/hooks`                                                                |
-| [Todos](todos.md)                                 | `/todos`                                                                |
-| [Users](users.md)                                 | `/users`                                                                |
-| [Validate `.gitlab-ci.yml` file](lint.md)         | `/lint`                                                                 |
-| [Version](version.md)                             | `/version`                                                              |
-
-### Templates API resources
-
-Endpoints are available for:
-
-- [Dockerfile templates](templates/dockerfiles.md).
-- [`.gitignore` templates](templates/gitignores.md).
-- [GitLab CI YAML templates](templates/gitlab_ci_ymls.md).
-- [Open source license templates](templates/licenses.md).
-
-## SCIM **[SILVER ONLY]**
+## Available API resources
+
+For a list of the available resources and their endpoints, see
+[API resources](api_resources.md).
+
+## SCIM **(SILVER ONLY)**
 
 [GitLab.com Silver and above](https://about.gitlab.com/pricing/) provides an [SCIM API](scim.md) that implements [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) and provides
 the `/Users` endpoint. The base URL is: `/api/scim/v2/groups/:group_path/Users/`.
 
 ## Road to GraphQL
 
-Going forward, we will start on moving to
-[GraphQL](graphql/index.md) and deprecate the use of
-controller-specific endpoints. GraphQL has a number of benefits:
+[GraphQL](graphql/index.md) is available in GitLab, which will
+allow deprecation of controller-specific endpoints.
+
+GraphQL has a number of benefits:
 
 1. We avoid having to maintain two different APIs.
 1. Callers of the API can request only what they need.
@@ -211,11 +77,12 @@ authentication is not provided. For
 those cases where it is not required, this will be mentioned in the documentation
 for each individual endpoint. For example, the [`/projects/:id` endpoint](projects.md).
 
-There are three ways to authenticate with the GitLab API:
+There are four ways to authenticate with the GitLab API:
 
 1. [OAuth2 tokens](#oauth2-tokens)
 1. [Personal access tokens](#personal-access-tokens)
 1. [Session cookie](#session-cookie)
+1. [GitLab CI job token](#gitlab-ci-job-token-premium) **(PREMIUM)**
 
 For admins who want to authenticate with the API as a specific user, or who want to build applications or scripts that do so, two options are available:
 
@@ -267,6 +134,12 @@ Example of using the personal access token in a header:
 curl --header "Private-Token: <your_access_token>" https://gitlab.example.com/api/v4/projects
 ```
 
+You can also use personal access tokens with OAuth-compliant headers:
+
+```shell
+curl --header "Authorization: Bearer <your_access_token>" https://gitlab.example.com/api/v4/projects
+```
+
 Read more about [personal access tokens][pat].
 
 ### Session cookie
@@ -279,6 +152,14 @@ The primary user of this authentication method is the web frontend of GitLab its
 which can use the API as the authenticated user to get a list of their projects,
 for example, without needing to explicitly pass an access token.
 
+### GitLab CI job token **(PREMIUM)**
+
+With a few API endpoints you can use a [GitLab CI job token](../user/project/new_ci_build_permissions_model.md#job-token)
+to authenticate with the API:
+
+* [Get job artifacts](jobs.md#get-job-artifacts)
+* [Pipeline triggers](pipeline_triggers.md)
+
 ### Impersonation tokens
 
 > [Introduced][ce-9099] in GitLab 9.0. Needs admin permissions.
@@ -308,25 +189,23 @@ By default, impersonation is enabled. To disable impersonation:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['impersonation_enabled'] = false
-    ```
+   ```ruby
+   gitlab_rails['impersonation_enabled'] = false
+   ```
 
 1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure)
    GitLab for the changes to take effect.
 
 To re-enable impersonation, remove this configuration and reconfigure GitLab.
 
----
-
 **For installations from source**
 
 1. Edit `config/gitlab.yml`:
 
-    ```yaml
-    gitlab:
-      impersonation_enabled: false
-    ```
+   ```yaml
+   gitlab:
+     impersonation_enabled: false
+   ```
 
 1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source)
    GitLab for the changes to take effect.
@@ -377,8 +256,6 @@ returned with status code `404`:
 }
 ```
 
----
-
 Example of a valid API call and a request using cURL with sudo request,
 providing a username:
 
@@ -508,7 +385,7 @@ more than 10,000, the `X-Total` and `X-Total-Pages` headers as well as the
 
 ## Namespaced path encoding
 
-If using namespaced API calls, make sure that the `NAMESPACE/PROJECT_NAME` is
+If using namespaced API calls, make sure that the `NAMESPACE/PROJECT_PATH` is
 URL-encoded.
 
 For example, `/` is represented by `%2F`:
@@ -517,6 +394,11 @@ For example, `/` is represented by `%2F`:
 GET /api/v4/projects/diaspora%2Fdiaspora
 ```
 
+NOTE: **Note:**
+A project's **path** is not necessarily the same as its **name**.  A
+project's path can found in the project's URL or in the project's settings
+under **General > Advanced > Change path**.
+
 ## Branches and tags name encoding
 
 If your branch or tag contains a `/`, make sure the branch/tag name is
@@ -683,6 +565,13 @@ The correct encoding for the query parameter would be:
 There are many unofficial GitLab API Clients for most of the popular
 programming languages. Visit the [GitLab website] for a complete list.
 
+## Rate limits
+
+For administrator documentation on rate limit settings, see
+[Rate limits](../security/rate_limits.md). To find the settings that are
+specifically used by GitLab.com, see
+[GitLab.com-specific rate limits](../user/gitlab_com/index.md#gitlabcom-specific-rate-limits).
+
 [GitLab website]: https://about.gitlab.com/applications/#api-clients "Clients using the GitLab API"
 [lib-api-url]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api/api.rb
 [ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749
diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md
new file mode 100644
index 00000000000..b32f11464ef
--- /dev/null
+++ b/doc/api/api_resources.md
@@ -0,0 +1,144 @@
+# API resources
+
+Available resources for the [GitLab API](README.md) can be grouped in the following contexts:
+
+- [Projects](#project-resources).
+- [Groups](#group-resources).
+- [Standalone](#standalone-resources).
+
+See also:
+
+- [V3 to V4](v3_to_v4.md).
+- Adding [deploy keys for multiple projects](deploy_key_multiple_projects.md).
+- [API Resources for various templates](#templates-api-resources).
+
+## Project resources
+
+The following API resources are available in the project context:
+
+| Resource                                                            | Available endpoints                                                                                                                                                                                   |
+|:--------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [Access requests](access_requests.md)                               | `/projects/:id/access_requests` (also available for groups)                                                                                                                                           |
+| [Award emoji](award_emoji.md)                                       | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji`                                                                      |
+| [Branches](branches.md)                                             | `/projects/:id/repository/branches/`, `/projects/:id/repository/merged_branches`                                                                                                                      |
+| [Commits](commits.md)                                               | `/projects/:id/repository/commits`, `/projects/:id/statuses`                                                                                                                                          |
+| [Container Registry](container_registry.md)                         | `/projects/:id/registry/repositories`                                                                                                                                                                 |
+| [Custom attributes](custom_attributes.md)                           | `/projects/:id/custom_attributes` (also available for groups and users)                                                                                                                               |
+| [Dependencies](dependencies.md) **(ULTIMATE)**                      | `/projects/:id/dependencies`
+| [Deploy keys](deploy_keys.md)                                       | `/projects/:id/deploy_keys` (also available standalone)                                                                                                                                               |
+| [Deployments](deployments.md)                                       | `/projects/:id/deployments`                                                                                                                                                                           |
+| [Discussions](discussions.md) (threaded comments)                   | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` (also available for groups) |
+| [Environments](environments.md)                                     | `/projects/:id/environments`                                                                                                                                                                          |
+| [Events](events.md)                                                 | `/projects/:id/events` (also available for users and standalone)                                                                                                                                      |
+| [Issues](issues.md)                                                 | `/projects/:id/issues` (also available for groups and standalone)                                                                                                                                     |
+| [Issues Statistics](issues_statistics.md)                           | `/projects/:id/issues_statistics` (also available for groups and standalone)                                                                                                                          |
+| [Issue boards](boards.md)                                           | `/projects/:id/boards`                                                                                                                                                                                |
+| [Issue links](issue_links.md) **(STARTER)**                         | `/projects/:id/issues/.../links`                                                                                                                                                                      |
+| [Jobs](jobs.md)                                                     | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs`                                                                                                                                              |
+| [Labels](labels.md)                                                 | `/projects/:id/labels`                                                                                                                                                                                |
+| [Managed licenses](managed_licenses.md) **(ULTIMATE)**              | `/projects/:id/managed_licenses`                                                                                                                                                                      |
+| [Members](members.md)                                               | `/projects/:id/members` (also available for groups)                                                                                                                                                   |
+| [Merge request approvals](merge_request_approvals.md) **(STARTER)** | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals`                                                                                                                               |
+| [Merge requests](merge_requests.md)                                 | `/projects/:id/merge_requests` (also available for groups and standalone)                                                                                                                             |
+| [Notes](notes.md) (comments)                                        | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` (also available for groups)                                                            |
+| [Notification settings](notification_settings.md)                   | `/projects/:id/notification_settings` (also available for groups and standalone)                                                                                                                      |
+| [Packages](packages.md) **(PREMIUM)**                               | `/projects/:id/packages`                                                                                                                                                                              |
+| [Pages domains](pages_domains.md)                                   | `/projects/:id/pages` (also available standalone)                                                                                                                                                     |
+| [Pipelines](pipelines.md)                                           | `/projects/:id/pipelines`                                                                                                                                                                             |
+| [Pipeline schedules](pipeline_schedules.md)                         | `/projects/:id/pipeline_schedules`                                                                                                                                                                    |
+| [Pipeline triggers](pipeline_triggers.md)                           | `/projects/:id/triggers`                                                                                                                                                                              |
+| [Projects](projects.md) including setting Webhooks                  | `/projects`, `/projects/:id/hooks` (also available for users)                                                                                                                                         |
+| [Project badges](project_badges.md)                                 | `/projects/:id/badges`                                                                                                                                                                                |
+| [Project clusters](project_clusters.md)                             | `/projects/:id/clusters`                                                                                                                                                                              |
+| [Project-level variables](project_level_variables.md)               | `/projects/:id/variables`                                                                                                                                                                             |
+| [Project import/export](project_import_export.md)                   | `/projects/:id/export`, `/projects/import`, `/projects/:id/import`                                                                                                                                    |
+| [Project milestones](milestones.md)                                 | `/projects/:id/milestones`                                                                                                                                                                            |
+| [Project snippets](project_snippets.md)                             | `/projects/:id/snippets`                                                                                                                                                                              |
+| [Project templates](project_templates.md)                           | `/projects/:id/templates`                                                                                                                                                                             |
+| [Protected branches](protected_branches.md)                         | `/projects/:id/protected_branches`                                                                                                                                                                    |
+| [Protected tags](protected_tags.md)                                 | `/projects/:id/protected_tags`                                                                                                                                                                        |
+| [Releases](releases/index.md)                                       | `/projects/:id/releases`                                                                                                                                                                              |
+| [Release links](releases/links.md)                                  | `/projects/:id/releases/.../assets/links`                                                                                                                                                             |
+| [Repositories](repositories.md)                                     | `/projects/:id/repository`                                                                                                                                                                            |
+| [Repository files](repository_files.md)                             | `/projects/:id/repository/files`                                                                                                                                                                      |
+| [Repository submodules](repository_submodules.md)                   | `/projects/:id/repository/submodules`                                                                                                                                                                 |
+| [Resource label events](resource_label_events.md)                   | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events` (also available for groups)                                                                |
+| [Runners](runners.md)                                               | `/projects/:id/runners` (also available standalone)                                                                                                                                                   |
+| [Search](search.md)                                                 | `/projects/:id/search` (also available for groups and standalone)                                                                                                                                     |
+| [Services](services.md)                                             | `/projects/:id/services`                                                                                                                                                                              |
+| [Tags](tags.md)                                                     | `/projects/:id/repository/tags`                                                                                                                                                                       |
+| [Vulnerabilities](vulnerabilities.md) **(ULTIMATE)**                | `/projects/:id/vulnerabilities` (also available for groups)                                                                                                                                           |
+| [Wikis](wikis.md)                                                   | `/projects/:id/wikis`                                                                                                                                                                                 |
+
+## Group resources
+
+The following API resources are available in the group context:
+
+| Resource                                                         | Available endpoints                                                              |
+|:-----------------------------------------------------------------|:---------------------------------------------------------------------------------|
+| [Access requests](access_requests.md)                            | `/groups/:id/access_requests/` (also available for projects)                     |
+| [Custom attributes](custom_attributes.md)                        | `/groups/:id/custom_attributes` (also available for projects and users)          |
+| [Discussions](discussions.md) (threaded comments) **(ULTIMATE)** | `/groups/:id/epics/.../discussions` (also available for projects)                |
+| [Epic issues](epic_issues.md) **(ULTIMATE)**                     | `/groups/:id/epics/.../issues`                                                   |
+| [Epic links](epic_links.md) **(ULTIMATE)**                       | `/groups/:id/epics/.../epics`                                                    |
+| [Epics](epics.md) **(ULTIMATE)**                                 | `/groups/:id/epics`                                                              |
+| [Groups](groups.md)                                              | `/groups`, `/groups/.../subgroups`                                               |
+| [Group badges](group_badges.md)                                  | `/groups/:id/badges`                                                             |
+| [Group issue boards](group_boards.md)                            | `/groups/:id/boards`                                                             |
+| [Group labels](group_labels.md)                                  | `/groups/:id/labels`                                                             |
+| [Group-level variables](group_level_variables.md)                | `/groups/:id/variables`                                                          |
+| [Group milestones](group_milestones.md)                          | `/groups/:id/milestones`                                                         |
+| [Issues](issues.md)                                              | `/groups/:id/issues` (also available for projects and standalone)                |
+| [Issues Statistics](issues_statistics.md)                        | `/groups/:id/issues_statistics` (also available for projects and standalone)     |
+| [Members](members.md)                                            | `/groups/:id/members` (also available for projects)                              |
+| [Merge requests](merge_requests.md)                              | `/groups/:id/merge_requests` (also available for projects and standalone)        |
+| [Notes](notes.md) (comments)                                     | `/groups/:id/epics/.../notes` (also available for projects)                      |
+| [Notification settings](notification_settings.md)                | `/groups/:id/notification_settings` (also available for projects and standalone) |
+| [Resource label events](resource_label_events.md)                | `/groups/:id/epics/.../resource_label_events` (also available for projects)      |
+| [Search](search.md)                                              | `/groups/:id/search` (also available for projects and standalone)                |
+
+## Standalone resources
+
+The following API resources are available outside of project and group contexts (including `/users`):
+
+| Resource                                          | Available endpoints                                                     |
+|:--------------------------------------------------|:------------------------------------------------------------------------|
+| [Applications](applications.md)                   | `/applications`                                                         |
+| [Avatar](avatar.md)                               | `/avatar`                                                               |
+| [Broadcast messages](broadcast_messages.md)       | `/broadcast_messages`                                                   |
+| [Code snippets](snippets.md)                      | `/snippets`                                                             |
+| [Custom attributes](custom_attributes.md)         | `/users/:id/custom_attributes` (also available for groups and projects) |
+| [Deploy keys](deploy_keys.md)                     | `/deploy_keys` (also available for projects)                            |
+| [Events](events.md)                               | `/events`, `/users/:id/events` (also available for projects)            |
+| [Feature flags](features.md)                      | `/features`                                                             |
+| [Geo Nodes](geo_nodes.md) **(PREMIUM ONLY)**      | `/geo_nodes`                                                            |
+| [Import repository from GitHub](import.md)        | `/import/github`                                                        |
+| [Issues](issues.md)                               | `/issues` (also available for groups and projects)                      |
+| [Issues Statistics](issues_statistics.md)         | `/issues_statistics` (also available for groups and projects)           |
+| [Keys](keys.md)                                   | `/keys`                                                                 |
+| [License](license.md) **(CORE ONLY)**             | `/license`                                                              |
+| [Markdown](markdown.md)                           | `/markdown`                                                             |
+| [Merge requests](merge_requests.md)               | `/merge_requests` (also available for groups and projects)              |
+| [Namespaces](namespaces.md)                       | `/namespaces`                                                           |
+| [Notification settings](notification_settings.md) | `/notification_settings` (also available for groups and projects)       |
+| [Pages domains](pages_domains.md)                 | `/pages/domains` (also available for projects)                          |
+| [Projects](projects.md)                           | `/users/:id/projects` (also available for projects)                     |
+| [Runners](runners.md)                             | `/runners` (also available for projects)                                |
+| [Search](search.md)                               | `/search` (also available for groups and projects)                      |
+| [Settings](settings.md)                           | `/application/settings`                                                 |
+| [Sidekiq metrics](sidekiq_metrics.md)             | `/sidekiq`                                                              |
+| [Suggestions](suggestions.md)                     | `/suggestions`                                                          |
+| [System hooks](system_hooks.md)                   | `/hooks`                                                                |
+| [Todos](todos.md)                                 | `/todos`                                                                |
+| [Users](users.md)                                 | `/users`                                                                |
+| [Validate `.gitlab-ci.yml` file](lint.md)         | `/lint`                                                                 |
+| [Version](version.md)                             | `/version`                                                              |
+
+## Templates API resources
+
+Endpoints are available for:
+
+- [Dockerfile templates](templates/dockerfiles.md).
+- [`.gitignore` templates](templates/gitignores.md).
+- [GitLab CI YAML templates](templates/gitlab_ci_ymls.md).
+- [Open source license templates](templates/licenses.md).
diff --git a/doc/api/boards.md b/doc/api/boards.md
index a96206f5df3..08ec1d832df 100644
--- a/doc/api/boards.md
+++ b/doc/api/boards.md
@@ -141,7 +141,7 @@ Example response:
   }
 ```
 
-## Create a board **[STARTER]**
+## Create a board **(STARTER)**
 
 Creates a board.
 
@@ -209,7 +209,7 @@ Example response:
   }
 ```
 
-## Update a board **[STARTER]**
+## Update a board **(STARTER)**
 
 > [Introduced][ee-5954] in [GitLab Starter](https://about.gitlab.com/pricing/) 11.1.
 
@@ -229,7 +229,6 @@ PUT /projects/:id/boards/:board_id
 | `labels`            | string         | no       | Comma-separated list of label names which the board should be scoped to |
 | `weight`            | integer        | no       | The weight range from 0 to 9, to which the board should be scoped to |
 
-
 ```bash
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/boards/1?name=new_name&milestone_id=43&assignee_id=1&labels=Doing&weight=4
 ```
@@ -291,7 +290,7 @@ Example response:
   }
 ```
 
-## Delete a board **[STARTER]**
+## Delete a board **(STARTER)**
 
 Deletes a board.
 
@@ -405,8 +404,8 @@ POST /projects/:id/boards/:board_id/lists
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `board_id` | integer | yes | The ID of a board |
 | `label_id` | integer | no | The ID of a label |
-| `assignee_id` **[PREMIUM]** | integer | no | The ID of a user |
-| `milestone_id` **[PREMIUM]** | integer | no | The ID of a milestone |
+| `assignee_id` **(PREMIUM)** | integer | no | The ID of a user |
+| `milestone_id` **(PREMIUM)** | integer | no | The ID of a milestone |
 
 NOTE: **Note**:
 Label, assignee and milestone arguments are mutually exclusive,
diff --git a/doc/api/commits.md b/doc/api/commits.md
index 25015fad9e3..1f17eaea46d 100644
--- a/doc/api/commits.md
+++ b/doc/api/commits.md
@@ -72,15 +72,16 @@ POST /projects/:id/repository/commits
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
-| `branch` | string | yes | Name of the branch to commit into. To create a new branch, also provide `start_branch`. |
+| `branch` | string | yes | Name of the branch to commit into. To create a new branch, also provide either `start_branch` or `start_sha`, and optionally `start_project`. |
 | `commit_message` | string | yes | Commit message |
-| `start_branch` | string | no | Name of the branch to start the new commit from |
-| `start_project` | integer/string | no | The project ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) to start the commit from. Defaults to the value of `id`. |
+| `start_branch` | string | no | Name of the branch to start the new branch from |
+| `start_sha` | string | no | SHA of the commit to start the new branch from |
+| `start_project` | integer/string | no | The project ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) to start the new branch from. Defaults to the value of `id`. |
 | `actions[]` | array | yes | An array of action hashes to commit as a batch. See the next table for what attributes it can take. |
 | `author_email` | string | no | Specify the commit author's email address |
 | `author_name` | string | no | Specify the commit author's name |
 | `stats` | boolean | no | Include commit stats. Default is true |
-| `force` | boolean | no | When `true` overwrites the target branch with a new commit based on the `start_branch` |
+| `force` | boolean | no | When `true` overwrites the target branch with a new commit based on the `start_branch` or `start_sha` |
 
 | `actions[]` Attribute | Type | Required | Description |
 | --------------------- | ---- | -------- | ----------- |
@@ -581,6 +582,7 @@ POST /projects/:id/statuses/:sha
 | `target_url` |  string  | no  | The target URL to associate with this status
 | `description` | string  | no  | The short description of the status
 | `coverage` | float  | no    | The total code coverage
+| `pipeline_id` |  integer  | no  | The ID of the pipeline to set status. Use in case of several pipeline on same SHA.
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success"
@@ -716,6 +718,7 @@ Example response if commit is signed:
 ```
 
 Example response if commit is unsigned:
+
 ```json
 {
   "message": "404 GPG Signature Not Found"
diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md
index 1f17af1f1e9..bf544f64178 100644
--- a/doc/api/container_registry.md
+++ b/doc/api/container_registry.md
@@ -6,6 +6,8 @@ This is the API docs of the [GitLab Container Registry](../user/project/containe
 
 ## List registry repositories
 
+### Within a project
+
 Get a list of registry repositories in a project.
 
 ```
@@ -14,7 +16,8 @@ GET /projects/:id/registry/repositories
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
+| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) accessible by the authenticated user. |
+| `tags`      | boolean | no | If the param is included as true, each repository will include an array of `"tags"` in the response. |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories"
@@ -28,6 +31,7 @@ Example response:
     "id": 1,
     "name": "",
     "path": "group/project",
+    "project_id": 9,
     "location": "gitlab.example.com:5000/group/project",
     "created_at": "2019-01-10T13:38:57.391Z"
   },
@@ -35,12 +39,77 @@ Example response:
     "id": 2,
     "name": "releases",
     "path": "group/project/releases",
+    "project_id": 9,
     "location": "gitlab.example.com:5000/group/project/releases",
     "created_at": "2019-01-10T13:39:08.229Z"
   }
 ]
 ```
 
+### Within a group
+
+Get a list of registry repositories in a group.
+
+```
+GET /groups/:id/registry/repositories
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) accessible by the authenticated user. |
+| `tags`      | boolean | no | If the param is included as true, each repository will include an array of `"tags"` in the response. |
+
+```bash
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/2/registry/repositories?tags=1"
+```
+
+Example response:
+
+```json
+[
+  {
+    "id": 1,
+    "name": "",
+    "path": "group/project",
+    "project_id": 9,
+    "location": "gitlab.example.com:5000/group/project",
+    "created_at": "2019-01-10T13:38:57.391Z",
+    "tags": [
+      {
+        "name": "0.0.1",
+        "path": "group/project:0.0.1",
+        "location": "gitlab.example.com:5000/group/project:0.0.1"
+      }
+    ]
+  },
+  {
+    "id": 2,
+    "name": "",
+    "path": "group/other_project",
+    "project_id": 11,
+    "location": "gitlab.example.com:5000/group/other_project",
+    "created_at": "2019-01-10T13:39:08.229Z",
+    "tags": [
+      {
+        "name": "0.0.1",
+        "path": "group/other_project:0.0.1",
+        "location": "gitlab.example.com:5000/group/other_project:0.0.1"
+      },
+      {
+        "name": "0.0.2",
+        "path": "group/other_project:0.0.2",
+        "location": "gitlab.example.com:5000/group/other_project:0.0.2"
+      },
+      {
+        "name": "latest",
+        "path": "group/other_project:latest",
+        "location": "gitlab.example.com:5000/group/other_project:latest"
+      }
+    ]
+  }
+]
+```
+
 ## Delete registry repository
 
 Delete a repository in registry.
@@ -62,6 +131,8 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git
 
 ## List repository tags
 
+### Within a project
+
 Get a list of tags for given registry repository.
 
 ```
@@ -70,7 +141,7 @@ GET /projects/:id/registry/repositories/:repository_id/tags
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
+| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) accessible by the authenticated user. |
 | `repository_id` | integer | yes | The ID of registry repository. |
 
 ```bash
@@ -104,7 +175,7 @@ GET /projects/:id/registry/repositories/:repository_id/tags/:tag_name
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
+| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) accessible by the authenticated user. |
 | `repository_id` | integer | yes | The ID of registry repository. |
 | `tag_name` | string | yes | The name of tag. |
 
@@ -145,6 +216,9 @@ DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0"
 ```
 
+This action does not delete blobs. In order to delete them and recycle disk space,
+[run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/README.html#removing-unused-layers-not-referenced-by-manifests).
+
 ## Delete repository tags in bulk
 
 Delete repository tags in bulk based on given criteria.
@@ -174,6 +248,8 @@ This API call performs the following operations:
 These operations are executed asynchronously and it might
 take time to get executed. You can run this at most
 once an hour for a given container repository.
+This action does not delete blobs. In order to delete them and recycle disk space,
+[run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/README.html#removing-unused-layers-not-referenced-by-manifests).
 
 NOTE: **Note:**
 Due to a [Docker Distribution deficiency](https://gitlab.com/gitlab-org/gitlab-ce/issues/21405),
@@ -188,13 +264,13 @@ Examples:
    curl --request DELETE --data 'name_regex=[0-9a-z]{40}' --data 'keep_n=5' --data 'older_than=2d' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"
    ```
 
-2. Remove all tags, but keep always the latest 5:
+1. Remove all tags, but keep always the latest 5:
 
    ```bash
    curl --request DELETE --data 'name_regex=.*' --data 'keep_n=5' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"
    ```
 
-3. Remove all tags that are older than 1 month:
+1. Remove all tags that are older than 1 month:
 
    ```bash
    curl --request DELETE --data 'name_regex=.*' --data 'older_than=1month' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"
diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md
new file mode 100644
index 00000000000..015ffbe60f6
--- /dev/null
+++ b/doc/api/dependencies.md
@@ -0,0 +1,50 @@
+# Dependencies API **(ULTIMATE)**
+
+CAUTION: **Caution:**
+This API is in an alpha stage and considered unstable.
+The response payload may be subject to change or breakage
+across GitLab releases.
+
+Every call to this endpoint requires authentication. To perform this call, user should be authorized to read 
+[Project Security Dashboard](../user/application_security/security_dashboard/index.md#project-security-dashboard). 
+
+## List project dependencies
+
+Get a list of project dependencies. This API partially mirroring 
+[Dependency List](../user/application_security/dependency_list/index.md) feature.
+This list can be generated only for [languages and package managers](../user/application_security/dependency_scanning/index.md#supported-languages-and-package-managers)
+supported by Gemnasium. 
+
+```
+GET /projects/:id/dependencies
+GET /projects/:id/vulnerabilities?package_manager=maven
+GET /projects/:id/vulnerabilities?package_manager=yarn,bundler
+```
+
+| Attribute     | Type           | Required | Description                                                                                                                                                                 |
+| ------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding).                                                            |
+| `package_manager` | string array   | no       | Returns dependencies belonging to specified package manager. Valid values: `bundler`, `composer`, `maven`, `npm`, `pip` or `yarn`.                                   |
+
+```bash
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/dependencies
+```
+
+Example response:
+
+```json
+[
+  {
+    "name": "rails",
+    "version": "5.0.1",
+    "package_manager": "bundler",
+    "dependency_file_path": "Gemfile.lock"
+  },
+  {
+      "name": "hanami",
+      "version": "1.3.1",
+      "package_manager": "bundler",
+      "dependency_file_path": "Gemfile.lock"
+    }
+]
+```
diff --git a/doc/api/deploy_key_multiple_projects.md b/doc/api/deploy_key_multiple_projects.md
index 0c9e3e66cae..85df972746e 100644
--- a/doc/api/deploy_key_multiple_projects.md
+++ b/doc/api/deploy_key_multiple_projects.md
@@ -1,29 +1,5 @@
-# Adding deploy keys to multiple projects via API
+---
+redirect_to: deploy_keys.md#adding-deploy-keys-to-multiple-projects
+---
 
-If you want to easily add the same deploy key to multiple projects in the same
-group, this can be achieved quite easily with the API.
-
-First, find the ID of the projects you're interested in, by either listing all
-projects:
-
-```
-curl --header 'PRIVATE-TOKEN: <your_access_token>' https://gitlab.example.com/api/v4/projects
-```
-
-Or finding the ID of a group and then listing all projects in that group:
-
-```
-curl --header 'PRIVATE-TOKEN: <your_access_token>' https://gitlab.example.com/api/v4/groups
-
-# For group 1234:
-curl --header 'PRIVATE-TOKEN: <your_access_token>' https://gitlab.example.com/api/v4/groups/1234
-```
-
-With those IDs, add the same deploy key to all:
-
-```
-for project_id in 321 456 987; do
-    curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
-    --data '{"title": "my key", "key": "ssh-rsa AAAA..."}' https://gitlab.example.com/api/v4/projects/${project_id}/deploy_keys
-done
-```
+This document was moved to [another location](deploy_keys.md#adding-deploy-keys-to-multiple-projects).
diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md
index 1d7523fcc3d..94351e1a300 100644
--- a/doc/api/deploy_keys.md
+++ b/doc/api/deploy_keys.md
@@ -19,13 +19,13 @@ Example response:
   {
     "id": 1,
     "title": "Public key",
-    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",    
+    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
     "created_at": "2013-10-02T10:12:29Z"
   },
   {
     "id": 3,
     "title": "Another Public key",
-    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",    
+    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
     "created_at": "2013-10-02T11:12:29Z"
   }
 ]
@@ -203,3 +203,32 @@ Example response:
    "created_at" : "2015-08-29T12:44:31.550Z"
 }
 ```
+## Adding deploy keys to multiple projects
+
+If you want to easily add the same deploy key to multiple projects in the same
+group, this can be achieved quite easily with the API.
+
+First, find the ID of the projects you're interested in, by either listing all
+projects:
+
+```
+curl --header 'PRIVATE-TOKEN: <your_access_token>' https://gitlab.example.com/api/v4/projects
+```
+
+Or finding the ID of a group and then listing all projects in that group:
+
+```
+curl --header 'PRIVATE-TOKEN: <your_access_token>' https://gitlab.example.com/api/v4/groups
+
+# For group 1234:
+curl --header 'PRIVATE-TOKEN: <your_access_token>' https://gitlab.example.com/api/v4/groups/1234
+```
+
+With those IDs, add the same deploy key to all:
+
+```
+for project_id in 321 456 987; do
+    curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
+    --data '{"title": "my key", "key": "ssh-rsa AAAA..."}' https://gitlab.example.com/api/v4/projects/${project_id}/deploy_keys
+done
+```
diff --git a/doc/api/discussions.md b/doc/api/discussions.md
index 9defef4fd53..b4a2d0b15f6 100644
--- a/doc/api/discussions.md
+++ b/doc/api/discussions.md
@@ -4,7 +4,7 @@ Discussions are a set of related notes on:
 
 - Snippets
 - Issues
-- Epics **[ULTIMATE]**
+- Epics **(ULTIMATE)**
 - Merge requests
 - Commits
 
@@ -12,16 +12,15 @@ This includes system notes, which are notes about changes to the object (for exa
 
 ## Discussions pagination
 
-By default, `GET` requests return 20 results at a time because the API results
-are paginated.
+By default, `GET` requests return 20 results at a time because the API results are paginated.
 
 Read more on [pagination](README.md#pagination).
 
 ## Issues
 
-### List project issue discussions
+### List project issue discussion items
 
-Gets a list of all discussions for a single issue.
+Gets a list of all discussion items for a single issue.
 
 ```
 GET /projects/:id/issues/:issue_iid/discussions
@@ -115,9 +114,9 @@ GET /projects/:id/issues/:issue_iid/discussions
 curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions
 ```
 
-### Get single issue discussion
+### Get single issue discussion item
 
-Returns a single discussion for a specific project issue
+Returns a single discussion item for a specific project issue
 
 ```
 GET /projects/:id/issues/:issue_iid/discussions/:discussion_id
@@ -129,16 +128,15 @@ Parameters:
 | --------------- | -------------- | -------- | ----------- |
 | `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `issue_iid`     | integer        | yes      | The IID of an issue |
-| `discussion_id` | integer        | yes      | The ID of a discussion |
+| `discussion_id` | integer        | yes      | The ID of a discussion item |
 
 ```bash
 curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
 ```
 
-### Create new issue discussion
+### Create new issue thread
 
-Creates a new discussion to a single project issue. This is similar to creating
-a note but other comments (replies) can be added to it later.
+Creates a new thread to a single project issue. This is similar to creating a note but other comments (replies) can be added to it later.
 
 ```
 POST /projects/:id/issues/:issue_iid/discussions
@@ -150,17 +148,19 @@ Parameters:
 | --------------- | -------------- | -------- | ----------- |
 | `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `issue_iid`     | integer        | yes      | The IID of an issue |
-| `body`          | string         | yes      | The content of a discussion |
+| `body`          | string         | yes      | The content of the thread |
 | `created_at`    | string         | no       | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment
 ```
 
-### Add note to existing issue discussion
+### Add note to existing issue thread
+
+Adds a new note to the thread. This can also [create a thread from a single comment](../user/discussions/#start-a-thread-by-replying-to-a-standard-comment).
 
-Adds a new note to the discussion. This can also
-[create a discussion from a single comment](../user/discussions/#start-a-discussion-by-replying-to-a-standard-comment).
+**WARNING**
+Notes can be added to other items than comments (system notes, etc.) making them threads. 
 
 ```
 POST /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes
@@ -172,18 +172,18 @@ Parameters:
 | --------------- | -------------- | -------- | ----------- |
 | `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `issue_iid`     | integer        | yes      | The IID of an issue |
-| `discussion_id` | integer        | yes      | The ID of a discussion |
-| `note_id`       | integer        | yes      | The ID of a discussion note |
-| `body`          | string         | yes      | The content of a discussion |
+| `discussion_id` | integer        | yes      | The ID of a thread |
+| `note_id`       | integer        | yes      | The ID of a thread note |
+| `body`          | string         | yes      | The content of the note/reply |
 | `created_at`    | string         | no       | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment
 ```
 
-### Modify existing issue discussion note
+### Modify existing issue thread note
 
-Modify existing discussion note of an issue.
+Modify existing thread note of an issue.
 
 ```
 PUT /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes/:note_id
@@ -195,17 +195,17 @@ Parameters:
 | --------------- | -------------- | -------- | ----------- |
 | `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `issue_iid`     | integer        | yes      | The IID of an issue |
-| `discussion_id` | integer        | yes      | The ID of a discussion |
-| `note_id`       | integer        | yes      | The ID of a discussion note |
-| `body`          | string         | yes      | The content of a discussion |
+| `discussion_id` | integer        | yes      | The ID of a thread |
+| `note_id`       | integer        | yes      | The ID of a thread note |
+| `body`          | string         | yes      | The content of the note/reply |
 
 ```bash
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment
 ```
 
-### Delete an issue discussion note
+### Delete an issue thread note
 
-Deletes an existing discussion note of an issue.
+Deletes an existing thread note of an issue.
 
 ```
 DELETE /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes/:note_id
@@ -226,9 +226,9 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitl
 
 ## Snippets
 
-### List project snippet discussions
+### List project snippet discussion items
 
-Gets a list of all discussions for a single snippet.
+Gets a list of all discussion items for a single snippet.
 
 ```
 GET /projects/:id/snippets/:snippet_id/discussions
@@ -322,9 +322,9 @@ GET /projects/:id/snippets/:snippet_id/discussions
 curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions
 ```
 
-### Get single snippet discussion
+### Get single snippet discussion item
 
-Returns a single discussion for a specific project snippet
+Returns a single discussion item for a specific project snippet
 
 ```
 GET /projects/:id/snippets/:snippet_id/discussions/:discussion_id
@@ -336,15 +336,15 @@ Parameters:
 | --------------- | -------------- | -------- | ----------- |
 | `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `snippet_id`    | integer        | yes      | The ID of an snippet |
-| `discussion_id` | integer        | yes      | The ID of a discussion |
+| `discussion_id` | integer        | yes      | The ID of a discussion item |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
 ```
 
-### Create new snippet discussion
+### Create new snippet thread
 
-Creates a new discussion to a single project snippet. This is similar to creating
+Creates a new thread to a single project snippet. This is similar to creating
 a note but other comments (replies) can be added to it later.
 
 ```
@@ -364,9 +364,9 @@ Parameters:
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment
 ```
 
-### Add note to existing snippet discussion
+### Add note to existing snippet thread
 
-Adds a new note to the discussion.
+Adds a new note to the thread.
 
 ```
 POST /projects/:id/snippets/:snippet_id/discussions/:discussion_id/notes
@@ -378,18 +378,18 @@ Parameters:
 | --------------- | -------------- | -------- | ----------- |
 | `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `snippet_id`    | integer        | yes      | The ID of an snippet |
-| `discussion_id` | integer        | yes      | The ID of a discussion |
-| `note_id`       | integer        | yes      | The ID of a discussion note |
-| `body`          | string         | yes      | The content of a discussion |
+| `discussion_id` | integer        | yes      | The ID of a thread |
+| `note_id`       | integer        | yes      | The ID of a thread note |
+| `body`          | string         | yes      | The content of the note/reply |
 | `created_at`    | string         | no       | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment
 ```
 
-### Modify existing snippet discussion note
+### Modify existing snippet thread note
 
-Modify existing discussion note of an snippet.
+Modify existing thread note of a snippet.
 
 ```
 PUT /projects/:id/snippets/:snippet_id/discussions/:discussion_id/notes/:note_id
@@ -401,17 +401,17 @@ Parameters:
 | --------------- | -------------- | -------- | ----------- |
 | `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `snippet_id`    | integer        | yes      | The ID of an snippet |
-| `discussion_id` | integer        | yes      | The ID of a discussion |
-| `note_id`       | integer        | yes      | The ID of a discussion note |
-| `body`          | string         | yes      | The content of a discussion |
+| `discussion_id` | integer        | yes      | The ID of a thread |
+| `note_id`       | integer        | yes      | The ID of a thread note |
+| `body`          | string         | yes      | The content of the note/reply |
 
 ```bash
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment
 ```
 
-### Delete an snippet discussion note
+### Delete a snippet thread note
 
-Deletes an existing discussion note of an snippet.
+Deletes an existing thread note of a snippet.
 
 ```
 DELETE /projects/:id/snippets/:snippet_id/discussions/:discussion_id/notes/:note_id
@@ -430,11 +430,11 @@ Parameters:
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636
 ```
 
-## Epics **[ULTIMATE]**
+## Epics **(ULTIMATE)**
 
-### List group epic discussions
+### List group epic discussion items
 
-Gets a list of all discussions for a single epic.
+Gets a list of all discussion items for a single epic.
 
 ```
 GET /groups/:id/epics/:epic_id/discussions
@@ -529,9 +529,9 @@ GET /groups/:id/epics/:epic_id/discussions
 curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/epics/11/discussions
 ```
 
-### Get single epic discussion
+### Get single epic discussion item
 
-Returns a single discussion for a specific group epic
+Returns a single discussion item for a specific group epic
 
 ```
 GET /groups/:id/epics/:epic_id/discussions/:discussion_id
@@ -543,16 +543,16 @@ Parameters:
 | --------------- | -------------- | -------- | ----------- |
 | `id`            | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
 | `epic_id`       | integer        | yes      | The ID of an epic |
-| `discussion_id` | integer        | yes      | The ID of a discussion |
+| `discussion_id` | integer        | yes      | The ID of a discussion item |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
 ```
 
-### Create new epic discussion
+### Create new epic thread
 
-Creates a new discussion to a single group epic. This is similar to creating
-a note but but another comments (replies) can be added to it later.
+Creates a new thread to a single group epic. This is similar to creating
+a note but but other comments (replies) can be added to it later.
 
 ```
 POST /groups/:id/epics/:epic_id/discussions
@@ -564,17 +564,17 @@ Parameters:
 | --------------- | -------------- | -------- | ----------- |
 | `id`            | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
 | `epic_id`       | integer        | yes      | The ID of an epic |
-| `body`          | string         | yes      | The content of a discussion |
+| `body`          | string         | yes      | The content of the thread |
 | `created_at`    | string         | no       | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/epics/11/discussions?body=comment
 ```
 
-### Add note to existing epic discussion
+### Add note to existing epic thread
 
-Adds a new note to the discussion. This can also
-[create a discussion from a single comment](../user/discussions/#start-a-discussion-by-replying-to-a-standard-comment).
+Adds a new note to the thread. This can also
+[create a thread from a single comment](../user/discussions/#start-a-thread-by-replying-to-a-standard-comment).
 
 ```
 POST /groups/:id/epics/:epic_id/discussions/:discussion_id/notes
@@ -585,19 +585,19 @@ Parameters:
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
 | `id`            | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
-| `epic_id`     | integer        | yes      | The ID of an epic |
-| `discussion_id` | integer        | yes      | The ID of a discussion |
-| `note_id`       | integer        | yes      | The ID of a discussion note |
-| `body`          | string         | yes      | The content of a discussion |
+| `epic_id`       | integer        | yes      | The ID of an epic |
+| `discussion_id` | integer        | yes      | The ID of a thread |
+| `note_id`       | integer        | yes      | The ID of a thread note |
+| `body`          | string         | yes      | The content of the note/reply |
 | `created_at`    | string         | no       | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment
 ```
 
-### Modify existing epic discussion note
+### Modify existing epic thread note
 
-Modify existing discussion note of an epic.
+Modify existing thread note of an epic.
 
 ```
 PUT /groups/:id/epics/:epic_id/discussions/:discussion_id/notes/:note_id
@@ -609,17 +609,17 @@ Parameters:
 | --------------- | -------------- | -------- | ----------- |
 | `id`            | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
 | `epic_id`       | integer        | yes      | The ID of an epic |
-| `discussion_id` | integer        | yes      | The ID of a discussion |
-| `note_id`       | integer        | yes      | The ID of a discussion note |
-| `body`          | string         | yes      | The content of a discussion |
+| `discussion_id` | integer        | yes      | The ID of a thread |
+| `note_id`       | integer        | yes      | The ID of a thread note |
+| `body`          | string         | yes      | The content of note/reply |
 
 ```bash
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment
 ```
 
-### Delete an epic discussion note
+### Delete an epic thread note
 
-Deletes an existing discussion note of an epic.
+Deletes an existing thread note of an epic.
 
 ```
 DELETE /groups/:id/epics/:epic_id/discussions/:discussion_id/notes/:note_id
@@ -631,8 +631,8 @@ Parameters:
 | --------------- | -------------- | -------- | ----------- |
 | `id`            | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
 | `epic_id`       | integer        | yes      | The ID of an epic |
-| `discussion_id` | integer        | yes      | The ID of a discussion |
-| `note_id`       | integer        | yes      | The ID of a discussion note |
+| `discussion_id` | integer        | yes      | The ID of a thread |
+| `note_id`       | integer        | yes      | The ID of a thread note |
 
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/636
@@ -640,9 +640,9 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitl
 
 ## Merge requests
 
-### List project merge request discussions
+### List project merge request discussion items
 
-Gets a list of all discussions for a single merge request.
+Gets a list of all discussion items for a single merge request.
 
 ```
 GET /projects/:id/merge_requests/:merge_request_iid/discussions
@@ -789,9 +789,9 @@ Diff comments contain also position:
 curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions
 ```
 
-### Get single merge request discussion
+### Get single merge request discussion item
 
-Returns a single discussion for a specific project merge request
+Returns a single discussion item for a specific project merge request
 
 ```
 GET /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id
@@ -803,15 +803,15 @@ Parameters:
 | ------------------- | -------------- | -------- | ----------- |
 | `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `merge_request_iid` | integer        | yes      | The IID of a merge request |
-| `discussion_id`     | integer        | yes      | The ID of a discussion |
+| `discussion_id`     | integer        | yes      | The ID of a discussion item |
 
 ```bash
 curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
 ```
 
-### Create new merge request discussion
+### Create new merge request thread
 
-Creates a new discussion to a single project merge request. This is similar to creating
+Creates a new thread to a single project merge request. This is similar to creating
 a note but other comments (replies) can be added to it later.
 
 ```
@@ -824,7 +824,7 @@ Parameters:
 | ------------------------- | -------------- | -------- | ----------- |
 | `id`                      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `merge_request_iid`       | integer        | yes      | The IID of a merge request |
-| `body`                    | string         | yes      | The content of a discussion |
+| `body`                    | string         | yes      | The content of the thread |
 | `created_at`              | string         | no       | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
 | `position`                | hash           | no       | Position when creating a diff note |
 | `position[base_sha]`      | string         | yes      | Base commit SHA in the source branch |
@@ -844,9 +844,9 @@ Parameters:
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment
 ```
 
-### Resolve a merge request discussion
+### Resolve a merge request thread
 
-Resolve/unresolve whole discussion of a merge request.
+Resolve/unresolve whole thread of a merge request.
 
 ```
 PUT /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id
@@ -858,17 +858,17 @@ Parameters:
 | ------------------- | -------------- | -------- | ----------- |
 | `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `merge_request_iid` | integer        | yes      | The IID of a merge request |
-| `discussion_id`     | integer        | yes      | The ID of a discussion |
+| `discussion_id`     | integer        | yes      | The ID of a thread |
 | `resolved`          | boolean        | yes      | Resolve/unresolve the discussion |
 
 ```bash
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7?resolved=true
 ```
 
-### Add note to existing merge request discussion
+### Add note to existing merge request thread
 
-Adds a new note to the discussion. This can also
-[create a discussion from a single comment](../user/discussions/#start-a-discussion-by-replying-to-a-standard-comment).
+Adds a new note to the thread. This can also
+[create a thread from a single comment](../user/discussions/#start-a-thread-by-replying-to-a-standard-comment).
 
 ```
 POST /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id/notes
@@ -880,18 +880,18 @@ Parameters:
 | ------------------- | -------------- | -------- | ----------- |
 | `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `merge_request_iid` | integer        | yes      | The IID of a merge request |
-| `discussion_id`     | integer        | yes      | The ID of a discussion |
-| `note_id`           | integer        | yes      | The ID of a discussion note |
-| `body`              | string         | yes      | The content of a discussion |
+| `discussion_id`     | integer        | yes      | The ID of a thread |
+| `note_id`           | integer        | yes      | The ID of a thread note |
+| `body`              | string         | yes      | The content of the note/reply |
 | `created_at`        | string         | no       | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment
 ```
 
-### Modify an existing merge request discussion note
+### Modify an existing merge request thread note
 
-Modify or resolve an existing discussion note of a merge request.
+Modify or resolve an existing thread note of a merge request.
 
 ```
 PUT /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id/notes/:note_id
@@ -903,9 +903,9 @@ Parameters:
 | ------------------- | -------------- | -------- | ----------- |
 | `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `merge_request_iid` | integer        | yes      | The IID of a merge request |
-| `discussion_id`     | integer        | yes      | The ID of a discussion |
-| `note_id`           | integer        | yes      | The ID of a discussion note |
-| `body`              | string         | no       | The content of a discussion (exactly one of `body` or `resolved` must be set |
+| `discussion_id`     | integer        | yes      | The ID of a thread |
+| `note_id`           | integer        | yes      | The ID of a thread note |
+| `body`              | string         | no       | The content of the note/reply (exactly one of `body` or `resolved` must be set |
 | `resolved`          | boolean        | no       | Resolve/unresolve the note (exactly one of `body` or `resolved` must be set |
 
 ```bash
@@ -918,9 +918,9 @@ Resolving a note:
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true
 ```
 
-### Delete a merge request discussion note
+### Delete a merge request thread note
 
-Deletes an existing discussion note of a merge request.
+Deletes an existing thread note of a merge request.
 
 ```
 DELETE /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id/notes/:note_id
@@ -932,8 +932,8 @@ Parameters:
 | ------------------- | -------------- | -------- | ----------- |
 | `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `merge_request_iid` | integer        | yes      | The IID of a merge request |
-| `discussion_id`     | integer        | yes      | The ID of a discussion |
-| `note_id`           | integer        | yes      | The ID of a discussion note |
+| `discussion_id`     | integer        | yes      | The ID of a thread |
+| `note_id`           | integer        | yes      | The ID of a thread note |
 
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636
@@ -941,9 +941,9 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitl
 
 ## Commits
 
-### List project commit discussions
+### List project commit discussion items
 
-Gets a list of all discussions for a single commit.
+Gets a list of all discussion items for a single commit.
 
 ```
 GET /projects/:id/commits/:commit_id/discussions
@@ -1082,9 +1082,9 @@ Diff comments contain also position:
 curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions
 ```
 
-### Get single commit discussion
+### Get single commit discussion item
 
-Returns a single discussion for a specific project commit
+Returns a single discussion item for a specific project commit
 
 ```
 GET /projects/:id/commits/:commit_id/discussions/:discussion_id
@@ -1096,15 +1096,15 @@ Parameters:
 | ------------------- | -------------- | -------- | ----------- |
 | `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `commit_id`         | integer        | yes      | The ID of a commit |
-| `discussion_id`     | integer        | yes      | The ID of a discussion |
+| `discussion_id`     | integer        | yes      | The ID of a discussion item |
 
 ```bash
 curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
 ```
 
-### Create new commit discussion
+### Create new commit thread
 
-Creates a new discussion to a single project commit. This is similar to creating
+Creates a new thread to a single project commit. This is similar to creating
 a note but other comments (replies) can be added to it later.
 
 ```
@@ -1117,7 +1117,7 @@ Parameters:
 | ------------------------- | -------------- | -------- | ----------- |
 | `id`                      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `commit_id`               | integer        | yes      | The ID of a commit |
-| `body`                    | string         | yes      | The content of a discussion |
+| `body`                    | string         | yes      | The content of the thread |
 | `created_at`              | string         | no       | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
 | `position`                | hash           | no       | Position when creating a diff note |
 | `position[base_sha]`      | string         | yes      | Base commit SHA in the source branch |
@@ -1137,9 +1137,9 @@ Parameters:
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment
 ```
 
-### Add note to existing commit discussion
+### Add note to existing commit thread
 
-Adds a new note to the discussion.
+Adds a new note to the thread.
 
 ```
 POST /projects/:id/commits/:commit_id/discussions/:discussion_id/notes
@@ -1151,18 +1151,18 @@ Parameters:
 | ------------------- | -------------- | -------- | ----------- |
 | `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `commit_id`         | integer        | yes      | The ID of a commit |
-| `discussion_id`     | integer        | yes      | The ID of a discussion |
-| `note_id`           | integer        | yes      | The ID of a discussion note |
-| `body`              | string         | yes      | The content of a discussion |
+| `discussion_id`     | integer        | yes      | The ID of a thread |
+| `note_id`           | integer        | yes      | The ID of a thread note |
+| `body`              | string         | yes      | The content of the note/reply |
 | `created_at`        | string         | no       | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment
 ```
 
-### Modify an existing commit discussion note
+### Modify an existing commit thread note
 
-Modify or resolve an existing discussion note of a commit.
+Modify or resolve an existing thread note of a commit.
 
 ```
 PUT /projects/:id/commits/:commit_id/discussions/:discussion_id/notes/:note_id
@@ -1174,8 +1174,8 @@ Parameters:
 | ------------------- | -------------- | -------- | ----------- |
 | `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `commit_id`         | integer        | yes      | The ID of a commit |
-| `discussion_id`     | integer        | yes      | The ID of a discussion |
-| `note_id`           | integer        | yes      | The ID of a discussion note |
+| `discussion_id`     | integer        | yes      | The ID of a thread |
+| `note_id`           | integer        | yes      | The ID of a thread note |
 | `body`              | string         | no       | The content of a note |
 
 ```bash
@@ -1188,9 +1188,9 @@ Resolving a note:
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true
 ```
 
-### Delete a commit discussion note
+### Delete a commit thread note
 
-Deletes an existing discussion note of a commit.
+Deletes an existing thread note of a commit.
 
 ```
 DELETE /projects/:id/commits/:commit_id/discussions/:discussion_id/notes/:note_id
@@ -1202,8 +1202,8 @@ Parameters:
 | ------------------- | -------------- | -------- | ----------- |
 | `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `commit_id`         | integer        | yes      | The ID of a commit |
-| `discussion_id`     | integer        | yes      | The ID of a discussion |
-| `note_id`           | integer        | yes      | The ID of a discussion note |
+| `discussion_id`     | integer        | yes      | The ID of a thread |
+| `note_id`           | integer        | yes      | The ID of a thread note |
 
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/636
diff --git a/doc/api/environments.md b/doc/api/environments.md
index ebcdc546d08..44f86861ff7 100644
--- a/doc/api/environments.md
+++ b/doc/api/environments.md
@@ -11,9 +11,11 @@ GET /projects/:id/environments
 | Attribute | Type    | Required | Description           |
 | --------- | ------- | -------- | --------------------- |
 | `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `name`    | string  | no       | Return the environment with this name. Mutually exclusive with `search` |
+| `search`  | string  | no       | Return list of environments matching the search criteria. Mutually exclusive with `name` |
 
 ```bash
-curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/environments
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/environments?name=review%2Ffix-foo
 ```
 
 Example response:
diff --git a/doc/api/epic_issues.md b/doc/api/epic_issues.md
index ec59ea7068e..02317cc6c09 100644
--- a/doc/api/epic_issues.md
+++ b/doc/api/epic_issues.md
@@ -1,4 +1,4 @@
-# Epic Issues API **[ULTIMATE]**
+# Epic Issues API **(ULTIMATE)**
 
 Every API call to epic_issues must be authenticated.
 
diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md
index 9ad90a6d0f1..6089198e46a 100644
--- a/doc/api/epic_links.md
+++ b/doc/api/epic_links.md
@@ -1,4 +1,4 @@
-# Epic Links API **[ULTIMATE]**
+# Epic Links API **(ULTIMATE)**
 
 >**Note:**
 > This endpoint was [introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9188) in GitLab 11.8.
diff --git a/doc/api/epics.md b/doc/api/epics.md
index 0541cfaa715..3036b3c2364 100644
--- a/doc/api/epics.md
+++ b/doc/api/epics.md
@@ -1,4 +1,4 @@
-# Epics API **[ULTIMATE]**
+# Epics API **(ULTIMATE)**
 
 Every API call to epic must be authenticated.
 
@@ -10,7 +10,7 @@ If epics feature is not available a `403` status code will be returned.
 
 The [epic issues API](epic_issues.md) allows you to interact with issues associated with an epic.
 
-# Milestone dates integration
+## Milestone dates integration
 
 > [Introduced][ee-6448] in GitLab 11.3.
 
@@ -302,7 +302,7 @@ POST /groups/:id/epics/:epic_iid/todo
 | Attribute   | Type    | Required | Description                          |
 |-------------|---------|----------|--------------------------------------|
 | `id`        | integer/string | yes   | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user  |
-| `epic_iid ` | integer | yes          | The internal ID of a group's epic |
+| `epic_iid` | integer | yes          | The internal ID of a group's epic |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/epics/5/todo
diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md
index ea31abdd87e..d0b33ab467f 100644
--- a/doc/api/geo_nodes.md
+++ b/doc/api/geo_nodes.md
@@ -1,4 +1,4 @@
-# Geo Nodes API **[PREMIUM ONLY]**
+# Geo Nodes API **(PREMIUM ONLY)**
 
 In order to interact with Geo node endpoints, you need to authenticate yourself
 as an admin.
@@ -10,7 +10,7 @@ GET /geo_nodes
 ```
 
 ```bash
-curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/geo_nodes
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://primary.example.com/api/v4/geo_nodes
 ```
 
 Example response:
@@ -27,8 +27,15 @@ Example response:
     "current": true,
     "files_max_capacity": 10,
     "repos_max_capacity": 25,
+    "container_repositories_max_capacity": 10,
     "verification_max_capacity": 100,
-    "clone_protocol": "http"
+    "clone_protocol": "http",
+    "web_edit_url": "https://primary.example.com/admin/geo/nodes/1/edit",
+    "_links": {
+      "self": "https://primary.example.com/api/v4/geo_nodes/1",
+      "status":"https://primary.example.com/api/v4/geo_nodes/1/status",
+      "repair":"https://primary.example.com/api/v4/geo_nodes/1/repair"
+    }
   },
   {
     "id": 2,
@@ -40,8 +47,17 @@ Example response:
     "current": false,
     "files_max_capacity": 10,
     "repos_max_capacity": 25,
+    "container_repositories_max_capacity": 10,
     "verification_max_capacity": 100,
-    "clone_protocol": "http"
+    "sync_object_storage": true,
+    "clone_protocol": "http",
+    "web_edit_url": "https://primary.example.com/admin/geo/nodes/2/edit",
+    "web_geo_projects_url": "https://secondary.example.com/admin/geo/projects",
+    "_links": {
+      "self":"https://primary.example.com/api/v4/geo_nodes/2",
+      "status":"https://primary.example.com/api/v4/geo_nodes/2/status",
+      "repair":"https://primary.example.com/api/v4/geo_nodes/2/repair"
+    }
   }
 ]
 ```
@@ -53,7 +69,7 @@ GET /geo_nodes/:id
 ```
 
 ```bash
-curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/geo_nodes/1
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://primary.example.com/api/v4/geo_nodes/1
 ```
 
 Example response:
@@ -69,8 +85,15 @@ Example response:
   "current": true,
   "files_max_capacity": 10,
   "repos_max_capacity": 25,
+  "container_repositories_max_capacity": 10,
   "verification_max_capacity": 100,
-  "clone_protocol": "http"
+  "clone_protocol": "http",
+  "web_edit_url": "https://primary.example.com/admin/geo/nodes/1/edit",
+  "_links": {
+    "self": "https://primary.example.com/api/v4/geo_nodes/1",
+    "status":"https://primary.example.com/api/v4/geo_nodes/1/status",
+    "repair":"https://primary.example.com/api/v4/geo_nodes/1/repair"
+  }
 }
 ```
 
@@ -84,16 +107,18 @@ _This can only be run against a primary Geo node._
 PUT /geo_nodes/:id
 ```
 
-| Attribute            | Type    | Required  | Description                                                               |
-|----------------------|---------|-----------|---------------------------------------------------------------------------|
-| `id`                 | integer | yes       | The ID of the Geo node.                                                   |
-| `enabled`            | boolean | no        | Flag indicating if the Geo node is enabled.                               |
-| `name`               | string  | yes       | The unique identifier for the Geo node. Must match `geo_node_name` if it is set in gitlab.rb, otherwise it must match `external_url`. |
-| `url`                | string  | yes       | The user-facing URL of the Geo node. |
-| `internal_url`       | string  | no        | The URL defined on the primary node that secondary nodes should use to contact it. Returns `url` if not set.|
-| `files_max_capacity` | integer | no        | Control the maximum concurrency of LFS/attachment backfill for this secondary node. |
-| `repos_max_capacity` | integer | no        | Control the maximum concurrency of repository backfill for this secondary node.     |
-| `verification_max_capacity` | integer | no | Control the maximum concurrency of verification for this node. |
+| Attribute                   | Type    | Required  | Description                                                               |
+|-----------------------------|---------|-----------|---------------------------------------------------------------------------|
+| `id`                        | integer | yes       | The ID of the Geo node.                                                   |
+| `enabled`                   | boolean | no        | Flag indicating if the Geo node is enabled.                               |
+| `name`                      | string  | yes       | The unique identifier for the Geo node. Must match `geo_node_name` if it is set in gitlab.rb, otherwise it must match `external_url`. |
+| `url`                       | string  | yes       | The user-facing URL of the Geo node. |
+| `internal_url`              | string  | no        | The URL defined on the primary node that secondary nodes should use to contact it. Returns `url` if not set.|
+| `files_max_capacity`        | integer | no        | Control the maximum concurrency of LFS/attachment backfill for this secondary node. |
+| `repos_max_capacity`        | integer | no        | Control the maximum concurrency of repository backfill for this secondary node.     |
+| `verification_max_capacity` | integer | no        | Control the maximum concurrency of verification for this node. |
+| `container_repositories_max_capacity` | integer | no | Control the maximum concurrency of container repository sync for this node. |
+| `sync_object_storage`       | boolean | no        | Flag indicating if the secondary Geo node will replicate blobs in Object Storage. |
 
 Example response:
 
@@ -108,8 +133,17 @@ Example response:
   "current": true,
   "files_max_capacity": 10,
   "repos_max_capacity": 25,
+  "container_repositories_max_capacity": 10,
   "verification_max_capacity": 100,
-  "clone_protocol": "http"
+  "sync_object_storage": true,
+  "clone_protocol": "http",
+  "web_edit_url": "https://primary.example.com/admin/geo/nodes/2/edit",
+  "web_geo_projects_url": "https://secondary.example.com/admin/geo/projects",
+  "_links": {
+    "self":"https://primary.example.com/api/v4/geo_nodes/2",
+    "status":"https://primary.example.com/api/v4/geo_nodes/2/status",
+    "repair":"https://primary.example.com/api/v4/geo_nodes/2/repair"
+  }
 }
 ```
 
@@ -151,8 +185,15 @@ Example response:
   "current": true,
   "files_max_capacity": 10,
   "repos_max_capacity": 25,
+  "container_repositories_max_capacity": 10,
   "verification_max_capacity": 100,
-  "clone_protocol": "http"
+  "clone_protocol": "http",
+  "web_edit_url": "https://primary.example.com/admin/geo/nodes/1/edit",
+  "_links": {
+    "self": "https://primary.example.com/api/v4/geo_nodes/1",
+    "status":"https://primary.example.com/api/v4/geo_nodes/1/status",
+    "repair":"https://primary.example.com/api/v4/geo_nodes/1/repair"
+  }
 }
 ```
 
@@ -163,7 +204,7 @@ GET /geo_nodes/status
 ```
 
 ```bash
-curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/geo_nodes/status
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://primary.example.com/api/v4/geo_nodes/status
 ```
 
 Example response:
@@ -192,6 +233,10 @@ Example response:
     "job_artifacts_failed_count": nil,
     "job_artifacts_synced_missing_on_primary_count": 0,
     "job_artifacts_synced_in_percentage": "0.00%",
+    "container_repositories_count": 3,
+    "container_repositories_synced_count": nil,
+    "container_repositories_failed_count": nil,
+    "container_repositories_synced_in_percentage": "0.00%",
     "projects_count": 41,
     "repositories_failed_count": nil,
     "repositories_synced_count": nil,
@@ -255,6 +300,10 @@ Example response:
     "job_artifacts_failed_count": 1,
     "job_artifacts_synced_missing_on_primary_count": 0,
     "job_artifacts_synced_in_percentage": "50.00%",
+    "container_repositories_count": 3,
+    "container_repositories_synced_count": nil,
+    "container_repositories_failed_count": nil,
+    "container_repositories_synced_in_percentage": "0.00%",
     "projects_count": 41,
     "repositories_failed_count": 1,
     "repositories_synced_count": 40,
@@ -306,7 +355,7 @@ GET /geo_nodes/:id/status
 ```
 
 ```bash
-curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/geo_nodes/2/status
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://primary.example.com/api/v4/geo_nodes/2/status
 ```
 
 Example response:
@@ -334,6 +383,10 @@ Example response:
   "job_artifacts_failed_count": 1,
   "job_artifacts_synced_missing_on_primary_count": 0,
   "job_artifacts_synced_in_percentage": "50.00%",
+  "container_repositories_count": 3,
+  "container_repositories_synced_count": nil,
+  "container_repositories_failed_count": nil,
+  "container_repositories_synced_in_percentage": "0.00%",
   "projects_count": 41,
   "repositories_failed_count": 1,
   "repositories_synced_count": 40,
@@ -376,7 +429,7 @@ GET /geo_nodes/current/failures
 This endpoint uses [Pagination](README.md#pagination).
 
 ```bash
-curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/geo_nodes/current/failures
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://primary.example.com/api/v4/geo_nodes/current/failures
 ```
 
 Example response:
diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md
index 88e657a5d2f..bdc7c1959d2 100644
--- a/doc/api/graphql/index.md
+++ b/doc/api/graphql/index.md
@@ -1,6 +1,8 @@
-# GraphQL API (Alpha)
+# GraphQL API
 
-> [Introduced][ce-19008] in GitLab 11.0.
+> - [Introduced][ce-19008] in GitLab 11.0 (enabled by feature flag `graphql`).
+> - [Always enabled](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30444)
+  in GitLab 12.1.
 
 [GraphQL](https://graphql.org/) is a query language for APIs that
 allows clients to request exactly the data they need, making it
@@ -23,30 +25,18 @@ programmatically with GitLab. To achieve this, it needs full coverage - anything
 possible in the REST API should also be possible in the GraphQL API.
 
 To help us meet this vision, the frontend should use GraphQL in preference to
-the REST API for new features, although the alpha status of GraphQL may prevent
-this from being a possibility at times.
+the REST API for new features.
 
 There are no plans to deprecate the REST API. To reduce the technical burden of
 supporting two APIs in parallel, they should share implementations as much as
 possible.
 
-## Enabling the GraphQL feature
-
-The GraphQL API itself is currently in Alpha, and therefore hidden behind a
-feature flag. You can enable the feature using the [features api][features-api] on a self-hosted instance.
-
-For example:
-
-```shell
-curl --data "value=100" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/features/graphql
-```
-
 ## Available queries
 
 A first iteration of a GraphQL API includes the following queries
 
 1. `project` : Within a project it is also possible to fetch a `mergeRequest` by IID.
-1. `group` : Only basic group information is currently supported.
+1. `group` : Basic group information and epics **(ULTIMATE)** are currently supported.
 1. `namespace` : Within a namespace it is also possible to fetch `projects`.
 
 ### Multiplex queries
@@ -57,6 +47,12 @@ info about multiplexed queries is also available for
 [graphql-ruby](https://graphql-ruby.org/queries/multiplex.html) the
 library GitLab uses on the backend.
 
+## Reference
+
+GitLab's GraphQL reference [is available](reference/index.md).
+
+It is automatically generated from GitLab's GraphQL schema and embedded in a Markdown file.
+
 ## GraphiQL
 
 The API can be explored by using the GraphiQL IDE, it is available on your
diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md
new file mode 100644
index 00000000000..2d3bec4ff67
--- /dev/null
+++ b/doc/api/graphql/reference/index.md
@@ -0,0 +1,507 @@
+<!---
+  This documentation is auto generated by a script.
+
+  Please do not edit this file directly, check compile_docs task on lib/tasks/gitlab/graphql.rake.
+--->
+
+# GraphQL API Resources
+
+This documentation is self-generated based on GitLab current GraphQL schema.
+
+The API can be explored interactively using the [GraphiQL IDE](../index.md#graphiql).
+
+## Objects
+
+### AddAwardEmojiPayload
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
+| `errors` | String! => Array | Reasons why the mutation failed. |
+| `awardEmoji` | AwardEmoji | The award emoji after mutation |
+
+### AwardEmoji
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `name` | String! | The emoji name |
+| `description` | String! | The emoji description |
+| `unicode` | String! | The emoji in unicode |
+| `emoji` | String! | The emoji as an icon |
+| `unicodeVersion` | String! | The unicode version for this emoji |
+| `user` | User! | The user who awarded the emoji |
+
+### Blob
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `id` | ID! |  |
+| `name` | String! |  |
+| `type` | EntryType! |  |
+| `path` | String! |  |
+| `flatPath` | String! |  |
+| `webUrl` | String |  |
+| `lfsOid` | String |  |
+
+### Commit
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `id` | ID! |  |
+| `sha` | String! |  |
+| `title` | String |  |
+| `description` | String |  |
+| `message` | String |  |
+| `authoredDate` | Time |  |
+| `webUrl` | String! |  |
+| `author` | User |  |
+| `latestPipeline` | Pipeline | Latest pipeline for this commit |
+
+### DetailedStatus
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `group` | String! |  |
+| `icon` | String! |  |
+| `favicon` | String! |  |
+| `detailsPath` | String! |  |
+| `hasDetails` | Boolean! |  |
+| `label` | String! |  |
+| `text` | String! |  |
+| `tooltip` | String! |  |
+
+### DiffPosition
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `headSha` | String! | The sha of the head at the time the comment was made |
+| `baseSha` | String | The merge base of the branch the comment was made on |
+| `startSha` | String! | The sha of the branch being compared against |
+| `filePath` | String! | The path of the file that was changed |
+| `oldPath` | String | The path of the file on the start sha. |
+| `newPath` | String | The path of the file on the head sha. |
+| `positionType` | DiffPositionType! |  |
+| `oldLine` | Int | The line on start sha that was changed |
+| `newLine` | Int | The line on head sha that was changed |
+| `x` | Int | The X postion on which the comment was made |
+| `y` | Int | The Y position on which the comment was made |
+| `width` | Int | The total width of the image |
+| `height` | Int | The total height of the image |
+
+### Discussion
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `id` | ID! |  |
+| `createdAt` | Time! |  |
+
+### Group
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `id` | ID! |  |
+| `name` | String! |  |
+| `path` | String! |  |
+| `fullName` | String! |  |
+| `fullPath` | ID! |  |
+| `description` | String |  |
+| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
+| `visibility` | String |  |
+| `lfsEnabled` | Boolean |  |
+| `requestAccessEnabled` | Boolean |  |
+| `userPermissions` | GroupPermissions! | Permissions for the current user on the resource |
+| `webUrl` | String! |  |
+| `avatarUrl` | String |  |
+| `parent` | Group |  |
+
+### GroupPermissions
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `readGroup` | Boolean! | Whether or not a user can perform `read_group` on this resource |
+
+### Issue
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `userPermissions` | IssuePermissions! | Permissions for the current user on the resource |
+| `iid` | ID! |  |
+| `title` | String! |  |
+| `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` |
+| `description` | String |  |
+| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
+| `state` | IssueState! |  |
+| `reference` | String! |  |
+| `author` | User! |  |
+| `milestone` | Milestone |  |
+| `dueDate` | Time |  |
+| `confidential` | Boolean! |  |
+| `discussionLocked` | Boolean! |  |
+| `upvotes` | Int! |  |
+| `downvotes` | Int! |  |
+| `userNotesCount` | Int! |  |
+| `webPath` | String! |  |
+| `webUrl` | String! |  |
+| `relativePosition` | Int |  |
+| `closedAt` | Time |  |
+| `createdAt` | Time! |  |
+| `updatedAt` | Time! |  |
+| `taskCompletionStatus` | TaskCompletionStatus! |  |
+
+### IssuePermissions
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `readIssue` | Boolean! | Whether or not a user can perform `read_issue` on this resource |
+| `adminIssue` | Boolean! | Whether or not a user can perform `admin_issue` on this resource |
+| `updateIssue` | Boolean! | Whether or not a user can perform `update_issue` on this resource |
+| `createNote` | Boolean! | Whether or not a user can perform `create_note` on this resource |
+| `reopenIssue` | Boolean! | Whether or not a user can perform `reopen_issue` on this resource |
+
+### Label
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `description` | String |  |
+| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
+| `title` | String! |  |
+| `color` | String! |  |
+| `textColor` | String! |  |
+
+### MergeRequest
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `userPermissions` | MergeRequestPermissions! | Permissions for the current user on the resource |
+| `id` | ID! |  |
+| `iid` | String! |  |
+| `title` | String! |  |
+| `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` |
+| `description` | String |  |
+| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
+| `state` | MergeRequestState! |  |
+| `createdAt` | Time! |  |
+| `updatedAt` | Time! |  |
+| `sourceProject` | Project |  |
+| `targetProject` | Project! |  |
+| `project` | Project! |  |
+| `projectId` | Int! |  |
+| `sourceProjectId` | Int |  |
+| `targetProjectId` | Int! |  |
+| `sourceBranch` | String! |  |
+| `targetBranch` | String! |  |
+| `workInProgress` | Boolean! |  |
+| `mergeWhenPipelineSucceeds` | Boolean |  |
+| `diffHeadSha` | String |  |
+| `mergeCommitSha` | String |  |
+| `userNotesCount` | Int |  |
+| `shouldRemoveSourceBranch` | Boolean |  |
+| `forceRemoveSourceBranch` | Boolean |  |
+| `mergeStatus` | String |  |
+| `inProgressMergeCommitSha` | String |  |
+| `mergeError` | String |  |
+| `allowCollaboration` | Boolean |  |
+| `shouldBeRebased` | Boolean! |  |
+| `rebaseCommitSha` | String |  |
+| `rebaseInProgress` | Boolean! |  |
+| `mergeCommitMessage` | String |  |
+| `defaultMergeCommitMessage` | String |  |
+| `mergeOngoing` | Boolean! |  |
+| `sourceBranchExists` | Boolean! |  |
+| `mergeableDiscussionsState` | Boolean |  |
+| `webUrl` | String |  |
+| `upvotes` | Int! |  |
+| `downvotes` | Int! |  |
+| `subscribed` | Boolean! |  |
+| `headPipeline` | Pipeline |  |
+| `taskCompletionStatus` | TaskCompletionStatus! |  |
+
+### MergeRequestPermissions
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `readMergeRequest` | Boolean! | Whether or not a user can perform `read_merge_request` on this resource |
+| `adminMergeRequest` | Boolean! | Whether or not a user can perform `admin_merge_request` on this resource |
+| `updateMergeRequest` | Boolean! | Whether or not a user can perform `update_merge_request` on this resource |
+| `createNote` | Boolean! | Whether or not a user can perform `create_note` on this resource |
+| `pushToSourceBranch` | Boolean! | Whether or not a user can perform `push_to_source_branch` on this resource |
+| `removeSourceBranch` | Boolean! | Whether or not a user can perform `remove_source_branch` on this resource |
+| `cherryPickOnCurrentMergeRequest` | Boolean! | Whether or not a user can perform `cherry_pick_on_current_merge_request` on this resource |
+| `revertOnCurrentMergeRequest` | Boolean! | Whether or not a user can perform `revert_on_current_merge_request` on this resource |
+
+### MergeRequestSetWipPayload
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
+| `errors` | String! => Array | Reasons why the mutation failed. |
+| `mergeRequest` | MergeRequest | The merge request after mutation |
+
+### Metadata
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `version` | String! |  |
+| `revision` | String! |  |
+
+### Milestone
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `description` | String |  |
+| `title` | String! |  |
+| `state` | String! |  |
+| `dueDate` | Time |  |
+| `startDate` | Time |  |
+| `createdAt` | Time! |  |
+| `updatedAt` | Time! |  |
+
+### Namespace
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `id` | ID! |  |
+| `name` | String! |  |
+| `path` | String! |  |
+| `fullName` | String! |  |
+| `fullPath` | ID! |  |
+| `description` | String |  |
+| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
+| `visibility` | String |  |
+| `lfsEnabled` | Boolean |  |
+| `requestAccessEnabled` | Boolean |  |
+
+### Note
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `userPermissions` | NotePermissions! | Permissions for the current user on the resource |
+| `id` | ID! |  |
+| `project` | Project | The project this note is associated to |
+| `author` | User! | The user who wrote this note |
+| `resolvedBy` | User | The user that resolved the discussion |
+| `system` | Boolean! | Whether or not this note was created by the system or by a user |
+| `body` | String! | The content note itself |
+| `bodyHtml` | String | The GitLab Flavored Markdown rendering of `note` |
+| `createdAt` | Time! |  |
+| `updatedAt` | Time! |  |
+| `discussion` | Discussion | The discussion this note is a part of |
+| `resolvable` | Boolean! |  |
+| `resolvedAt` | Time | The time the discussion was resolved |
+| `position` | DiffPosition | The position of this note on a diff |
+
+### NotePermissions
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `readNote` | Boolean! | Whether or not a user can perform `read_note` on this resource |
+| `createNote` | Boolean! | Whether or not a user can perform `create_note` on this resource |
+| `adminNote` | Boolean! | Whether or not a user can perform `admin_note` on this resource |
+| `resolveNote` | Boolean! | Whether or not a user can perform `resolve_note` on this resource |
+| `awardEmoji` | Boolean! | Whether or not a user can perform `award_emoji` on this resource |
+
+### PageInfo
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `hasNextPage` | Boolean! | When paginating forwards, are there more items? |
+| `hasPreviousPage` | Boolean! | When paginating backwards, are there more items? |
+| `startCursor` | String | When paginating backwards, the cursor to continue. |
+| `endCursor` | String | When paginating forwards, the cursor to continue. |
+
+### Pipeline
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `userPermissions` | PipelinePermissions! | Permissions for the current user on the resource |
+| `id` | ID! |  |
+| `iid` | String! |  |
+| `sha` | String! |  |
+| `beforeSha` | String |  |
+| `status` | PipelineStatusEnum! |  |
+| `detailedStatus` | DetailedStatus! |  |
+| `duration` | Int | Duration of the pipeline in seconds |
+| `coverage` | Float | Coverage percentage |
+| `createdAt` | Time! |  |
+| `updatedAt` | Time! |  |
+| `startedAt` | Time |  |
+| `finishedAt` | Time |  |
+| `committedAt` | Time |  |
+
+### PipelinePermissions
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `updatePipeline` | Boolean! | Whether or not a user can perform `update_pipeline` on this resource |
+| `adminPipeline` | Boolean! | Whether or not a user can perform `admin_pipeline` on this resource |
+| `destroyPipeline` | Boolean! | Whether or not a user can perform `destroy_pipeline` on this resource |
+
+### Project
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `userPermissions` | ProjectPermissions! | Permissions for the current user on the resource |
+| `id` | ID! |  |
+| `fullPath` | ID! |  |
+| `path` | String! |  |
+| `nameWithNamespace` | String! |  |
+| `name` | String! |  |
+| `description` | String |  |
+| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
+| `tagList` | String |  |
+| `sshUrlToRepo` | String |  |
+| `httpUrlToRepo` | String |  |
+| `webUrl` | String |  |
+| `starCount` | Int! |  |
+| `forksCount` | Int! |  |
+| `createdAt` | Time |  |
+| `lastActivityAt` | Time |  |
+| `archived` | Boolean |  |
+| `visibility` | String |  |
+| `containerRegistryEnabled` | Boolean |  |
+| `sharedRunnersEnabled` | Boolean |  |
+| `lfsEnabled` | Boolean |  |
+| `mergeRequestsFfOnlyEnabled` | Boolean |  |
+| `avatarUrl` | String |  |
+| `issuesEnabled` | Boolean |  |
+| `mergeRequestsEnabled` | Boolean |  |
+| `wikiEnabled` | Boolean |  |
+| `snippetsEnabled` | Boolean |  |
+| `jobsEnabled` | Boolean |  |
+| `publicJobs` | Boolean |  |
+| `openIssuesCount` | Int |  |
+| `importStatus` | String |  |
+| `onlyAllowMergeIfPipelineSucceeds` | Boolean |  |
+| `requestAccessEnabled` | Boolean |  |
+| `onlyAllowMergeIfAllDiscussionsAreResolved` | Boolean |  |
+| `printingMergeRequestLinkEnabled` | Boolean |  |
+| `namespace` | Namespace |  |
+| `group` | Group |  |
+| `statistics` | ProjectStatistics |  |
+| `repository` | Repository |  |
+| `mergeRequest` | MergeRequest |  |
+| `issue` | Issue |  |
+
+### ProjectPermissions
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `changeNamespace` | Boolean! | Whether or not a user can perform `change_namespace` on this resource |
+| `changeVisibilityLevel` | Boolean! | Whether or not a user can perform `change_visibility_level` on this resource |
+| `renameProject` | Boolean! | Whether or not a user can perform `rename_project` on this resource |
+| `removeProject` | Boolean! | Whether or not a user can perform `remove_project` on this resource |
+| `archiveProject` | Boolean! | Whether or not a user can perform `archive_project` on this resource |
+| `removeForkProject` | Boolean! | Whether or not a user can perform `remove_fork_project` on this resource |
+| `removePages` | Boolean! | Whether or not a user can perform `remove_pages` on this resource |
+| `readProject` | Boolean! | Whether or not a user can perform `read_project` on this resource |
+| `createMergeRequestIn` | Boolean! | Whether or not a user can perform `create_merge_request_in` on this resource |
+| `readWiki` | Boolean! | Whether or not a user can perform `read_wiki` on this resource |
+| `readProjectMember` | Boolean! | Whether or not a user can perform `read_project_member` on this resource |
+| `createIssue` | Boolean! | Whether or not a user can perform `create_issue` on this resource |
+| `uploadFile` | Boolean! | Whether or not a user can perform `upload_file` on this resource |
+| `readCycleAnalytics` | Boolean! | Whether or not a user can perform `read_cycle_analytics` on this resource |
+| `downloadCode` | Boolean! | Whether or not a user can perform `download_code` on this resource |
+| `downloadWikiCode` | Boolean! | Whether or not a user can perform `download_wiki_code` on this resource |
+| `forkProject` | Boolean! | Whether or not a user can perform `fork_project` on this resource |
+| `createProjectSnippet` | Boolean! | Whether or not a user can perform `create_project_snippet` on this resource |
+| `readCommitStatus` | Boolean! | Whether or not a user can perform `read_commit_status` on this resource |
+| `requestAccess` | Boolean! | Whether or not a user can perform `request_access` on this resource |
+| `createPipeline` | Boolean! | Whether or not a user can perform `create_pipeline` on this resource |
+| `createPipelineSchedule` | Boolean! | Whether or not a user can perform `create_pipeline_schedule` on this resource |
+| `createMergeRequestFrom` | Boolean! | Whether or not a user can perform `create_merge_request_from` on this resource |
+| `createWiki` | Boolean! | Whether or not a user can perform `create_wiki` on this resource |
+| `pushCode` | Boolean! | Whether or not a user can perform `push_code` on this resource |
+| `createDeployment` | Boolean! | Whether or not a user can perform `create_deployment` on this resource |
+| `pushToDeleteProtectedBranch` | Boolean! | Whether or not a user can perform `push_to_delete_protected_branch` on this resource |
+| `adminWiki` | Boolean! | Whether or not a user can perform `admin_wiki` on this resource |
+| `adminProject` | Boolean! | Whether or not a user can perform `admin_project` on this resource |
+| `updatePages` | Boolean! | Whether or not a user can perform `update_pages` on this resource |
+| `adminRemoteMirror` | Boolean! | Whether or not a user can perform `admin_remote_mirror` on this resource |
+| `createLabel` | Boolean! | Whether or not a user can perform `create_label` on this resource |
+| `updateWiki` | Boolean! | Whether or not a user can perform `update_wiki` on this resource |
+| `destroyWiki` | Boolean! | Whether or not a user can perform `destroy_wiki` on this resource |
+| `createPages` | Boolean! | Whether or not a user can perform `create_pages` on this resource |
+| `destroyPages` | Boolean! | Whether or not a user can perform `destroy_pages` on this resource |
+| `readPagesContent` | Boolean! | Whether or not a user can perform `read_pages_content` on this resource |
+
+### ProjectStatistics
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `commitCount` | Int! |  |
+| `storageSize` | Int! |  |
+| `repositorySize` | Int! |  |
+| `lfsObjectsSize` | Int! |  |
+| `buildArtifactsSize` | Int! |  |
+| `packagesSize` | Int! |  |
+| `wikiSize` | Int |  |
+
+### RemoveAwardEmojiPayload
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
+| `errors` | String! => Array | Reasons why the mutation failed. |
+| `awardEmoji` | AwardEmoji | The award emoji after mutation |
+
+### Repository
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `rootRef` | String |  |
+| `empty` | Boolean! |  |
+| `exists` | Boolean! |  |
+| `tree` | Tree |  |
+
+### Submodule
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `id` | ID! |  |
+| `name` | String! |  |
+| `type` | EntryType! |  |
+| `path` | String! |  |
+| `flatPath` | String! |  |
+
+### TaskCompletionStatus
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `count` | Int! |  |
+| `completedCount` | Int! |  |
+
+### ToggleAwardEmojiPayload
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
+| `errors` | String! => Array | Reasons why the mutation failed. |
+| `awardEmoji` | AwardEmoji | The award emoji after mutation |
+| `toggledOn` | Boolean! | True when the emoji was awarded, false when it was removed |
+
+### Tree
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `lastCommit` | Commit |  |
+
+### TreeEntry
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `id` | ID! |  |
+| `name` | String! |  |
+| `type` | EntryType! |  |
+| `path` | String! |  |
+| `flatPath` | String! |  |
+| `webUrl` | String |  |
+
+### User
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `name` | String! |  |
+| `username` | String! |  |
+| `avatarUrl` | String! |  |
+| `webUrl` | String! |  |
+
diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md
index 9b0ac23b41c..4d10f83720b 100644
--- a/doc/api/group_boards.md
+++ b/doc/api/group_boards.md
@@ -5,7 +5,7 @@ Every API call to group boards must be authenticated.
 If a user is not a member of a group and the group is private, a `GET`
 request will result in `404` status code.
 
-## Group Board
+## List all group issue boards in a group
 
 Lists Issue Boards in the given group.
 
@@ -27,7 +27,68 @@ Example response:
 [
   {
     "id": 1,
-    "group_id": 5,
+    "name:": "group issue board",
+    "group": {
+      "id": 5,
+      "name": "Documentcloud",
+      "web_url": "http://example.com/groups/documentcloud"
+    },
+    "milestone":   {
+      "id": 12
+      "title": "10.0"
+    },
+    "lists" : [
+      {
+        "id" : 1,
+        "label" : {
+          "name" : "Testing",
+          "color" : "#F0AD4E",
+          "description" : null
+        },
+        "position" : 1
+      },
+      {
+        "id" : 2,
+        "label" : {
+          "name" : "Ready",
+          "color" : "#FF0000",
+          "description" : null
+        },
+        "position" : 2
+      },
+      {
+        "id" : 3,
+        "label" : {
+          "name" : "Production",
+          "color" : "#FF5F00",
+          "description" : null
+        },
+        "position" : 3
+      }
+    ]
+  }
+]
+```
+
+Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see
+different parameters, due to the ability to have multiple group boards.
+
+Example response:
+
+```json
+[
+  {
+    "id": 1,
+    "name:": "group issue board",
+    "group": {
+      "id": 5,
+      "name": "Documentcloud",
+      "web_url": "http://example.com/groups/documentcloud"
+    },
+    "milestone":   {
+      "id": 12
+      "title": "10.0"
+    },
     "lists" : [
       {
         "id" : 1,
@@ -61,9 +122,9 @@ Example response:
 ]
 ```
 
-## Single board
+## Single group issue board
 
-Gets a single board.
+Gets a single group issue board.
 
 ```
 GET /groups/:id/boards/:board_id
@@ -83,7 +144,66 @@ Example response:
 ```json
   {
     "id": 1,
-    "group_id": 5,
+    "name:": "group issue board",
+    "group": {
+      "id": 5,
+      "name": "Documentcloud",
+      "web_url": "http://example.com/groups/documentcloud"
+    },
+    "milestone":   {
+      "id": 12
+      "title": "10.0"
+    },
+    "lists" : [
+      {
+        "id" : 1,
+        "label" : {
+          "name" : "Testing",
+          "color" : "#F0AD4E",
+          "description" : null
+        },
+        "position" : 1
+      },
+      {
+        "id" : 2,
+        "label" : {
+          "name" : "Ready",
+          "color" : "#FF0000",
+          "description" : null
+        },
+        "position" : 2
+      },
+      {
+        "id" : 3,
+        "label" : {
+          "name" : "Production",
+          "color" : "#FF5F00",
+          "description" : null
+        },
+        "position" : 3
+      }
+    ]
+  }
+```
+
+Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see
+different parameters, due to the ability to have multiple group issue boards.s
+
+Example response:
+
+```json
+  {
+    "id": 1,
+    "name:": "group issue board",
+    "group": {
+      "id": 5,
+      "name": "Documentcloud",
+      "web_url": "http://example.com/groups/documentcloud"
+    },
+    "milestone":   {
+      "id": 12
+      "title": "10.0"
+    },
     "lists" : [
       {
         "id" : 1,
@@ -116,7 +236,156 @@ Example response:
   }
 ```
 
-## List board lists
+## Create a group issue board **(PREMIUM)**
+
+Creates a Group Issue Board.
+
+```
+POST /groups/:id/boards
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `name` | string | yes | The name of the new board |
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards?name=newboard
+```
+
+Example response:
+
+```json
+  {
+    "id": 1,
+    "name": "newboard",
+    "group": {
+      "id": 5,
+      "name": "Documentcloud",
+      "web_url": "http://example.com/groups/documentcloud"
+    },
+    "milestone":   {
+      "id": 12
+      "title": "10.0"
+    },
+    "lists" : [
+      {
+        "id" : 1,
+        "label" : {
+          "name" : "Testing",
+          "color" : "#F0AD4E",
+          "description" : null
+        },
+        "position" : 1
+      },
+      {
+        "id" : 2,
+        "label" : {
+          "name" : "Ready",
+          "color" : "#FF0000",
+          "description" : null
+        },
+        "position" : 2
+      },
+      {
+        "id" : 3,
+        "label" : {
+          "name" : "Production",
+          "color" : "#FF5F00",
+          "description" : null
+        },
+        "position" : 3
+      }
+    ]
+  }
+```
+
+## Update a group issue board **(PREMIUM)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5954) in GitLab 11.1.
+
+Updates a Group Issue Board.
+
+```
+PUT /groups/:id/boards/:board_id
+```
+
+| Attribute           | Type           | Required | Description |
+| ------------------- | -------------- | -------- | ----------- |
+| `id`                | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `board_id`          | integer        | yes      | The ID of a board |
+| `name`              | string         | no       | The new name of the board |
+| `assignee_id`       | integer        | no       | The assignee the board should be scoped to |
+| `milestone_id`      | integer        | no       | The milestone the board should be scoped to |
+| `labels`            | string         | no       | Comma-separated list of label names which the board should be scoped to |
+| `weight`            | integer        | no       | The weight range from 0 to 9, to which the board should be scoped to |
+
+```bash
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1?name=new_name&milestone_id=44&assignee_id=1&labels=GroupLabel&weight=4
+```
+
+Example response:
+
+```json
+  {
+    "id": 1,
+    "project": null,
+    "lists": [],
+    "name": "new_name",
+    "group": {
+      "id": 5,
+      "name": "Documentcloud",
+      "web_url": "http://example.com/groups/documentcloud"
+    },
+    "milestone": {
+      "id": 44,
+      "iid": 1,
+      "group_id": 5,
+      "title": "Group Milestone",
+      "description": "Group Milestone Desc",
+      "state": "active",
+      "created_at": "2018-07-03T07:15:19.271Z",
+      "updated_at": "2018-07-03T07:15:19.271Z",
+      "due_date": null,
+      "start_date": null,
+      "web_url": "http://example.com/groups/documentcloud/-/milestones/1"
+    },
+    "assignee": {
+      "id": 1,
+      "name": "Administrator",
+      "username": "root",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+      "web_url": "http://example.com/root"
+    },
+    "labels": [{
+      "id": 11,
+      "name": "GroupLabel",
+      "color": "#428BCA",
+      "description": ""
+    }],
+    "weight": 4
+  }
+```
+
+## Delete a group issue board **(PREMIUM)**
+
+Deletes a Group Issue Board.
+
+```
+DELETE /groups/:id/boards/:board_id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `board_id` | integer | yes | The ID of a board |
+
+```bash
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1
+```
+
+## List group issue board lists
 
 Get a list of the board's lists.
 Does not include `open` and `closed` lists
@@ -168,7 +437,7 @@ Example response:
 ]
 ```
 
-## Single board list
+## Single group issue board list
 
 Get a single board list.
 
@@ -200,7 +469,7 @@ Example response:
 }
 ```
 
-## New board list
+## New group issue board list
 
 Creates a new Issue Board list.
 
@@ -232,7 +501,7 @@ Example response:
 }
 ```
 
-## Edit board list
+## Edit group issue board list
 
 Updates an existing Issue Board list. This call is used to change list position.
 
@@ -265,7 +534,7 @@ Example response:
 }
 ```
 
-## Delete a board list
+## Delete a group issue board list
 
 Only for admins and group owners. Soft deletes the board list in question.
 
diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md
new file mode 100644
index 00000000000..29e58d9279a
--- /dev/null
+++ b/doc/api/group_clusters.md
@@ -0,0 +1,280 @@
+# Group clusters API
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30213)
+in GitLab 12.1.
+
+NOTE: **Note:**
+User will need at least maintainer access for the group to use these endpoints.
+
+## List group clusters
+
+Returns a list of group clusters.
+
+```
+GET /groups/:id/clusters
+```
+
+Parameters:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
+
+Example request:
+
+```bash
+curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/groups/26/clusters
+```
+
+Example response:
+
+```json
+[
+  {
+    "id":18,
+    "name":"cluster-1",
+    "domain":"example.com",
+    "created_at":"2019-01-02T20:18:12.563Z",
+    "provider_type":"user",
+    "platform_type":"kubernetes",
+    "environment_scope":"*",
+    "cluster_type":"group_type",
+    "user":
+    {
+      "id":1,
+      "name":"Administrator",
+      "username":"root",
+      "state":"active",
+      "avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..",
+      "web_url":"https://gitlab.example.com/root"
+    },
+    "platform_kubernetes":
+    {
+      "api_url":"https://104.197.68.152",
+      "authorization_type":"rbac",
+      "ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"
+    }
+  },
+  {
+    "id":19,
+    "name":"cluster-2",
+    ...
+  }
+]
+```
+
+## Get a single group cluster
+
+Gets a single group cluster.
+
+```
+GET /groups/:id/clusters/:cluster_id
+```
+
+Parameters:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
+| `cluster_id` | integer | yes | The ID of the cluster |
+
+Example request:
+
+```bash
+curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/groups/26/clusters/18
+```
+
+Example response:
+
+```json
+{
+  "id":18,
+  "name":"cluster-1",
+  "domain":"example.com",
+  "created_at":"2019-01-02T20:18:12.563Z",
+  "provider_type":"user",
+  "platform_type":"kubernetes",
+  "environment_scope":"*",
+  "cluster_type":"group_type",
+  "user":
+  {
+    "id":1,
+    "name":"Administrator",
+    "username":"root",
+    "state":"active",
+    "avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..",
+    "web_url":"https://gitlab.example.com/root"
+  },
+  "platform_kubernetes":
+  {
+    "api_url":"https://104.197.68.152",
+    "authorization_type":"rbac",
+    "ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"
+  },
+  "group":
+  {
+    "id":26,
+    "name":"group-with-clusters-api",
+    "web_url":"https://gitlab.example.com/group-with-clusters-api"
+  }
+}
+```
+
+## Add existing cluster to group
+
+Adds an existing Kubernetes cluster to the group.
+
+```
+POST /groups/:id/clusters/user
+```
+
+Parameters:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
+| `name` | String | yes | The name of the cluster |
+| `domain` | String | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster |
+| `enabled` | Boolean | no | Determines if cluster is active or not, defaults to true |
+| `managed` | Boolean | no | Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true |
+| `platform_kubernetes_attributes[api_url]` | String | yes | The URL to access the Kubernetes API |
+| `platform_kubernetes_attributes[token]` | String | yes | The token to authenticate against Kubernetes |
+| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
+| `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. |
+| `environment_scope` | String | no | The associated environment to the cluster. Defaults to `*` **(PREMIUM)** |
+
+Example request:
+
+```bash
+curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/groups/26/clusters/user \
+-H "Accept: application/json" \
+-H "Content-Type:application/json" \
+--request POST --data '{"name":"cluster-5", "platform_kubernetes_attributes":{"api_url":"https://35.111.51.20","token":"12345","ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"}}'
+```
+
+Example response:
+
+```json
+{
+  "id":24,
+  "name":"cluster-5",
+  "created_at":"2019-01-03T21:53:40.610Z",
+  "provider_type":"user",
+  "platform_type":"kubernetes",
+  "environment_scope":"*",
+  "cluster_type":"group_type",
+  "user":
+  {
+    "id":1,
+    "name":"Administrator",
+    "username":"root",
+    "state":"active",
+    "avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..",
+    "web_url":"https://gitlab.example.com/root"
+  },
+  "platform_kubernetes":
+  {
+    "api_url":"https://35.111.51.20",
+    "authorization_type":"rbac",
+    "ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"
+  },
+  "group":
+  {
+    "id":26,
+    "name":"group-with-clusters-api",
+    "web_url":"https://gitlab.example.com/root/group-with-clusters-api"
+  }
+}
+```
+
+## Edit group cluster
+
+Updates an existing group cluster.
+
+```
+PUT /groups/:id/clusters/:cluster_id
+```
+
+Parameters:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
+| `cluster_id` | integer | yes | The ID of the cluster |
+| `name` | String | no | The name of the cluster |
+| `domain` | String | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster |
+| `platform_kubernetes_attributes[api_url]` | String | no | The URL to access the Kubernetes API |
+| `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes |
+| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
+| `environment_scope` | String | no | The associated environment to the cluster **(PREMIUM)** |
+
+NOTE: **Note:**
+`name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added
+through the ["Add existing Kubernetes cluster"](../user/project/clusters/index.md#add-existing-kubernetes-cluster) option or
+through the ["Add existing cluster to group"](#add-existing-cluster-to-group) endpoint.
+
+Example request:
+
+```bash
+curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/groups/26/clusters/24 \
+-H "Content-Type:application/json" \
+--request PUT --data '{"name":"new-cluster-name","domain":"new-domain.com","api_url":"https://new-api-url.com"}'
+```
+
+Example response:
+
+```json
+{
+  "id":24,
+  "name":"new-cluster-name",
+  "domain":"new-domain.com",
+  "created_at":"2019-01-03T21:53:40.610Z",
+  "provider_type":"user",
+  "platform_type":"kubernetes",
+  "environment_scope":"*",
+  "cluster_type":"group_type",
+  "user":
+  {
+    "id":1,
+    "name":"Administrator",
+    "username":"root",
+    "state":"active",
+    "avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..",
+    "web_url":"https://gitlab.example.com/root"
+  },
+  "platform_kubernetes":
+  {
+    "api_url":"https://new-api-url.com",
+    "authorization_type":"rbac",
+    "ca_cert":null
+  },
+  "group":
+  {
+    "id":26,
+    "name":"group-with-clusters-api",
+    "web_url":"https://gitlab.example.com/group-with-clusters-api"
+  }
+}
+
+```
+
+## Delete group cluster
+
+Deletes an existing group cluster.
+
+```
+DELETE /groups/:id/clusters/:cluster_id
+```
+
+Parameters:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
+| `cluster_id` | integer | yes | The ID of the cluster |
+
+Example request:
+
+```bash
+curl --request DELETE --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/groups/26/clusters/23'
+```
diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md
index 3d4b099b49e..e2ba0dea642 100644
--- a/doc/api/group_labels.md
+++ b/doc/api/group_labels.md
@@ -12,12 +12,13 @@ Get all labels for a given group.
 GET /groups/:id/labels
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. |
+| Attribute     | Type           | Required | Description                                                                                                                                                                  |
+| ---------     | ----           | -------- | -----------                                                                                                                                                                  |
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user.                                                               |
+| `with_counts` | boolean        | no       | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced in GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/31543))_ |
 
 ```bash
-curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels?with_counts=true
 ```
 
 Example response:
diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md
index 260eb09cc38..a819e06bcd9 100644
--- a/doc/api/group_milestones.md
+++ b/doc/api/group_milestones.md
@@ -18,13 +18,13 @@ GET /groups/:id/milestones?search=version
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `iids[]` | Array[integer] | optional | Return only the milestones having the given `iid` |
-| `state` | string | optional | Return only `active` or `closed` milestones |
-| `title` | string | optional | Return only the milestones having the given `title` |
-| `search` | string | optional | Return only milestones with a title or description matching the provided string |
+| Attribute | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| `id`      | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `iids[]`  | integer array | optional | Return only the milestones having the given `iid` |
+| `state`   | string | optional | Return only `active` or `closed` milestones |
+| `title`   | string | optional | Return only the milestones having the given `title` |
+| `search`  | string | optional | Return only milestones with a title or description matching the provided string |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/milestones
@@ -136,3 +136,18 @@ Parameters:
 - `milestone_id` (required) - The ID of a group milestone
 
 [ce-12819]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12819
+
+## Get all burndown chart events for a single milestone **(STARTER)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4737) in GitLab 12.1
+
+Get all burndown chart events for a single milestone.
+
+```
+GET /groups/:id/milestones/:milestone_id/burndown_events
+```
+
+Parameters:
+
+- `id` (required) - The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user
+- `milestone_id` (required) - The ID of a group milestone
diff --git a/doc/api/groups.md b/doc/api/groups.md
index 20789a1d4a4..0d500f783aa 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -7,17 +7,17 @@ authentication, only public groups are returned.
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `skip_groups` | array of integers | no | Skip the group IDs passed |
-| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have precedence |
-| `search` | string | no | Return the list of authorized groups matching the search criteria |
-| `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` |
-| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` |
-| `statistics` | boolean | no | Include group statistics (admins only) |
-| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
-| `owned` | boolean | no | Limit to groups explicitly owned by the current user |
-| `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md) |
+| Attribute                | Type              | Required | Description |
+| ------------------------ | ----------------- | -------- | ---------- |
+| `skip_groups`            | array of integers | no       | Skip the group IDs passed |
+| `all_available`          | boolean           | no       | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have precedence |
+| `search`                 | string            | no       | Return the list of authorized groups matching the search criteria |
+| `order_by`               | string            | no       | Order groups by `name`, `path` or `id`. Default is `name` |
+| `sort`                   | string            | no       | Order groups in `asc` or `desc` order. Default is `asc` |
+| `statistics`             | boolean           | no       | Include group statistics (admins only) |
+| `with_custom_attributes` | boolean           | no       | Include [custom attributes](custom_attributes.md) in response (admins only) |
+| `owned`                  | boolean           | no       | Limit to groups explicitly owned by the current user |
+| `min_access_level`       | integer           | no       | Limit to groups where current user has at least this [access level](members.md) |
 
 ```
 GET /groups
@@ -70,8 +70,8 @@ GET /groups?statistics=true
       "repository_size" : 33,
       "wiki_size" : 100,
       "lfs_objects_size" : 123,
-      "job_artifacts_size" : 57
-
+      "job_artifacts_size" : 57,
+      "packages_size": 0
     }
   }
 ]
@@ -94,18 +94,18 @@ When accessed without authentication, only public groups are returned.
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) of the parent group |
-| `skip_groups` | array of integers | no | Skip the group IDs passed |
-| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have precedence |
-| `search` | string | no | Return the list of authorized groups matching the search criteria |
-| `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` |
-| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` |
-| `statistics` | boolean | no | Include group statistics (admins only) |
-| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
-| `owned` | boolean | no | Limit to groups explicitly owned by the current user |
-| `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md) |
+| Attribute                | Type              | Required | Description |
+| ------------------------ | ----------------- | -------- | ----------- |
+| `id`                     | integer/string    | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) of the parent group |
+| `skip_groups`            | array of integers | no       | Skip the group IDs passed |
+| `all_available`          | boolean           | no       | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have preceden |
+| `search`                 | string            | no       | Return the list of authorized groups matching the search criteria |
+| `order_by`               | string            | no       | Order groups by `name`, `path` or `id`. Default is `name` |
+| `sort`                   | string            | no       | Order groups in `asc` or `desc` order. Default is `asc` |
+| `statistics`             | boolean           | no       | Include group statistics (admins only) |
+| `with_custom_attributes` | boolean           | no       | Include [custom attributes](custom_attributes.md) in response (admins only) |
+| `owned`                  | boolean           | no       | Limit to groups explicitly owned by the current user |
+| `min_access_level`       | integer           | no       | Limit to groups where current user has at least this [access level](members.md) |
 
 ```
 GET /groups/:id/subgroups
@@ -142,22 +142,22 @@ GET /groups/:id/projects
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `archived` | boolean | no | Limit by archived status |
-| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` |
-| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` |
-| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` |
-| `search` | string | no | Return list of authorized projects matching the search criteria |
-| `simple` | boolean | no | Return only the ID, URL, name, and path of each project |
-| `owned` | boolean | no | Limit by projects owned by the current user |
-| `starred` | boolean | no | Limit by projects starred by the current user |
-| `with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false` |
-| `with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false` |
-| `with_shared` | boolean | no | Include projects shared to this group. Default is `true` |
-| `include_subgroups` | boolean | no | Include projects in subgroups of this group. Default is `false` |
-| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
+| Attribute                     | Type           | Required | Description |
+| ----------------------------- | -------------- | -------- | ----------- |
+| `id`                          | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `archived`                    | boolean        | no       | Limit by archived status |
+| `visibility`                  | string         | no       | Limit by visibility `public`, `internal`, or `private` |
+| `order_by`                    | string         | no       | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` |
+| `sort`                        | string         | no       | Return projects sorted in `asc` or `desc` order. Default is `desc` |
+| `search`                      | string         | no       | Return list of authorized projects matching the search criteria |
+| `simple`                      | boolean        | no       | Return only the ID, URL, name, and path of each project |
+| `owned`                       | boolean        | no       | Limit by projects owned by the current user |
+| `starred`                     | boolean        | no       | Limit by projects starred by the current user |
+| `with_issues_enabled`         | boolean        | no       | Limit by projects with issues feature enabled. Default is `false` |
+| `with_merge_requests_enabled` | boolean        | no       | Limit by projects with merge requests feature enabled. Default is `false` |
+| `with_shared`                 | boolean        | no       | Include projects shared to this group. Default is `true` |
+| `include_subgroups`           | boolean        | no       | Include projects in subgroups of this group. Default is `false` |
+| `with_custom_attributes`      | boolean        | no       | Include [custom attributes](custom_attributes.md) in response (admins only) |
 
 Example response:
 
@@ -214,11 +214,11 @@ GET /groups/:id
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
-| `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). |
+| Attribute                | Type           | Required | Description |
+| ------------------------ | -------------- | -------- | ----------- |
+| `id`                     | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. |
+| `with_custom_attributes` | boolean        | no       | Include [custom attributes](custom_attributes.md) in response (admins only). |
+| `with_projects`          | boolean        | no       | Include details from projects that belong to the specified group (defaults to `true`). |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4
@@ -375,6 +375,21 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters:
+
+Additional response parameters:
+
+```json
+{
+  "id": 4,
+  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
+  "shared_runners_minutes_limit": 133,
+  "extra_shared_runners_minutes_limit": 133,
+  ...
+}
+```
+
 When adding the parameter `with_projects=false`, projects will not be returned.
 
 ```bash
@@ -410,15 +425,17 @@ POST /groups
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `name` | string | yes | The name of the group |
-| `path` | string | yes | The path of the group |
-| `description` | string | no | The group's description |
-| `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. |
-| `lfs_enabled` | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group |
-| `request_access_enabled` | boolean | no | Allow users to request member access. |
-| `parent_id` | integer | no | The parent group id for creating nested group. |
+| Attribute                            | Type    | Required | Description |
+| ------------------------------------ | ------- | -------- | ----------- |
+| `name`                               | string  | yes      | The name of the group. |
+| `path`                               | string  | yes      | The path of the group. |
+| `description`                        | string  | no       | The group's description. |
+| `visibility`                         | string  | no       | The group's visibility. Can be `private`, `internal`, or `public`. |
+| `lfs_enabled`                        | boolean | no       | Enable/disable Large File Storage (LFS) for the projects in this group. |
+| `request_access_enabled`             | boolean | no       | Allow users to request member access. |
+| `parent_id`                          | integer | no       | The parent group ID for creating nested group. |
+| `shared_runners_minutes_limit`       | integer | no       | **(STARTER ONLY)** Pipeline minutes quota for this group. |
+| `extra_shared_runners_minutes_limit` | integer | no       | **(STARTER ONLY)** Extra pipeline minutes quota for this group. |
 
 ## Transfer project to group
 
@@ -430,10 +447,10 @@ POST  /groups/:id/projects/:project_id
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+| Attribute    | Type           | Required | Description |
+| ------------ | -------------- | -------- | ----------- |
+| `id`         | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `project_id` | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 
 ## Update group
 
@@ -443,16 +460,20 @@ Updates the project group. Only available to group owners and administrators.
 PUT /groups/:id
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of the group |
-| `name` | string | no | The name of the group |
-| `path` | string | no | The path of the group |
-| `description` | string | no | The description of the group |
-| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. |
-| `lfs_enabled` (optional) | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group |
-| `request_access_enabled` | boolean | no | Allow users to request member access. |
-| `file_template_project_id` | integer | no | **(Premium)** The ID of a project to load custom file templates from |
+| Attribute                            | Type    | Required | Description |
+| ------------------------------------ | ------- | -------- | ----------- |
+| `id`                                 | integer | yes      | The ID of the group. |
+| `name`                               | string  | no       | The name of the group. |
+| `path`                               | string  | no       | The path of the group. |
+| `description`                        | string  | no       | The description of the group. |
+| `membership_lock`                    | boolean | no       | **(STARTER)** Prevent adding new members to project membership within this group. |
+| `share_with_group_lock`              | boolean | no       | Prevent sharing a project with another group within this group. |
+| `visibility`                         | string  | no       | The visibility level of the group. Can be `private`, `internal`, or `public`. |
+| `lfs_enabled` (optional)             | boolean | no       | Enable/disable Large File Storage (LFS) for the projects in this group. |
+| `request_access_enabled`             | boolean | no       | Allow users to request member access. |
+| `file_template_project_id`           | integer | no       | **(PREMIUM)** The ID of a project to load custom file templates from. |
+| `shared_runners_minutes_limit`       | integer | no       | **(STARTER ONLY)** Pipeline minutes quota for this group. |
+| `extra_shared_runners_minutes_limit` | integer | no       | **(STARTER ONLY)** Extra pipeline minutes quota for this group. |
 
 ```bash
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5?name=Experimental"
@@ -520,7 +541,7 @@ Example response:
 
 ## Remove group
 
-Removes group with all projects inside.
+Removes group with all projects inside. Only available to group owners and administrators.
 
 ```
 DELETE /groups/:id
@@ -552,20 +573,74 @@ GET /groups?search=foobar
 ]
 ```
 
+## Sync group with LDAP **(CORE ONLY)**
+
+Syncs the group with its linked LDAP group. Only available to group owners and administrators.
+
+```
+POST /groups/:id/ldap_sync
+```
+
+Parameters:
+
+- `id` (required) - The ID or path of a user group
+
 ## Group members
 
 Please consult the [Group Members](members.md) documentation.
 
+### Add LDAP group link **(CORE ONLY)**
+
+Adds an LDAP group link.
+
+```
+POST /groups/:id/ldap_group_links
+```
+
+Parameters:
+
+- `id` (required) - The ID of a group
+- `cn` (required) - The CN of a LDAP group
+- `group_access` (required) - Minimum access level for members of the LDAP group
+- `provider` (required) - LDAP provider for the LDAP group
+
+### Delete LDAP group link **(CORE ONLY)**
+
+Deletes an LDAP group link.
+
+```
+DELETE /groups/:id/ldap_group_links/:cn
+```
+
+Parameters:
+
+- `id` (required) - The ID of a group
+- `cn` (required) - The CN of a LDAP group
+
+Deletes a LDAP group link for a specific LDAP provider
+
+```
+DELETE /groups/:id/ldap_group_links/:provider/:cn
+```
+
+Parameters:
+
+- `id` (required) - The ID of a group
+- `cn` (required) - The CN of a LDAP group
+- `provider` (required) - Name of a LDAP provider
+
 ## Namespaces in groups
 
 By default, groups only get 20 namespaces at a time because the API results are paginated.
 
 To get more (up to 100), pass the following as an argument to the API call:
+
 ```
 /groups?per_page=100
 ```
 
 And to switch pages add:
+
 ```
 /groups?per_page=100&page=2
 ```
diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md
index 1c7db6a8e4c..280431fa87c 100644
--- a/doc/api/issue_links.md
+++ b/doc/api/issue_links.md
@@ -1,4 +1,4 @@
-# Issue links API **[STARTER]**
+# Issue links API **(STARTER)**
 
 ## List issue relations
 
@@ -67,7 +67,6 @@ POST /projects/:id/issues/:issue_iid/links
 | `target_project_id` | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) of a target project  |
 | `target_issue_iid` | integer/string | yes      | The internal ID of a target project's issue |
 
-
 ```json
 {
   "source_issue" : {
@@ -141,14 +140,12 @@ Deletes an issue link, thus removes the two-way relationship.
 DELETE /projects/:id/issues/:issue_iid/links/:issue_link_id
 ```
 
-
 | Attribute   | Type    | Required | Description                          |
 |-------------|---------|----------|--------------------------------------|
 | `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
 | `issue_iid` | integer | yes      | The internal ID of a project's issue |
 | `issue_link_id` | integer/string | yes      | The ID of an issue relationship |
 
-
 ```json
 {
   "source_issue" : {
diff --git a/doc/api/issues.md b/doc/api/issues.md
index 0d96cfa1b21..11c18ef94ba 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -3,7 +3,7 @@
 Every API call to issues must be authenticated.
 
 If a user is not a member of a project and the project is private, a `GET`
-request on that project will result to a `404` status code.
+request on that project will result in a `404` status code.
 
 ## Issues pagination
 
@@ -39,15 +39,16 @@ GET /issues?confidential=true
 | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `state`             | string           | no         | Return `all` issues or just those that are `opened` or `closed`                                                                                       |
 | `labels`            | string           | no         | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. |
-| `with_labels_details`| Boolean          | no         | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:text_color`. Default is `false`. |
+| `with_labels_details` | Boolean        | no         | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:text_color`. Default is `false`. |
 | `milestone`         | string           | no         | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone.                             |
 | `scope`             | string           | no         | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ |
 | `author_id`         | integer          | no         | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced][ce-13004] in GitLab 9.5)_ |
-| `author_username`   | string           | no         | Return issues created by the given `username`. Simillar to `author_id` and mutually exclusive with `author_id`. |
+| `author_username`   | string           | no         | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. |
 | `assignee_id`       | integer          | no         | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ |
-| `assignee_username` | Array[String]    | no         | Return issues assigned to the given `username`. Simillar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. |
+| `assignee_username` | string array     | no         | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. |
 | `my_reaction_emoji` | string           | no         | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
-| `iids[]`            | Array[integer]   | no         | Return only the issues having the given `iid`                                                                                                       |
+| `weight` **(STARTER)** | integer       | no         | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned.              |
+| `iids[]`            | integer array    | no         | Return only the issues having the given `iid`                                                                                                       |
 | `order_by`          | string           | no         | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at`                                                               |
 | `sort`              | string           | no         | Return issues sorted in `asc` or `desc` order. Default is `desc`                                                                                    |
 | `search`            | string           | no         | Search issues against their `title` and `description`                                                                                               |
@@ -56,7 +57,7 @@ GET /issues?confidential=true
 | `created_before`    | datetime         | no         | Return issues created on or before the given time                                                                                                   |
 | `updated_after`     | datetime         | no         | Return issues updated on or after the given time                                                                                                    |
 | `updated_before`    | datetime         | no         | Return issues updated on or before the given time                                                                                                   |
-| `confidential `     | Boolean          | no         | Filter confidential or public issues.                                                                                                               |
+| `confidential`     | Boolean          | no         | Filter confidential or public issues.                                                                                                               |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/issues
@@ -135,7 +136,6 @@ Example response:
          "award_emoji":"http://example.com/api/v4/projects/1/issues/76/award_emoji",
          "project":"http://example.com/api/v4/projects/1"
       },
-      "subscribed": false,
       "task_completion_status":{
          "count":0,
          "completed_count":0
@@ -144,6 +144,20 @@ Example response:
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `weight` parameter:
+
+```json
+[
+   {
+      "state" : "opened",
+      "description" : "Ratione dolores corrupti mollitia soluta quia.",
+      "weight": null,
+      ...
+   }
+]
+```
+
 **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
 
 **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists.
@@ -174,15 +188,16 @@ GET /groups/:id/issues?confidential=true
 | `id`                | integer/string   | yes        | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user                 |
 | `state`             | string           | no         | Return all issues or just those that are `opened` or `closed`                                                                 |
 | `labels`            | string           | no         | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. |
-| `with_labels_details`| Boolean          | no         | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:text_color`. Default is `false`. |
-| `iids[]`            | Array[integer]   | no         | Return only the issues having the given `iid`                                                                                 |
+| `with_labels_details` | Boolean        | no         | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:text_color`. Default is `false`. |
+| `iids[]`            | integer array    | no         | Return only the issues having the given `iid`                                                                                 |
 | `milestone`         | string           | no         | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone.       |
 | `scope`             | string           | no         | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ |
 | `author_id`         | integer          | no         | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced][ce-13004] in GitLab 9.5)_ |
-| `author_username`   | string           | no         | Return issues created by the given `username`. Simillar to `author_id` and mutually exclusive with `author_id`. |
+| `author_username`   | string           | no         | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. |
 | `assignee_id`       | integer          | no         | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ |
-| `assignee_username` | Array[String]    | no         | Return issues assigned to the given `username`. Simillar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. |
+| `assignee_username` | string array     | no         | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. |
 | `my_reaction_emoji` | string           | no         | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
+| `weight` **(STARTER)** | integer       | no         | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. |
 | `order_by`          | string           | no         | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at`                                         |
 | `sort`              | string           | no         | Return issues sorted in `asc` or `desc` order. Default is `desc`                                                              |
 | `search`            | string           | no         | Search group issues against their `title` and `description`                                                                   |
@@ -190,7 +205,7 @@ GET /groups/:id/issues?confidential=true
 | `created_before`    | datetime         | no         | Return issues created on or before the given time                                                                             |
 | `updated_after`     | datetime         | no         | Return issues updated on or after the given time                                                                              |
 | `updated_before`    | datetime         | no         | Return issues updated on or before the given time                                                                             |
-| `confidential `     | Boolean          | no         | Filter confidential or public issues.                                                                                         |
+| `confidential`     | Boolean          | no         | Filter confidential or public issues.                                                                                         |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4/issues
@@ -278,6 +293,20 @@ Example response:
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `weight` parameter:
+
+```json
+[
+   {
+      "project_id" : 4,
+      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
+      "weight": null,
+      ...
+   }
+]
+```
+
 **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
 
 **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists.
@@ -306,17 +335,18 @@ GET /projects/:id/issues?confidential=true
 | Attribute           | Type             | Required   | Description                                                                                                                   |
 | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user               |
-| `iids[]`            | Array[integer]   | no         | Return only the milestone having the given `iid`                                                                              |
+| `iids[]`            | integer array    | no         | Return only the milestone having the given `iid`                                                                              |
 | `state`             | string           | no         | Return all issues or just those that are `opened` or `closed`                                                                 |
 | `labels`            | string           | no         | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. |
-| `with_labels_details`| Boolean          | no         | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:text_color`. Default is `false`. |
+| `with_labels_details` | Boolean        | no         | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:text_color`. Default is `false`. |
 | `milestone`         | string           | no         | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone.       |
 | `scope`             | string           | no         | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ |
 | `author_id`         | integer          | no         | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced][ce-13004] in GitLab 9.5)_ |
-| `author_username`   | string           | no         | Return issues created by the given `username`. Simillar to `author_id` and mutually exclusive with `author_id`. |
+| `author_username`   | string           | no         | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. |
 | `assignee_id`       | integer          | no         | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ |
-| `assignee_username` | Array[String]    | no         | Return issues assigned to the given `username`. Simillar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. |
+| `assignee_username` | string array     | no         | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. |
 | `my_reaction_emoji` | string           | no         | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
+| `weight` **(STARTER)** | integer       | no         | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. |
 | `order_by`          | string           | no         | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at`                                         |
 | `sort`              | string           | no         | Return issues sorted in `asc` or `desc` order. Default is `desc`                                                              |
 | `search`            | string           | no         | Search project issues against their `title` and `description`                                                                 |
@@ -324,8 +354,7 @@ GET /projects/:id/issues?confidential=true
 | `created_before`    | datetime         | no         | Return issues created on or before the given time                                                                             |
 | `updated_after`     | datetime         | no         | Return issues updated on or after the given time                                                                              |
 | `updated_before`    | datetime         | no         | Return issues updated on or before the given time                                                                             |
-| `confidential `     | Boolean          | no         | Filter confidential or public issues.                                                                                         |
-
+| `confidential`     | Boolean          | no         | Filter confidential or public issues.                                                                                         |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues
@@ -411,7 +440,6 @@ Example response:
          "award_emoji":"http://example.com/api/v4/projects/4/issues/41/award_emoji",
          "project":"http://example.com/api/v4/projects/4"
       },
-      "subscribed": false,
       "task_completion_status":{
          "count":0,
          "completed_count":0
@@ -420,6 +448,20 @@ Example response:
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `weight` parameter:
+
+```json
+[
+   {
+      "project_id" : 4,
+      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
+      "weight": null,
+      ...
+   }
+]
+```
+
 **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
 
 **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists.
@@ -520,6 +562,18 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `weight` parameter:
+
+```json
+{
+   "project_id" : 4,
+   "description" : "Omnis vero earum sunt corporis dolor et placeat.",
+   "weight": null,
+   ...
+}
+```
+
 **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
 
 **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists.
@@ -536,16 +590,17 @@ POST /projects/:id/issues
 |-------------------------------------------|----------------|----------|--------------|
 | `id`                                      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `iid`                                     | integer/string | no       | The internal ID of the project's issue (requires admin or project owner rights) |
-| `title`                                   | string  | yes      | The title of an issue |
-| `description`                             | string  | no       | The description of an issue  |
-| `confidential`                            | boolean | no       | Set an issue to be confidential. Default is `false`.  |
-| `assignee_ids`                            | Array[integer] | no       | The ID of the users to assign issue |
-| `milestone_id`                            | integer | no       | The global ID of a milestone to assign issue  |
-| `labels`                                  | string  | no       | Comma-separated label names for an issue  |
-| `created_at`                              | string  | no       | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project/group owner rights) |
-| `due_date`                                | string  | no       | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` |
-| `merge_request_to_resolve_discussions_of` | integer | no       | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values.|
-| `discussion_to_resolve`                   | string  | no       | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. |
+| `title`                                   | string         | yes      | The title of an issue |
+| `description`                             | string         | no       | The description of an issue  |
+| `confidential`                            | boolean        | no       | Set an issue to be confidential. Default is `false`.  |
+| `assignee_ids`                            | integer array  | no       | The ID of a user to assign issue |
+| `milestone_id`                            | integer        | no       | The global ID of a milestone to assign issue  |
+| `labels`                                  | string         | no       | Comma-separated label names for an issue  |
+| `created_at`                              | string         | no       | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project/group owner rights) |
+| `due_date`                                | string         | no       | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` |
+| `merge_request_to_resolve_discussions_of` | integer        | no       | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values.|
+| `discussion_to_resolve`                   | string         | no       | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. |
+| `weight` **(STARTER)**                    | integer        | no       | The weight of the issue. Valid values are greater than or equal to 0. |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug
@@ -607,6 +662,18 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `weight` parameter:
+
+```json
+{
+   "project_id" : 4,
+   "description" : null,
+   "weight": null,
+   ...
+}
+```
+
 **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
 
 **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists.
@@ -622,17 +689,18 @@ PUT /projects/:id/issues/:issue_iid
 
 | Attribute      | Type    | Required | Description                                                                                                |
 |----------------|---------|----------|------------------------------------------------------------------------------------------------------------|
-| `id`           | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`           | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `issue_iid`    | integer | yes      | The internal ID of a project's issue                                                                       |
 | `title`        | string  | no       | The title of an issue                                                                                      |
 | `description`  | string  | no       | The description of an issue                                                                                |
 | `confidential` | boolean | no       | Updates an issue to be confidential                                                                        |
-| `assignee_ids`  | Array[integer] | no  | The ID of the user(s) to assign the issue to. Set to `0` or provide an empty value to unassign all assignees.  |
+| `assignee_ids` | integer array | no | The ID of the user(s) to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. |
 | `milestone_id` | integer | no       | The global ID of a milestone to assign the issue to. Set to `0` or provide an empty value to unassign a milestone.|
 | `labels`       | string  | no       | Comma-separated label names for an issue. Set to an empty string to unassign all labels.                   |
 | `state_event`  | string  | no       | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it                      |
 | `updated_at`   | string  | no       | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) |
 | `due_date`     | string  | no       | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11`                                           |
+| `weight` **(STARTER)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. 0                                                                    |
 | `discussion_locked` | boolean | no  | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. |
 
 ```bash
@@ -702,6 +770,18 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `weight` parameter:
+
+```json
+{
+   "project_id" : 4,
+   "description" : null,
+   "weight": null,
+   ...
+}
+```
+
 **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
 
 **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists.
@@ -812,6 +892,18 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `weight` parameter:
+
+```json
+{
+  "project_id": 5,
+  "description": "Repellat voluptas quibusdam voluptatem exercitationem.",
+  "weight": null,
+  ...
+}
+```
+
 **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
 
 **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists.
@@ -901,6 +993,18 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `weight` parameter:
+
+```json
+{
+  "project_id": 5,
+  "description": "Repellat voluptas quibusdam voluptatem exercitationem.",
+  "weight": null,
+  ...
+}
+```
+
 **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
 
 **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists.
diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md
index 82bc9c142cc..d7edb296be2 100644
--- a/doc/api/issues_statistics.md
+++ b/doc/api/issues_statistics.md
@@ -34,16 +34,16 @@ GET /issues_statistics?confidential=true
 | `author_id`         | integer          | no         | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. |
 | `author_username`   | string           | no         | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. |
 | `assignee_id`       | integer          | no         | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. |
-| `assignee_username` | Array[String]    | no         | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. |
+| `assignee_username` | string array     | no         | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. |
 | `my_reaction_emoji` | string           | no         | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. |
-| `iids[]`            | Array[integer]   | no         | Return only the issues having the given `iid`                                                                                                       |
+| `iids[]`            | integer array    | no         | Return only the issues having the given `iid`                                                                                                       |
 | `search`            | string           | no         | Search issues against their `title` and `description`                                                                                               |
 | `in`                | string           | no         | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description`             |
 | `created_after`     | datetime         | no         | Return issues created on or after the given time                                                                                                    |
 | `created_before`    | datetime         | no         | Return issues created on or before the given time                                                                                                   |
 | `updated_after`     | datetime         | no         | Return issues updated on or after the given time                                                                                                    |
 | `updated_before`    | datetime         | no         | Return issues updated on or before the given time                                                                                                   |
-| `confidential `     | Boolean          | no         | Filter confidential or public issues.                                                                                                               |
+| `confidential`     | Boolean          | no         | Filter confidential or public issues.                                                                                                               |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/issues_statistics
@@ -86,20 +86,20 @@ GET /groups/:id/issues_statistics?confidential=true
 | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | `id`                | integer/string   | yes        | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user                 |
 | `labels`            | string           | no         | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. |
-| `iids[]`            | Array[integer]   | no         | Return only the issues having the given `iid`                                                                                 |
+| `iids[]`            | integer array    | no         | Return only the issues having the given `iid`                                                                                 |
 | `milestone`         | string           | no         | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone.       |
 | `scope`             | string           | no         | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. |
 | `author_id`         | integer          | no         | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. |
 | `author_username`   | string           | no         | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. |
 | `assignee_id`       | integer          | no         | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. |
-| `assignee_username` | Array[String]    | no         | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. |
+| `assignee_username` | string array     | no         | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. |
 | `my_reaction_emoji` | string           | no         | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. |
 | `search`            | string           | no         | Search group issues against their `title` and `description`                                                                   |
 | `created_after`     | datetime         | no         | Return issues created on or after the given time                                                                              |
 | `created_before`    | datetime         | no         | Return issues created on or before the given time                                                                             |
 | `updated_after`     | datetime         | no         | Return issues updated on or after the given time                                                                              |
 | `updated_before`    | datetime         | no         | Return issues updated on or before the given time                                                                             |
-| `confidential `     | Boolean          | no         | Filter confidential or public issues.                                                                                         |
+| `confidential`     | Boolean          | no         | Filter confidential or public issues.                                                                                         |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4/issues_statistics
@@ -141,22 +141,21 @@ GET /projects/:id/issues_statistics?confidential=true
 | Attribute           | Type             | Required   | Description                                                                                                                   |
 | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user               |
-| `iids[]`            | Array[integer]   | no         | Return only the milestone having the given `iid`                                                                              |
+| `iids[]`            | integer array    | no         | Return only the milestone having the given `iid`                                                                              |
 | `labels`            | string           | no         | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. |
 | `milestone`         | string           | no         | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone.       |
 | `scope`             | string           | no         | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. |
 | `author_id`         | integer          | no         | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. |
 | `author_username`   | string           | no         | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. |
 | `assignee_id`       | integer          | no         | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. |
-| `assignee_username` | Array[String]    | no         | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. |
+| `assignee_username` | string array     | no         | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. |
 | `my_reaction_emoji` | string           | no         | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. |
 | `search`            | string           | no         | Search project issues against their `title` and `description`                                                                 |
 | `created_after`     | datetime         | no         | Return issues created on or after the given time                                                                              |
 | `created_before`    | datetime         | no         | Return issues created on or before the given time                                                                             |
 | `updated_after`     | datetime         | no         | Return issues updated on or after the given time                                                                              |
 | `updated_before`    | datetime         | no         | Return issues updated on or before the given time                                                                             |
-| `confidential `     | Boolean          | no         | Filter confidential or public issues.                                                                                         |
-
+| `confidential`     | Boolean          | no         | Filter confidential or public issues.                                                                                         |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues_statistics
diff --git a/doc/api/jobs.md b/doc/api/jobs.md
index 72973b69117..2a1c1b5f6f3 100644
--- a/doc/api/jobs.md
+++ b/doc/api/jobs.md
@@ -14,7 +14,7 @@ GET /projects/:id/jobs
 | `scope`   | string **or** array of strings | no       | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. |
 
 ```sh
-curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/1/jobs?scope[]=pending&scope[]=running'
+curl --globoff --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/1/jobs?scope[]=pending&scope[]=running'
 ```
 
 Example of response
@@ -359,7 +359,7 @@ GET /projects/:id/jobs/:job_id/artifacts
 |-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------|
 | `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user.                                |
 | `job_id`    | integer        | yes      | ID of a job.                                                                                                                                |
-| `job_token` **[PREMIUM]** | string         | no       | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
+| `job_token` **(PREMIUM)** | string         | no       | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
 
 Example request using the `PRIVATE-TOKEN` header:
 
@@ -368,7 +368,7 @@ curl --output artifacts.zip --header "PRIVATE-TOKEN: <your_access_token>" "https
 ```
 
 To use this in a [`script` definition](../ci/yaml/README.md#script) inside
-`.gitlab-ci.yml` **[PREMIUM]**, you can use either:
+`.gitlab-ci.yml` **(PREMIUM)**, you can use either:
 
 - The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable.
   For example, the following job will download the artifacts of the job with ID
@@ -409,10 +409,10 @@ Possible response status codes:
 > - The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346]
 >   in [GitLab Premium][ee] 9.5.
 
-Download the artifacts zipped archive from the given reference name and job,
-provided the job finished successfully. This is the same as
-[getting the job's artifacts](#get-job-artifacts), but by defining the job's
-name instead of its ID.
+Download the artifacts zipped archive from the latest successful pipeline for
+the given reference name and job, provided the job finished successfully. This
+is the same as [getting the job's artifacts](#get-job-artifacts), but by
+defining the job's name instead of its ID.
 
 ```
 GET /projects/:id/jobs/artifacts/:ref_name/download?job=name
@@ -425,7 +425,7 @@ Parameters
 | `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user.                                |
 | `ref_name`  | string         | yes      | Branch or tag name in repository. HEAD or SHA references are not supported.                                                                     |
 | `job`       | string         | yes      | The name of the job.                                                                                                                            |
-| `job_token` **[PREMIUM]** | string         | no       | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
+| `job_token` **(PREMIUM)** | string         | no       | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
 
 Example request using the `PRIVATE-TOKEN` header:
 
@@ -434,7 +434,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
 ```
 
 To use this in a [`script` definition](../ci/yaml/README.md#script) inside
-`.gitlab-ci.yml` **[PREMIUM]**, you can use either:
+`.gitlab-ci.yml` **(PREMIUM)**, you can use either:
 
 - The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable.
   For example, the following job will download the artifacts of the `test` job
@@ -485,13 +485,13 @@ Parameters
 | Attribute       | Type           | Required | Description                                                                                                      |
 |-----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
 | `id`            | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
-| `job_id  `      | integer        | yes      | The unique job identifier.                                                                                       |
+| `job_id`        | integer        | yes      | The unique job identifier.                                                                                       |
 | `artifact_path` | string         | yes      | Path to a file inside the artifacts archive.                                                                     |
 
 Example request:
 
 ```sh
-curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/5/artifacts/some/release/file.pdf"
+curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/5/artifacts/some/release/file.pdf"
 ```
 
 Possible response status codes:
@@ -506,9 +506,9 @@ Possible response status codes:
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23538) in GitLab 11.5.
 
-Download a single artifact file from a specific tag or branch from within the
-job's artifacts archive. The file is extracted from the archive and streamed to
-the client.
+Download a single artifact file for a specific job of the latest successful
+pipeline for the given reference name from within the job's artifacts archive.
+The file is extracted from the archive and streamed to the client.
 
 ```
 GET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_path?job=name
@@ -526,7 +526,7 @@ Parameters:
 Example request:
 
 ```sh
-curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/raw/some/release/file.pdf?job=pdf"
+curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/raw/some/release/file.pdf?job=pdf"
 ```
 
 Possible response status codes:
@@ -551,7 +551,7 @@ GET /projects/:id/jobs/:job_id/trace
 | job_id    | integer        | yes      | ID of a job.                                                                                                 |
 
 ```sh
-curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/trace"
+curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/trace"
 ```
 
 Possible response status codes:
@@ -782,7 +782,6 @@ DELETE /projects/:id/jobs/:job_id/artifacts
 | `id`      | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `job_id`  | integer        | yes      | ID of a job.                                                                |
 
-
 Example request:
 
 ```sh
diff --git a/doc/api/labels.md b/doc/api/labels.md
index 9d10d383bf9..5db0edcf14d 100644
--- a/doc/api/labels.md
+++ b/doc/api/labels.md
@@ -8,12 +8,13 @@ Get all labels for a given project.
 GET /projects/:id/labels
 ```
 
-| Attribute | Type    | Required | Description           |
-| --------- | ------- | -------- | --------------------- |
-| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| Attribute     | Type           | Required | Description                                                                                                                                                                  |
+| ---------     | -------        | -------- | ---------------------                                                                                                                                                        |
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user                                                              |
+| `with_counts` | boolean        | no       | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced in GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/31543))_ |
 
 ```bash
-curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/labels
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/labels?with_counts=true
 ```
 
 Example response:
diff --git a/doc/api/license.md b/doc/api/license.md
index 2a8de64bdbf..12f1d03d576 100644
--- a/doc/api/license.md
+++ b/doc/api/license.md
@@ -1,4 +1,4 @@
-# License **[CORE ONLY]**
+# License **(CORE ONLY)**
 
 In order to interact with license endpoints, you need to authenticate yourself
 as an admin.
@@ -131,7 +131,6 @@ Returns:
 - `201 Created` if the license is successfully added.
 - `400 Bad Request` if the license couldn't be added, with an error message explaining the reason.
 
-
 ## Delete a license
 
 ```
diff --git a/doc/api/lint.md b/doc/api/lint.md
index 71c09d35b8c..79f5e629c7f 100644
--- a/doc/api/lint.md
+++ b/doc/api/lint.md
@@ -5,7 +5,7 @@
 Checks if your `.gitlab-ci.yml` file is valid.
 
 ```
-POST /lint
+POST /ci/lint
 ```
 
 | Attribute  | Type    | Required | Description |
@@ -22,30 +22,30 @@ Example responses:
 
 - Valid content:
 
-    ```json
-    {
-      "status": "valid",
-      "errors": []
-    }
-    ```
+  ```json
+  {
+    "status": "valid",
+    "errors": []
+  }
+  ```
 
 - Invalid content:
 
-    ```json
-    {
-      "status": "invalid",
-      "errors": [
-        "variables config should be a hash of key value pairs"
-      ]
-    }
-    ```
+  ```json
+  {
+    "status": "invalid",
+    "errors": [
+      "variables config should be a hash of key value pairs"
+    ]
+  }
+  ```
 
 - Without the content attribute:
 
-    ```json
-    {
-      "error": "content is missing"
-    }
-    ```
+  ```json
+  {
+    "error": "content is missing"
+  }
+  ```
 
 [ce-5953]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5953
diff --git a/doc/api/managed_licenses.md b/doc/api/managed_licenses.md
index 47b193111b6..1af7567626f 100644
--- a/doc/api/managed_licenses.md
+++ b/doc/api/managed_licenses.md
@@ -1,4 +1,4 @@
-# Managed Licenses API **[ULTIMATE]**
+# Managed Licenses API **(ULTIMATE)**
 
 ## List managed licenses
 
@@ -105,7 +105,7 @@ DELETE /projects/:id/managed_licenses/:managed_license_id
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/managed_licenses/4"
 ```
 
-When successful, it replies with an HTTP 204 response. 
+When successful, it replies with an HTTP 204 response.
 
 ## Edit an existing managed license
 
diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md
index ddac81328b9..bf83bfd7e6a 100644
--- a/doc/api/merge_request_approvals.md
+++ b/doc/api/merge_request_approvals.md
@@ -1,4 +1,4 @@
-# Merge request approvals API **[STARTER]**
+# Merge request approvals API **(STARTER)**
 
 Configuration for approvals on all Merge Requests (MR) in the project. Must be authenticated for all endpoints.
 
@@ -23,36 +23,6 @@ GET /projects/:id/approvals
 
 ```json
 {
-  "approvers": [
-    {
-      "user": {
-        "id": 5,
-        "name": "John Doe6",
-        "username": "user5",
-        "state":"active","avatar_url":"https://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80\u0026d=identicon","web_url":"http://localhost/user5"
-      }
-    }
-  ],
-  "approver_groups": [
-    {
-      "group": {
-        "id": 1,
-        "name": "group1",
-        "path": "group1",
-        "description": "",
-        "visibility": "public",
-        "lfs_enabled": false,
-        "avatar_url": null,
-        "web_url": "http://localhost/groups/group1",
-        "request_access_enabled": false,
-        "full_name": "group1",
-        "full_path": "group1",
-        "parent_id": null,
-        "ldap_cn": null,
-        "ldap_access": null
-      }
-    }
-  ],
   "approvals_before_merge": 2,
   "reset_approvals_on_push": true,
   "disable_overriding_approvers_per_merge_request": false
@@ -72,30 +42,79 @@ POST /projects/:id/approvals
 
 **Parameters:**
 
-| Attribute                                        | Type    | Required | Description                                                   |
-| ------------------------------------------------ | ------- | -------- | ----------------------------------------------------------    |
-| `id`                                             | integer | yes      | The ID of a project                                           |
-| `approvals_before_merge`                         | integer | no       | How many approvals are required before an MR can be merged    |
-| `reset_approvals_on_push`                        | boolean | no       | Reset approvals on a new push                                 |
-| `disable_overriding_approvers_per_merge_request` | boolean | no       | Allow/Disallow overriding approvers per MR                    |
-| `merge_requests_author_approval`                 | boolean | no       | Allow/Disallow authors be able to self approve merge requests |
+| Attribute                                        | Type    | Required | Description                                                                                         |
+| ------------------------------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------- |
+| `id`                                             | integer | yes      | The ID of a project                                                                                 |
+| `approvals_before_merge`                         | integer | no       | How many approvals are required before an MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. |
+| `reset_approvals_on_push`                        | boolean | no       | Reset approvals on a new push                                                                       |
+| `disable_overriding_approvers_per_merge_request` | boolean | no       | Allow/Disallow overriding approvers per MR                                                          |
+| `merge_requests_author_approval`                 | boolean | no       | Allow/Disallow authors from self approving merge requests; `true` means authors cannot self approve |
+| `merge_requests_disable_committers_approval`     | boolean | no       | Allow/Disallow committers from self approving merge requests                                        |
 
 ```json
 {
-  "approvers": [
-    {
-      "user": {
+  "approvals_before_merge": 2,
+  "reset_approvals_on_push": true,
+  "disable_overriding_approvers_per_merge_request": false,
+  "merge_requests_author_approval": false,
+  "merge_requests_disable_committers_approval": false
+}
+```
+
+### Get project-level rules
+
+>**Note:** This API endpoint is only available on 12.3 Starter and above.
+
+You can request information about a project's approval rules using the following endpoint:
+
+```
+GET /projects/:id/approval_rules
+```
+
+**Parameters:**
+
+| Attribute            | Type    | Required | Description                                               |
+|----------------------|---------|----------|-----------------------------------------------------------|
+| `id`                 | integer | yes      | The ID of a project                                       |
+
+```json
+[
+  {
+    "id": 1,
+    "name": "security",
+    "rule_type": "regular",
+    "eligible_approvers": [
+      {
         "id": 5,
-        "name": "John Doe6",
-        "username": "user5",
-        "state":"active","avatar_url":"https://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80\u0026d=identicon","web_url":"http://localhost/user5"
+        "name": "John Doe",
+        "username": "jdoe",
+        "state": "active",
+        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+        "web_url": "http://localhost/jdoe"
+      },
+      {
+        "id": 50,
+        "name": "Group Member 1",
+        "username": "group_member_1",
+        "state": "active",
+        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+        "web_url": "http://localhost/group_member_1"
       }
-    }
-  ],
-  "approver_groups": [
-    {
-      "group": {
-        "id": 1,
+    ],
+    "approvals_required": 3,
+    "users": [
+      {
+        "id": 5,
+        "name": "John Doe",
+        "username": "jdoe",
+        "state": "active",
+        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+        "web_url": "http://localhost/jdoe"
+      }
+    ],
+    "groups": [
+      {
+        "id": 5,
         "name": "group1",
         "path": "group1",
         "description": "",
@@ -110,17 +129,187 @@ POST /projects/:id/approvals
         "ldap_cn": null,
         "ldap_access": null
       }
+    ],
+    "contains_hidden_groups": false
+  }
+]
+```
+
+### Create project-level rule
+
+>**Note:** This API endpoint is only available on 12.3 Starter and above.
+
+You can create project approval rules using the following endpoint:
+
+```
+POST /projects/:id/approval_rules
+```
+
+**Parameters:**
+
+| Attribute            | Type    | Required | Description                                               |
+|----------------------|---------|----------|-----------------------------------------------------------|
+| `id`                 | integer | yes      | The ID of a project                                       |
+| `name`               | string  | yes      | The name of the approval rule                             |
+| `approvals_required` | integer | yes      | The number of required approvals for this rule            |
+| `users`              | integer | no       | The ids of users as approvers                             |
+| `groups`             | integer | no       | The ids of groups as approvers                            |
+
+```json
+{
+  "id": 1,
+  "name": "security",
+  "rule_type": "regular",
+  "eligible_approvers": [
+    {
+      "id": 2,
+      "name": "John Doe",
+      "username": "jdoe",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+      "web_url": "http://localhost/jdoe"
+    },
+    {
+      "id": 50,
+      "name": "Group Member 1",
+      "username": "group_member_1",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+      "web_url": "http://localhost/group_member_1"
     }
   ],
-  "approvals_before_merge": 2,
-  "reset_approvals_on_push": true,
-  "disable_overriding_approvers_per_merge_request": false,
-  "merge_requests_author_approval": false
+  "approvals_required": 1,
+  "users": [
+    {
+      "id": 2,
+      "name": "John Doe",
+      "username": "jdoe",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+      "web_url": "http://localhost/jdoe"
+    }
+  ],
+  "groups": [
+    {
+      "id": 5,
+      "name": "group1",
+      "path": "group1",
+      "description": "",
+      "visibility": "public",
+      "lfs_enabled": false,
+      "avatar_url": null,
+      "web_url": "http://localhost/groups/group1",
+      "request_access_enabled": false,
+      "full_name": "group1",
+      "full_path": "group1",
+      "parent_id": null,
+      "ldap_cn": null,
+      "ldap_access": null
+    }
+  ],
+  "contains_hidden_groups": false
 }
 ```
 
+### Update project-level rule
+
+>**Note:** This API endpoint is only available on 12.3 Starter and above.
+
+You can update project approval rules using the following endpoint:
+
+```
+PUT /projects/:id/approval_rules/:approval_rule_id
+```
+
+**Important:** Approvers and groups not in the `users`/`groups` param will be **removed**
+
+**Parameters:**
+
+| Attribute            | Type    | Required | Description                                               |
+|----------------------|---------|----------|-----------------------------------------------------------|
+| `id`                 | integer | yes      | The ID of a project                                       |
+| `approval_rule_id`   | integer | yes      | The ID of a approval rule                                 |
+| `name`               | string  | yes      | The name of the approval rule                             |
+| `approvals_required` | integer | yes      | The number of required approvals for this rule            |
+| `users`              | integer | no       | The ids of users as approvers                             |
+| `groups`             | integer | no       | The ids of groups as approvers                            |
+
+```json
+{
+  "id": 1,
+  "name": "security",
+  "rule_type": "regular",
+  "eligible_approvers": [
+    {
+      "id": 2,
+      "name": "John Doe",
+      "username": "jdoe",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+      "web_url": "http://localhost/jdoe"
+    },
+    {
+      "id": 50,
+      "name": "Group Member 1",
+      "username": "group_member_1",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+      "web_url": "http://localhost/group_member_1"
+    }
+  ],
+  "approvals_required": 1,
+  "users": [
+    {
+      "id": 2,
+      "name": "John Doe",
+      "username": "jdoe",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
+      "web_url": "http://localhost/jdoe"
+    }
+  ],
+  "groups": [
+    {
+      "id": 5,
+      "name": "group1",
+      "path": "group1",
+      "description": "",
+      "visibility": "public",
+      "lfs_enabled": false,
+      "avatar_url": null,
+      "web_url": "http://localhost/groups/group1",
+      "request_access_enabled": false,
+      "full_name": "group1",
+      "full_path": "group1",
+      "parent_id": null,
+      "ldap_cn": null,
+      "ldap_access": null
+    }
+  ],
+  "contains_hidden_groups": false
+}
+```
+
+### Delete project-level rule
+
+>**Note:** This API endpoint is only available on 12.3 Starter and above.
+
+You can delete project approval rules using the following endpoint:
+
+```
+DELETE /projects/:id/approval_rules/:approval_rule_id
+```
+
+**Parameters:**
+
+| Attribute            | Type    | Required | Description                                               |
+|----------------------|---------|----------|-----------------------------------------------------------|
+| `id`                 | integer | yes      | The ID of a project                                       |
+| `approval_rule_id`   | integer | yes      | The ID of a approval rule
+
 ### Change allowed approvers
 
+>**Note:** This API endpoint has been deprecated. Please use Approval Rule API instead.
 >**Note:** This API endpoint is only available on 10.6 Starter and above.
 
 If you are allowed to, you can change approvers and approver groups using
@@ -178,7 +367,6 @@ PUT /projects/:id/approvers
 }
 ```
 
-
 ## Merge Request-level MR approvals
 
 Configuration for approvals on a specific Merge Request. Must be authenticated for all endpoints.
@@ -222,12 +410,10 @@ GET /projects/:id/merge_requests/:merge_request_iid/approvals
         "id": 1,
         "state": "active",
         "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon",
-        "web_url": "http://localhost:3000/u/root"
+        "web_url": "http://localhost:3000/root"
       }
     }
   ],
-  "approvers": [],
-  "approver_groups": []
 }
 ```
 
@@ -248,8 +434,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals
 |----------------------|---------|----------|--------------------------------------------|
 | `id`                 | integer | yes      | The ID of a project                        |
 | `merge_request_iid`  | integer | yes      | The IID of MR                              |
-| `approvals_required` | integer | yes      | Approvals required before MR can be merged |
-
+| `approvals_required` | integer | yes      | Approvals required before MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. |
 
 ```json
 {
@@ -264,14 +449,13 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals
   "merge_status": "cannot_be_merged",
   "approvals_required": 2,
   "approvals_left": 2,
-  "approved_by": [],
-  "approvers": [],
-  "approver_groups": []
+  "approved_by": []
 }
 ```
 
 ### Change allowed approvers for Merge Request
 
+>**Note:** This API endpoint has been deprecated. Please use Approval Rule API instead.
 >**Note:** This API endpoint is only available on 10.6 Starter and above.
 
 If you are allowed to, you can change approvers and approver groups using
@@ -314,7 +498,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/approvers
         "id": 1,
         "state": "active",
         "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon",
-        "web_url": "http://localhost:3000/u/root" 
+        "web_url": "http://localhost:3000/root"
       }
     }
   ],
@@ -359,7 +543,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve
 | `id`                | integer | yes      | The ID of a project     |
 | `merge_request_iid` | integer | yes      | The IID of MR           |
 | `sha`               | string  | no       | The HEAD of the MR      |
-| `approval_password` **[STARTER]** | string  | no      | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/merge_request_approvals.md#require-authentication-when-approving-a-merge-request-starter) is enabled in the project settings. |
+| `approval_password` **(STARTER)** | string  | no      | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/merge_request_approvals.md#require-authentication-when-approving-a-merge-request-starter) is enabled in the project settings. |
 
 The `sha` parameter works in the same way as
 when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must
@@ -387,7 +571,7 @@ does not match, the response code will be `409`.
         "id": 1,
         "state": "active",
         "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon",
-        "web_url": "http://localhost:3000/u/root"
+        "web_url": "http://localhost:3000/root"
       }
     },
     {
@@ -397,12 +581,10 @@ does not match, the response code will be `409`.
         "id": 2,
         "state": "active",
         "avatar_url": "http://www.gravatar.com/avatar/cf7ad14b34162a76d593e3affca2adca?s=80\u0026d=identicon",
-        "web_url": "http://localhost:3000/u/ryley"
+        "web_url": "http://localhost:3000/ryley"
       }
     }
   ],
-  "approvers": [],
-  "approver_groups": []
 }
 ```
 
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index dd7810c3403..1ade46efb1c 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -29,27 +29,28 @@ GET /merge_requests?search=foo&in=title
 
 Parameters:
 
-| Attribute           | Type     | Required | Description                                                                                                            |
-| ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `state`             | string   | no       | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`                             |
-| `order_by`          | string   | no       | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`                                |
-| `sort`              | string   | no       | Return requests sorted in `asc` or `desc` order. Default is `desc`                                                     |
-| `milestone`         | string   | no       | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
-| `view`              | string   | no       | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request                              |
-| `labels`            | string   | no       | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
-| `created_after`     | datetime | no       | Return merge requests created on or after the given time                                                               |
-| `created_before`    | datetime | no       | Return merge requests created on or before the given time                                                              |
-| `updated_after`     | datetime | no       | Return merge requests updated on or after the given time                                                               |
-| `updated_before`    | datetime | no       | Return merge requests updated on or before the given time                                                              |
-| `scope`             | string   | no       | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. |
-| `author_id`         | integer  | no       | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me`              |
-| `assignee_id`       | integer  | no       | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. |
-| `my_reaction_emoji` | string   | no       | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
-| `source_branch`     | string   | no       | Return merge requests with the given source branch                                                                     |
-| `target_branch`     | string   | no       | Return merge requests with the given target branch                                                                     |
-| `search`            | string   | no       | Search merge requests against their `title` and `description`                                                          |
-| `in`                | string   | no       | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` |
-| `wip`               | string   | no       | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests |
+| Attribute           | Type           | Required | Description                                                                                                            |
+| ------------------- | --------       | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `state`             | string         | no       | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`                             |
+| `order_by`          | string         | no       | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`                                |
+| `sort`              | string         | no       | Return requests sorted in `asc` or `desc` order. Default is `desc`                                                     |
+| `milestone`         | string         | no       | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
+| `view`              | string         | no       | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request                              |
+| `labels`            | string         | no       | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
+| `created_after`     | datetime       | no       | Return merge requests created on or after the given time                                                               |
+| `created_before`    | datetime       | no       | Return merge requests created on or before the given time                                                              |
+| `updated_after`     | datetime       | no       | Return merge requests updated on or after the given time                                                               |
+| `updated_before`    | datetime       | no       | Return merge requests updated on or before the given time                                                              |
+| `scope`             | string         | no       | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. |
+| `author_id`         | integer        | no       | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me`              |
+| `assignee_id`       | integer        | no       | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. |
+| `approver_ids` **(STARTER)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. |
+| `my_reaction_emoji` | string         | no       | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
+| `source_branch`     | string         | no       | Return merge requests with the given source branch                                                                     |
+| `target_branch`     | string         | no       | Return merge requests with the given target branch                                                                     |
+| `search`            | string         | no       | Search merge requests against their `title` and `description`                                                          |
+| `in`                | string         | no       | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` |
+| `wip`               | string         | no       | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests |
 
 ```json
 [
@@ -147,6 +148,20 @@ Parameters:
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+[
+  {
+    "id": 1,
+    "title": "test1",
+    "approvals_before_merge": null
+    ...
+  }
+]
+```
+
 ## List project merge requests
 
 Get all merge requests for this project.
@@ -177,7 +192,7 @@ Parameters:
 | Attribute           | Type           | Required | Description                                                                                                                    |
 | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | `id`                | integer        | yes      | The ID of a project                                                                                                            |
-| `iids[]`            | Array[integer] | no       | Return the request having the given `iid`                                                                                      |
+| `iids[]`            | integer array  | no     | Return the request having the given `iid`                                                                                      |
 | `state`             | string         | no       | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`                                     |
 | `order_by`          | string         | no       | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`                                        |
 | `sort`              | string         | no       | Return requests sorted in `asc` or `desc` order. Default is `desc`                                                             |
@@ -191,6 +206,7 @@ Parameters:
 | `scope`             | string         | no       | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13060] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ |
 | `author_id`         | integer        | no       | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_                                 |
 | `assignee_id`       | integer        | no       | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ |
+| `approver_ids` **(STARTER)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. |
 | `my_reaction_emoji` | string         | no       | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
 | `source_branch`     | string         | no       | Return merge requests with the given source branch                                                                             |
 | `target_branch`     | string         | no       | Return merge requests with the given target branch                                                                             |
@@ -293,6 +309,20 @@ Parameters:
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+[
+  {
+    "id": 1,
+    "title": "test1",
+    "approvals_before_merge": null
+    ...
+  }
+]
+```
+
 ## List group merge requests
 
 Get all merge requests for this group and its subgroups.
@@ -328,6 +358,7 @@ Parameters:
 | `scope`             | string         | no       | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br>                                     |
 | `author_id`         | integer        | no       | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_                                 |
 | `assignee_id`       | integer        | no       | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ |
+| `approver_ids` **(STARTER)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. |
 | `my_reaction_emoji` | string         | no       | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
 | `source_branch`     | string         | no       | Return merge requests with the given source branch                                                                             |
 | `target_branch`     | string         | no       | Return merge requests with the given target branch                                                                             |
@@ -427,6 +458,20 @@ Parameters:
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+[
+  {
+    "id": 1,
+    "title": "test1",
+    "approvals_before_merge": null
+    ...
+  }
+]
+```
+
 ## Get single MR
 
 Shows information about a single merge request.
@@ -565,6 +610,18 @@ Parameters:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
 ## Get single MR participants
 
 Get a list of merge request participants.
@@ -767,18 +824,19 @@ Parameters:
 ## Create MR
 
 Creates a new merge request.
+
 ```
 POST /projects/:id/merge_requests
 ```
 
 | Attribute                  | Type    | Required | Description                                                                     |
 | ---------                  | ----    | -------- | -----------                                                                     |
-| `id`                       | integer/string  | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`                       | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `source_branch`            | string  | yes      | The source branch                                                               |
 | `target_branch`            | string  | yes      | The target branch                                                               |
 | `title`                    | string  | yes      | Title of MR                                                                     |
 | `assignee_id`              | integer | no       | Assignee user ID                                                                |
-| `assignee_ids`             | Array[integer] | no  | The ID of the user(s) to assign the MR to. Set to `0` or provide an empty value to unassign all assignees.  |
+| `assignee_ids`             | integer array | no | The ID of the user(s) to assign the MR to. Set to `0` or provide an empty value to unassign all assignees.  |
 | `description`              | string  | no       | Description of MR                                                               |
 | `target_project_id`        | integer | no       | The target project (numeric id)                                                 |
 | `labels`                   | string  | no       | Labels for MR as a comma-separated list                                         |
@@ -788,6 +846,15 @@ POST /projects/:id/merge_requests
 | `allow_maintainer_to_push` | boolean | no       | Deprecated, see allow_collaboration                                             |
 | `squash`                   | boolean | no       | Squash commits into a single commit when merging                                |
 
+If `approvals_before_merge` **(STARTER)** is not provided, it inherits the value from the
+target project. If it is provided, then the following conditions must hold in
+order for it to take effect:
+
+1. The target project's `approvals_before_merge` must be greater than zero. A
+   value of zero disables approvals for that project.
+1. The provided value of `approvals_before_merge` must be greater than the
+   target project's `approvals_before_merge`.
+
 ```json
 {
   "id": 1,
@@ -893,6 +960,18 @@ POST /projects/:id/merge_requests
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
 ## Update MR
 
 Updates an existing merge request. You can change the target branch, title, or even close the MR.
@@ -908,7 +987,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid
 | `target_branch`            | string  | no       | The target branch                                                               |
 | `title`                    | string  | no       | Title of MR                                                                     |
 | `assignee_id`              | integer | no       | The ID of the user to assign the merge request to. Set to `0` or provide an empty value to unassign all assignees.  |
-| `assignee_ids`             | Array[integer] | no  | The ID of the user(s) to assign the MR to. Set to `0` or provide an empty value to unassign all assignees.  |
+| `assignee_ids`             | integer array | no | The ID of the user(s) to assign the MR to. Set to `0` or provide an empty value to unassign all assignees.  |
 | `milestone_id`             | integer | no       | The global ID of a milestone to assign the merge request to. Set to `0` or provide an empty value to unassign a milestone.|
 | `labels`                   | string  | no       | Comma-separated label names for a merge request. Set to an empty string to unassign all labels.                    |
 | `description`              | string  | no       | Description of MR                                                               |
@@ -1034,6 +1113,18 @@ Must include at least one non-required attribute from above.
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
 ## Delete a merge request
 
 Only for admins and project owners. Soft deletes the merge request in question.
@@ -1191,33 +1282,41 @@ Parameters:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
 ## Merge to default merge ref path
 
-Merge the changes between the merge request source and target branches into `refs/merge-requests/:iid/merge` 
-ref, of the target project repository. This ref will have the state the target branch would have if
+Merge the changes between the merge request source and target branches into `refs/merge-requests/:iid/merge`
+ref, of the target project repository, if possible. This ref will have the state the target branch would have if
 a regular merge action was taken.
 
-This is not a regular merge action given it doesn't change the merge request state in any manner.
+This is not a regular merge action given it doesn't change the merge request target branch state in any manner.
 
-This ref (`refs/merge-requests/:iid/merge`) is **always** overwritten when submitting
-requests to this API, so none of its state is kept or used in the process.
+This ref (`refs/merge-requests/:iid/merge`) isn't necessarily overwritten when submitting
+requests to this API, though it'll make sure the ref has the latest possible state.
 
-If the merge request has conflicts, is empty or already merged,
-you'll get a `400` and a descriptive error message. If you don't have permissions to do so, 
-you'll get a `403`.
+If the merge request has conflicts, is empty or already merged, you'll get a `400` and a descriptive error message.
 
-It returns the HEAD commit of `refs/merge-requests/:iid/merge` in the response body in
-case of `200`.
+It returns the HEAD commit of `refs/merge-requests/:iid/merge` in the response body in case of `200`.
 
 ```
-PUT /projects/:id/merge_requests/:merge_request_iid/merge_to_ref
+GET /projects/:id/merge_requests/:merge_request_iid/merge_ref
 ```
 
 Parameters:
 
 - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
 - `merge_request_iid` (required)            - Internal ID of MR
-- `merge_commit_message` (optional)         - Custom merge commit message
 
 ```json
 {
@@ -1232,9 +1331,11 @@ If you don't have permissions to accept this merge request - you'll get a `401`
 If the merge request is already merged or closed - you get `405` and error message 'Method Not Allowed'
 
 In case the merge request is not set to be merged when the pipeline succeeds, you'll also get a `406` error.
+
 ```
 PUT /projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_succeeds
 ```
+
 Parameters:
 
 - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
@@ -1353,6 +1454,18 @@ Parameters:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
 ## Rebase a merge request
 
 Automatically rebase the `source_branch` of the merge request against its
@@ -1374,8 +1487,14 @@ PUT /projects/:id/merge_requests/:merge_request_iid/rebase
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/76/merge_requests/1/rebase
 ```
 
-This is an asynchronous request. The API will return an empty `202 Accepted`
-response if the request is enqueued successfully.
+This is an asynchronous request. The API will return a `202 Accepted` response
+if the request is enqueued successfully, with a response containing:
+
+```json
+{
+  "rebase_in_progress": true
+}
+```
 
 You can poll the [Get single MR](#get-single-mr) endpoint with the
 `include_rebase_in_progress` parameter to check the status of the
@@ -1477,7 +1596,7 @@ Example response when the GitLab issue tracker is used:
 ]
 ```
 
-Example response when an external issue tracker (e.g. JIRA) is used:
+Example response when an external issue tracker (e.g. Jira) is used:
 
 ```json
 [
@@ -1620,6 +1739,18 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
 ## Unsubscribe from a merge request
 
 Unsubscribes the authenticated user from a merge request to not receive
@@ -1753,6 +1884,18 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
 ## Create a todo
 
 Manually creates a todo for the current user on a merge request.
@@ -1974,6 +2117,7 @@ Example response:
   }]
 }
 ```
+
 ## Set a time estimate for a merge request
 
 Sets an estimated time of work for this merge request.
@@ -2118,3 +2262,7 @@ Example response:
 [ce-14016]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14016
 [ce-15454]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15454
 [ce-18935]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18935
+
+## Approvals **(STARTER)**
+
+For approvals, please see [Merge Request Approvals](merge_request_approvals.md)
diff --git a/doc/api/milestones.md b/doc/api/milestones.md
index 90d8c033cd6..a6ded7d3bd2 100644
--- a/doc/api/milestones.md
+++ b/doc/api/milestones.md
@@ -16,13 +16,13 @@ GET /projects/:id/milestones?search=version
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `iids[]` | Array[integer] | optional | Return only the milestones having the given `iid` |
-| `state` | string | optional | Return only `active` or `closed` milestones |
-| `title` | string | optional | Return only the milestones having the given `title` |
-| `search` | string | optional | Return only milestones with a title or description matching the provided string |
+| Attribute | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `iids[]`  | integer array | optional | Return only the milestones having the given `iid` |
+| `state`   | string | optional | Return only `active` or `closed` milestones |
+| `title`   | string | optional | Return only the milestones having the given `title` |
+| `search`  | string | optional | Return only milestones with a title or description matching the provided string |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/milestones
@@ -147,3 +147,18 @@ Parameters:
 
 - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
 - `milestone_id` (required) - The ID of a project milestone
+
+## Get all burndown chart events for a single milestone **(STARTER)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4737) in GitLab 12.1
+
+Gets all burndown chart events for a single milestone.
+
+```
+GET /projects/:id/milestones/:milestone_id/burndown_events
+```
+
+Parameters:
+
+- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
+- `milestone_id` (required) - The ID of a project milestone
diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md
index b66a3198ffb..2b6eddf78a1 100644
--- a/doc/api/namespaces.md
+++ b/doc/api/namespaces.md
@@ -54,7 +54,21 @@ Example response:
 ]
 ```
 
-**Note**: `members_count_with_descendants` are presented only for group maintainers/owners.
+Users on GitLab.com [Bronze or higher](https://about.gitlab.com/pricing/#gitlab-com) may also see
+the `plan` parameter associated with a namespace:
+
+```json
+[
+  {
+    "id": 1,
+    "name": "user1",
+    "plan": "bronze",
+    ...
+  }
+]
+```
+
+NOTE: **Note:** Only group maintainers/owners are presented with `members_count_with_descendants`, as well as `plan` **(BRONZE ONLY)**.
 
 ## Search for namespace
 
diff --git a/doc/api/notes.md b/doc/api/notes.md
index c09129c22d4..acbf0334563 100644
--- a/doc/api/notes.md
+++ b/doc/api/notes.md
@@ -5,7 +5,7 @@ Notes are comments on:
 - Snippets
 - Issues
 - Merge requests
-- Epics **[ULTIMATE]**
+- Epics **(ULTIMATE)**
 
 This includes system notes, which are notes about changes to the object (for example, when a milestone changes, there will be a corresponding system note). Label notes are not part of this API, but recorded as separate events in [resource label events](resource_label_events.md).
 
@@ -396,7 +396,7 @@ Parameters:
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602
 ```
 
-## Epics **[ULTIMATE]**
+## Epics **(ULTIMATE)**
 
 ### List all epic notes
 
diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md
index e21e73c7dac..c6667784617 100644
--- a/doc/api/notification_settings.md
+++ b/doc/api/notification_settings.md
@@ -1,8 +1,8 @@
 # Notification settings API
 
->**Note:** This feature was [introduced][ce-5632] in GitLab 8.12.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632) in GitLab 8.12.
 
-**Valid notification levels**
+## Valid notification levels
 
 The notification levels are defined in the `NotificationSetting.level` model enumeration. Currently, these levels are recognized:
 
@@ -17,22 +17,21 @@ custom
 
 If the `custom` level is used, specific email events can be controlled. Available events are returned by `NotificationSetting.email_events`. Currently, these events are recognized:
 
-```
-new_note
-new_issue
-reopen_issue
-close_issue
-reassign_issue
-issue_due
-new_merge_request
-push_to_merge_request
-reopen_merge_request
-close_merge_request
-reassign_merge_request
-merge_merge_request
-failed_pipeline
-success_pipeline
-```
+- `new_note`
+- `new_issue`
+- `reopen_issue`
+- `close_issue`
+- `reassign_issue`
+- `issue_due`
+- `new_merge_request`
+- `push_to_merge_request`
+- `reopen_merge_request`
+- `close_merge_request`
+- `reassign_merge_request`
+- `merge_merge_request`
+- `failed_pipeline`
+- `success_pipeline`
+- `new_epic` **(ULTIMATE)**
 
 ## Global notification settings
 
@@ -85,6 +84,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.
 | `merge_merge_request` | boolean | no | Enable/disable this notification |
 | `failed_pipeline` | boolean | no | Enable/disable this notification |
 | `success_pipeline` | boolean | no | Enable/disable this notification |
+| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) **(ULTIMATE)** |
 
 Example response:
 
@@ -153,6 +153,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.
 | `merge_merge_request` | boolean | no | Enable/disable this notification |
 | `failed_pipeline` | boolean | no | Enable/disable this notification |
 | `success_pipeline` | boolean | no | Enable/disable this notification |
+| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) **(ULTIMATE)** |
 
 Example responses:
 
@@ -182,4 +183,17 @@ Example responses:
 }
 ```
 
-[ce-5632]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632
+Users on GitLab [Ultimate or Gold](https://about.gitlab.com/pricing/) will also see
+the `new_epic` parameter:
+
+```json
+{
+  "level": "custom",
+  "events": {
+    "new_note": true,
+    "new_issue": false,
+    "new_epic": false,
+    ...
+  }
+}
+```
diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md
index dfe62554852..f9382361187 100644
--- a/doc/api/oauth2.md
+++ b/doc/api/oauth2.md
@@ -50,11 +50,14 @@ The web application flow is:
    `/oauth/authorize` endpoint with the following GET parameters:
 
    ```
-   https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=YOUR_UNIQUE_STATE_HASH
+   https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=YOUR_UNIQUE_STATE_HASH&scope=REQUESTED_SCOPES
    ```
 
-   This will ask the user to approve the applications access to their account and
-   then redirect back to the `REDIRECT_URI` you provided. The redirect will
+   This will ask the user to approve the applications access to their account
+   based on the scopes specified in `REQUESTED_SCOPES` and then redirect back to
+   the `REDIRECT_URI` you provided. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes)
+   is a space separated list of scopes you want to have access to (e.g. `scope=read_user+profile`
+   would request `read_user` and `profile` scopes). The redirect will
    include the GET `code` parameter, for example:
 
    ```
@@ -110,11 +113,14 @@ To request the access token, you should redirect the user to the
 `/oauth/authorize` endpoint using `token` response type:
 
 ```
-https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=token&state=YOUR_UNIQUE_STATE_HASH
+https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=token&state=YOUR_UNIQUE_STATE_HASH&scope=REQUESTED_SCOPES
 ```
 
-This will ask the user to approve the application's access to their account and
-then redirect them back to the `REDIRECT_URI` you provided. The redirect
+This will ask the user to approve the applications access to their account
+based on the scopes specified in `REQUESTED_SCOPES` and then redirect back to
+the `REDIRECT_URI` you provided. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes)
+   is a space separated list of scopes you want to have access to (e.g. `scope=read_user+profile`
+would request `read_user` and `profile` scopes). The redirect
 will include a fragment with `access_token` as well as token details in GET
 parameters, for example:
 
@@ -192,7 +198,7 @@ access_token = client.password.get_token('user@example.com', 'secret')
 puts access_token.token
 ```
 
-##  Access GitLab API with `access token`
+## Access GitLab API with `access token`
 
 The `access token` allows you to make requests to the API on behalf of a user.
 You can pass the token either as GET parameter:
diff --git a/doc/api/packages.md b/doc/api/packages.md
index 618e5c3056a..ca90771b085 100644
--- a/doc/api/packages.md
+++ b/doc/api/packages.md
@@ -1,4 +1,4 @@
-# Packages API **[PREMIUM]**
+# Packages API **(PREMIUM)**
 
 This is the API docs of [GitLab Packages](../administration/packages.md).
 
@@ -76,7 +76,7 @@ Example response:
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9305) in GitLab 11.8.
 
-Get a list of package files of a single package. 
+Get a list of package files of a single package.
 
 ```
 GET /projects/:id/packages/:package_id/package_files
diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md
index 70fbe24099f..9678203eb40 100644
--- a/doc/api/pages_domains.md
+++ b/doc/api/pages_domains.md
@@ -1,6 +1,6 @@
 # Pages domains API
 
-Endpoints for connecting custom domain(s) and TLS certificates in [GitLab Pages](https://about.gitlab.com/features/pages/).
+Endpoints for connecting custom domain(s) and TLS certificates in [GitLab Pages](https://about.gitlab.com/product/pages/).
 
 The GitLab Pages feature must be enabled to use these endpoints. Find out more about [administering](../administration/pages/index.md) and [using](../user/project/pages/index.md) the feature.
 
diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md
index 470e55425f8..acf1ac90315 100644
--- a/doc/api/pipeline_schedules.md
+++ b/doc/api/pipeline_schedules.md
@@ -108,9 +108,9 @@ POST /projects/:id/pipeline_schedules
 | `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user      |
 | `description` | string  | yes      | The description of pipeline schedule         |
 | `ref` | string  | yes      | The branch/tag name will be triggered         |
-| `cron ` | string  | yes      | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron))       |
-| `cron_timezone ` | string  | no      | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) (default: `'UTC'`)     |
-| `active ` | boolean  | no      | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially (default: `true`) |
+| `cron` | string  | yes      | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron))       |
+| `cron_timezone` | string  | no      | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) (default: `'UTC'`)     |
+| `active` | boolean  | no      | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially (default: `true`) |
 
 ```sh
 curl --request POST --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form description="Build packages" --form ref="master" --form cron="0 1 * * 5" --form cron_timezone="UTC" --form active="true" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
@@ -153,9 +153,9 @@ PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id
 | `pipeline_schedule_id`  | integer | yes      | The pipeline schedule id           |
 | `description` | string  | no      | The description of pipeline schedule         |
 | `ref` | string  | no      | The branch/tag name will be triggered         |
-| `cron ` | string  | no      | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron))       |
-| `cron_timezone ` | string  | no      | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) or `TZInfo::Timezone` (e.g. `America/Los_Angeles`)      |
-| `active ` | boolean  | no      | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially. |
+| `cron` | string  | no      | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron))       |
+| `cron_timezone` | string  | no      | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) or `TZInfo::Timezone` (e.g. `America/Los_Angeles`)      |
+| `active` | boolean  | no      | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially. |
 
 ```sh
 curl --request PUT --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form cron="0 2 * * *" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md
index 736312df116..e207ff8e98a 100644
--- a/doc/api/pipeline_triggers.md
+++ b/doc/api/pipeline_triggers.md
@@ -120,35 +120,6 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form descript
 }
 ```
 
-## Take ownership of a project trigger
-
-Update an owner of a project trigger.
-
-```
-POST /projects/:id/triggers/:trigger_id/take_ownership
-```
-
-| Attribute     | Type    | required | Description              |
-|---------------|---------|----------|--------------------------|
-| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user      |
-| `trigger_id`  | integer | yes      | The trigger id           |
-
-```
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers/10/take_ownership"
-```
-
-```json
-{
-    "id": 10,
-    "description": "my trigger",
-    "created_at": "2016-01-07T09:53:58.235Z",
-    "last_used": null,
-    "token": "6d056f63e50fe6f8c5f8f4aa10edb7",
-    "updated_at": "2016-01-07T09:53:58.235Z",
-    "owner": null
-}
-```
-
 ## Remove a project trigger
 
 Remove a project's build trigger.
diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md
index 753faec3cc8..e36f74e7c77 100644
--- a/doc/api/pipelines.md
+++ b/doc/api/pipelines.md
@@ -132,11 +132,11 @@ Example of response
 POST /projects/:id/pipeline
 ```
 
-| Attribute  | Type    | Required | Description         |
-|------------|---------|----------|---------------------|
-| `id`       | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `ref`       | string | yes      | Reference to commit |
-| `variables` | array | no | An array containing the variables available in the pipeline, matching the structure [{ 'key' => 'UPLOAD_TO_S3', 'variable_type' => 'file', 'value' => 'true' }] |
+| Attribute   | Type    | Required | Description         |
+|-------------|---------|----------|---------------------|
+| `id`        | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `ref`       | string  | yes      | Reference to commit |
+| `variables` | array   | no       | An array containing the variables available in the pipeline, matching the structure `[{ 'key' => 'UPLOAD_TO_S3', 'variable_type' => 'file', 'value' => 'true' }]` |
 
 ```
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=master"
diff --git a/doc/api/project_aliases.md b/doc/api/project_aliases.md
new file mode 100644
index 00000000000..271632b61c3
--- /dev/null
+++ b/doc/api/project_aliases.md
@@ -0,0 +1,111 @@
+# Project Aliases API **(PREMIUM ONLY)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1.
+
+All methods require administrator authorization.
+
+## List all project aliases
+
+Get a list of all project aliases:
+
+```
+GET /project_aliases
+```
+
+```
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/project_aliases"
+```
+
+Example response:
+
+```json
+[
+  {
+    "id": 1,
+    "project_id": 1,
+    "name": "gitlab-ce"
+  },
+  {
+    "id": 2,
+    "project_id": 2,
+    "name": "gitlab-ee"
+  }
+]
+```
+
+## Get project alias' details
+
+Get details of a project alias:
+
+```
+GET /project_aliases/:name
+```
+
+| Attribute | Type   | Required | Description           |
+|-----------|--------|----------|-----------------------|
+| `name`    | string | yes      | The name of the alias |
+
+```
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/project_aliases/gitlab-ee"
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "project_id": 1,
+  "name": "gitlab-ee"
+}
+```
+
+## Create a project alias
+
+Add a new alias for a project. Responds with a 201 when successful,
+400 when there are validation errors (e.g. alias already exists):
+
+```
+POST /project_aliases
+```
+
+| Attribute    | Type           | Required | Description                            |
+|--------------|----------------|----------|----------------------------------------|
+| `project_id` | integer/string | yes      | The ID or path of the project.         |
+| `name`       | string         | yes      | The name of the alias. Must be unique. |
+
+```
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/project_aliases" --form "project_id=1" --form "name=gitlab-ee"
+```
+
+or
+
+```
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/project_aliases" --form "project_id=gitlab-org/gitlab-ee" --form "name=gitlab-ee"
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "project_id": 1,
+  "name": "gitlab-ee"
+}
+```
+
+## Delete a project alias
+
+Removes a project aliases. Responds with a 204 when project alias
+exists, 404 when it doesn't:
+
+```
+DELETE /project_aliases/:name
+```
+
+| Attribute | Type   | Required | Description           |
+|-----------|--------|----------|-----------------------|
+| `name`    | string | yes      | The name of the alias |
+
+```
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/project_aliases/gitlab-ee"
+```
diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md
index 3a7b3d8975e..1c382232837 100644
--- a/doc/api/project_badges.md
+++ b/doc/api/project_badges.md
@@ -91,7 +91,7 @@ POST /projects/:id/badges
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id`      | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `link_url` | string         | yes | URL of the badge link |
 | `image_url` | string | yes | URL of the badge image |
 
diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md
index 327781f6c93..762a4ad95ab 100644
--- a/doc/api/project_clusters.md
+++ b/doc/api/project_clusters.md
@@ -167,7 +167,7 @@ Parameters:
 | `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
 | `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project |
 | `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. |
-| `environment_scope` | String | no | The associated environment to the cluster. Defaults to `*` **[PREMIUM]** |
+| `environment_scope` | String | no | The associated environment to the cluster. Defaults to `*` **(PREMIUM)** |
 
 Example request:
 
@@ -257,11 +257,11 @@ Parameters:
 | `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes |
 | `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
 | `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project |
-| `environment_scope` | String | no | The associated environment to the cluster **[PREMIUM]** |
+| `environment_scope` | String | no | The associated environment to the cluster **(PREMIUM)** |
 
 NOTE: **Note:**
 `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added
-through the ["Add an existing Kubernetes Cluster"](../user/project/clusters/index.md#adding-an-existing-kubernetes-cluster) option or
+through the ["Add existing Kubernetes cluster"](../user/project/clusters/index.md#add-existing-kubernetes-cluster) option or
 through the ["Add existing cluster to project"](#add-existing-cluster-to-project) endpoint.
 
 Example request:
diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md
index 66a749e4811..591911bb8ec 100644
--- a/doc/api/project_level_variables.md
+++ b/doc/api/project_level_variables.md
@@ -74,7 +74,7 @@ POST /projects/:id/variables
 | `variable_type`     | string  | no       | The type of a variable. Available types are: `env_var` (default) and `file` |
 | `protected`         | boolean | no       | Whether the variable is protected |
 | `masked`            | boolean | no       | Whether the variable is masked |
-| `environment_scope` | string  | no       | The `environment_scope` of the variable **[PREMIUM]** |
+| `environment_scope` | string  | no       | The `environment_scope` of the variable |
 
 ```
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value"
@@ -108,7 +108,7 @@ PUT /projects/:id/variables/:key
 | `variable_type`     | string  | no       | The type of a variable. Available types are: `env_var` (default) and `file` |
 | `protected`         | boolean | no       | Whether the variable is protected |
 | `masked`            | boolean | no       | Whether the variable is masked |
-| `environment_scope` | string  | no       | The `environment_scope` of the variable **[PREMIUM]** |
+| `environment_scope` | string  | no       | The `environment_scope` of the variable |
 
 ```
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value"
diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md
index 0ccb0517e08..c1588f2292a 100644
--- a/doc/api/project_snippets.md
+++ b/doc/api/project_snippets.md
@@ -1,6 +1,6 @@
 # Project snippets
 
-### Snippet visibility level
+## Snippet visibility level
 
 Snippets in GitLab can be either private, internal or public.
 You can set it with the `visibility` field in the snippet.
@@ -13,6 +13,12 @@ Constants for snippet visibility levels are:
 | `internal` | The snippet is visible for any logged in user |
 | `public`   | The snippet can be accessed without any authentication |
 
+NOTE: **Note:**
+From July 2019, the `Internal` visibility setting is disabled for new projects, groups,
+and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal`
+visibility setting keep this setting. You can read more about the change in the
+[relevant issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/12388).
+
 ## List snippets
 
 Get a list of project snippets.
diff --git a/doc/api/project_statistics.md b/doc/api/project_statistics.md
index 34d73abfcbf..2732fa47fa0 100644
--- a/doc/api/project_statistics.md
+++ b/doc/api/project_statistics.md
@@ -14,7 +14,7 @@ GET /projects/:id/statistics
 
 | Attribute  | Type   | Required | Description |
 | ---------- | ------ | -------- | ----------- |
-| `id `      | integer / string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+| `id`      | integer / string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 
 Example response:
 
diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md
index 0a94a8d47ae..cc932e3ef58 100644
--- a/doc/api/project_templates.md
+++ b/doc/api/project_templates.md
@@ -16,7 +16,7 @@ Support will be added for [Issue and Merge Request templates](../user/project/de
 in a future release.
 
 Support for [Group-level file templates](../user/group/index.md#group-file-templates-premium)
-**[PREMIUM]** was [added](https://gitlab.com/gitlab-org/gitlab-ee/issues/5987)
+**(PREMIUM)** was [added](https://gitlab.com/gitlab-org/gitlab-ee/issues/5987)
 in GitLab 11.5
 
 ## Get all templates of a particular type
@@ -27,7 +27,7 @@ GET /projects/:id/templates/:type
 
 | Attribute  | Type   | Required | Description |
 | ---------- | ------ | -------- | ----------- |
-| `id `      | integer / string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+| `id`      | integer / string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `type`     | string | yes| The type `(dockerfiles|gitignores|gitlab_ci_ymls|licenses)` of the template |
 
 Example response (licenses):
@@ -93,7 +93,7 @@ GET /projects/:id/templates/:type/:key
 
 | Attribute  | Type   | Required | Description |
 | ---------- | ------ | -------- | ----------- |
-| `id `      | integer / string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+| `id`      | integer / string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `type`     | string | yes| The type `(dockerfiles|gitignores|gitlab_ci_ymls|licenses)` of the template |
 | `key`      | string | yes      | The key of the template, as obtained from the collection endpoint |
 | `project`  | string | no       | The project name to use when expanding placeholders in the template. Only affects licenses |
diff --git a/doc/api/projects.md b/doc/api/projects.md
index 1d58e390d9e..70df44ec0fd 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -14,7 +14,7 @@ Values for the project visibility level are:
   The project can be cloned by any logged in user.
 
 - `public`:
-  The project can be cloned without any authentication.
+  The project can be accessed without any authentication.
 
 ## Project merge method
 
@@ -41,23 +41,23 @@ GET /projects
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `archived` | boolean | no | Limit by archived status |
-| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` |
-| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` |
-| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` |
-| `search` | string | no | Return list of projects matching the search criteria |
-| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. |
-| `owned` | boolean | no | Limit by projects explicitly owned by the current user |
-| `membership` | boolean | no | Limit by projects that the current user is a member of |
-| `starred` | boolean | no | Limit by projects starred by the current user |
-| `statistics` | boolean | no | Include project statistics |
-| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
-| `with_issues_enabled` | boolean | no | Limit by enabled issues feature |
+| `archived`                    | boolean | no | Limit by archived status |
+| `visibility`                  | string  | no | Limit by visibility `public`, `internal`, or `private` |
+| `order_by`                    | string  | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` |
+| `sort`                        | string  | no | Return projects sorted in `asc` or `desc` order. Default is `desc` |
+| `search`                      | string  | no | Return list of projects matching the search criteria |
+| `simple`                      | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. |
+| `owned`                       | boolean | no | Limit by projects explicitly owned by the current user |
+| `membership`                  | boolean | no | Limit by projects that the current user is a member of |
+| `starred`                     | boolean | no | Limit by projects starred by the current user |
+| `statistics`                  | boolean | no | Include project statistics |
+| `with_custom_attributes`      | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
+| `with_issues_enabled`         | boolean | no | Limit by enabled issues feature |
 | `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature |
-| `with_programming_language` | string | no | Limit by projects which use the given programming language |
-| `wiki_checksum_failed` | boolean | no | Limit projects where the wiki checksum calculation has failed _([Introduced][ee-6137] in [GitLab Premium][eep] 11.2)_ |
-| `repository_checksum_failed` | boolean | no | Limit projects where the repository checksum calculation has failed _([Introduced][ee-6137] in [GitLab Premium][eep] 11.2)_ |
-| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md) |
+| `with_programming_language`   | string  | no | Limit by projects which use the given programming language |
+| `wiki_checksum_failed`        | boolean | no | **(PREMIUM)** Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2) |
+| `repository_checksum_failed`  | boolean | no | **(PREMIUM)** Limit projects where the repository checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2) |
+| `min_access_level`            | integer | no | Limit by current user minimal [access level](members.md) |
 
 When `simple=true` or the user is unauthenticated this returns something like:
 
@@ -156,7 +156,8 @@ When the user is authenticated and `simple` is not set this returns something li
       "repository_size": 1038090,
       "wiki_size" : 0,
       "lfs_objects_size": 0,
-      "job_artifacts_size": 0
+      "job_artifacts_size": 0,
+      "packages_size": 0
     },
     "_links": {
       "self": "http://example.com/api/v4/projects",
@@ -239,7 +240,8 @@ When the user is authenticated and `simple` is not set this returns something li
       "repository_size": 2066080,
       "wiki_size" : 0,
       "lfs_objects_size": 0,
-      "job_artifacts_size": 0
+      "job_artifacts_size": 0,
+      "packages_size": 0
     },
     "_links": {
       "self": "http://example.com/api/v4/projects",
@@ -254,6 +256,20 @@ When the user is authenticated and `simple` is not set this returns something li
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+[
+  {
+    "id": 4,
+    "description": null,
+    "approvals_before_merge": 0,
+    ...
+  }
+]
+```
+
 You can filter by [custom attributes](custom_attributes.md) with:
 
 ```
@@ -349,7 +365,8 @@ GET /users/:user_id/projects
       "repository_size": 1038090,
       "wiki_size" : 0,
       "lfs_objects_size": 0,
-      "job_artifacts_size": 0
+      "job_artifacts_size": 0,
+      "packages_size": 0
     },
     "_links": {
       "self": "http://example.com/api/v4/projects",
@@ -432,6 +449,195 @@ GET /users/:user_id/projects
       "repository_size": 2066080,
       "wiki_size" : 0,
       "lfs_objects_size": 0,
+      "job_artifacts_size": 0,
+      "packages_size": 0
+    },
+    "_links": {
+      "self": "http://example.com/api/v4/projects",
+      "issues": "http://example.com/api/v4/projects/1/issues",
+      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
+      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
+      "labels": "http://example.com/api/v4/projects/1/labels",
+      "events": "http://example.com/api/v4/projects/1/events",
+      "members": "http://example.com/api/v4/projects/1/members"
+    }
+  }
+]
+```
+
+## List projects starred by a user
+
+Get a list of visible projects owned by the given user. When accessed without authentication, only public projects are returned.
+
+```
+GET /users/:user_id/starred_projects
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `user_id` | string | yes | The ID or username of the user. |
+| `archived` | boolean | no | Limit by archived status. |
+| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private`. |
+| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. |
+| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc`. |
+| `search` | string | no | Return list of projects matching the search criteria. |
+| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned.. |
+| `owned` | boolean | no | Limit by projects explicitly owned by the current user. |
+| `membership` | boolean | no | Limit by projects that the current user is a member of. |
+| `starred` | boolean | no | Limit by projects starred by the current user. |
+| `statistics` | boolean | no | Include project statistics. |
+| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only). |
+| `with_issues_enabled` | boolean | no | Limit by enabled issues feature. |
+| `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature. |
+| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md). |
+
+```bash
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/5/starred_projects"
+```
+
+Example response:
+
+```json
+[
+  {
+    "id": 4,
+    "description": null,
+    "default_branch": "master",
+    "visibility": "private",
+    "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git",
+    "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
+    "web_url": "http://example.com/diaspora/diaspora-client",
+    "readme_url": "http://example.com/diaspora/diaspora-client/blob/master/README.md",
+    "tag_list": [
+      "example",
+      "disapora client"
+    ],
+    "owner": {
+      "id": 3,
+      "name": "Diaspora",
+      "created_at": "2013-09-30T13:46:02Z"
+    },
+    "name": "Diaspora Client",
+    "name_with_namespace": "Diaspora / Diaspora Client",
+    "path": "diaspora-client",
+    "path_with_namespace": "diaspora/diaspora-client",
+    "issues_enabled": true,
+    "open_issues_count": 1,
+    "merge_requests_enabled": true,
+    "jobs_enabled": true,
+    "wiki_enabled": true,
+    "snippets_enabled": false,
+    "resolve_outdated_diff_discussions": false,
+    "container_registry_enabled": false,
+    "created_at": "2013-09-30T13:46:02Z",
+    "last_activity_at": "2013-09-30T13:46:02Z",
+    "creator_id": 3,
+    "namespace": {
+      "id": 3,
+      "name": "Diaspora",
+      "path": "diaspora",
+      "kind": "group",
+      "full_path": "diaspora"
+    },
+    "import_status": "none",
+    "archived": false,
+    "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
+    "shared_runners_enabled": true,
+    "forks_count": 0,
+    "star_count": 0,
+    "runners_token": "b8547b1dc37721d05889db52fa2f02",
+    "public_jobs": true,
+    "shared_with_groups": [],
+    "only_allow_merge_if_pipeline_succeeds": false,
+    "only_allow_merge_if_all_discussions_are_resolved": false,
+    "request_access_enabled": false,
+    "merge_method": "merge",
+    "statistics": {
+      "commit_count": 37,
+      "storage_size": 1038090,
+      "repository_size": 1038090,
+      "lfs_objects_size": 0,
+      "job_artifacts_size": 0
+    },
+    "_links": {
+      "self": "http://example.com/api/v4/projects",
+      "issues": "http://example.com/api/v4/projects/1/issues",
+      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
+      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
+      "labels": "http://example.com/api/v4/projects/1/labels",
+      "events": "http://example.com/api/v4/projects/1/events",
+      "members": "http://example.com/api/v4/projects/1/members"
+    }
+  },
+  {
+    "id": 6,
+    "description": null,
+    "default_branch": "master",
+    "visibility": "private",
+    "ssh_url_to_repo": "git@example.com:brightbox/puppet.git",
+    "http_url_to_repo": "http://example.com/brightbox/puppet.git",
+    "web_url": "http://example.com/brightbox/puppet",
+    "readme_url": "http://example.com/brightbox/puppet/blob/master/README.md",
+    "tag_list": [
+      "example",
+      "puppet"
+    ],
+    "owner": {
+      "id": 4,
+      "name": "Brightbox",
+      "created_at": "2013-09-30T13:46:02Z"
+    },
+    "name": "Puppet",
+    "name_with_namespace": "Brightbox / Puppet",
+    "path": "puppet",
+    "path_with_namespace": "brightbox/puppet",
+    "issues_enabled": true,
+    "open_issues_count": 1,
+    "merge_requests_enabled": true,
+    "jobs_enabled": true,
+    "wiki_enabled": true,
+    "snippets_enabled": false,
+    "resolve_outdated_diff_discussions": false,
+    "container_registry_enabled": false,
+    "created_at": "2013-09-30T13:46:02Z",
+    "last_activity_at": "2013-09-30T13:46:02Z",
+    "creator_id": 3,
+    "namespace": {
+      "id": 4,
+      "name": "Brightbox",
+      "path": "brightbox",
+      "kind": "group",
+      "full_path": "brightbox"
+    },
+    "import_status": "none",
+    "import_error": null,
+    "permissions": {
+      "project_access": {
+        "access_level": 10,
+        "notification_level": 3
+      },
+      "group_access": {
+        "access_level": 50,
+        "notification_level": 3
+      }
+    },
+    "archived": false,
+    "avatar_url": null,
+    "shared_runners_enabled": true,
+    "forks_count": 0,
+    "star_count": 0,
+    "runners_token": "b8547b1dc37721d05889db52fa2f02",
+    "public_jobs": true,
+    "shared_with_groups": [],
+    "only_allow_merge_if_pipeline_succeeds": false,
+    "only_allow_merge_if_all_discussions_are_resolved": false,
+    "request_access_enabled": false,
+    "merge_method": "merge",
+    "statistics": {
+      "commit_count": 12,
+      "storage_size": 2066080,
+      "repository_size": 2066080,
+      "lfs_objects_size": 0,
       "job_artifacts_size": 0
     },
     "_links": {
@@ -548,6 +754,7 @@ GET /projects/:id
       "group_access_level": 10
     }
   ],
+  "repository_storage": "default",
   "only_allow_merge_if_pipeline_succeeds": false,
   "only_allow_merge_if_all_discussions_are_resolved": false,
   "printing_merge_requests_link_enabled": true,
@@ -559,7 +766,8 @@ GET /projects/:id
     "repository_size": 1038090,
     "wiki_size" : 0,
     "lfs_objects_size": 0,
-    "job_artifacts_size": 0
+    "job_artifacts_size": 0,
+    "packages_size": 0
   },
   "_links": {
     "self": "http://example.com/api/v4/projects",
@@ -573,6 +781,18 @@ GET /projects/:id
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 3,
+  "description": null,
+  "approvals_before_merge": 0,
+  ...
+}
+```
+
 **Note**: The `web_url` and `avatar_url` attributes on `namespace` were [introduced][ce-27427] in GitLab 11.11.
 
 If the project is a fork, and you provide a valid token to authenticate, the
@@ -674,12 +894,19 @@ POST /projects
 | `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. |
 | `path` | string | yes if name is not provided | Repository name for new project. Generated based on name if not provided (generated lowercased with dashes). |
 | `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) |
+| `default_branch` | string | no | `master` by default |
 | `description` | string | no | Short project description |
-| `issues_enabled` | boolean | no | Enable issues for this project |
-| `merge_requests_enabled` | boolean | no | Enable merge requests for this project |
-| `jobs_enabled` | boolean | no | Enable jobs for this project |
-| `wiki_enabled` | boolean | no | Enable wiki for this project |
-| `snippets_enabled` | boolean | no | Enable snippets for this project |
+| `issues_enabled` | boolean | no | (deprecated) Enable issues for this project. Use `issues_access_level` instead |
+| `merge_requests_enabled` | boolean | no | (deprecated) Enable merge requests for this project. Use `merge_requests_access_level` instead |
+| `jobs_enabled` | boolean | no | (deprecated) Enable jobs for this project. Use `builds_access_level` instead |
+| `wiki_enabled` | boolean | no | (deprecated) Enable wiki for this project. Use `wiki_access_level` instead |
+| `snippets_enabled` | boolean | no | (deprecated) Enable snippets for this project. Use `snippets_access_level` instead |
+| `issues_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `repository_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `merge_requests_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `builds_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `wiki_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` |
 | `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push |
 | `container_registry_enabled` | boolean | no | Enable container registry for this project |
 | `shared_runners_enabled` | boolean | no | Enable shared runners for this project |
@@ -688,15 +915,29 @@ POST /projects
 | `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members |
 | `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs |
 | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved |
-| `merge_method` | string | no | Set the merge method used |
+| `merge_method` | string | no | Set the [merge method](#project-merge-method) used |
 | `lfs_enabled` | boolean | no | Enable LFS |
 | `request_access_enabled` | boolean | no | Allow users to request member access |
 | `tag_list`    | array   | no       | The list of tags for a project; put array of tags, that should be finally assigned to a project |
 | `avatar`    | mixed   | no      | Image file for avatar of the project                |
 | `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line |
+| `build_git_strategy` | string | no | The Git strategy. Defaults to `fetch` |
+| `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) |
+| `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled |
+| `build_coverage_regex` | string | no | Test coverage parsing |
 | `ci_config_path` | string | no | The path to CI config file |
+| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project |
+| `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) |
+| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
+| `approvals_before_merge` | integer | no | **(STARTER)** How many approvers should approve merge requests by default |
+| `mirror` | boolean | no | **(STARTER)** Enables pull mirroring in a project |
+| `mirror_trigger_builds` | boolean | no | **(STARTER)** Pull mirroring triggers builds |
 | `initialize_with_readme` | boolean | no | `false` by default |
 
+NOTE: **Note:** If your HTTP repository is not publicly accessible,
+add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git`
+where `password` is a public access key with the `api` scope enabled.
+
 ## Create project for user
 
 Creates a new project owned by the specified user. Available only for admins.
@@ -710,14 +951,19 @@ POST /projects/user/:user_id
 | `user_id` | integer | yes | The user ID of the project owner |
 | `name` | string | yes | The name of the new project |
 | `path` | string | no | Custom repository name for new project. By default generated based on name |
-| `default_branch` | string | no | `master` by default |
 | `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) |
 | `description` | string | no | Short project description |
-| `issues_enabled` | boolean | no | Enable issues for this project |
-| `merge_requests_enabled` | boolean | no | Enable merge requests for this project |
-| `jobs_enabled` | boolean | no | Enable jobs for this project |
-| `wiki_enabled` | boolean | no | Enable wiki for this project |
-| `snippets_enabled` | boolean | no | Enable snippets for this project |
+| `issues_enabled` | boolean | no | (deprecated) Enable issues for this project. Use `issues_access_level` instead |
+| `merge_requests_enabled` | boolean | no | (deprecated) Enable merge requests for this project. Use `merge_requests_access_level` instead |
+| `jobs_enabled` | boolean | no | (deprecated) Enable jobs for this project. Use `builds_access_level` instead |
+| `wiki_enabled` | boolean | no | (deprecated) Enable wiki for this project. Use `wiki_access_level` instead |
+| `snippets_enabled` | boolean | no | (deprecated) Enable snippets for this project. Use `snippets_access_level` instead |
+| `issues_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `repository_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `merge_requests_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `builds_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `wiki_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` |
 | `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push |
 | `container_registry_enabled` | boolean | no | Enable container registry for this project |
 | `shared_runners_enabled` | boolean | no | Enable shared runners for this project |
@@ -726,13 +972,28 @@ POST /projects/user/:user_id
 | `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members |
 | `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs |
 | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved |
-| `merge_method` | string | no | Set the merge method used |
+| `merge_method` | string | no | Set the [merge method](#project-merge-method) used |
 | `lfs_enabled` | boolean | no | Enable LFS |
 | `request_access_enabled` | boolean | no | Allow users to request member access |
 | `tag_list`    | array   | no       | The list of tags for a project; put array of tags, that should be finally assigned to a project |
 | `avatar`    | mixed   | no      | Image file for avatar of the project                |
 | `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line |
+| `build_git_strategy` | string | no | The Git strategy. Defaults to `fetch` |
+| `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) |
+| `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled |
+| `build_coverage_regex` | string | no | Test coverage parsing |
 | `ci_config_path` | string | no | The path to CI config file |
+| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project |
+| `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) |
+| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
+| `approvals_before_merge` | integer | no | **(STARTER)** How many approvers should approve merge requests by default |
+| `external_authorization_classification_label` | string | no | **(PREMIUM)** The classification label for the project |
+| `mirror` | boolean | no | **(STARTER)** Enables pull mirroring in a project |
+| `mirror_trigger_builds` | boolean | no | **(STARTER)** Pull mirroring triggers builds |
+
+NOTE: **Note:** If your HTTP repository is not publicly accessible,
+add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git`
+where `password` is a public access key with the `api` scope enabled.
 
 ## Edit project
 
@@ -749,11 +1010,17 @@ PUT /projects/:id
 | `path` | string | no | Custom repository name for the project. By default generated based on name |
 | `default_branch` | string | no | `master` by default |
 | `description` | string | no | Short project description |
-| `issues_enabled` | boolean | no | Enable issues for this project |
-| `merge_requests_enabled` | boolean | no | Enable merge requests for this project |
-| `jobs_enabled` | boolean | no | Enable jobs for this project |
-| `wiki_enabled` | boolean | no | Enable wiki for this project |
-| `snippets_enabled` | boolean | no | Enable snippets for this project |
+| `issues_enabled` | boolean | no | (deprecated) Enable issues for this project. Use `issues_access_level` instead |
+| `merge_requests_enabled` | boolean | no | (deprecated) Enable merge requests for this project. Use `merge_requests_access_level` instead |
+| `jobs_enabled` | boolean | no | (deprecated) Enable jobs for this project. Use `builds_access_level` instead |
+| `wiki_enabled` | boolean | no | (deprecated) Enable wiki for this project. Use `wiki_access_level` instead |
+| `snippets_enabled` | boolean | no | (deprecated) Enable snippets for this project. Use `snippets_access_level` instead |
+| `issues_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `repository_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `merge_requests_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `builds_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `wiki_access_level` | string | no | One of `disabled`, `private` or `enabled` |
+| `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` |
 | `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push |
 | `container_registry_enabled` | boolean | no | Enable container registry for this project |
 | `shared_runners_enabled` | boolean | no | Enable shared runners for this project |
@@ -762,13 +1029,32 @@ PUT /projects/:id
 | `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members |
 | `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs |
 | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved |
-| `merge_method` | string | no | Set the merge method used |
+| `merge_method` | string | no | Set the [merge method](#project-merge-method) used |
 | `lfs_enabled` | boolean | no | Enable LFS |
 | `request_access_enabled` | boolean | no | Allow users to request member access |
 | `tag_list`    | array   | no       | The list of tags for a project; put array of tags, that should be finally assigned to a project |
 | `avatar`    | mixed   | no      | Image file for avatar of the project                |
+| `build_git_strategy` | string | no | The Git strategy. Defaults to `fetch` |
+| `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) |
+| `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled |
+| `build_coverage_regex` | string | no | Test coverage parsing |
 | `ci_config_path` | string | no | The path to CI config file |
 | `ci_default_git_depth` | integer | no | Default number of revisions for [shallow cloning](../user/project/pipelines/settings.md#git-shallow-clone) |
+| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project |
+| `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) |
+| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
+| `approvals_before_merge` | integer | no | **(STARTER)** How many approvers should approve merge request by default |
+| `external_authorization_classification_label` | string | no | **(PREMIUM)** The classification label for the project |
+| `mirror` | boolean | no | **(STARTER)** Enables pull mirroring in a project |
+| `mirror_user_id` | integer | no | **(STARTER)** User responsible for all the activity surrounding a pull mirror event |
+| `mirror_trigger_builds` | boolean | no | **(STARTER)** Pull mirroring triggers builds |
+| `only_mirror_protected_branches` | boolean | no | **(STARTER)** Only mirror protected branches |
+| `mirror_overwrites_diverged_branches` | boolean | no | **(STARTER)** Pull mirror overwrites diverged branches |
+| `packages_enabled` | boolean | no | **(PREMIUM ONLY)** Enable or disable packages repository feature |
+
+NOTE: **Note:** If your HTTP repository is not publicly accessible,
+add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git`
+where `password` is a public access key with the `api` scope enabled.
 
 ## Fork project
 
@@ -1057,6 +1343,51 @@ Example response:
 }
 ```
 
+## List Starrers of a project
+
+List the users who starred the specified project.
+
+```
+GET /projects/:id/starrers
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `search` | string | no | Search for specific users. |
+
+```bash
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/starrers"
+```
+
+Example responses:
+
+```json
+[
+  {
+    "starred_since": "2019-01-28T14:47:30.642Z",
+    "user":
+      {
+        "id": 1,
+        "username": "jane_smith",
+        "name": "Jane Smith",
+        "state": "active",
+        "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
+        "web_url": "http://localhost:3000/jane_smith"
+      }
+  },
+    "starred_since": "2018-01-02T11:40:26.570Z",
+    "user":
+      {
+        "id": 2,
+        "username": "janine_smith",
+        "name": "Janine Smith",
+        "state": "blocked",
+        "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
+        "web_url": "http://localhost:3000/janine_smith"
+      }
+]
+```
+
 ## Languages
 
 Get languages used in a project with percentage value.
@@ -1292,7 +1623,7 @@ Example response:
 
 ## Remove project
 
-Removes a project including all associated resources (issues, merge requests etc.)
+Removes a project including all associated resources (issues, merge requests etc).
 
 ```
 DELETE /projects/:id
@@ -1548,9 +1879,118 @@ POST /projects/:id/housekeeping
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME |
+
+## Push Rules **(STARTER)**
+
+### Get project push rules
+
+Get the push rules of a project.
+
+```
+GET /projects/:id/push_rule
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME |
+
+```json
+{
+  "id": 1,
+  "project_id": 3,
+  "commit_message_regex": "Fixes \d+\..*",
+  "commit_message_negative_regex": "ssh\:\/\/",
+  "branch_name_regex": "",
+  "deny_delete_tag": false,
+  "created_at": "2012-10-12T17:04:47Z",
+  "member_check": false,
+  "prevent_secrets": false,
+  "author_email_regex": "",
+  "file_name_regex": "",
+  "max_file_size": 5,
+  "commit_committer_check": false,
+  "reject_unsigned_commits": false
+}
+```
+
+Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will also see
+the `commit_committer_check` and `reject_unsigned_commits` parameters:
+
+```json
+{
+  "id": 1,
+  "project_id": 3,
+  "commit_committer_check": false,
+  "reject_unsigned_commits": false
+  ...
+}
+```
+
+### Add project push rule
+
+Adds a push rule to a specified project.
+
+```
+POST /projects/:id/push_rule
+```
+
+| Attribute                                     | Type           | Required | Description |
+| --------------------------------------------- | -------------- | -------- | ----------- |
+| `id`                                          | integer/string | yes      | The ID of the project or NAMESPACE/PROJECT_NAME |
+| `deny_delete_tag` **(STARTER)**               | boolean        | no       | Deny deleting a tag |
+| `member_check` **(STARTER)**                  | boolean        | no       | Restrict commits by author (email) to existing GitLab users |
+| `prevent_secrets` **(STARTER)**               | boolean        | no       | GitLab will reject any files that are likely to contain secrets |
+| `commit_message_regex` **(STARTER)**          | string         | no       | All commit messages must match this, e.g. `Fixed \d+\..*` |
+| `commit_message_negative_regex` **(STARTER)** | string         | no       | No commit message is allowed to match this, e.g. `ssh\:\/\/` |
+| `branch_name_regex` **(STARTER)**             | string         | no       | All branch names must match this, e.g. `(feature|hotfix)\/*` |
+| `author_email_regex` **(STARTER)**            | string         | no       | All commit author emails must match this, e.g. `@my-company.com$` |
+| `file_name_regex` **(STARTER)**               | string         | no       | All commited filenames must **not** match this, e.g. `(jar|exe)$` |
+| `max_file_size` **(STARTER)**                 | integer        | no       | Maximum file size (MB) |
+| `commit_committer_check` **(PREMIUM)**        | boolean        | no       | Users can only push commits to this repository that were committed with one of their own verified emails. |
+| `reject_unsigned_commits` **(PREMIUM)**        | boolean        | no       | Reject commit when it is not signed through GPG. |
+
+### Edit project push rule
+
+Edits a push rule for a specified project.
+
+```
+PUT /projects/:id/push_rule
+```
+
+| Attribute                                     | Type           | Required | Description |
+| --------------------------------------------- | -------------- | -------- | ----------- |
+| `id`                                          | integer/string | yes      | The ID of the project or NAMESPACE/PROJECT_NAME |
+| `deny_delete_tag` **(STARTER)**               | boolean        | no       | Deny deleting a tag |
+| `member_check` **(STARTER)**                  | boolean        | no       | Restrict commits by author (email) to existing GitLab users |
+| `prevent_secrets` **(STARTER)**               | boolean        | no       | GitLab will reject any files that are likely to contain secrets |
+| `commit_message_regex` **(STARTER)**          | string         | no       | All commit messages must match this, e.g. `Fixed \d+\..*` |
+| `commit_message_negative_regex` **(STARTER)** | string         | no       | No commit message is allowed to match this, e.g. `ssh\:\/\/` |
+| `branch_name_regex` **(STARTER)**             | string         | no       | All branch names must match this, e.g. `(feature|hotfix)\/*` |
+| `author_email_regex` **(STARTER)**            | string         | no       | All commit author emails must match this, e.g. `@my-company.com$` |
+| `file_name_regex` **(STARTER)**               | string         | no       | All commited filenames must **not** match this, e.g. `(jar|exe)$` |
+| `max_file_size` **(STARTER)**                 | integer        | no       | Maximum file size (MB) |
+| `commit_committer_check` **(PREMIUM)**        | boolean        | no       | Users can only push commits to this repository that were committed with one of their own verified emails. |
+| `reject_unsigned_commits` **(PREMIUM)**        | boolean        | no       | Reject commits when they are not GPG signed. |
+
+### Delete project push rule
+
+> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 9.0.
+
+Removes a push rule from a project. This is an idempotent method and can be called multiple times.
+Either the push rule is available or not.
+
+```
+DELETE /projects/:id/push_rule
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 
-### Transfer a project to a new namespace
+## Transfer a project to a new namespace
+
+> Introduced in GitLab 11.1.
 
 ```
 PUT /projects/:id/transfer
@@ -1572,6 +2012,22 @@ Read more in the [Project import/export](project_import_export.md) documentation
 
 Read more in the [Project members](members.md) documentation.
 
+## Start the pull mirroring process for a Project **(STARTER)**
+
+> Introduced in [GitLab Starter](https://about.gitlab.com/pricing) 10.3.
+
+```
+POST /projects/:id/mirror/pull
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/mirror/pull
+```
+
 ## Project badges
 
 Read more in the [Project Badges](project_badges.md) documentation.
@@ -1602,6 +2058,4 @@ GET /projects/:id/snapshot
 | `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `wiki`    | boolean | no | Whether to download the wiki, rather than project, repository |
 
-[eep]: https://about.gitlab.com/pricing/ "Available only in GitLab Premium"
-[ee-6137]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6137
 [ce-27427]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27427
diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md
index a261bb75be5..9309306ba05 100644
--- a/doc/api/protected_branches.md
+++ b/doc/api/protected_branches.md
@@ -10,6 +10,7 @@ The access levels are defined in the `ProtectedRefAccess.allowed_access_levels`
 0  => No access
 30 => Developer access
 40 => Maintainer access
+60 => Admin access
 ```
 
 ## List protected branches
@@ -51,6 +52,36 @@ Example response:
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `user_id` and `group_id` parameters:
+
+Example response:
+
+```json
+[
+  {
+    "name": "master",
+    "push_access_levels": [
+      {
+        "access_level": 40,
+        "user_id": null,
+        "group_id": null,
+        "access_level_description": "Maintainers"
+      }
+    ],
+    "merge_access_levels": [
+      {
+        "access_level": null,
+        "user_id": null,
+        "group_id": 1234,
+        "access_level_description": "Example Merge Group"
+      }
+    ]
+  },
+  ...
+]
+```
+
 ## Get a single protected branch or wildcard protected branch
 
 Gets a single protected branch or wildcard protected branch.
@@ -88,6 +119,33 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `user_id` and `group_id` parameters:
+
+Example response:
+
+```json
+{
+  "name": "master",
+  "push_access_levels": [
+    {
+      "access_level": 40,
+      "user_id": null,
+      "group_id": null,
+      "access_level_description": "Maintainers"
+    }
+  ],
+  "merge_access_levels": [
+    {
+      "access_level": null,
+      "user_id": null,
+      "group_id": 1234,
+      "access_level_description": "Example Merge Group"
+    }
+  ]
+}
+```
+
 ## Protect repository branches
 
 Protects a single repository branch or several project repository
@@ -98,15 +156,47 @@ POST /projects/:id/protected_branches
 ```
 
 ```bash
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30'
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30&unprotect_access_level=40'
 ```
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `name` | string | yes | The name of the branch or wildcard |
-| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, maintainer access level) |
-| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, maintainer access level) |
+| `id`                     | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `name`                   | string         | yes | The name of the branch or wildcard |
+| `push_access_level`      | string         | no  | Access levels allowed to push (defaults: `40`, maintainer access level) |
+| `merge_access_level`     | string         | no  | Access levels allowed to merge (defaults: `40`, maintainer access level) |
+| `unprotect_access_level` | string         | no  | Access levels allowed to unprotect (defaults: `40`, maintainer access level) |
+| `allowed_to_push`        | array          | no  | **(STARTER)** Array of access levels allowed to push, with each described by a hash |
+| `allowed_to_merge`       | array          | no  | **(STARTER)** Array of access levels allowed to merge, with each described by a hash |
+| `allowed_to_unprotect`   | array          | no  | **(STARTER)**Array of access levels allowed to unprotect, with each described by a hash |
+
+Example response:
+
+```json
+{
+  "name": "*-stable",
+  "push_access_levels": [
+    {
+      "access_level": 30,
+      "access_level_description": "Developers + Maintainers"
+    }
+  ],
+  "merge_access_levels": [
+    {
+      "access_level": 30,
+      "access_level_description": "Developers + Maintainers"
+  ],
+  "unprotect_access_levels": [
+    {
+      "access_level": 40,
+      "access_level_description": "Maintainers"
+    }
+  ]
+}
+```
+
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `user_id` and `group_id` parameters:
 
 Example response:
 
@@ -116,13 +206,65 @@ Example response:
   "push_access_levels": [
     {
       "access_level": 30,
+      "user_id": null,
+      "group_id": null,
       "access_level_description": "Developers + Maintainers"
     }
   ],
   "merge_access_levels": [
     {
       "access_level": 30,
+      "user_id": null,
+      "group_id": null,
       "access_level_description": "Developers + Maintainers"
+  ],
+  "unprotect_access_levels": [
+    {
+      "access_level": 40,
+      "user_id": null,
+      "group_id": null,
+      "access_level_description": "Maintainers"
+    }
+  ]
+}
+```
+
+### Example with user / group level access **(STARTER)**
+
+Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the
+form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md#restricting-push-and-merge-access-to-certain-users-starter) and were [added to the API in ][ee-3516] in GitLab 10.3 EE.
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&allowed_to_push%5B%5D%5Buser_id%5D=1'
+```
+
+Example response:
+
+```json
+{
+  "name":"*-stable",
+  "push_access_levels": [
+    {
+      "access_level":null,
+      "user_id":1,
+      "group_id":null,
+      "access_level_description":"Administrator"
+    }
+  ],
+  "merge_access_levels": [
+    {
+      "access_level":40,
+      "user_id":null,
+      "group_id":null,
+      "access_level_description":"Maintainers"
+    }
+  ],
+  "unprotect_access_levels": [
+    {
+      "access_level":40,
+      "user_id":null,
+      "group_id":null,
+      "access_level_description":"Maintainers"
     }
   ]
 }
@@ -144,3 +286,5 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://git
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `name` | string | yes | The name of the branch |
+
+[ee-3516]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3516 "ProtectedBranches API handles per user/group granularity"
diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md
index 3adca61a108..fb6fa040244 100644
--- a/doc/api/protected_tags.md
+++ b/doc/api/protected_tags.md
@@ -5,6 +5,7 @@
 **Valid access levels**
 
 Currently, these levels are recognized:
+
 ```
 0  => No access
 30 => Developer access
diff --git a/doc/api/releases/img/upcoming_release_v12_1.png b/doc/api/releases/img/upcoming_release_v12_1.png
new file mode 100644
index 00000000000..cc3070fd19d
--- /dev/null
+++ b/doc/api/releases/img/upcoming_release_v12_1.png
diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md
index e7f79a0d359..e74b35fd959 100644
--- a/doc/api/releases/index.md
+++ b/doc/api/releases/index.md
@@ -6,7 +6,7 @@
 
 ## List Releases
 
-Paginated list of Releases, sorted by `created_at`.
+Paginated list of Releases, sorted by `released_at`.
 
 ```
 GET /projects/:id/releases
@@ -32,6 +32,7 @@ Example response:
       "name":"Awesome app v0.2 beta",
       "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eEscape label and milestone titles to prevent XSS in GFM autocomplete. !2740\u003c/li\u003e\n\u003cli\u003ePrevent private snippets from being embeddable.\u003c/li\u003e\n\u003cli\u003eAdd subresources removal to member destroy service.\u003c/li\u003e\n\u003c/ul\u003e",
       "created_at":"2019-01-03T01:56:19.539Z",
+      "released_at":"2019-01-03T01:56:19.539Z",
       "author":{
          "id":1,
          "name":"Administrator",
@@ -98,6 +99,7 @@ Example response:
       "name":"Awesome app v0.1 alpha",
       "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e",
       "created_at":"2019-01-03T01:55:18.203Z",
+      "released_at":"2019-01-03T01:55:18.203Z",
       "author":{
          "id":1,
          "name":"Administrator",
@@ -178,6 +180,7 @@ Example response:
    "name":"Awesome app v0.1 alpha",
    "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e",
    "created_at":"2019-01-03T01:55:18.203Z",
+   "released_at":"2019-01-03T01:55:18.203Z",
    "author":{
       "id":1,
       "name":"Administrator",
@@ -247,6 +250,7 @@ POST /projects/:id/releases
 | `assets:links`| array of hash  | no       | An array of assets links.               |
 | `assets:links:name`| string    | no (if `assets:links` specified, it's required)    | The name of the link. |
 | `assets:links:url`| string    | no (if `assets:links` specified, it's required)    | The url of the link. |
+| `released_at` | datetime       | no       | The date when the release will be/was ready. Defaults to the current time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
 
 Example request:
 
@@ -265,6 +269,7 @@ Example response:
    "name":"New release",
    "description_html":"\u003cp dir=\"auto\"\u003eSuper nice release\u003c/p\u003e",
    "created_at":"2019-01-03T02:22:45.118Z",
+   "released_at":"2019-01-03T02:22:45.118Z",
    "author":{
       "id":1,
       "name":"Administrator",
@@ -335,6 +340,7 @@ PUT /projects/:id/releases/:tag_name
 | `tag_name`    | string         | yes      | The tag where the release will be created from. |
 | `name`        | string         | no       | The release name.                       |
 | `description` | string         | no       | The description of the release. You can use [markdown](../../user/markdown.md). |
+| `released_at` | datetime       | no       | The date when the release will be/was ready. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
 
 Example request:
 
@@ -351,6 +357,7 @@ Example response:
    "name":"new name",
    "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e",
    "created_at":"2019-01-03T01:55:18.203Z",
+   "released_at":"2019-01-03T01:55:18.203Z",
    "author":{
       "id":1,
       "name":"Administrator",
@@ -430,6 +437,7 @@ Example response:
    "name":"new name",
    "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e",
    "created_at":"2019-01-03T01:55:18.203Z",
+   "released_at":"2019-01-03T01:55:18.203Z",
    "author":{
       "id":1,
       "name":"Administrator",
@@ -480,3 +488,11 @@ Example response:
    }
 }
 ```
+
+## Upcoming Releases
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/38105) in GitLab 12.1.
+
+A release with a `released_at` attribute set to a future date will be labeled an **Upcoming Release** in the UI:
+
+![Upcoming release](img/upcoming_release_v12_1.png)
diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md
index 9c91264ed65..b1b75abe32f 100644
--- a/doc/api/releases/links.md
+++ b/doc/api/releases/links.md
@@ -21,7 +21,7 @@ GET /projects/:id/releases/:tag_name/assets/links
 Example request:
 
 ```sh
-curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links"
+curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links"
 ```
 
 Example response:
@@ -60,7 +60,7 @@ GET /projects/:id/releases/:tag_name/assets/links/:link_id
 Example request:
 
 ```sh
-curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links/1"
+curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links/1"
 ```
 
 Example response:
@@ -96,7 +96,7 @@ curl --request POST \
      --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" \
      --data name="awesome-v0.2.dmg" \
      --data url="http://192.168.10.15:3000" \
-     "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links"
+     "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links"
 ```
 
 Example response:
@@ -132,7 +132,7 @@ You have to specify at least one of `name` or `url`
 Example request:
 
 ```sh
-curl --request PUT --data name="new name" --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links/1"
+curl --request PUT --data name="new name" --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links/1"
 ```
 
 Example response:
@@ -163,7 +163,7 @@ DELETE /projects/:id/releases/:tag_name/assets/links/:link_id
 Example request:
 
 ```sh
-curl --request DELETE --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links/1"
+curl --request DELETE --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links/1"
 ```
 
 Example response:
diff --git a/doc/api/repositories.md b/doc/api/repositories.md
index 681dc72c934..4aff79c9c62 100644
--- a/doc/api/repositories.md
+++ b/doc/api/repositories.md
@@ -121,9 +121,9 @@ Parameters:
 - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
 - `sha` (optional) - The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. For example:
 
-    ```sh
-    curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha>
-    ```
+```sh
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha>
+```
 
 ## Compare branches, tags or commits
 
@@ -235,17 +235,17 @@ Example response:
 
 ```json
 {
-	"id": "1a0b36b3cdad1d2ee32457c102a8c0b7056fa863",
-	"short_id": "1a0b36b3",
-	"title": "Initial commit",
-	"created_at": "2014-02-27T08:03:18.000Z",
-	"parent_ids": [],
-	"message": "Initial commit\n",
-	"author_name": "Dmitriy Zaporozhets",
-	"author_email": "dmitriy.zaporozhets@gmail.com",
-	"authored_date": "2014-02-27T08:03:18.000Z",
-	"committer_name": "Dmitriy Zaporozhets",
-	"committer_email": "dmitriy.zaporozhets@gmail.com",
-	"committed_date": "2014-02-27T08:03:18.000Z"
+  "id": "1a0b36b3cdad1d2ee32457c102a8c0b7056fa863",
+  "short_id": "1a0b36b3",
+  "title": "Initial commit",
+  "created_at": "2014-02-27T08:03:18.000Z",
+  "parent_ids": [],
+  "message": "Initial commit\n",
+  "author_name": "Dmitriy Zaporozhets",
+  "author_email": "dmitriy.zaporozhets@gmail.com",
+  "authored_date": "2014-02-27T08:03:18.000Z",
+  "committer_name": "Dmitriy Zaporozhets",
+  "committer_email": "dmitriy.zaporozhets@gmail.com",
+  "committed_date": "2014-02-27T08:03:18.000Z"
 }
 ```
diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md
index 87c7f371de1..b292c9dd7de 100644
--- a/doc/api/repository_files.md
+++ b/doc/api/repository_files.md
@@ -80,6 +80,75 @@ X-Gitlab-Size: 1476
 ...
 ```
 
+## Get file blame from repository
+
+Allows you to receive blame information. Each blame range contains lines and corresponding commit info.
+
+```
+GET /projects/:id/repository/files/:file_path/blame
+```
+
+```bash
+curl --request GET --header 'PRIVATE-TOKEN: <your_access_token>' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=master'
+```
+
+Example response:
+
+```json
+[
+  {
+    "commit": {
+      "id": "d42409d56517157c48bf3bd97d3f75974dde19fb",
+      "message": "Add feature\n\nalso fix bug\n",
+      "parent_ids": [
+        "cc6e14f9328fa6d7b5a0d3c30dc2002a3f2a3822"
+      ],
+      "authored_date": "2015-12-18T08:12:22.000Z",
+      "author_name": "John Doe",
+      "author_email": "john.doe@example.com",
+      "committed_date": "2015-12-18T08:12:22.000Z",
+      "committer_name": "John Doe",
+      "committer_email": "john.doe@example.com"
+    },
+    "lines": [
+      "require 'fileutils'",
+      "require 'open3'",
+      ""
+    ]
+  },
+  ...
+]
+```
+
+Parameters:
+
+- `file_path` (required) - Url encoded full path to new file. Ex. lib%2Fclass%2Erb
+- `ref` (required) - The name of branch, tag or commit
+
+NOTE: **Note:**
+`HEAD` method return just file metadata as in [Get file from repository](repository_files.md#get-file-from-repository).
+
+```bash
+curl --head --header 'PRIVATE-TOKEN: <your_access_token>' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=master'
+```
+
+Example response:
+
+```text
+HTTP/1.1 200 OK
+...
+X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83
+X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50
+X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481
+X-Gitlab-Encoding: base64
+X-Gitlab-File-Name: file.rb
+X-Gitlab-File-Path: path/to/file.rb
+X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d
+X-Gitlab-Ref: master
+X-Gitlab-Size: 1476
+...
+```
+
 ## Get raw file from repository
 
 ```
diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md
index 2c44c4abc93..5a722a75cb9 100644
--- a/doc/api/repository_submodules.md
+++ b/doc/api/repository_submodules.md
@@ -43,7 +43,7 @@ Example response:
     "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
   ],
   "committed_date": "2018-09-20T09:26:24.000-07:00",
-  "authored_date": "2018-09-20T09:26:24.000-07:00",  
+  "authored_date": "2018-09-20T09:26:24.000-07:00",
   "status": null
 }
 ```
diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md
index f0a7ac4e41d..7ad4d78014c 100644
--- a/doc/api/resource_label_events.md
+++ b/doc/api/resource_label_events.md
@@ -88,7 +88,7 @@ Parameters:
 curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/resource_label_events/1
 ```
 
-## Epics **[ULTIMATE]**
+## Epics **(ULTIMATE)**
 
 ### List group epic label events
 
diff --git a/doc/api/runners.md b/doc/api/runners.md
index 2d91428d1c1..e6962d17a98 100644
--- a/doc/api/runners.md
+++ b/doc/api/runners.md
@@ -20,10 +20,10 @@ Here's an example of how the two tokens are used in Runner registration:
 1. You use that authentication token and add it to the
    [Runner's configuration file](https://docs.gitlab.com/runner/commands/#configuration-file):
 
-    ```toml
-    [[runners]]
-      token = "<authentication_token>"
-    ```
+   ```toml
+   [[runners]]
+     token = "<authentication_token>"
+   ```
 
 GitLab and Runner are then connected.
 
@@ -44,7 +44,7 @@ GET /runners?tag_list=tag1,tag2
 | `scope`     | string         | no       | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided |
 | `type`      | string         | no       | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` |
 | `status`    | string         | no       | The status of runners to show, one of: `active`, `paused`, `online`, `offline` |
-| `tag_list`  | Array[String]  | no       | List of of the runner's tags |
+| `tag_list`  | string array   | no       | List of of the runner's tags |
 
 ```
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
@@ -95,7 +95,7 @@ GET /runners/all?tag_list=tag1,tag2
 | `scope`     | string         | no       | Deprecated: Use `type` or `status` instead. The scope of runners to show, one of: `specific`, `shared`, `active`, `paused`, `online`, `offline`; showing all runners if none provided |
 | `type`      | string         | no       | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` |
 | `status`    | string         | no       | The status of runners to show, one of: `active`, `paused`, `online`, `offline` |
-| `tag_list`  | Array[String]  | no       | List of of the runner's tags |
+| `tag_list`  | string array   | no       | List of of the runner's tags |
 
 ```
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
@@ -214,10 +214,10 @@ PUT /runners/:id
 | `description` | string  | no       | The description of a runner |
 | `active`      | boolean | no       | The state of a runner; can be set to `true` or `false` |
 | `tag_list`    | array   | no       | The list of tags for a runner; put array of tags, that should be finally assigned to a runner |
-| `run_untagged`    | boolean   | no       | Flag indicating the runner can execute untagged jobs |
-| `locked`    | boolean   | no       | Flag indicating the runner is locked |
-| `access_level`    | string   | no       | The access_level of the runner; `not_protected` or `ref_protected` |
-| `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job |
+| `run_untagged`| boolean | no       | Flag indicating the runner can execute untagged jobs |
+| `locked`      | boolean | no       | Flag indicating the runner is locked |
+| `access_level` | string | no       | The access_level of the runner; `not_protected` or `ref_protected` |
+| `maximum_timeout` | integer | no   | Maximum timeout set when this Runner will handle the job |
 
 ```
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"
@@ -291,6 +291,8 @@ GET /runners/:id/jobs
 |-----------|---------|----------|---------------------|
 | `id`      | integer | yes      | The ID of a runner  |
 | `status`  | string  | no       | Status of the job; one of: `running`, `success`, `failed`, `canceled` |
+| `order_by`| string  | no       | Order jobs by `id`. |
+| `sort`    | string  | no       | Sort jobs in `asc` or `desc` order (default: `desc`) |
 
 ```
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"
@@ -385,7 +387,7 @@ GET /projects/:id/runners?tag_list=tag1,tag2
 | `scope`    | string         | no       | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided |
 | `type`     | string         | no       | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` |
 | `status`   | string         | no       | The status of runners to show, one of: `active`, `paused`, `online`, `offline` |
-| `tag_list` | Array[String]  | no       | List of of the runner's tags |
+| `tag_list` | string array   | no       | List of of the runner's tags |
 
 ```
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"
@@ -477,17 +479,17 @@ Register a new Runner for the instance.
 POST /runners
 ```
 
-| Attribute   | Type    | Required | Description         |
-|-------------|---------|----------|---------------------|
-| `token`     | string  | yes      | [Registration token](#registration-and-authentication-tokens).  |
-| `description`| string | no       | Runner's description|
-| `info`       | hash   | no       | Runner's metadata   |
-| `active`     | boolean| no       | Whether the Runner is active   |
-| `locked`     | boolean| no       | Whether the Runner should be locked for current project |
-| `run_untagged` | boolean | no | Whether the Runner should handle untagged jobs |
-| `tag_list` | Array[String] | no | List of Runner's tags |
-| `access_level`    | string   | no       | The access_level of the runner; `not_protected` or `ref_protected` |
-| `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job |
+| Attribute    | Type    | Required | Description         |
+|--------------|---------|----------|---------------------|
+| `token`      | string  | yes      | [Registration token](#registration-and-authentication-tokens).  |
+| `description`| string  | no       | Runner's description|
+| `info`       | hash    | no       | Runner's metadata   |
+| `active`     | boolean | no       | Whether the Runner is active   |
+| `locked`     | boolean | no       | Whether the Runner should be locked for current project |
+| `run_untagged` | boolean | no     | Whether the Runner should handle untagged jobs |
+| `tag_list`   | string array | no  | List of Runner's tags |
+| `access_level`    | string | no   | The access_level of the runner; `not_protected` or `ref_protected` |
+| `maximum_timeout` | integer | no  | Maximum timeout set when this Runner will handle the job |
 
 ```
 curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=<registration_token>" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"
diff --git a/doc/api/scim.md b/doc/api/scim.md
index 3870ea788e7..ece7f56e394 100644
--- a/doc/api/scim.md
+++ b/doc/api/scim.md
@@ -1,4 +1,4 @@
-# SCIM API **[SILVER ONLY]**
+# SCIM API **(SILVER ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9388) in [GitLab Silver](https://about.gitlab.com/pricing/) 11.10.
 
@@ -6,7 +6,7 @@ The SCIM API implements the [the RFC7644 protocol](https://tools.ietf.org/html/r
 
 NOTE: **Note:**
 [Group SSO](../user/group/saml_sso/index.md) and the feature
-flag `:group_scim` must be enabled for the group. For more information, see [SCIM setup documentation](../user/group/saml_sso/scim_setup.md#requirements). 
+flag `:group_scim` must be enabled for the group. For more information, see [SCIM setup documentation](../user/group/saml_sso/scim_setup.md#requirements).
 
 ## Get a list of SAML users
 
diff --git a/doc/api/search.md b/doc/api/search.md
index da81c8321c9..60acf600ac7 100644
--- a/doc/api/search.md
+++ b/doc/api/search.md
@@ -19,7 +19,7 @@ GET /search
 
 Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, snippet_blobs, users.
 
-If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **[STARTER]**
+If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **(STARTER)**
 
 The response depends on the requested scope.
 
@@ -283,9 +283,9 @@ Example response:
 ]
 ```
 
-### Scope: wiki_blobs **[STARTER]**
+### Scope: wiki_blobs **(STARTER)**
 
-This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. 
+This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
 
 ```bash
 curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=wiki_blobs&search=bye
@@ -308,7 +308,7 @@ Example response:
 ]
 ```
 
-### Scope: commits **[STARTER]**
+### Scope: commits **(STARTER)**
 
 This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
 
@@ -341,11 +341,12 @@ Example response:
 ]
 ```
 
-### Scope: blobs **[STARTER]**
+### Scope: blobs **(STARTER)**
 
 This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
 
 Filters are available for this scope:
+
 - filename
 - path
 - extension
@@ -414,7 +415,7 @@ GET /groups/:id/search
 
 Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users.
 
-If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **[STARTER]**
+If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **(STARTER)**
 
 The response depends on the requested scope.
 
@@ -616,7 +617,7 @@ Example response:
 ]
 ```
 
-### Scope: wiki_blobs **[STARTER]**
+### Scope: wiki_blobs **(STARTER)**
 
 This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
 
@@ -641,7 +642,7 @@ Example response:
 ]
 ```
 
-### Scope: commits **[STARTER]**
+### Scope: commits **(STARTER)**
 
 This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
 
@@ -674,11 +675,12 @@ Example response:
 ]
 ```
 
-### Scope: blobs **[STARTER]**
+### Scope: blobs **(STARTER)**
 
 This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
 
 Filters are available for this scope:
+
 - filename
 - path
 - extension
diff --git a/doc/api/services.md b/doc/api/services.md
index 898cfad7254..7d025cd3bdf 100644
--- a/doc/api/services.md
+++ b/doc/api/services.md
@@ -22,6 +22,7 @@ Parameters:
 | --------- | ---- | -------- | ----------- |
 | `api_key` | string | true | User API token. User must have access to task, all comments will be attributed to this user. |
 | `restrict_to_branch` | string | false | Comma-separated list of branches which will be automatically inspected. Leave blank to include all branches. |
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete Asana service
 
@@ -57,6 +58,7 @@ Parameters:
 | --------- | ---- | -------- | ----------- |
 | `token` | string | true | The authentication token
 | `subdomain` | string | false | The subdomain setting |
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete Assembla service
 
@@ -96,6 +98,7 @@ Parameters:
 | `build_key` | string | true | Bamboo build plan key like KEY |
 | `username` | string | true | A user with API access, if applicable |
 | `password` | string | true | Password of the user |
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete Atlassian Bamboo CI service
 
@@ -134,6 +137,7 @@ Parameters:
 | `project_url` | string | true | Project url |
 | `description` | string | false | Description |
 | `title` | string | false | Title |
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete Bugzilla Service
 
@@ -170,6 +174,7 @@ Parameters:
 | `token` | string | true | Buildkite project GitLab token |
 | `project_url` | string | true | `https://buildkite.com/example/project` |
 | `enable_ssl_verification` | boolean | false | Enable SSL verification |
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete Buildkite service
 
@@ -206,6 +211,7 @@ Parameters:
 | `token` | string | true | Campfire token |
 | `subdomain` | string | false | Campfire subdomain |
 | `room`  | string | false | Campfire room |
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete Campfire service
 
@@ -244,6 +250,7 @@ Parameters:
 | `project_url` | string | true | Project url
 | `description` | string | false | Description
 | `title` | string | false | Title
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete Custom Issue Tracker service
 
@@ -280,6 +287,9 @@ Parameters:
 | `token` | string | true | Drone CI project specific token |
 | `drone_url` | string | true | `http://drone.example.com` |
 | `enable_ssl_verification` | boolean | false | Enable SSL verification |
+| `push_events` | boolean | false | Enable notifications for push events |
+| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
+| `tag_push_events` | boolean | false | Enable notifications for tag push events |
 
 ### Delete Drone CI service
 
@@ -316,6 +326,8 @@ Parameters:
 | `recipients` | string | true | Emails separated by whitespace |
 | `disable_diffs` | boolean | false | Disable code diffs |
 | `send_from_committer_email` | boolean | false | Send from committer |
+| `push_events` | boolean | false | Enable notifications for push events |
+| `tag_push_events` | boolean | false | Enable notifications for tag push events |
 
 ### Delete Emails on push service
 
@@ -384,6 +396,7 @@ Parameters:
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `token` | string | true | Flowdock Git source token |
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete Flowdock service
 
@@ -471,6 +484,14 @@ Parameters:
 | `room` | string | false |Room name or ID |
 | `api_version` | string | false | Leave blank for default (v2) |
 | `server` | string | false | Leave blank for default. For example, `https://hipchat.example.com`. |
+| `push_events` | boolean | false | Enable notifications for push events |
+| `issues_events` | boolean | false | Enable notifications for issue events |
+| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events |
+| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
+| `tag_push_events` | boolean | false | Enable notifications for tag push events |
+| `note_events` | boolean | false | Enable notifications for note events |
+| `confidental_note_events` | boolean | false | Enable notifications for confidential note events |
+| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
 
 ### Delete HipChat service
 
@@ -511,6 +532,7 @@ Parameters:
 | `server_host` | string | false | localhost |
 | `server_port` | integer | false | 6659 |
 | `colorize_messages` | boolean | false | Colorize messages |
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete Irker (IRC gateway) service
 
@@ -528,21 +550,21 @@ Get Irker (IRC gateway) service settings for a project.
 GET /projects/:id/services/irker
 ```
 
-## JIRA
+## Jira
 
-JIRA issue tracker.
+Jira issue tracker.
 
-### Get JIRA service settings
+### Get Jira service settings
 
-Get JIRA service settings for a project.
+Get Jira service settings for a project.
 
 ```
 GET /projects/:id/services/jira
 ```
 
-### Create/Edit JIRA service
+### Create/Edit Jira service
 
-Set JIRA service for a project.
+Set Jira service for a project.
 
 > Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and
 > `project_url` are replaced by `url`. If you are using an
@@ -556,59 +578,23 @@ Parameters:
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `url`           | string | yes | The URL to the JIRA project which is being linked to this GitLab project. For example, `https://jira.example.com`. |
-| `api_url`   | string | no | The base URL to the JIRA instance API. Web URL value will be used if not set. For example, `https://jira-api.example.com`. |
-| `username`      | string | yes  | The username of the user created to be used with GitLab/JIRA. |
-| `password`      | string | yes  | The password of the user created to be used with GitLab/JIRA. |
+| `url`           | string | yes | The URL to the Jira project which is being linked to this GitLab project. For example, `https://jira.example.com`. |
+| `api_url`   | string | no | The base URL to the Jira instance API. Web URL value will be used if not set. For example, `https://jira-api.example.com`. |
+| `username`      | string | yes  | The username of the user created to be used with GitLab/Jira. |
+| `password`      | string | yes  | The password of the user created to be used with GitLab/Jira. |
 | `active`        | boolean | no  | Activates or deactivates the service. Defaults to false (deactivated). |
-| `jira_issue_transition_id` | string | no | The ID of a transition that moves issues to a closed state. You can find this number under the JIRA workflow administration (**Administration > Issues > Workflows**) by selecting **View** under **Operations** of the desired workflow of your project. The ID of each state can be found inside the parenthesis of each transition name under the **Transitions (id)** column ([see screenshot][trans]). By default, this ID is set to `2`. |
+| `jira_issue_transition_id` | string | no | The ID of a transition that moves issues to a closed state. You can find this number under the Jira workflow administration (**Administration > Issues > Workflows**) by selecting **View** under **Operations** of the desired workflow of your project. The ID of each state can be found inside the parenthesis of each transition name under the **Transitions (id)** column. By default, this ID is set to `2`. |
+| `commit_events` | boolean | false | Enable notifications for commit events |
+| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
 
-### Delete JIRA service
+### Delete Jira service
 
-Remove all previously JIRA settings from a project.
+Remove all previously Jira settings from a project.
 
 ```
 DELETE /projects/:id/services/jira
 ```
 
-## Kubernetes
-
-Kubernetes / OpenShift integration
-
-CAUTION: **Warning:**
-Kubernetes service integration has been deprecated in GitLab 10.3. API service endpoints will continue to work as long as the Kubernetes service is active, however if the service is inactive API endpoints will automatically return a `400 Bad Request`. Read [GitLab 10.3 release post](https://about.gitlab.com/2017/12/22/gitlab-10-3-released/#kubernetes-integration-service) for more information.
-
-### Create/Edit Kubernetes service
-
-Set Kubernetes service for a project.
-
-```
-PUT /projects/:id/services/kubernetes
-```
-
-Parameters:
-
-- `namespace` (**required**) - The Kubernetes namespace to use
-- `api_url` (**required**) - The URL to the Kubernetes cluster API. For example, `https://kubernetes.example.com`
-- `token` (**required**) - The service token to authenticate against the Kubernetes cluster with
-- `ca_pem` (optional) - A custom certificate authority bundle to verify the Kubernetes cluster with (PEM format)
-
-### Delete Kubernetes service
-
-Delete Kubernetes service for a project.
-
-```
-DELETE /projects/:id/services/kubernetes
-```
-
-### Get Kubernetes service settings
-
-Get Kubernetes service settings for a project.
-
-```
-GET /projects/:id/services/kubernetes
-```
-
 ## Slack slash commands
 
 Ability to receive slash commands from a Slack chat instance.
@@ -715,9 +701,14 @@ PUT /projects/:id/services/packagist
 
 Parameters:
 
-- `username` (**required**)
-- `token` (**required**)
-- `server` (optional)
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `username` | string | yes | The username of a Packagist account |
+| `token` | string | yes | API token to the Packagist server |
+| `server` | boolean | no | URL of the Packagist server. Leave blank for default: <https://packagist.org> |
+| `push_events` | boolean | false | Enable notifications for push events |
+| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
+| `tag_push_events` | boolean | false | Enable notifications for tag push events |
 
 ### Delete Packagist service
 
@@ -755,6 +746,7 @@ Parameters:
 | `add_pusher` | boolean | no | Add pusher to recipients list |
 | `notify_only_broken_pipelines` | boolean | no | Notify only broken pipelines |
 | `notify_only_default_branch` | boolean | no | Send notifications only for the default branch ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/28271)) |
+| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
 
 ### Delete Pipeline-Emails service
 
@@ -790,6 +782,7 @@ Parameters:
 | --------- | ---- | -------- | ----------- |
 | `token` | string | true | The PivotalTracker token |
 | `restrict_to_branch` | boolean | false | Comma-separated list of branches which will be automatically inspected. Leave blank to include all branches. |
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete PivotalTracker service
 
@@ -862,6 +855,7 @@ Parameters:
 | `priority` | string | true | The priority |
 | `device` | string | false | Leave blank for all active devices |
 | `sound` | string | false | The sound of the notification |
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete Pushover service
 
@@ -899,6 +893,7 @@ Parameters:
 | `project_url` | string | true | Project url |
 | `issues_url` | string | true | Issue url |
 | `description` | string | false | Description |
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete Redmine service
 
@@ -939,22 +934,28 @@ Parameters:
 | `channel` | string | false | Default channel to use if others are not configured |
 | `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines |
 | `notify_only_default_branch` | boolean | false | Send notifications only for the default branch |
-| `push_events` | boolean | false | Enable notifications for push events |
-| `issues_events` | boolean | false | Enable notifications for issue events |
+| `commit_events` | boolean | false | Enable notifications for commit events |
+| `confidential_issue_channel` | string | false | The name of the channel to receive confidential issues events notifications |
 | `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events |
+| `confidential_note_channel` | string | false | The name of the channel to receive confidential note events notifications |
+| `confidential_note_events` | boolean | false | Enable notifications for confidential note events |
+| `deployment_channel` | string | false | The name of the channel to receive deployment events notifications |
+| `deployment_events` | boolean | false | Enable notifications for deployment events |
+| `issue_channel` | string | false | The name of the channel to receive issues events notifications |
+| `issues_events` | boolean | false | Enable notifications for issue events |
+| `job_events` | boolean | false | Enable notifications for job events |
+| `merge_request_channel` | string | false | The name of the channel to receive merge request events notifications |
 | `merge_requests_events` | boolean | false | Enable notifications for merge request events |
-| `tag_push_events` | boolean | false | Enable notifications for tag push events |
+| `note_channel` | string | false | The name of the channel to receive note events notifications |
 | `note_events` | boolean | false | Enable notifications for note events |
+| `pipeline_channel` | string | false | The name of the channel to receive pipeline events notifications |
 | `pipeline_events` | boolean | false | Enable notifications for pipeline events |
-| `wiki_page_events` | boolean | false | Enable notifications for wiki page events |
 | `push_channel` | string | false | The name of the channel to receive push events notifications |
-| `issue_channel` | string | false | The name of the channel to receive issues events notifications |
-| `confidential_issue_channel` | string | false | The name of the channel to receive confidential issues events notifications |
-| `merge_request_channel` | string | false | The name of the channel to receive merge request events notifications |
-| `note_channel` | string | false | The name of the channel to receive note events notifications |
+| `push_events` | boolean | false | Enable notifications for push events |
 | `tag_push_channel` | string | false | The name of the channel to receive tag push events notifications |
-| `pipeline_channel` | string | false | The name of the channel to receive pipeline events notifications |
+| `tag_push_events` | boolean | false | Enable notifications for tag push events |
 | `wiki_page_channel` | string | false | The name of the channel to receive wiki page events notifications |
+| `wiki_page_events` | boolean | false | Enable notifications for wiki page events |
 
 ### Delete Slack service
 
@@ -989,6 +990,17 @@ Parameters:
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `webhook` | string | true | The Microsoft Teams webhook. For example, `https://outlook.office.com/webhook/...` |
+| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines |
+| `notify_only_default_branch` | boolean | false | Send notifications only for the default branch |
+| `push_events` | boolean | false | Enable notifications for push events |
+| `issues_events` | boolean | false | Enable notifications for issue events |
+| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events |
+| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
+| `tag_push_events` | boolean | false | Enable notifications for tag push events |
+| `note_events` | boolean | false | Enable notifications for note events |
+| `confidental_note_events` | boolean | false | Enable notifications for confidential note events |
+| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
+| `wiki_page_events` | boolean | false | Enable notifications for wiki page events |
 
 ### Delete Microsoft Teams service
 
@@ -1084,6 +1096,7 @@ Parameters:
 | `build_type` | string | true | Build configuration ID |
 | `username` | string | true | A user with permissions to trigger a manual build |
 | `password` | string | true | The password of the user |
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete JetBrains TeamCity CI service
 
@@ -1101,7 +1114,7 @@ Get JetBrains TeamCity CI service settings for a project.
 GET /projects/:id/services/teamcity
 ```
 
-## Jenkins CI **[STARTER]**
+## Jenkins CI **(STARTER)**
 
 A continuous integration and build server
 
@@ -1115,7 +1128,7 @@ PUT /projects/:id/services/jenkins
 
 Parameters:
 
-- `jenkins_url` (**required**) - Jenkins URL like http://jenkins.example.com
+- `jenkins_url` (**required**) - Jenkins URL like `http://jenkins.example.com`
 - `project_name` (**required**) - The URL-friendly project name. Example: my_project_name
 - `username` (optional) - A user with access to the Jenkins server, if applicable
 - `password` (optional) - The password of the user
@@ -1150,7 +1163,7 @@ PUT /projects/:id/services/jenkins-deprecated
 
 Parameters:
 
-- `project_url` (**required**) - Jenkins project URL like http://jenkins.example.com/job/my-project/
+- `project_url` (**required**) - Jenkins project URL like `http://jenkins.example.com/job/my-project/`
 - `multiproject_enabled` (optional) - Multi-project mode is configured in Jenkins GitLab Hook plugin
 - `pass_unstable` (optional) - Unstable builds will be treated as passing
 
@@ -1230,6 +1243,7 @@ Parameters:
 | `issues_url` | string | true | Issue url |
 | `project_url` | string | true | Project url |
 | `description` | string | false | Description |
+| `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete YouTrack Service
 
diff --git a/doc/api/settings.md b/doc/api/settings.md
index c2a1f7feefd..248d19461f6 100644
--- a/doc/api/settings.md
+++ b/doc/api/settings.md
@@ -39,6 +39,7 @@ Example response:
    "session_expire_delay" : 10080,
    "home_page_url" : null,
    "default_snippet_visibility" : "private",
+   "outbound_local_requests_whitelist": [],
    "domain_whitelist" : [],
    "domain_blacklist_enabled" : false,
    "domain_blacklist" : [],
@@ -63,7 +64,23 @@ Example response:
    "performance_bar_allowed_group_id": 42,
    "instance_statistics_visibility_private": false,
    "user_show_add_ssh_key_message": true,
-   "local_markdown_version": 0
+   "local_markdown_version": 0,
+   "allow_local_requests_from_hooks_and_services": true,
+   "allow_local_requests_from_web_hooks_and_services": true,
+   "allow_local_requests_from_system_hooks": false
+}
+```
+
+Users on GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/) may also see
+the `file_template_project_id` or the `geo_node_allowed_ips` parameters:
+
+```json
+{
+   "id" : 1,
+   "signup_enabled" : true,
+   "file_template_project_id": 1,
+   "geo_node_allowed_ips": "0.0.0.0/0, ::/0"
+   ...
 }
 ```
 
@@ -100,6 +117,7 @@ Example response:
   "default_project_visibility": "internal",
   "default_snippet_visibility": "private",
   "default_group_visibility": "private",
+  "outbound_local_requests_whitelist": [],
   "domain_whitelist": [],
   "domain_blacklist_enabled" : false,
   "domain_blacklist" : [],
@@ -121,10 +139,36 @@ Example response:
   "performance_bar_allowed_group_id": 42,
   "instance_statistics_visibility_private": false,
   "user_show_add_ssh_key_message": true,
-  "local_markdown_version": 0
+  "file_template_project_id": 1,
+  "local_markdown_version": 0,
+  "geo_node_allowed_ips": "0.0.0.0/0, ::/0",
+  "allow_local_requests_from_hooks_and_services": true,
+  "allow_local_requests_from_web_hooks_and_services": true,
+  "allow_local_requests_from_system_hooks": false
 }
 ```
 
+Users on GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/) may also see
+these parameters:
+
+- `external_authorization_service_enabled`
+- `external_authorization_service_url`
+- `external_authorization_service_default_label`
+- `external_authorization_service_timeout`
+- `file_template_project_id`
+- `geo_node_allowed_ips`
+
+Example responses: **(PREMIUM ONLY)**
+
+```json
+  "external_authorization_service_enabled": true,
+  "external_authorization_service_url": "https://authorize.me",
+  "external_authorization_service_default_label": "default",
+  "external_authorization_service_timeout": 0.5,
+  "file_template_project_id": 1,
+  "geo_node_allowed_ips": "0.0.0.0/0, ::/0"
+```
+
 ## List of settings that can be accessed via API calls
 
 In general, all settings are optional. Certain settings though, if enabled, will
@@ -138,10 +182,14 @@ are listed in the descriptions of the relevant settings.
 | `after_sign_up_text`                     | string           | no                                   | Text shown to the user after signing up |
 | `akismet_api_key`                        | string           | required by: `akismet_enabled`       | API key for akismet spam protection. |
 | `akismet_enabled`                        | boolean          | no                                   | (**If enabled, requires:** `akismet_api_key`) Enable or disable akismet spam protection. |
-| `allow_local_requests_from_hooks_and_services` | boolean    | no                                   | Allow requests to the local network from hooks and services. |
+| `allow_group_owners_to_manage_ldap`      | boolean          | no                                   | **(PREMIUM)** Set to `true` to allow group owners to manage LDAP |
+| `allow_local_requests_from_hooks_and_services` | boolean    | no                                   | (Deprecated: Use `allow_local_requests_from_web_hooks_and_services` instead) Allow requests to the local network from hooks and services. |
+| `allow_local_requests_from_web_hooks_and_services` | boolean    | no                                   | Allow requests to the local network from web hooks and services. |
+| `allow_local_requests_from_system_hooks` | boolean    | no                                   | Allow requests to the local network from system hooks. |
 | `authorized_keys_enabled`                | boolean          | no                                   | By default, we write to the `authorized_keys` file to support Git over SSH without additional configuration. GitLab can be optimized to authenticate SSH keys via the database file. Only disable this if you have configured your OpenSSH server to use the AuthorizedKeysCommand. |
 | `auto_devops_domain`                     | string           | no                                   | Specify a domain to use by default for every project's Auto Review Apps and Auto Deploy stages. |
 | `auto_devops_enabled`                    | boolean          | no                                   | Enable Auto DevOps for projects by default. It will automatically build, test, and deploy applications based on a predefined CI/CD configuration. |
+| `check_namespace_plan`                   | boolean          | no                                   | **(PREMIUM)** Enabling this will make only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. |
 | `clientside_sentry_dsn`                  | string           | required by: `clientside_sentry_enabled` | Clientside Sentry Data Source Name. |
 | `clientside_sentry_enabled`              | boolean          | no                                   | (**If enabled, requires:** `clientside_sentry_dsn`) Enable Sentry error reporting for the client side. |
 | `container_registry_token_expire_delay`  | integer          | no                                   | Container Registry token duration in minutes. |
@@ -155,21 +203,44 @@ are listed in the descriptions of the relevant settings.
 | `domain_blacklist`                       | array of strings | required by: `domain_blacklist_enabled` | Users with e-mail addresses that match these domain(s) will NOT be able to sign-up. Wildcards allowed. Use separate lines for multiple entries. Ex: `domain.com`, `*.domain.com`. |
 | `domain_blacklist_enabled`               | boolean          | no                                   | (**If enabled, requires:** `domain_blacklist`) Allows blocking sign-ups from emails from specific domains. |
 | `domain_whitelist`                       | array of strings | no                                   | Force people to use only corporate emails for sign-up. Default is `null`, meaning there is no restriction. |
+| `outbound_local_requests_whitelist`      | array of strings | no                                   | Define a list of trusted domains or ip addresses to which local requests are allowed when local requests for hooks and services are disabled.
 | `dsa_key_restriction`                    | integer          | no                                   | The minimum allowed bit length of an uploaded DSA key. Default is `0` (no restriction). `-1` disables DSA keys. |
 | `ecdsa_key_restriction`                  | integer          | no                                   | The minimum allowed curve size (in bits) of an uploaded ECDSA key. Default is `0` (no restriction). `-1` disables ECDSA keys. |
 | `ed25519_key_restriction`                | integer          | no                                   | The minimum allowed curve size (in bits) of an uploaded ED25519 key. Default is `0` (no restriction). `-1` disables ED25519 keys. |
+| `elasticsearch_aws`                      | boolean          | no                                   | **(PREMIUM)** Enable the use of AWS hosted Elasticsearch |
+| `elasticsearch_aws_access_key`           | string           | no                                   | **(PREMIUM)** AWS IAM access key |
+| `elasticsearch_aws_region`               | string           | no                                   | **(PREMIUM)** The AWS region the elasticsearch domain is configured |
+| `elasticsearch_aws_secret_access_key`    | string           | no                                   | **(PREMIUM)** AWS IAM secret access key |
+| `elasticsearch_experimental_indexer`     | boolean          | no                                   | **(PREMIUM)** Use the experimental elasticsearch indexer. More info: <https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer> |
+| `elasticsearch_indexing`                 | boolean          | no                                   | **(PREMIUM)** Enable Elasticsearch indexing |
+| `elasticsearch_search`                   | boolean          | no                                   | **(PREMIUM)** Enable Elasticsearch search |
+| `elasticsearch_url`                      | string           | no                                   | **(PREMIUM)** The url to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (e.g., `http://localhost:9200, http://localhost:9201"`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). |
+| `elasticsearch_limit_indexing`           | boolean          | no                                   | **(PREMIUM)** Limit Elasticsearch to index certain namespaces and projects |
+| `elasticsearch_project_ids`              | array of integers | no                                  | **(PREMIUM)** The projects to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. |
+| `elasticsearch_namespace_ids`            | array of integers | no                                  | **(PREMIUM)** The namespaces to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. |
+| `email_additional_text`                  | string           | no                                   | **(PREMIUM)** Additional text added to the bottom of every email for legal/auditing/compliance reasons |
 | `email_author_in_body`                   | boolean          | no                                   | Some email servers do not support overriding the email sender name. Enable this option to include the name of the author of the issue, merge request or comment in the email body instead. |
 | `enabled_git_access_protocol`            | string           | no                                   | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `nil` to allow both protocols. |
 | `enforce_terms`                          | boolean          | no                                   | (**If enabled, requires:** `terms`) Enforce application ToS to all users. |
-| `first_day_of_week`            | integer          | no                                   | Start day of the week for calendar views and date pickers. Valid values are `0` (default) for Sunday, `1` for Monday, and `6` for Saturday. |
+| `external_auth_client_cert`              | string           | no                                   | **(PREMIUM)** (**If enabled, requires:** `external_auth_client_key`) The certificate to use to authenticate with the external authorization service |
+| `external_auth_client_key`               | string           | required by: `external_auth_client_cert` | **(PREMIUM)** Private key for the certificate when authentication is required for the external authorization service, this is encrypted when stored |
+| `external_auth_client_key_pass`          | string           | no                                   | **(PREMIUM)** Passphrase to use for the private key when authenticating with the external service this is encrypted when stored |
+| `external_authorization_service_enabled` | boolean          | no                                   | **(PREMIUM)** (**If enabled, requires:** `external_authorization_service_default_label`, `external_authorization_service_timeout` and `external_authorization_service_url` )  Enable using an external authorization service for accessing projects |
+| `external_authorization_service_default_label` | string     | required by: `external_authorization_service_enabled` | **(PREMIUM)** The default classification label to use when requesting authorization and no classification label has been specified on the project |
+| `external_authorization_service_timeout` | float            | required by: `external_authorization_service_enabled` | **(PREMIUM)** The timeout after which an authorization request is aborted, in seconds. When a request times out, access is denied to the user. (min: 0.001, max: 10, step: 0.001) |
+| `external_authorization_service_url`     | string           | required by: `external_authorization_service_enabled` | **(PREMIUM)** URL to which authorization requests will be directed |
+| `file_template_project_id`               | integer          | no                                   | **(PREMIUM)** The ID of a project to load custom file templates from |
+| `first_day_of_week`                      | integer          | no                                   | Start day of the week for calendar views and date pickers. Valid values are `0` (default) for Sunday, `1` for Monday, and `6` for Saturday. |
+| `geo_status_timeout`                     | integer          | no                                   | **(PREMIUM)** The amount of seconds after which a request to get a secondary node status will time out. |
 | `gitaly_timeout_default`                 | integer          | no                                   | Default Gitaly timeout, in seconds. This timeout is not enforced for git fetch/push operations or Sidekiq jobs. Set to `0` to disable timeouts. |
 | `gitaly_timeout_fast`                    | integer          | no                                   | Gitaly fast operation timeout, in seconds. Some Gitaly operations are expected to be fast. If they exceed this threshold, there may be a problem with a storage shard and 'failing fast' can help maintain the stability of the GitLab instance. Set to `0` to disable timeouts. |
 | `gitaly_timeout_medium`                  | integer          | no                                   | Medium Gitaly timeout, in seconds. This should be a value between the Fast and the Default timeout. Set to `0` to disable timeouts. |
 | `gravatar_enabled`                       | boolean          | no                                   | Enable Gravatar. |
 | `hashed_storage_enabled`                 | boolean          | no                                   | Create new projects using hashed storage paths: Enable immutable, hash-based paths and repository names to store repositories on disk. This prevents repositories from having to be moved or renamed when the Project URL changes and may improve disk I/O performance. (EXPERIMENTAL) |
 | `help_page_hide_commercial_content`      | boolean          | no                                   | Hide marketing-related entries from help. |
-| `help_page_support_url`                  | string           | no                                   | Alternate support URL for help page. |
+| `help_page_support_url`                  | string           | no                                   | Alternate support URL for help page and help dropdown. |
 | `help_page_text`                         | string           | no                                   | Custom text displayed on the help page. |
+| `help_text`                              | string           | no                                   | **(PREMIUM)** GitLab server administrator information |
 | `hide_third_party_offers`                | boolean          | no                                   | Do not display offers from third parties within GitLab. |
 | `home_page_url`                          | string           | no                                   | Redirect to this URL when not logged in. |
 | `housekeeping_bitmaps_enabled`           | boolean          | required by: `housekeeping_enabled`  | Enable Git pack file bitmap creation. |
@@ -192,6 +263,9 @@ are listed in the descriptions of the relevant settings.
 | `metrics_sample_interval`                | integer          | required by: `metrics_enabled`       | The sampling interval in seconds. |
 | `metrics_timeout`                        | integer          | required by: `metrics_enabled`       | The amount of seconds after which InfluxDB will time out. |
 | `mirror_available`                       | boolean          | no                                   | Allow mirrors to be set up for projects. If disabled, only admins will be able to set up mirrors in projects. |
+| `mirror_capacity_threshold`              | integer          | no                                   | **(PREMIUM)** Minimum capacity to be available before scheduling more mirrors preemptively |
+| `mirror_max_capacity`                    | integer          | no                                   | **(PREMIUM)** Maximum number of mirrors that can be synchronizing at the same time. |
+| `mirror_max_delay`                       | integer          | no                                   | **(PREMIUM)** Maximum time (in minutes) between updates that a mirror can have when scheduled to synchronize. |
 | `pages_domain_verification_enabled`      | boolean          | no                                   | Require users to prove ownership of custom domains. Domain verification is an essential security measure for public GitLab sites. Users are required to demonstrate they control a domain before it is enabled. |
 | `password_authentication_enabled_for_git` | boolean         | no                                   | Enable authentication for Git over HTTP(S) via a GitLab account password. Default is `true`. |
 | `password_authentication_enabled_for_web` | boolean         | no                                   | Enable authentication for the web interface via a GitLab account password. Default is `true`. |
@@ -203,23 +277,28 @@ are listed in the descriptions of the relevant settings.
 | `polling_interval_multiplier`            | decimal          | no                                   | Interval multiplier used by endpoints that perform polling. Set to `0` to disable polling. |
 | `project_export_enabled`                 | boolean          | no                                   | Enable project export. |
 | `prometheus_metrics_enabled`             | boolean          | no                                   | Enable prometheus metrics. |
+| `pseudonymizer_enabled`                  | boolean          | no                                   | **(PREMIUM)** When enabled, GitLab will run a background job that will produce pseudonymized CSVs of the GitLab database that will be uploaded to your configured object storage directory.
 | `recaptcha_enabled`                      | boolean          | no                                   | (**If enabled, requires:** `recaptcha_private_key` and `recaptcha_site_key`) Enable recaptcha. |
 | `recaptcha_private_key`                  | string           | required by: `recaptcha_enabled`     | Private key for recaptcha. |
 | `recaptcha_site_key`                     | string           | required by: `recaptcha_enabled`     | Site key for recaptcha. |
 | `repository_checks_enabled`              | boolean          | no                                   | GitLab will periodically run `git fsck` in all project and wiki repositories to look for silent disk corruption issues. |
+| `repository_size_limit`                  | integer          | no                                   | **(PREMIUM)** Size limit per repository (MB) |
 | `repository_storages`                    | array of strings | no                                   | A list of names of enabled storage paths, taken from `gitlab.yml`. New projects will be created in one of these stores, chosen at random. |
 | `require_two_factor_authentication`      | boolean          | no                                   | (**If enabled, requires:** `two_factor_grace_period`) Require all users to set up Two-factor authentication. |
 | `restricted_visibility_levels`           | array of strings | no                                   | Selected levels cannot be used by non-admin users for groups, projects or snippets. Can take `private`, `internal` and `public` as a parameter. Default is `null` which means there is no restriction. |
 | `rsa_key_restriction`                    | integer          | no                                   | The minimum allowed bit length of an uploaded RSA key. Default is `0` (no restriction). `-1` disables RSA keys. |
 | `send_user_confirmation_email`           | boolean          | no                                   | Send confirmation email on sign-up. |
-| `sentry_dsn`                             | string           | required by: `sentry_enabled`        | Sentry Data Source Name. |
-| `sentry_enabled`                         | boolean          | no                                   | (**If enabled, requires:** `sentry_dsn`) Sentry is an error reporting and logging tool which is currently not shipped with GitLab, available at <https://sentry.io>. |
 | `session_expire_delay`                   | integer          | no                                   | Session duration in minutes. GitLab restart is required to apply changes |
-| `shared_runners_enabled`                 | boolean          | no                                   | (**If enabled, requires:** `shared_runners_text`) Enable shared runners for new projects. |
+| `shared_runners_enabled`                 | boolean          | no                                   | (**If enabled, requires:** `shared_runners_text` and `shared_runners_minutes`) Enable shared runners for new projects. |
+| `shared_runners_minutes`                 | integer          | required by: `shared_runners_enabled` | **(PREMIUM)** Set the maximum number of pipeline minutes that a group can use on shared Runners per month. |
 | `shared_runners_text`                    | string           | required by: `shared_runners_enabled` | Shared runners text. |
 | `sign_in_text`                           | string           | no                                   | Text on the login page. |
 | `signin_enabled`                         | string           | no                                   | (Deprecated: Use `password_authentication_enabled_for_web` instead) Flag indicating if password authentication is enabled for the web interface. |
 | `signup_enabled`                         | boolean          | no                                   | Enable registration. Default is `true`. |
+| `slack_app_enabled`                      | boolean          | no                                   | **(PREMIUM)** (**If enabled, requires:** `slack_app_id`, `slack_app_secret` and `slack_app_secret`) Enable Slack app. |
+| `slack_app_id`                           | string           | required by: `slack_app_enabled`      | **(PREMIUM)** The app id of the Slack-app. |
+| `slack_app_secret`                       | string           | required by: `slack_app_enabled`      | **(PREMIUM)** The app secret of the Slack-app. |
+| `slack_app_verification_token`           | string           | required by: `slack_app_enabled`      | **(PREMIUM)** The verification token of the Slack-app. |
 | `terminal_max_session_time`              | integer          | no                                   | Maximum time for web terminal websocket connection (in seconds). Set to `0` for unlimited time. |
 | `terms`                                  | text             | required by: `enforce_terms`         | (**Required by:** `enforce_terms`) Markdown content for the ToS. |
 | `throttle_authenticated_api_enabled`     | boolean          | no                                   | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (e.g. from crawlers or abusive bots). |
@@ -231,6 +310,7 @@ are listed in the descriptions of the relevant settings.
 | `throttle_unauthenticated_enabled`       | boolean          | no                                   | (**If enabled, requires:** `throttle_unauthenticated_period_in_seconds` and `throttle_unauthenticated_requests_per_period`) Enable unauthenticated request rate limit. Helps reduce request volume (e.g. from crawlers or abusive bots). |
 | `throttle_unauthenticated_period_in_seconds` | integer      | required by: `throttle_unauthenticated_enabled` | Rate limit period in seconds.  |
 | `throttle_unauthenticated_requests_per_period` | integer    | required by: `throttle_unauthenticated_enabled` | Max requests per period per IP. |
+| `time_tracking_limit_to_hours`           | boolean          | no                                   | Limit display of time tracking units to hours. Default is `false`. |
 | `two_factor_grace_period`                | integer          | required by: `require_two_factor_authentication` | Amount of time (in hours) that users are allowed to skip forced configuration of two-factor authentication. |
 | `unique_ips_limit_enabled`               | boolean          | no                                   | (**If enabled, requires:** `unique_ips_limit_per_user` and `unique_ips_limit_time_window`) Limit sign in from multiple ips. |
 | `unique_ips_limit_per_user`              | integer          | required by: `unique_ips_limit_enabled` | Maximum number of ips per user. |
@@ -241,3 +321,8 @@ are listed in the descriptions of the relevant settings.
 | `user_show_add_ssh_key_message`          | boolean          | no                                   | When set to `false` disable the "You won't be able to pull or push project code via SSH" warning shown to users with no uploaded SSH key. |
 | `version_check_enabled`                  | boolean          | no                                   | Let GitLab inform you when an update is available. |
 | `local_markdown_version`                 | integer          | no                                   | Increase this value when any cached markdown should be invalidated. |
+| `snowplow_enabled`                       | boolean          | no                                   | Enable snowplow tracking. |
+| `snowplow_collector_hostname`            | string           | required by: `snowplow_enabled`      | The Snowplow collector hostname. (e.g. `snowplow.trx.gitlab.net`) | 
+| `snowplow_site_id`                       | string           | no                                   | The Snowplow site name / application id. (e.g. `gitlab`) |
+| `snowplow_cookie_domain`                 | string           | no                                   | The Snowplow cookie domain. (e.g. `.gitlab.com`) |
+| `geo_node_allowed_ips`                   | string           | yes                                  | **(PREMIUM)** Comma-separated list of IPs and CIDRs of allowed secondary nodes. For example, `1.1.1.1, 2.2.2.0/24`. |
diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md
index f8563e819db..1b8c23b8e2d 100644
--- a/doc/api/system_hooks.md
+++ b/doc/api/system_hooks.md
@@ -11,8 +11,6 @@ Read more about [system hooks](../system_hooks/system_hooks.md).
 
 Get a list of all system hooks.
 
----
-
 ```
 GET /hooks
 ```
@@ -44,8 +42,6 @@ Example response:
 
 Add a new system hook.
 
----
-
 ```
 POST /hooks
 ```
@@ -116,8 +112,6 @@ Example response:
 
 Deletes a system hook.
 
----
-
 ```
 DELETE /hooks/:id
 ```
@@ -130,4 +124,4 @@ Example request:
 
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/hooks/2
-```
\ No newline at end of file
+```
diff --git a/doc/api/tags.md b/doc/api/tags.md
index 3177fec618f..af86ba961f4 100644
--- a/doc/api/tags.md
+++ b/doc/api/tags.md
@@ -141,6 +141,7 @@ Parameters:
   "message": null
 }
 ```
+
 The message will be `null` when creating a lightweight tag otherwise
 it will contain the annotation.
 
diff --git a/doc/api/users.md b/doc/api/users.md
index 47028c679b8..b41fd106fc5 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -2,6 +2,8 @@
 
 ## List users
 
+Active users = Total accounts - Blocked users
+
 Get a list of users.
 
 This function takes pagination parameters `page` and `per_page` to restrict the list of users.
@@ -68,11 +70,11 @@ Username search is case insensitive.
 GET /users
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `order_by` | string | no | Return users ordered by `id`, `name`, `username`, `created_at`, or `updated_at` fields. Default is `id` |
-| `sort` | string | no | Return users sorted in `asc` or `desc` order. Default is `desc` |
-| `two_factor` | string | no | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users |
+| Attribute    | Type   | Required | Description |
+| ------------ | ------ | -------- | ----------- |
+| `order_by`   | string | no       | Return users ordered by `id`, `name`, `username`, `created_at`, or `updated_at` fields. Default is `id` |
+| `sort`       | string | no       | Return users sorted in `asc` or `desc` order. Default is `desc` |
+| `two_factor` | string | no       | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users |
 
 ```json
 [
@@ -145,6 +147,40 @@ GET /users
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, and `note` parameters.
+
+```json
+[
+  {
+    "id": 1,
+    ...
+    "shared_runners_minutes_limit": 133,
+    "extra_shared_runners_minutes_limit": 133,
+    "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123"
+    ...
+  }
+]
+```
+
+Users on GitLab [Silver or higher](https://about.gitlab.com/pricing/) will also see
+the `group_saml` provider option:
+
+```json
+[
+  {
+    "id": 1,
+    ...
+    "identities": [
+      {"provider": "github", "extern_uid": "2435223452345"},
+      {"provider": "bitbucket", "extern_uid": "john.smith"},
+      {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"},
+      {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10}
+    ],
+    ...
+  }
+]
+```
+
 You can lookup users by external UID and provider:
 
 ```
@@ -221,6 +257,8 @@ Parameters:
 
 - `id` (required) - The ID of a user
 
+Example Responses:
+
 ```json
 {
   "id": 1,
@@ -256,8 +294,41 @@ Parameters:
   "can_create_project": true,
   "two_factor_enabled": true,
   "external": false,
-  "private_profile": false,
-  "highest_role":10
+  "private_profile": false
+}
+```
+
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, and `note` parameters.
+
+```json
+{
+  "id": 1,
+  "username": "john_smith",
+  "shared_runners_minutes_limit": 133,
+  "extra_shared_runners_minutes_limit": 133,
+  "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123"
+  ...
+}
+```
+
+Users on GitLab.com [Silver, or higher](https://about.gitlab.com/pricing/) will also
+see the `group_saml` option:
+
+```json
+{
+  "id": 1,
+  "username": "john_smith",
+  "shared_runners_minutes_limit": 133,
+  "extra_shared_runners_minutes_limit": 133,
+  "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123"
+  "identities": [
+    {"provider": "github", "extern_uid": "2435223452345"},
+    {"provider": "bitbucket", "extern_uid": "john.smith"},
+    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"},
+    {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10}
+  ],
+  ...
 }
 ```
 
@@ -269,7 +340,17 @@ GET /users/:id?with_custom_attributes=true
 
 ## User creation
 
-Creates a new user. Note only administrators can create new users. Either `password` or `reset_password` should be specified (`reset_password` takes priority). If `reset_password` is `false`, then `password` is required.
+Creates a new user. Note only administrators can create new
+users. Either `password`, `reset_password`, or `force_random_password`
+must be specified. If `reset_password` and `force_random_password` are
+both `false`, then `password` is required.
+
+Note that `force_random_password` and `reset_password` take priority
+over `password`. In addition, `reset_password` and
+`force_random_password` can be used together.
+
+NOTE: **Note:**
+From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29888/), `private_profile` will default to `false`.
 
 ```
 POST /users
@@ -296,9 +377,11 @@ Parameters:
 - `admin` (optional)             - User is admin - true or false (default)
 - `can_create_group` (optional)  - User can create groups - true or false
 - `skip_confirmation` (optional) - Skip confirmation - true or false (default)
-- `external` (optional)          - Flags the user as external - true or false(default)
+- `external` (optional)          - Flags the user as external - true or false (default)
 - `avatar` (optional)            - Image file for user's avatar
-- `private_profile` (optional)   - User's profile is private - true or false
+- `private_profile` (optional)   - User's profile is private - true or false (default)
+- `shared_runners_minutes_limit` (optional)       - Pipeline minutes quota for this user **(STARTER)**
+- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **(STARTER)**
 
 ## User modification
 
@@ -322,15 +405,21 @@ Parameters:
 - `projects_limit`                 - Limit projects each user can create
 - `extern_uid`                     - External UID
 - `provider`                       - External provider name
+- `group_id_for_saml` (optional)   - ID of group where SAML has been configured
 - `bio`                            - User's biography
 - `location` (optional)            - User's location
 - `public_email` (optional)        - The public email of the user
 - `admin` (optional)               - User is admin - true or false (default)
 - `can_create_group` (optional)    - User can create groups - true or false
 - `skip_reconfirmation` (optional) - Skip reconfirmation - true or false (default)
-- `external` (optional)            - Flags the user as external - true or false(default)
+- `external` (optional)            - Flags the user as external - true or false (default)
+- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user
+- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user
 - `avatar` (optional)              - Image file for user's avatar
-- `private_profile` (optional)     - User's profile is private - true or false
+- `private_profile` (optional)     - User's profile is private - true or false (default)
+- `shared_runners_minutes_limit` (optional)       - Pipeline minutes quota for this user **(STARTER)**
+- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **(STARTER)**
+- `note` (optional) - Admin notes for this user **(STARTER)**
 
 On password update, user will be forced to change it upon next login.
 Note, at the moment this method does only return a `404` error,
@@ -353,9 +442,7 @@ Parameters:
   [moved to the ghost user](../user/profile/account/delete_account.md#associated-records)
   will be deleted instead, as well as groups owned solely by this user.
 
-## User
-
-### For normal users
+## List current user (for normal users)
 
 Gets currently authenticated user.
 
@@ -401,7 +488,7 @@ GET /user
 }
 ```
 
-### For admins
+## List current user (for admins)
 
 Parameters:
 
@@ -480,9 +567,9 @@ Get the status of a user.
 GET /users/:id_or_username/status
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id_or_username` | string | yes    | The id or username of the user to get a status of |
+| Attribute        | Type   | Required | Description |
+| ---------------- | ------ | -------- | ----------- |
+| `id_or_username` | string | yes      | The id or username of the user to get a status of |
 
 ```bash
 curl "https://gitlab.example.com/users/janedoe/status"
@@ -506,8 +593,8 @@ Set the status of the current user.
 PUT /user/status
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
+| Attribute | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
 | `emoji`   | string | no     | The name of the emoji to use as status, if omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index][gemojione-index]. |
 | `message` | string | no     | The message to set as a status. It can also contain emoji codes. |
 
@@ -527,9 +614,33 @@ Example responses
 }
 ```
 
+## User counts
+
+Get the counts (same as in top right menu) of the currently signed in user.
+
+| Attribute | Type | Description |
+| --------- | ---- | ----------- |
+| `merge_requests`   | number | Merge requests that are active and assigned to current user. |
+
+```
+GET /user_counts
+```
+
+```bash
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user_counts"
+```
+
+Example response:
+
+```json
+{
+  "merge_requests": 4
+}
+```
+
 ## List user projects
 
-Please refer to the [List of user projects ](projects.md#list-user-projects).
+Please refer to the [List of user projects](projects.md#list-user-projects).
 
 ## List SSH keys
 
@@ -705,9 +816,9 @@ GET /user/gpg_keys/:key_id
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `key_id`  | integer | yes   | The ID of the GPG key |
+| Attribute | Type    | Required | Description |
+| --------- | ------- | -------- | ----------- |
+| `key_id`  | integer | yes      | The ID of the GPG key |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys/1
@@ -733,9 +844,9 @@ POST /user/gpg_keys
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| key       | string | yes    | The new GPG key |
+| Attribute | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| key       | string | yes      | The new GPG key |
 
 ```bash
 curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..."  --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys
@@ -763,9 +874,9 @@ DELETE /user/gpg_keys/:key_id
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `key_id`  | integer | yes   | The ID of the GPG key |
+| Attribute | Type    | Required | Description |
+| --------- | ------- | -------- | ----------- |
+| `key_id`  | integer | yes      | The ID of the GPG key |
 
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys/1
@@ -783,9 +894,9 @@ GET /users/:id/gpg_keys
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of the user |
+| Attribute | Type    | Required | Description |
+| --------- | ------- | -------- | ----------- |
+| `id`      | integer | yes      | The ID of the user |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys
@@ -813,10 +924,10 @@ GET /users/:id/gpg_keys/:key_id
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of the user |
-| `key_id`  | integer | yes   | The ID of the GPG key |
+| Attribute | Type    | Required | Description |
+| --------- | ------- | -------- | ----------- |
+| `id`      | integer | yes      | The ID of the user |
+| `key_id`  | integer | yes      | The ID of the GPG key |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys/1
@@ -842,10 +953,10 @@ POST /users/:id/gpg_keys
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of the user |
-| `key_id`  | integer | yes   | The ID of the GPG key |
+| Attribute | Type    | Required | Description |
+| --------- | ------- | -------- | ----------- |
+| `id`      | integer | yes      | The ID of the user |
+| `key_id`  | integer | yes      | The ID of the GPG key |
 
 ```bash
 curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..."  --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys
@@ -873,10 +984,10 @@ DELETE /users/:id/gpg_keys/:key_id
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of the user |
-| `key_id`  | integer | yes   | The ID of the GPG key |
+| Attribute | Type    | Required | Description |
+| --------- | ------- | -------- | ----------- |
+| `id`      | integer | yes      | The ID of the user |
+| `key_id`  | integer | yes      | The ID of the GPG key |
 
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys/1
@@ -1057,10 +1168,10 @@ GET /users/:user_id/impersonation_tokens
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `user_id` | integer | yes | The ID of the user |
-| `state`   | string  | no | filter tokens based on state (`all`, `active`, `inactive`) |
+| Attribute | Type    | Required | Description                                                |
+| --------- | ------- | -------- | ---------------------------------------------------------- |
+| `user_id` | integer | yes      | The ID of the user                                         |
+| `state`   | string  | no       | filter tokens based on state (`all`, `active`, `inactive`) |
 
 ```
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
@@ -1109,10 +1220,10 @@ GET /users/:user_id/impersonation_tokens/:impersonation_token_id
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `user_id` | integer | yes | The ID of the user |
-| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
+| Attribute                | Type    | Required | Description                       |
+| ------------------------ | ------- | -------- | --------------------------------- |
+| `user_id`                | integer | yes      | The ID of the user                |
+| `impersonation_token_id` | integer | yes      | The ID of the impersonation token |
 
 ```
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2
@@ -1138,7 +1249,6 @@ Example response:
 ## Create an impersonation token
 
 > Requires admin permissions.
-
 > Token values are returned once. Make sure you save it - you won't be able to access it again.
 
 It creates a new impersonation token. Note that only administrators can do this.
@@ -1150,14 +1260,12 @@ settings page.
 POST /users/:user_id/impersonation_tokens
 ```
 
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `user_id` | integer | yes | The ID of the user |
-| `name`    | string  | yes | The name of the impersonation token |
-| `expires_at` | date | no  | The expiration date of the impersonation token in ISO format (`YYYY-MM-DD`)|
-| `scopes` | array    | yes | The array of scopes of the impersonation token (`api`, `read_user`) |
+| Attribute    | Type    | Required | Description |
+| ------------ | ------- | -------- | ----------- |
+| `user_id`    | integer | yes      | The ID of the user |
+| `name`       | string  | yes      | The name of the impersonation token |
+| `expires_at` | date    | no       | The expiration date of the impersonation token in ISO format (`YYYY-MM-DD`)|
+| `scopes`     | array   | yes      | The array of scopes of the impersonation token (`api`, `read_user`) |
 
 ```
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" --data "scopes[]=api" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
@@ -1204,15 +1312,15 @@ Parameters:
 
 ### Get user activities (admin only)
 
->**Note:** This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above.
+NOTE: **Note:** This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above.
 
 Get the last activity date for all users, sorted from oldest to newest.
 
 The activities that update the timestamp are:
 
-  - Git HTTP/SSH activities (such as clone, push)
-  - User logging in into GitLab
-  - User visiting pages related to Dashboards, Projects, Issues and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/54947) in GitLab 11.8)
+- Git HTTP/SSH activities (such as clone, push)
+- User logging in into GitLab
+- User visiting pages related to Dashboards, Projects, Issues and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/54947) in GitLab 11.8)
 
 By default, it shows the activity for all users in the last 6 months, but this can be
 amended by using the `from` parameter.
diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md
index 5752fb7c078..5f875528a6c 100644
--- a/doc/api/v3_to_v4.md
+++ b/doc/api/v3_to_v4.md
@@ -9,7 +9,7 @@ The V3 API documentation is still
 
 Below are the changes made between V3 and V4.
 
-### 8.17
+## 8.17
 
 - Removed `GET /projects/:search` (use: `GET /projects?search=x`) [!8877](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8877)
 - `iid` filter has been removed from `GET /projects/:id/issues` [!8967](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8967)
@@ -18,7 +18,7 @@ Below are the changes made between V3 and V4.
 - Project snippets do not return deprecated field `expires_at` [!8723](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8723)
 - Endpoints under `GET /projects/:id/keys` have been removed (use `GET /projects/:id/deploy_keys`) [!8716](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8716)
 
-### 9.0
+## 9.0
 
 - Status 409 returned for `POST /projects/:id/members` when a member already exists [!9093](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9093)
 - Moved `DELETE /projects/:id/star` to `POST /projects/:id/unstar` [!9328](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9328)
diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md
index 390d0966244..eaa4c13de55 100644
--- a/doc/api/vulnerabilities.md
+++ b/doc/api/vulnerabilities.md
@@ -1,4 +1,4 @@
-# Vulnerabilities API **[ULTIMATE]**
+# Vulnerabilities API **(ULTIMATE)**
 
 Every API call to vulnerabilities must be authenticated.
 
@@ -30,15 +30,17 @@ GET /projects/:id/vulnerabilities?scope=all
 GET /projects/:id/vulnerabilities?scope=dismissed
 GET /projects/:id/vulnerabilities?severity=high
 GET /projects/:id/vulnerabilities?confidence=unknown,experimental
+GET /projects/:id/vulnerabilities?pipeline_id=42
 ```
 
-| Attribute           | Type             | Required   | Description                                                                                                                                                                 |
-| ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user.                                                            |
-| `report_type`       | Array[string]    | no         | Returns vulnerabilities belonging to specified report type. Valid values: `sast`, `dast`, `dependency_scanning`, or `container_scanning`.                                   |
-| `scope`             | string           | no         | Returns vulnerabilities for the given scope: `all` or `dismissed`. Defaults to `dismissed`                                                                                  |
-| `severity`          | Array[string]    | no         | Returns vulnerabilities belonging to specified severity level: `undefined`, `info`, `unknown`, `low`, `medium`, `high`, or `critical`. Defaults to all'                     |
-| `confidence`        | Array[string]    | no         | Returns vulnerabilities belonging to specified confidence level: `undefined`, `ignore`, `unknown`, `experimental`, `low`, `medium`, `high`, or `confirmed`. Defaults to all |
+| Attribute     | Type           | Required | Description                                                                                                                                                                 |
+| ------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user.                                                            |
+| `report_type` | string array   | no       | Returns vulnerabilities belonging to specified report type. Valid values: `sast`, `dast`, `dependency_scanning`, or `container_scanning`.                                   |
+| `scope`       | string         | no       | Returns vulnerabilities for the given scope: `all` or `dismissed`. Defaults to `dismissed`                                                                                  |
+| `severity`    | string array   | no       | Returns vulnerabilities belonging to specified severity level: `undefined`, `info`, `unknown`, `low`, `medium`, `high`, or `critical`. Defaults to all'                     |
+| `confidence`  | string array   | no       | Returns vulnerabilities belonging to specified confidence level: `undefined`, `ignore`, `unknown`, `experimental`, `low`, `medium`, `high`, or `confirmed`. Defaults to all |
+| `pipeline_id` | integer/string | no       | Returns vulnerabilities belonging to specified pipeline.                                                                                                                    |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/vulnerabilities
diff --git a/doc/ci/README.md b/doc/ci/README.md
index 1743c38eb46..ca9d0aa61bd 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -13,6 +13,11 @@ through the [continuous methodologies](introduction/index.md#introduction-to-cic
 - Continuous Delivery (CD)
 - Continuous Deployment (CD)
 
+NOTE: **Out-of-the-box management systems can decrease hours spent on maintaining toolchains by 10% or more.**
+Watch our
+["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/)
+webcast to learn about continuous methods and how GitLab’s built-in CI can help you simplify and scale software development.
+
 ## Overview
 
 Continuous Integration works by pushing small code chunks to your
@@ -48,6 +53,9 @@ the following documents:
 - [GitLab CI/CD basic workflow](introduction/index.md#basic-cicd-workflow).
 - [Step-by-step guide for writing `.gitlab-ci.yml` for the first time](../user/project/pages/getting_started_part_four.md).
 
+If you're coming over from Jenkins, you can also check out our handy [reference](jenkins/index.md)
+for converting your pipelines.
+
 You can also get started by using one of the
 [`.gitlab-ci.yml` templates](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates)
 available through the UI. You can use them by creating a new file,
@@ -59,11 +67,11 @@ to your needs:
 For a broader overview, see the [CI/CD getting started](quick_start/README.md) guide.
 
 Once you're familiar with how GitLab CI/CD works, see the
-[`. gitlab-ci.yml` full reference](yaml/README.md)
+[`.gitlab-ci.yml` full reference](yaml/README.md)
 for all the attributes you can set and use.
 
 NOTE: **Note:**
-GitLab CI/CD and [shared runners](runners/README.md#shared-specific-and-group-runners) are enabled in GitLab.com and available for all users, limited only to the [user's pipelines quota](../user/admin_area/settings/continuous_integration.md#extra-shared-runners-pipeline-minutes-quota).
+GitLab CI/CD and [shared runners](runners/README.md#shared-specific-and-group-runners) are enabled in GitLab.com and available for all users, limited only to the [user's pipelines quota](../user/gitlab_com/index.md#shared-runners).
 
 ## Configuration
 
@@ -81,6 +89,7 @@ GitLab CI/CD supports numerous configuration options:
 | [Git submodules for CI/CD](git_submodules.md) | Configure jobs for using Git submodules.|
 | [SSH keys for CI/CD](ssh_keys/README.md) | Using SSH keys in your CI pipelines. |
 | [Pipelines triggers](triggers/README.md) | Trigger pipelines through the API. |
+| [Pipelines for Merge Requests](merge_request_pipelines/index.md) | Design a pipeline structure for running a pipeline in merge requests. |
 | [Integrate with Kubernetes clusters](../user/project/clusters/index.md) | Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes cluster. |
 | [GitLab Runner](https://docs.gitlab.com/runner/) | Configure your own GitLab Runners to execute your scripts. |
 | [Optimize GitLab and Runner for large repositories](large_repositories/index.md) | Recommended strategies for handling large repos. |
@@ -103,27 +112,27 @@ Its feature set is listed on the table below according to DevOps stages.
 | **Verify** ||
 | [Browser Performance Testing](../user/project/merge_requests/browser_performance_testing.md) | Quickly determine the performance impact of pending code changes. |
 | [CI services](services/README.md) | Link Docker containers with your base image.|
-| [Code Quality](../user/project/merge_requests/code_quality.md) **[STARTER]** | Analyze your source code quality. |
-| [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **[PREMIUM]** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and BitBucket Cloud. |
-| [Interactive Web Terminals](interactive_web_terminal/index.md) **[CORE ONLY]** | Open an interactive web terminal to debug the running jobs. |
+| [Code Quality](../user/project/merge_requests/code_quality.md) **(STARTER)** | Analyze your source code quality. |
+| [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **(PREMIUM)** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and BitBucket Cloud. |
+| [Interactive Web Terminals](interactive_web_terminal/index.md) **(CORE ONLY)** | Open an interactive web terminal to debug the running jobs. |
 | [JUnit tests](junit_test_reports.md) | Identify script failures directly on merge requests. |
 | [Using Docker images](docker/using_docker_images.md) | Use GitLab and GitLab Runner with Docker to build and test applications. |
 |---+---|
 | **Release** ||
 | [Auto Deploy](../topics/autodevops/index.md#auto-deploy) | Deploy your application to a production environment in a Kubernetes cluster. |
 | [Building Docker images](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. |
-| [Canary Deployments](../user/project/canary_deployments.md) **[PREMIUM]** | Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature. |
-| [Deploy Boards](../user/project/deploy_boards.md) **[PREMIUM]** | Check the current health and status of each CI/CD environment running on Kubernetes. |
-| [Feature Flags](../user/project/operations/feature_flags.md) **[PREMIUM]** | Deploy your features behind Feature Flags. |
+| [Canary Deployments](../user/project/canary_deployments.md) **(PREMIUM)** | Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature. |
+| [Deploy Boards](../user/project/deploy_boards.md) **(PREMIUM)** | Check the current health and status of each CI/CD environment running on Kubernetes. |
+| [Feature Flags](../user/project/operations/feature_flags.md) **(PREMIUM)** | Deploy your features behind Feature Flags. |
 | [GitLab Pages](../user/project/pages/index.md) | Deploy static websites. |
 | [GitLab Releases](../user/project/releases/index.md) | Add release notes to Git tags. |
 | [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes. |
 |---+---|
 | **Secure** ||
-| [Container Scanning](../user/application_security/container_scanning/index.md) **[ULTIMATE]** | Check your Docker containers for known vulnerabilities.|
-| [Dependency Scanning](../user/application_security/dependency_scanning/index.md) **[ULTIMATE]** | Analyze your dependencies for known vulnerabilities. |
-| [License Management](../user/application_security/license_management/index.md) **[ULTIMATE]** | Search your project dependencies for their licenses. |
-| [Security Test reports](../user/project/merge_requests/index.md#security-reports-ultimate) **[ULTIMATE]** | Check for app vulnerabilities. |
+| [Container Scanning](../user/application_security/container_scanning/index.md) **(ULTIMATE)** | Check your Docker containers for known vulnerabilities.|
+| [Dependency Scanning](../user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. |
+| [License Management](../user/application_security/license_management/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. |
+| [Security Test reports](../user/project/merge_requests/index.md#security-reports-ultimate) **(ULTIMATE)** | Check for app vulnerabilities. |
 
 ## Examples
 
@@ -132,7 +141,7 @@ on the [CI Examples](examples/README.md) page.
 
 GitLab also provides [example projects](https://gitlab.com/gitlab-examples) pre-configured to use GitLab CI/CD.
 
-## Administration **[CORE ONLY]**
+## Administration **(CORE ONLY)**
 
 As a GitLab administrator, you can change the default behavior
 of GitLab CI/CD for:
@@ -154,6 +163,7 @@ for your CI/CD infrastructure:
 
 - [Why we chose GitLab CI for our CI/CD solution](https://about.gitlab.com/2016/10/17/gitlab-ci-oohlala/)
 - [Building our web-app on GitLab CI](https://about.gitlab.com/2016/07/22/building-our-web-app-on-gitlab-ci/)
+- [5 Teams that made the switch to GitLab CI/CD](https://about.gitlab.com/2019/04/25/5-teams-that-made-the-switch-to-gitlab-ci-cd/)
 
 See also the [Why CI/CD?](https://docs.google.com/presentation/d/1OGgk2Tcxbpl7DJaIOzCX4Vqg3dlwfELC3u2jEeCBbDk) presentation.
 
diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md
index 9a5a3624c73..f8151e3e18c 100644
--- a/doc/ci/caching/index.md
+++ b/doc/ci/caching/index.md
@@ -8,7 +8,7 @@ GitLab CI/CD provides a caching mechanism that can be used to save time
 when your jobs are running.
 
 Caching is about speeding the time a job is executed by reusing the same
-content of a previous job. It can be particularly useful when your are
+content of a previous job. It can be particularly useful when you are
 developing software that depends on other libraries which are fetched via the
 internet during build time.
 
@@ -378,8 +378,8 @@ Here's what happens behind the scenes:
 1. `script` is executed.
 1. `after_script` is executed.
 1. `cache` runs and the `vendor/` directory is zipped into `cache.zip`.
-    This file is then saved in the directory based on the
-    [Runner's setting](#where-the-caches-are-stored) and the `cache: key`.
+   This file is then saved in the directory based on the
+   [Runner's setting](#where-the-caches-are-stored) and the `cache: key`.
 1. `job B` runs.
 1. The cache is extracted (if found).
 1. `before_script` is executed.
@@ -520,7 +520,7 @@ via GitLab's UI:
 1. Navigate to your project's **CI/CD > Pipelines** page.
 1. Click on the **Clear Runner caches** button to clean up the cache.
 
-    ![Clear Runners cache](img/clear_runners_cache.png)
+   ![Clear Runners cache](img/clear_runners_cache.png)
 
 1. On the next push, your CI/CD job will use a new cache.
 
diff --git a/doc/ci/chatops/README.md b/doc/ci/chatops/README.md
index 241134783da..29d4f93f02e 100644
--- a/doc/ci/chatops/README.md
+++ b/doc/ci/chatops/README.md
@@ -4,14 +4,14 @@ type: index, concepts, howto
 
 # GitLab ChatOps
 
-> **Notes:**
->
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9.
->
-> - ChatOps is currently in alpha, with some important features missing like access control.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6.
+> - [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9.
 
 GitLab ChatOps provides a method to interact with CI/CD jobs through chat services like Slack. Many organizations' discussion, collaboration, and troubleshooting is taking place in chat services these days, and having a method to run CI/CD jobs with output posted back to the channel can significantly augment a team's workflow.
 
+NOTE: **Note:**
+ChatOps is currently in alpha with some important features missing, like access control.
+
 ## How it works
 
 GitLab ChatOps is built upon two existing features:
diff --git a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md
index bbb25c78ec5..54b21939116 100644
--- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md
+++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md
@@ -2,7 +2,7 @@
 type: howto
 ---
 
-# Using GitLab CI/CD with a Bitbucket Cloud repository **[PREMIUM]**
+# Using GitLab CI/CD with a Bitbucket Cloud repository **(PREMIUM)**
 
 GitLab CI/CD can be used with Bitbucket Cloud by:
 
@@ -14,9 +14,9 @@ To use GitLab CI/CD with a Bitbucket Cloud repository:
 1. In GitLab create a **CI/CD for external repo**, select **Repo by URL** and
    create the project.
 
-    ![Create project](img/external_repository.png)
+   ![Create project](img/external_repository.png)
 
-    GitLab will import the repository and enable [Pull Mirroring][pull-mirroring].
+   GitLab will import the repository and enable [Pull Mirroring][pull-mirroring].
 
 1. In GitLab create a
    [Personal Access Token](../../user/profile/personal_access_tokens.md)
@@ -26,127 +26,127 @@ To use GitLab CI/CD with a Bitbucket Cloud repository:
 1. In Bitbucket, from **Settings > Webhooks**, create a new web hook to notify
    GitLab of new commits.
 
-    The web hook URL should be set to the GitLab API to trigger pull mirroring,
-    using the Personal Access Token we just generated for authentication.
+   The web hook URL should be set to the GitLab API to trigger pull mirroring,
+   using the Personal Access Token we just generated for authentication.
 
-    ```text
-    https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/mirror/pull?private_token=<PERSONAL_ACCESS_TOKEN>
-    ```
+   ```text
+   https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/mirror/pull?private_token=<PERSONAL_ACCESS_TOKEN>
+   ```
 
-    The web hook Trigger should be set to 'Repository Push'.
+   The web hook Trigger should be set to 'Repository Push'.
 
-    ![Bitbucket Cloud webhook](img/bitbucket_webhook.png)
+   ![Bitbucket Cloud webhook](img/bitbucket_webhook.png)
 
-    After saving, test the web hook by pushing a change to your Bitbucket
-    repository.
+   After saving, test the web hook by pushing a change to your Bitbucket
+   repository.
 
 1. In Bitbucket, create an **App Password** from **Bitbucket Settings > App
    Passwords** to authenticate the build status script setting commit build
    statuses in Bitbucket. Repository write permissions are required.
 
-    ![Bitbucket Cloud webhook](img/bitbucket_app_password.png)
+   ![Bitbucket Cloud webhook](img/bitbucket_app_password.png)
 
 1. In GitLab, from **Settings > CI/CD > Environment variables**, add variables to allow
    communication with Bitbucket via the Bitbucket API:
 
-    `BITBUCKET_ACCESS_TOKEN`: the Bitbucket app password created above.
+   `BITBUCKET_ACCESS_TOKEN`: the Bitbucket app password created above.
 
-    `BITBUCKET_USERNAME`: the username of the Bitbucket account.
+   `BITBUCKET_USERNAME`: the username of the Bitbucket account.
 
-    `BITBUCKET_NAMESPACE`: set this if your GitLab and Bitbucket namespaces differ.
+   `BITBUCKET_NAMESPACE`: set this if your GitLab and Bitbucket namespaces differ.
 
-    `BITBUCKET_REPOSITORY`: set this if your GitLab and Bitbucket project names differ.
+   `BITBUCKET_REPOSITORY`: set this if your GitLab and Bitbucket project names differ.
 
 1. In Bitbucket, add a script to push the pipeline status to Bitbucket.
 
-    > Note: changes made in GitLab will be overwritten by any changes made
-    > upstream in Bitbucket.
-
-    Create a file `build_status` and insert the script below and run
-    `chmod +x build_status` in your terminal to make the script executable.
-
-    ```bash
-    #!/usr/bin/env bash
-
-    # Push GitLab CI/CD build status to Bitbucket Cloud
-
-    if [ -z "$BITBUCKET_ACCESS_TOKEN" ]; then
-       echo "ERROR: BITBUCKET_ACCESS_TOKEN is not set"
-    exit 1
-    fi
-    if [ -z "$BITBUCKET_USERNAME" ]; then
-        echo "ERROR: BITBUCKET_USERNAME is not set"
-    exit 1
-    fi
-    if [ -z "$BITBUCKET_NAMESPACE" ]; then
-        echo "Setting BITBUCKET_NAMESPACE to $CI_PROJECT_NAMESPACE"
-        BITBUCKET_NAMESPACE=$CI_PROJECT_NAMESPACE
-    fi
-    if [ -z "$BITBUCKET_REPOSITORY" ]; then
-        echo "Setting BITBUCKET_REPOSITORY to $CI_PROJECT_NAME"
-        BITBUCKET_REPOSITORY=$CI_PROJECT_NAME
-    fi
-
-    BITBUCKET_API_ROOT="https://api.bitbucket.org/2.0"
-    BITBUCKET_STATUS_API="$BITBUCKET_API_ROOT/repositories/$BITBUCKET_NAMESPACE/$BITBUCKET_REPOSITORY/commit/$CI_COMMIT_SHA/statuses/build"
-    BITBUCKET_KEY="ci/gitlab-ci/$CI_JOB_NAME"
-
-    case "$BUILD_STATUS" in
-    running)
-       BITBUCKET_STATE="INPROGRESS"
-       BITBUCKET_DESCRIPTION="The build is running!"
-       ;;
-    passed)
-       BITBUCKET_STATE="SUCCESSFUL"
-       BITBUCKET_DESCRIPTION="The build passed!"
-       ;;
-    failed)
-       BITBUCKET_STATE="FAILED"
-       BITBUCKET_DESCRIPTION="The build failed."
-       ;;
-    esac
-
-    echo "Pushing status to $BITBUCKET_STATUS_API..."
-    curl --request POST $BITBUCKET_STATUS_API \
-    --user $BITBUCKET_USERNAME:$BITBUCKET_ACCESS_TOKEN \
-    --header "Content-Type:application/json" \
-    --silent \
-    --data "{ \"state\": \"$BITBUCKET_STATE\", \"key\": \"$BITBUCKET_KEY\", \"description\":
-    \"$BITBUCKET_DESCRIPTION\",\"url\": \"$CI_PROJECT_URL/-/jobs/$CI_JOB_ID\" }"
-    ```
+   > Note: changes made in GitLab will be overwritten by any changes made
+   > upstream in Bitbucket.
+
+   Create a file `build_status` and insert the script below and run
+   `chmod +x build_status` in your terminal to make the script executable.
+
+   ```bash
+   #!/usr/bin/env bash
+
+   # Push GitLab CI/CD build status to Bitbucket Cloud
+
+   if [ -z "$BITBUCKET_ACCESS_TOKEN" ]; then
+      echo "ERROR: BITBUCKET_ACCESS_TOKEN is not set"
+   exit 1
+   fi
+   if [ -z "$BITBUCKET_USERNAME" ]; then
+       echo "ERROR: BITBUCKET_USERNAME is not set"
+   exit 1
+   fi
+   if [ -z "$BITBUCKET_NAMESPACE" ]; then
+       echo "Setting BITBUCKET_NAMESPACE to $CI_PROJECT_NAMESPACE"
+       BITBUCKET_NAMESPACE=$CI_PROJECT_NAMESPACE
+   fi
+   if [ -z "$BITBUCKET_REPOSITORY" ]; then
+       echo "Setting BITBUCKET_REPOSITORY to $CI_PROJECT_NAME"
+       BITBUCKET_REPOSITORY=$CI_PROJECT_NAME
+   fi
+
+   BITBUCKET_API_ROOT="https://api.bitbucket.org/2.0"
+   BITBUCKET_STATUS_API="$BITBUCKET_API_ROOT/repositories/$BITBUCKET_NAMESPACE/$BITBUCKET_REPOSITORY/commit/$CI_COMMIT_SHA/statuses/build"
+   BITBUCKET_KEY="ci/gitlab-ci/$CI_JOB_NAME"
+
+   case "$BUILD_STATUS" in
+   running)
+      BITBUCKET_STATE="INPROGRESS"
+      BITBUCKET_DESCRIPTION="The build is running!"
+      ;;
+   passed)
+      BITBUCKET_STATE="SUCCESSFUL"
+      BITBUCKET_DESCRIPTION="The build passed!"
+      ;;
+   failed)
+      BITBUCKET_STATE="FAILED"
+      BITBUCKET_DESCRIPTION="The build failed."
+      ;;
+   esac
+
+   echo "Pushing status to $BITBUCKET_STATUS_API..."
+   curl --request POST $BITBUCKET_STATUS_API \
+   --user $BITBUCKET_USERNAME:$BITBUCKET_ACCESS_TOKEN \
+   --header "Content-Type:application/json" \
+   --silent \
+   --data "{ \"state\": \"$BITBUCKET_STATE\", \"key\": \"$BITBUCKET_KEY\", \"description\":
+   \"$BITBUCKET_DESCRIPTION\",\"url\": \"$CI_PROJECT_URL/-/jobs/$CI_JOB_ID\" }"
+   ```
 
 1. Still in Bitbucket, create a `.gitlab-ci.yml` file to use the script to push
    pipeline success and failures to Bitbucket.
 
-    ```yaml
-    stages:
-      - test
-      - ci_status
-
-    unit-tests:
-      script:
-        - echo "Success. Add your tests!"
-
-    success:
-      stage: ci_status
-      before_script:
-        - ""
-      after_script:
-        - ""
-      script:
-        - BUILD_STATUS=passed BUILD_KEY=push ./build_status
-      when: on_success
-
-    failure:
-      stage: ci_status
-      before_script:
-        - ""
-      after_script:
-        - ""
-      script:
-        - BUILD_STATUS=failed BUILD_KEY=push ./build_status
-      when: on_failure
-    ```
+   ```yaml
+   stages:
+     - test
+     - ci_status
+
+   unit-tests:
+     script:
+       - echo "Success. Add your tests!"
+
+   success:
+     stage: ci_status
+     before_script:
+       - ""
+     after_script:
+       - ""
+     script:
+       - BUILD_STATUS=passed BUILD_KEY=push ./build_status
+     when: on_success
+
+   failure:
+     stage: ci_status
+     before_script:
+       - ""
+     after_script:
+       - ""
+     script:
+       - BUILD_STATUS=failed BUILD_KEY=push ./build_status
+     when: on_failure
+   ```
 
 GitLab is now configured to mirror changes from Bitbucket, run CI/CD pipelines
 configured in `.gitlab-ci.yml` and push the status to Bitbucket.
diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md
index 53b36181062..f639e3dadee 100644
--- a/doc/ci/ci_cd_for_external_repos/github_integration.md
+++ b/doc/ci/ci_cd_for_external_repos/github_integration.md
@@ -2,7 +2,7 @@
 type: howto
 ---
 
-# Using GitLab CI/CD with a GitHub repository **[PREMIUM]**
+# Using GitLab CI/CD with a GitHub repository **(PREMIUM)**
 
 GitLab CI/CD can be used with **GitHub.com** and **GitHub Enterprise** by
 creating a [CI/CD project](index.md) to connect your GitHub repository to
@@ -19,12 +19,12 @@ administrator:
 1. In GitLab create a **CI/CD for external repo** project and select
    **GitHub**.
 
-    ![Create project](img/github_omniauth.png)
+   ![Create project](img/github_omniauth.png)
 
 1. Once authenticated, you will be redirected to a list of your repositories to
    connect. Click **Connect** to select the repository.
 
-    ![Create project](img/github_repo_list.png)
+   ![Create project](img/github_repo_list.png)
 
 1. In GitHub, add a `.gitlab-ci.yml` to [configure GitLab CI/CD](../quick_start/README.md).
 
@@ -55,14 +55,14 @@ repositories:
    Token**. This token with be used to access your repository and push commit
    statuses to GitHub.
 
-    The `repo` and `admin:repo_hook` should be enable to allow GitLab access to
-    your project, update commit statuses, and create a web hook to notify
-    GitLab of new commits.
+   The `repo` and `admin:repo_hook` should be enable to allow GitLab access to
+   your project, update commit statuses, and create a web hook to notify
+   GitLab of new commits.
 
 1. In GitLab create a **CI/CD for external repo** project and select
    **GitHub**.
 
-    ![Create project](img/github_omniauth.png)
+   ![Create project](img/github_omniauth.png)
 
 1. Paste the token into the **Personal access token** field and click **List
    Repositories**. Click **Connect** to select the repository.
@@ -86,21 +86,21 @@ your repository:
    Access Token.** GitLab will use this token to access your repository and
    push commit statuses.
 
-    Enter a **Token description** and update the scope to allow:
+   Enter a **Token description** and update the scope to allow:
 
-    `repo` so that GitLab can access your project and update commit statuses
+   `repo` so that GitLab can access your project and update commit statuses
 
 1. In GitLab create a **CI/CD project** using the Git URL option and the HTTPS
    URL for your GitHub repository. If your project is private, use the personal
    access token you just created for authentication.
 
-    GitLab will automatically configure polling-based pull mirroring.
+   GitLab will automatically configure polling-based pull mirroring.
 
 1. Still in GitLab, enable the [GitHub project integration](../../user/project/integrations/github.md)
    from **Settings > Integrations.**
 
-    Check the **Active** checkbox to enable the integration, paste your
-    personal access token and HTTPS repository URL into the form, and **Save.**
+   Check the **Active** checkbox to enable the integration, paste your
+   personal access token and HTTPS repository URL into the form, and **Save.**
 
 1. Still in GitLab create a **Personal Access Token** with `API` scope to
    authenticate the GitHub web hook notifying GitLab of new commits.
@@ -108,15 +108,15 @@ your repository:
 1. In GitHub from **Settings > Webhooks** create a web hook to notify GitLab of
    new commits.
 
-    The web hook URL should be set to the GitLab API to
-    [trigger pull mirroring](https://docs.gitlab.com/ee/api/projects.html#start-the-pull-mirroring-process-for-a-project-starter),
-    using the GitLab personal access token we just created.
+   The web hook URL should be set to the GitLab API to
+   [trigger pull mirroring](../../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter),
+   using the GitLab personal access token we just created.
 
-    ```
-    https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/mirror/pull?private_token=<PERSONAL_ACCESS_TOKEN>
-    ```
+   ```
+   https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/mirror/pull?private_token=<PERSONAL_ACCESS_TOKEN>
+   ```
 
-    ![Create web hook](img/github_push_webhook.png)
+   ![Create web hook](img/github_push_webhook.png)
 
 1. In GitHub add a `.gitlab-ci.yml` to configure GitLab CI/CD.
 
diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md
index d46e451c609..02b8eb7daa7 100644
--- a/doc/ci/ci_cd_for_external_repos/index.md
+++ b/doc/ci/ci_cd_for_external_repos/index.md
@@ -2,7 +2,7 @@
 type: index, howto
 ---
 
-# GitLab CI/CD for external repositories **[PREMIUM]**
+# GitLab CI/CD for external repositories **(PREMIUM)**
 
 >[Introduced][ee-4642] in [GitLab Premium][eep] 10.6.
 
diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md
new file mode 100644
index 00000000000..e54be9f3bd9
--- /dev/null
+++ b/doc/ci/directed_acyclic_graph/index.md
@@ -0,0 +1,76 @@
+---
+type: reference
+---
+
+# Directed Acyclic Graph
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/47063) in GitLab 12.2 (enabled by `ci_dag_support` feature flag).
+
+A [directed acyclic graph](https://www.techopedia.com/definition/5739/directed-acyclic-graph-dag) can be
+used in the context of a CI/CD pipeline to build relationships between jobs such that
+execution is performed in the quickest possible manner, regardless how stages may
+be set up.
+
+For example, you may have a specific tool or separate website that is built
+as part of your main project. Using a DAG, you can specify the relationship between
+these jobs and GitLab will then execute the jobs as soon as possible instead of waiting
+for each stage to complete.
+
+Unlike other DAG solutions for CI/CD, GitLab does not require you to choose one or the
+other. You can implement a hybrid combination of DAG and traditional
+stage-based operation within a single pipeline. Configuration is kept very simple,
+requiring a single keyword to enable the feature for any job.
+
+Consider a monorepo as follows:
+
+```
+./service_a
+./service_b
+./service_c
+./service_d
+```
+
+It has a pipeline that looks like the following:
+
+| build | test | deploy |
+| ----- | ---- | ------ |
+| build_a | test_a | deploy_a |
+| build_b | test_b | deploy_b |
+| build_c | test_c | deploy_c | 
+| build_d | test_d | deploy_d |
+
+Using a DAG, you can relate the `_a` jobs to each other separately from the `_b` jobs,
+and even if service `a` takes a very long time to build, service `b` will not
+wait for it and will finish as quickly as it can. In this very same pipeline, `_c` and
+`_d` can be left alone and will run together in staged sequence just like any normal
+GitLab pipeline.
+
+## Use cases
+
+A DAG can help solve several different kinds of relationships between jobs within
+a CI/CD pipeline. Most typically this would cover when jobs need to fan in or out,
+and/or merge back together (diamond dependencies). This can happen when you're
+handling multi-platform builds or complex webs of dependencies as in something like
+an operating system build or a complex deployment graph of independently deployable
+but related microservices.
+
+Additionally, a DAG can help with general speediness of pipelines and helping
+to deliver fast feedback. By creating dependency relationships that don't unnecessarily
+block each other, your pipelines will run as quickly as possible regardless of
+pipeline stages, ensuring output (including errors) is available to developers
+as quickly as possible.
+
+## Usage
+
+Relationships are defined between jobs using the [`needs:` keyword](../yaml/README.md#needs).
+
+Note that `needs:` also works with the [parallel](../yaml/README.md#parallel) keyword,
+giving your powerful options for parallelization within your pipeline.
+
+## Limitations
+
+A directed acyclic graph is a complicated feature, and as of the initial MVC there
+are certain use cases that you may need to work around. For more information:
+
+- [`needs` requirements and limitations](../yaml/README.md#requirements-and-limitations).
+- Related epic [gitlab-org#1716](https://gitlab.com/groups/gitlab-org/-/epics/1716).
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md
index b4c4bea6447..2cbad5f101c 100644
--- a/doc/ci/docker/using_docker_build.md
+++ b/doc/ci/docker/using_docker_build.md
@@ -6,7 +6,6 @@ type: concepts, howto
 
 GitLab CI/CD allows you to use Docker Engine to build and test docker-based projects.
 
-
 One of the new trends in Continuous Integration/Deployment is to:
 
 1. Create an application image.
@@ -29,7 +28,16 @@ during jobs.
 
 ## Runner Configuration
 
-There are three methods to enable the use of `docker build` and `docker run` during jobs; each with their own tradeoffs.
+There are three methods to enable the use of `docker build` and `docker run`
+during jobs; each with their own tradeoffs.
+
+An alternative to using `docker build` is to [use kaniko](using_kaniko.md).
+This avoids having to execute Runner in privileged mode.
+
+TIP: **Tip:**
+To see how Docker and Runner are configured for shared Runners on
+GitLab.com, see [GitLab.com Shared
+Runners](../../user/gitlab_com/index.md#shared-runners).
 
 ### Use shell executor
 
@@ -40,42 +48,42 @@ GitLab Runner then executes job scripts as the `gitlab-runner` user.
 
 1. During GitLab Runner installation select `shell` as method of executing job scripts or use command:
 
-    ```bash
-    sudo gitlab-runner register -n \
-      --url https://gitlab.com/ \
-      --registration-token REGISTRATION_TOKEN \
-      --executor shell \
-      --description "My Runner"
-    ```
+   ```bash
+   sudo gitlab-runner register -n \
+     --url https://gitlab.com/ \
+     --registration-token REGISTRATION_TOKEN \
+     --executor shell \
+     --description "My Runner"
+   ```
 
 1. Install Docker Engine on server.
 
-    For more information how to install Docker Engine on different systems
-    checkout the [Supported installations](https://docs.docker.com/engine/installation/).
+   For more information how to install Docker Engine on different systems
+   checkout the [Supported installations](https://docs.docker.com/engine/installation/).
 
 1. Add `gitlab-runner` user to `docker` group:
 
-    ```bash
-    sudo usermod -aG docker gitlab-runner
-    ```
+   ```bash
+   sudo usermod -aG docker gitlab-runner
+   ```
 
 1. Verify that `gitlab-runner` has access to Docker:
 
-    ```bash
-    sudo -u gitlab-runner -H docker info
-    ```
+   ```bash
+   sudo -u gitlab-runner -H docker info
+   ```
 
-    You can now verify that everything works by adding `docker info` to `.gitlab-ci.yml`:
+   You can now verify that everything works by adding `docker info` to `.gitlab-ci.yml`:
 
-    ```yaml
-    before_script:
-      - docker info
+   ```yaml
+   before_script:
+     - docker info
 
-    build_image:
-      script:
-        - docker build -t my-docker-image .
-        - docker run my-docker-image /script/to/run/tests
-    ```
+   build_image:
+     script:
+       - docker build -t my-docker-image .
+       - docker run my-docker-image /script/to/run/tests
+   ```
 
 1. You can now use `docker` command (and **install** `docker-compose` if needed).
 
@@ -83,101 +91,28 @@ NOTE: **Note:**
 By adding `gitlab-runner` to the `docker` group you are effectively granting `gitlab-runner` full root permissions.
 For more information please read [On Docker security: `docker` group considered harmful](https://www.andreas-jung.com/contents/on-docker-security-docker-group-considered-harmful).
 
-### Use docker-in-docker executor
+### Use docker-in-docker workflow with Docker executor
 
 The second approach is to use the special docker-in-docker (dind)
 [Docker image](https://hub.docker.com/_/docker/) with all tools installed
 (`docker`) and run the job script in context of that
-image in privileged mode. 
-
-NOTE: **Note:** `docker-compose` is not part of docker-in-docker (dind). In case you'd like to use `docker-compose` in your CI builds, please follow the [installation instructions for docker-compose](https://docs.docker.com/compose/install/) provided by docker. 
-
-In order to do that, follow the steps:
-
-1. Install [GitLab Runner](https://docs.gitlab.com/runner/install).
-
-1. Register GitLab Runner from the command line to use `docker` and `privileged`
-   mode:
-
-    ```bash
-    sudo gitlab-runner register -n \
-      --url https://gitlab.com/ \
-      --registration-token REGISTRATION_TOKEN \
-      --executor docker \
-      --description "My Docker Runner" \
-      --docker-image "docker:stable" \
-      --docker-privileged
-    ```
-
-    The above command will register a new Runner to use the special
-    `docker:stable` image which is provided by Docker. **Notice that it's using
-    the `privileged` mode to start the build and service containers.** If you
-    want to use [docker-in-docker] mode, you always have to use `privileged = true`
-    in your Docker containers.
-
-    The above command will create a `config.toml` entry similar to this:
-
-    ```toml
-    [[runners]]
-      url = "https://gitlab.com/"
-      token = TOKEN
-      executor = "docker"
-      [runners.docker]
-        tls_verify = false
-        image = "docker:stable"
-        privileged = true
-        disable_cache = false
-        volumes = ["/cache"]
-      [runners.cache]
-        Insecure = false
-    ```
-
-1. You can now use `docker` in the build script (note the inclusion of the
-   `docker:dind` service):
+image in privileged mode.
 
-    ```yaml
-    image: docker:stable
+NOTE: **Note:**
+`docker-compose` is not part of docker-in-docker (dind). To use `docker-compose` in your
+CI builds, follow the `docker-compose`
+[installation instructions](https://docs.docker.com/compose/install/).
 
-    variables:
-      # When using dind service we need to instruct docker, to talk with the
-      # daemon started inside of the service. The daemon is available with
-      # a network connection instead of the default /var/run/docker.sock socket.
-      #
-      # The 'docker' hostname is the alias of the service container as described at
-      # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services
-      #
-      # Note that if you're using the Kubernetes executor, the variable should be set to
-      # tcp://localhost:2375/ because of how the Kubernetes executor connects services
-      # to the job container
-      # DOCKER_HOST: tcp://localhost:2375/
-      #
-      # For non-Kubernetes executors, we use tcp://docker:2375/
-      DOCKER_HOST: tcp://docker:2375/
-      # When using dind, it's wise to use the overlayfs driver for
-      # improved performance.
-      DOCKER_DRIVER: overlay2
-
-    services:
-      - docker:dind
-
-    before_script:
-      - docker info
-
-    build:
-      stage: build
-      script:
-        - docker build -t my-docker-image .
-        - docker run my-docker-image /script/to/run/tests
-    ```
+DANGER: **Danger:**
+By enabling `--docker-privileged`, you are effectively disabling all of
+the security mechanisms of containers and exposing your host to privilege
+escalation which can lead to container breakout. For more information, check
+out the official Docker documentation on
+[Runtime privilege and Linux capabilities][docker-cap].
 
 Docker-in-Docker works well, and is the recommended configuration, but it is
 not without its own challenges:
 
-- By enabling `--docker-privileged`, you are effectively disabling all of
-  the security mechanisms of containers and exposing your host to privilege
-  escalation which can lead to container breakout. For more information, check
-  out the official Docker documentation on
-  [Runtime privilege and Linux capabilities][docker-cap].
 - When using docker-in-docker, each job is in a clean environment without the past
   history. Concurrent jobs work fine because every build gets it's own
   instance of Docker engine so they won't conflict with each other. But this
@@ -187,7 +122,7 @@ not without its own challenges:
   [Using the overlayfs driver](#using-the-overlayfs-driver).
 - Since the `docker:dind` container and the runner container don't share their
   root filesystem, the job's working directory can be used as a mount point for
-  children containers. For example, if you have files you want to share with a
+  child containers. For example, if you have files you want to share with a
   child container, you may create a subdirectory under `/builds/$CI_PROJECT_PATH`
   and use it as your mount point (for a more thorough explanation, check [issue
   #41227](https://gitlab.com/gitlab-org/gitlab-ce/issues/41227)):
@@ -203,9 +138,187 @@ not without its own challenges:
 
 An example project using this approach can be found here: <https://gitlab.com/gitlab-examples/docker>.
 
+In the examples below, we are using Docker images tags to specify a
+specific version, such as `docker:19.03.1`. If tags like `docker:stable`
+are used, you have no control over what version is going to be used and this
+can lead to unpredictable behavior, especially when new versions are
+released.
+
+#### TLS enabled
+
+NOTE: **Note**
+This requires GitLab Runner 11.11 or higher.
+
+The Docker daemon supports connection over TLS and it's done by default
+for Docker 19.03.1 or higher. This is the **suggested** way to use the
+docker-in-docker service and
+[GitLab.com Shared Runners](../../user/gitlab_com/index.html#shared-runners)
+support this.
+
+1. Install [GitLab Runner](https://docs.gitlab.com/runner/install).
+
+1. Register GitLab Runner from the command line to use `docker` and `privileged`
+   mode:
+
+   ```bash
+   sudo gitlab-runner register -n \
+     --url https://gitlab.com/ \
+     --registration-token REGISTRATION_TOKEN \
+     --executor docker \
+     --description "My Docker Runner" \
+     --docker-image "docker:19.03.1" \
+     --docker-privileged \
+     --docker-volumes "/certs/client"
+   ```
+
+   The above command will register a new Runner to use the special
+   `docker:19.03.1` image, which is provided by Docker. **Notice that it's
+   using the `privileged` mode to start the build and service
+   containers.** If you want to use [docker-in-docker] mode, you always
+   have to use `privileged = true` in your Docker containers.
+
+   This will also mount `/certs/client` for the service and build
+   container, which is needed for the docker client to use the
+   certificates inside of that directory. For more information how
+   Docker with TLS works check <https://hub.docker.com/_/docker/#tls>.
+
+   The above command will create a `config.toml` entry similar to this:
+
+   ```toml
+   [[runners]]
+     url = "https://gitlab.com/"
+     token = TOKEN
+     executor = "docker"
+     [runners.docker]
+       tls_verify = false
+       image = "docker:19.03.1"
+       privileged = true
+       disable_cache = false
+       volumes = ["/certs/client", "/cache"]
+     [runners.cache]
+       [runners.cache.s3]
+       [runners.cache.gcs]
+    ```
+
+1. You can now use `docker` in the build script (note the inclusion of the
+   `docker:19.03.1-dind` service):
+
+   ```yaml
+   image: docker:19.03.1
+
+   variables:
+     # When using dind service, we need to instruct docker, to talk with
+     # the daemon started inside of the service. The daemon is available
+     # with a network connection instead of the default
+     # /var/run/docker.sock socket. docker:19.03.1 does this automatically
+     # by setting the DOCKER_HOST in
+     # https://github.com/docker-library/docker/blob/d45051476babc297257df490d22cbd806f1b11e4/19.03.1/docker-entrypoint.sh#L23-L29
+     #
+     # The 'docker' hostname is the alias of the service container as described at
+     # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services.
+     #
+     # Note that if you're using the Kubernetes executor, the variable
+     # should be set to tcp://localhost:2376/ because of how the
+     # Kubernetes executor connects services to the job container
+     # DOCKER_HOST: tcp://localhost:2376/
+     #
+     # When using dind, it's wise to use the overlayfs driver for
+     # improved performance.
+     DOCKER_DRIVER: overlay2
+     # Specify to Docker where to create the certificates, Docker will
+     # create them automatically on boot, and will create
+     # `/certs/client` that will be shared between the service and job
+     # container, thanks to volume mount from config.toml
+     DOCKER_TLS_CERTDIR: "/certs"
+
+   services:
+     - docker:19.03.1-dind
+
+   before_script:
+     - docker info
+
+   build:
+     stage: build
+     script:
+       - docker build -t my-docker-image .
+       - docker run my-docker-image /script/to/run/tests
+   ```
+
+#### TLS disabled
+
+Sometimes there are legitimate reasons why you might want to disable TLS.
+For example, you have no control over the GitLab Runner configuration
+that you are using.
+
+Assuming that the Runner `config.toml` is similar to:
+
+```toml
+[[runners]]
+  url = "https://gitlab.com/"
+  token = TOKEN
+  executor = "docker"
+  [runners.docker]
+    tls_verify = false
+    image = "docker:19.03.1"
+    privileged = true
+    disable_cache = false
+    volumes = ["/cache"]
+  [runners.cache]
+    [runners.cache.s3]
+    [runners.cache.gcs]
+```
+
+You can now use `docker` in the build script (note the inclusion of the
+`docker:19.03.1-dind` service):
+
+```yaml
+image: docker:19.03.1
+
+variables:
+  # When using dind service we need to instruct docker, to talk with the
+  # daemon started inside of the service. The daemon is available with
+  # a network connection instead of the default /var/run/docker.sock socket.
+  #
+  # The 'docker' hostname is the alias of the service container as described at
+  # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services
+  #
+  # Note that if you're using the Kubernetes executor, the variable should be set to
+  # tcp://localhost:2375/ because of how the Kubernetes executor connects services
+  # to the job container
+  # DOCKER_HOST: tcp://localhost:2375/
+  #
+  # For non-Kubernetes executors, we use tcp://docker:2375/
+  DOCKER_HOST: tcp://docker:2375/
+  # When using dind, it's wise to use the overlayfs driver for
+  # improved performance.
+  DOCKER_DRIVER: overlay2
+  #
+  # This will instruct Docker not to start over TLS.
+  DOCKER_TLS_CERTDIR: ""
+
+services:
+  - docker:19.03.1-dind
+
+before_script:
+  - docker info
+
+build:
+  stage: build
+  script:
+    - docker build -t my-docker-image .
+    - docker run my-docker-image /script/to/run/tests
+```
+
 ### Use Docker socket binding
 
-The third approach is to bind-mount `/var/run/docker.sock` into the container so that docker is available in the context of that image.
+The third approach is to bind-mount `/var/run/docker.sock` into the
+container so that Docker is available in the context of that image.
+
+NOTE: **Note:**
+If you bind the Docker socket [when using GitLab Runner 11.11 or
+newer](https://gitlab.com/gitlab-org/gitlab-runner/merge_requests/1261),
+you can no longer use `docker:dind` as a service because volume bindings
+are done to the services as well, making these incompatible.
 
 In order to do that, follow the steps:
 
@@ -213,54 +326,54 @@ In order to do that, follow the steps:
 
 1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`:
 
-    ```bash
-    sudo gitlab-runner register -n \
-      --url https://gitlab.com/ \
-      --registration-token REGISTRATION_TOKEN \
-      --executor docker \
-      --description "My Docker Runner" \
-      --docker-image "docker:stable" \
-      --docker-volumes /var/run/docker.sock:/var/run/docker.sock
-    ```
-
-    The above command will register a new Runner to use the special
-    `docker:stable` image which is provided by Docker. **Notice that it's using
-    the Docker daemon of the Runner itself, and any containers spawned by docker
-    commands will be siblings of the Runner rather than children of the runner.**
-    This may have complications and limitations that are unsuitable for your workflow.
-
-    The above command will create a `config.toml` entry similar to this:
-
-    ```toml
-    [[runners]]
-      url = "https://gitlab.com/"
-      token = REGISTRATION_TOKEN
-      executor = "docker"
-      [runners.docker]
-        tls_verify = false
-        image = "docker:stable"
-        privileged = false
-        disable_cache = false
-        volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
-      [runners.cache]
-        Insecure = false
-    ```
+   ```bash
+   sudo gitlab-runner register -n \
+     --url https://gitlab.com/ \
+     --registration-token REGISTRATION_TOKEN \
+     --executor docker \
+     --description "My Docker Runner" \
+     --docker-image "docker:stable" \
+     --docker-volumes /var/run/docker.sock:/var/run/docker.sock
+   ```
+
+   The above command will register a new Runner to use the special
+   `docker:stable` image which is provided by Docker. **Notice that it's using
+   the Docker daemon of the Runner itself, and any containers spawned by docker
+   commands will be siblings of the Runner rather than children of the runner.**
+   This may have complications and limitations that are unsuitable for your workflow.
+
+   The above command will create a `config.toml` entry similar to this:
+
+   ```toml
+   [[runners]]
+     url = "https://gitlab.com/"
+     token = REGISTRATION_TOKEN
+     executor = "docker"
+     [runners.docker]
+       tls_verify = false
+       image = "docker:stable"
+       privileged = false
+       disable_cache = false
+       volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
+     [runners.cache]
+       Insecure = false
+   ```
 
 1. You can now use `docker` in the build script (note that you don't need to
    include the `docker:dind` service as when using the Docker in Docker executor):
 
-    ```yaml
-    image: docker:stable
+   ```yaml
+   image: docker:stable
 
-    before_script:
-      - docker info
+   before_script:
+     - docker info
 
-    build:
-      stage: build
-      script:
-        - docker build -t my-docker-image .
-        - docker run my-docker-image /script/to/run/tests
-    ```
+   build:
+     stage: build
+     script:
+       - docker build -t my-docker-image .
+       - docker run my-docker-image /script/to/run/tests
+   ```
 
 While the above method avoids using Docker in privileged mode, you should be
 aware of the following implications:
@@ -276,9 +389,9 @@ aware of the following implications:
   work as expected since volume mounting is done in the context of the host
   machine, not the build container. For example:
 
-    ```sh
-    docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests
-    ```
+   ```sh
+   docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests
+   ```
 
 ## Making docker-in-docker builds faster with Docker layer caching
 
@@ -349,23 +462,23 @@ which can be avoided if a different driver is used, for example `overlay2`.
 1. Make sure a recent kernel is used, preferably `>= 4.2`.
 1. Check whether the `overlay` module is loaded:
 
-    ```sh
-    sudo lsmod | grep overlay
-    ```
+   ```sh
+   sudo lsmod | grep overlay
+   ```
 
-    If you see no result, then it isn't loaded. To load it use:
+   If you see no result, then it isn't loaded. To load it use:
 
-    ```sh
-    sudo modprobe overlay
-    ```
+   ```sh
+   sudo modprobe overlay
+   ```
 
-    If everything went fine, you need to make sure module is loaded on reboot.
-    On Ubuntu systems, this is done by editing `/etc/modules`. Just add the
-    following line into it:
+   If everything went fine, you need to make sure module is loaded on reboot.
+   On Ubuntu systems, this is done by editing `/etc/modules`. Just add the
+   following line into it:
 
-    ```text
-    overlay
-    ```
+   ```text
+   overlay
+   ```
 
 ### Use driver per project
 
@@ -433,9 +546,9 @@ For all projects, mostly suitable for public ones:
   your Docker images and has read/write access to the Registry. This is ephemeral,
   so it's only valid for one job. You can use the following example as-is:
 
-    ```sh
-    docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
-    ```
+  ```sh
+  docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
+  ```
 
 For private and internal projects:
 
@@ -448,9 +561,9 @@ For private and internal projects:
 
   Replace the `<username>` and `<access_token>` in the following example:
 
-    ```sh
-    docker login -u <username> -p <access_token> $CI_REGISTRY
-    ```
+  ```sh
+  docker login -u <username> -p <access_token> $CI_REGISTRY
+  ```
 
 - **Using the GitLab Deploy Token**: You can create and use a
   [special deploy token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token)
@@ -458,9 +571,9 @@ For private and internal projects:
   Once created, you can use the special environment variables, and GitLab CI/CD
   will fill them in for you. You can use the following example as-is:
 
-    ```sh
-    docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
-    ```
+  ```sh
+  docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
+  ```
 
 ### Container Registry examples
 
diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md
index 29578efacbb..489791141ed 100644
--- a/doc/ci/docker/using_docker_images.md
+++ b/doc/ci/docker/using_docker_images.md
@@ -35,8 +35,8 @@ sudo gitlab-runner register \
   --description "docker-ruby-2.1" \
   --executor "docker" \
   --docker-image ruby:2.1 \
-  --docker-postgres latest \
-  --docker-mysql latest
+  --docker-services postgres:latest \
+  --docker-services mysql:latest
 ```
 
 The registered runner will use the `ruby:2.1` Docker image and will run two
@@ -193,13 +193,14 @@ You can simply define an image that will be used for all jobs and a list of
 services that you want to use during build time:
 
 ```yaml
-image: ruby:2.2
+default:
+  image: ruby:2.2
 
-services:
-  - postgres:9.3
+  services:
+    - postgres:9.3
 
-before_script:
-  - bundle install
+  before_script:
+    - bundle install
 
 test:
   script:
@@ -209,8 +210,9 @@ test:
 It is also possible to define different images and services per job:
 
 ```yaml
-before_script:
-  - bundle install
+default:
+  before_script:
+    - bundle install
 
 test:2.1:
   image: ruby:2.1
@@ -231,16 +233,53 @@ Or you can pass some [extended configuration options](#extended-docker-configura
 for `image` and `services`:
 
 ```yaml
+default:
+  image:
+    name: ruby:2.2
+    entrypoint: ["/bin/bash"]
+
+  services:
+  - name: my-postgres:9.4
+    alias: db-postgres
+    entrypoint: ["/usr/local/bin/db-postgres"]
+    command: ["start"]
+
+  before_script:
+  - bundle install
+
+test:
+  script:
+  - bundle exec rake spec
+```
+
+## Passing environment variables to services
+
+You can also pass custom environment [variables](../variables/README.md)
+to fine tune your Docker `images` and `services` directly in the `.gitlab-ci.yml` file.
+For more information, see [custom environment variables](../variables/README.md#gitlab-ciyml-defined-variables)
+
+```yaml
+# The following variables will automatically be passed down to the Postgres container
+# as well as the Ruby container and available within each.
+variables:
+  HTTPS_PROXY: "https://10.1.1.1:8090"
+  HTTP_PROXY: "https://10.1.1.1:8090"
+  POSTGRES_DB: "my_custom_db"
+  POSTGRES_USER: "postgres"
+  POSTGRES_PASSWORD: "example"
+  PGDATA: "/var/lib/postgresql/data"
+  POSTGRES_INITDB_ARGS: "--encoding=UTF8 --data-checksums"
+
+services:
+- name: postgres:9.4
+  alias: db
+  entrypoint: ["docker-entrypoint.sh"]
+  command: ["postgres"]
+
 image:
   name: ruby:2.2
   entrypoint: ["/bin/bash"]
 
-services:
-- name: my-postgres:9.4
-  alias: db-postgres
-  entrypoint: ["/usr/local/bin/db-postgres"]
-  command: ["start"]
-
 before_script:
 - bundle install
 
@@ -266,25 +305,25 @@ For example, the following two definitions are equal:
 
 1. Using a string as an option to `image` and `services`:
 
-    ```yaml
-    image: "registry.example.com/my/image:latest"
+   ```yaml
+   image: "registry.example.com/my/image:latest"
 
-    services:
-    - postgresql:9.4
-    - redis:latest
-    ```
+   services:
+   - postgresql:9.4
+   - redis:latest
+   ```
 
 1. Using a map as an option to `image` and `services`. The use of `image:name` is
    required:
 
-    ```yaml
-    image:
-      name: "registry.example.com/my/image:latest"
+   ```yaml
+   image:
+     name: "registry.example.com/my/image:latest"
 
-    services:
-    - name: postgresql:9.4
-    - name: redis:latest
-    ```
+   services:
+   - name: postgresql:9.4
+   - name: redis:latest
+   ```
 
 ### Available settings for `image`
 
@@ -456,16 +495,6 @@ that runner.
 
 ## Define an image from a private Container Registry
 
-> **Notes:**
->
-> - This feature requires GitLab Runner **1.8** or higher
-> - For GitLab Runner versions **>= 0.6, <1.8** there was a partial
->   support for using private registries, which required manual configuration
->   of credentials on runner's host. We recommend to upgrade your Runner to
->   at least version **1.8** if you want to use private registries.
-> - If the repository is private you need to authenticate your GitLab Runner in the
->   registry. Learn more about how [GitLab Runner works in this case][runner-priv-reg].
-
 To access private container registries, the GitLab Runner process can use:
 
 - [Statically defined credentials](#using-statically-defined-credentials). That is, a username and password for a specific registry.
@@ -478,17 +507,43 @@ To define which should be used, the GitLab Runner process reads the configuratio
   - A [variable](../variables/README.md#gitlab-cicd-environment-variables) in `.gitlab-ci.yml`.
   - A project's variables stored on the projects **Settings > CI/CD** page.
 - `DOCKER_AUTH_CONFIG` variable provided as environment variable in `config.toml` of the Runner.
-- `config.json` file placed in `$HOME/docker` directory of the user running GitLab Runner process.
+- `config.json` file placed in `$HOME/.docker` directory of the user running GitLab Runner process.
   If the `--user` flag is provided to run the GitLab Runner child processes as unprivileged user,
   the home directory of the main GitLab Runner process user will be used.
 
-NOTE: **Note:** 
-GitLab Runner reads this configuration **only** from `config.toml` and ignores it if 
+NOTE: **Note:**
+GitLab Runner reads this configuration **only** from `config.toml` and ignores it if
 it's provided as an environment variable. This is because GitLab Runnner uses **only**
 `config.toml` configuration and doesn't interpolate **ANY** environment variables at
 runtime.
 
+### Requirements and limitations
+
+- This feature requires GitLab Runner **1.8** or higher.
+- For GitLab Runner versions **>= 0.6, <1.8** there was a partial
+  support for using private registries, which required manual configuration
+  of credentials on runner's host. We recommend to upgrade your Runner to
+  at least version **1.8** if you want to use private registries.
+- Not available for [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html),
+  follow <https://gitlab.com/gitlab-org/gitlab-runner/issues/2673> for
+  details.
+
 ### Using statically-defined credentials
+
+There are two approaches that you can take in order to access a
+private registry. Both require setting the environment variable
+`DOCKER_AUTH_CONFIG` with appropriate authentication info.
+
+1. Per-job: To configure one job to access a private registry, add
+   `DOCKER_AUTH_CONFIG` as a job variable.
+1. Per-runner: To configure a Runner so all its jobs can access a
+   private registry, add `DOCKER_AUTH_CONFIG` to the environment in the
+   Runner's configuration.
+
+See below for examples of each.
+
+#### Determining your `DOCKER_AUTH_CONFIG` data
+
 As an example, let's assume that you want to use the `registry.example.com:5000/private/image:latest`
 image which is private and requires you to login into a private container registry.
 
@@ -500,61 +555,64 @@ Let's also assume that these are the login credentials:
 | username | `my_username`               |
 | password | `my_password`               |
 
-To configure access for `registry.example.com:5000`, follow these steps:
+There are two ways to determine the value of `DOCKER_AUTH_CONFIG`:
 
-1. Find what the value of `DOCKER_AUTH_CONFIG` should be. There are two ways to
-   accomplish this:
-   - **First way -** Do a `docker login` on your local machine:
+- **First way -** Do a `docker login` on your local machine:
 
-        ```bash
-        docker login registry.example.com:5000 --username my_username --password my_password
-        ```
+  ```bash
+  docker login registry.example.com:5000 --username my_username --password my_password
+  ```
 
-        Then copy the content of `~/.docker/config.json`.
-   - **Second way -** In some setups, it's possible that Docker client will use
-       the available system keystore to store the result of `docker login`. In
-       that case, it's impossible to read `~/.docker/config.json`, so you will
-       need to prepare the required base64-encoded version of
-       `${username}:${password}` manually. Open a terminal and execute the
-       following command:
+  Then copy the content of `~/.docker/config.json`.
 
-        ```bash
-        echo -n "my_username:my_password" | base64
+  If you don't need access to the registry from your computer, you
+  can do a `docker logout`:
 
-        # Example output to copy
-        bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=
-        ```
+  ```bash
+  docker logout registry.example.com:5000
+  ```
 
-1. Create a [variable](../variables/README.md#gitlab-cicd-environment-variables) `DOCKER_AUTH_CONFIG` with the content of the
-   Docker configuration file as the value:
+- **Second way -** In some setups, it's possible that Docker client
+  will use the available system keystore to store the result of `docker
+  login`. In that case, it's impossible to read `~/.docker/config.json`,
+  so you will need to prepare the required base64-encoded version of
+  `${username}:${password}` manually. Open a terminal and execute the
+  following command:
+
+  ```bash
+  echo -n "my_username:my_password" | base64
 
-    ```json
-    {
-        "auths": {
-            "registry.example.com:5000": {
-                "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ="
-            }
-        }
-    }
-    ```
+  # Example output to copy
+  bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=
+  ```
 
-1. Optionally,if you followed the first way of finding the `DOCKER_AUTH_CONFIG`
-   value, do a `docker logout` on your computer if you don't need access to the
-   registry from it:
+#### Configuring a job
 
-    ```bash
-    docker logout registry.example.com:5000
-    ```
+To configure a single job with access for `registry.example.com:5000`,
+follow these steps:
+
+1. Create a [variable](../variables/README.md#gitlab-cicd-environment-variables) `DOCKER_AUTH_CONFIG` with the content of the
+   Docker configuration file as the value:
+
+   ```json
+   {
+       "auths": {
+           "registry.example.com:5000": {
+               "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ="
+           }
+       }
+   }
+   ```
 
 1. You can now use any private image from `registry.example.com:5000` defined in
    `image` and/or `services` in your `.gitlab-ci.yml` file:
 
-    ```yaml
-    image: registry.example.com:5000/namespace/image:tag
-    ```
+   ```yaml
+   image: registry.example.com:5000/namespace/image:tag
+   ```
 
-    In the example above, GitLab Runner will look at `registry.example.com:5000` for the
-    image `namespace/image:tag`.
+   In the example above, GitLab Runner will look at `registry.example.com:5000` for the
+   image `namespace/image:tag`.
 
 You can add configuration for as many registries as you want, adding more
 registries to the `"auths"` hash as described above.
@@ -566,6 +624,37 @@ for the Runner to match the `DOCKER_AUTH_CONFIG`. For example, if
 then the `DOCKER_AUTH_CONFIG` must also specify `registry.example.com:5000`.
 Specifying only `registry.example.com` will not work.
 
+### Configuring a Runner
+
+If you have many pipelines that access the same registry, it'll
+probably be better to setup registry access at the runner level.  This
+allows pipeline authors to have access to a private registry just by
+running a job on the appropriate runner. It also makes registry
+changes and credential rotations much simpler.
+
+Of course this means that any job on that runner can access the
+registry with the same privilege, even across projects. If you need to
+control access to the registry, you'll need to be sure to control
+access to the runner.
+
+To add `DOCKER_AUTH_CONFIG` to a Runner:
+
+1. Modify the Runner's `config.toml` file as follows:
+
+   ```toml
+   [[runners]]
+     environment = ["DOCKER_AUTH_CONFIG={\"auths\":{\"registry.example.com:5000\":{\"auth\":\"bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=\"}}}"]
+   ```
+
+1. Restart the Runner service.
+
+NOTE: **Note:** The double quotes included in the `DOCKER_AUTH_CONFIG`
+data must be escaped with backslashes. This prevents them from being
+interpreted as TOML.
+
+NOTE: **Note:** The `environment` option is a list. So your Runner may
+have existing entries and you should add this to the list, not replace
+it.
 
 ### Using Credentials Store
 
@@ -574,19 +663,20 @@ Specifying only `registry.example.com` will not work.
 To configure credentials store, follow these steps:
 
 1. To use a credentials store, you need an external helper program to interact with a specific keychain or external store.
-Make sure helper program is available in GitLab Runner `$PATH`.
+   Make sure helper program is available in GitLab Runner `$PATH`.
 
 1. Make GitLab Runner use it. There are two ways to accomplish this. Either:
-   - Create a 
+
+   - Create a
      [variable](../variables/README.md#gitlab-cicd-environment-variables)
      `DOCKER_AUTH_CONFIG` with the content of the
-   Docker configuration file as the value:
+     Docker configuration file as the value:
 
-    ```json
-      {
-        "credsStore": "osxkeychain"
-      }
-    ```
+     ```json
+       {
+         "credsStore": "osxkeychain"
+       }
+     ```
 
    - Or, if you are running self-hosted Runners, add the above JSON to
      `${GITLAB_RUNNER_HOME}/.docker/config.json`. GitLab Runner will read this config file
@@ -608,17 +698,18 @@ To configure access for `aws_account_id.dkr.ecr.region.amazonaws.com`, follow th
 1. Make sure `docker-credential-ecr-login` is available in GitLab Runner's `$PATH`.
 
 1. Make GitLab Runner use it. There are two ways to accomplish this. Either:
+
    - Create a [variable](../variables/README.md#gitlab-cicd-environment-variables)
      `DOCKER_AUTH_CONFIG` with the content of the
-   Docker configuration file as the value:
+     Docker configuration file as the value:
 
-    ```json
-    {
-      "credHelpers": {
-        "aws_account_id.dkr.ecr.region.amazonaws.com": "ecr-login"
-      }
-    }
-    ```
+     ```json
+     {
+       "credHelpers": {
+         "aws_account_id.dkr.ecr.region.amazonaws.com": "ecr-login"
+       }
+     }
+     ```
 
    - Or, if you are running self-hosted Runners,
      add the above JSON to `${GITLAB_RUNNER_HOME}/.docker/config.json`.
@@ -628,12 +719,12 @@ To configure access for `aws_account_id.dkr.ecr.region.amazonaws.com`, follow th
 1. You can now use any private image from `aws_account_id.dkr.ecr.region.amazonaws.com` defined in
    `image` and/or `services` in your `.gitlab-ci.yml` file:
 
-    ```yaml
-    image: aws_account_id.dkr.ecr.region.amazonaws.com/private/image:latest
-    ```
+   ```yaml
+   image: aws_account_id.dkr.ecr.region.amazonaws.com/private/image:latest
+   ```
 
-    In the example above, GitLab Runner will look at `aws_account_id.dkr.ecr.region.amazonaws.com` for the
-    image `private/image:latest`.
+   In the example above, GitLab Runner will look at `aws_account_id.dkr.ecr.region.amazonaws.com` for the
+   image `private/image:latest`.
 
 You can add configuration for as many registries as you want, adding more
 registries to the `"credHelpers"` hash as described above.
@@ -741,7 +832,6 @@ creation.
 [tutum/wordpress]: https://hub.docker.com/r/tutum/wordpress/
 [postgres-hub]: https://hub.docker.com/r/_/postgres/
 [mysql-hub]: https://hub.docker.com/r/_/mysql/
-[runner-priv-reg]: http://docs.gitlab.com/runner/configuration/advanced-configuration.html#using-a-private-container-registry
 [entrypoint]: https://docs.docker.com/engine/reference/builder/#entrypoint
 [cmd]: https://docs.docker.com/engine/reference/builder/#cmd
 [register]: https://docs.gitlab.com/runner/register/
diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md
index 50f1ac3d54a..925653f9fdf 100644
--- a/doc/ci/docker/using_kaniko.md
+++ b/doc/ci/docker/using_kaniko.md
@@ -11,7 +11,8 @@ Requires GitLab Runner 11.2 and above.
 container images from a Dockerfile, inside a container or Kubernetes cluster.
 
 kaniko solves two problems with using the
-[docker-in-docker build](using_docker_build.md#use-docker-in-docker-executor) method:
+[docker-in-docker
+build](using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor) method:
 
 - Docker-in-docker requires [privileged mode](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)
   in order to function, which is a significant security concern.
diff --git a/doc/ci/environments.md b/doc/ci/environments.md
index a32dbc11a33..f6c47a99712 100644
--- a/doc/ci/environments.md
+++ b/doc/ci/environments.md
@@ -591,15 +591,13 @@ exist, you should see something like:
 
 ### Monitoring environments
 
-> **Notes:**
->
-> - For the monitoring dashboard to appear, you need to:
->   - Enable the [Prometheus integration](../user/project/integrations/prometheus.md).
->   - Configure Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/index.md).
-> - With GitLab 9.2, all deployments to an environment are shown directly on the monitoring dashboard.
-
 If you have enabled [Prometheus for monitoring system and response metrics](../user/project/integrations/prometheus.md),
-you can monitor the behavior of your app running in each environment.
+you can monitor the behavior of your app running in each environment. For the monitoring
+dashboard to appear, you need to Configure Prometheus to collect at least one
+[supported metric](../user/project/integrations/prometheus_library/index.md).
+
+NOTE: **Note:**
+Since GitLab 9.2, all deployments to an environment are shown directly on the monitoring dashboard.
 
 Once configured, GitLab will attempt to retrieve [supported performance metrics](../user/project/integrations/prometheus_library/index.md)
 for any environment that has had a successful deployment. If monitoring data was
@@ -621,6 +619,10 @@ versions of the app, all without leaving GitLab.
 
 Add a [button to the Monitoring dashboard](../user/project/operations/linking_to_an_external_dashboard.md) linking directly to your existing external dashboards.
 
+#### Embedding metrics in GitLab Flavored Markdown
+
+Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab Flavored Markdown](../user/project/integrations/prometheus.md#embedding-metric-charts-within-gitlab-flavored-markdown) for more details.
+
 ### Web terminals
 
 > Web terminals were added in GitLab 8.15 and are only available to project Maintainers and Owners.
@@ -673,7 +675,7 @@ fetch line:
 fetch = +refs/environments/*:refs/remotes/origin/environments/*
 ```
 
-### Scoping environments with specs **[PREMIUM]**
+### Scoping environments with specs **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2112) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.4.
 
@@ -692,7 +694,7 @@ with `review/` would have that particular variable.
 
 Some GitLab features can behave differently for each environment.
 For example, you can
-[create a secret variable to be injected only into a production environment](variables/README.md#limiting-environment-scopes-of-environment-variables-premium). **[PREMIUM]**
+[create a secret variable to be injected only into a production environment](variables/README.md#limiting-environment-scopes-of-environment-variables).
 
 In most cases, these features use the _environment specs_ mechanism, which offers
 an efficient way to implement scoping within each environment group.
@@ -734,7 +736,7 @@ Below are some links you may find interesting:
 - [The `.gitlab-ci.yml` definition of environments](yaml/README.md#environment)
 - [A blog post on Deployments & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
 - [Review Apps - Use dynamic environments to deploy your code for every branch](review_apps/index.md)
-- [Deploy Boards for your applications running on Kubernetes](../user/project/deploy_boards.md) **[PREMIUM]**
+- [Deploy Boards for your applications running on Kubernetes](../user/project/deploy_boards.md) **(PREMIUM)**
 
 <!-- ## Troubleshooting
 
diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md
index b72ebe838b8..e5213881862 100644
--- a/doc/ci/environments/protected_environments.md
+++ b/doc/ci/environments/protected_environments.md
@@ -2,7 +2,7 @@
 type: concepts, howto
 ---
 
-# Protected Environments **[PREMIUM]**
+# Protected Environments **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6303) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3.
 
diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md
index 2b4fe321cb3..00995f881da 100644
--- a/doc/ci/examples/README.md
+++ b/doc/ci/examples/README.md
@@ -33,19 +33,20 @@ The following table lists examples with step-by-step tutorials that are containe
 | Java with Maven             | [How to deploy Maven projects to Artifactory with GitLab CI/CD](artifactory_and_gitlab/index.md).                          |
 | PHP with PHPunit, atoum     | [Testing PHP projects](php.md).                                                                                            |
 | PHP with NPM, SCP           | [Running Composer and NPM scripts with deployment via SCP in GitLab CI/CD](deployment/composer-npm-deploy.md).             |
-| PHP with Laravel, Ennvoy    | [Test and deploy Laravel applications with GitLab CI/CD and Envoy](laravel_with_gitlab_and_envoy/index.md).                |
+| PHP with Laravel, Envoy     | [Test and deploy Laravel applications with GitLab CI/CD and Envoy](laravel_with_gitlab_and_envoy/index.md).                |
 | Python on Heroku            | [Test and deploy a Python application with GitLab CI/CD](test-and-deploy-python-application-to-heroku.md).                 |
 | Ruby on Heroku              | [Test and deploy a Ruby application with GitLab CI/CD](test-and-deploy-ruby-application-to-heroku.md).                     |
 | Scala on Heroku             | [Test and deploy a Scala application to Heroku](test-scala-application.md).                                                |
+| Parallel testing Ruby & JS  | [GitLab CI parallel jobs testing for Ruby & JavaScript projects](https://docs.knapsackpro.com/2019/how-to-run-parallel-jobs-for-rspec-tests-on-gitlab-ci-pipeline-and-speed-up-ruby-javascript-testing). |
 
 ### Contributing examples
 
 Contributions are welcome! You can help your favorite programming
 language users and GitLab by sending a merge request with a guide for that language.
-You may want to apply for the [GitLab Community Writers Program](https://about.gitlab.com/community-writers/)
+You may want to apply for the [GitLab Community Writers Program](https://about.gitlab.com/community/writers/)
 to get paid for writing complete articles for GitLab.
 
-## Adding templates to your GitLab installation **[PREMIUM ONLY]**
+## Adding templates to your GitLab installation **(PREMIUM ONLY)**
 
 If you want to have customized examples and templates for your own self-managed GitLab instance available to your team, your GitLab administrator can [designate an instance template repository](../../user/admin_area/settings/instance_template_repository.md) that contains examples and templates specific to your enterprise.
 
diff --git a/doc/ci/examples/artifactory_and_gitlab/index.md b/doc/ci/examples/artifactory_and_gitlab/index.md
index 2117b342903..e5f307e570d 100644
--- a/doc/ci/examples/artifactory_and_gitlab/index.md
+++ b/doc/ci/examples/artifactory_and_gitlab/index.md
@@ -1,5 +1,5 @@
 ---
-redirect_from: 'https://docs.gitlab.com/ee/articles/artifactory_and_gitlab/index.html'
+disqus_identifier: 'https://docs.gitlab.com/ee/articles/artifactory_and_gitlab/index.html'
 author: Fabio Busatto
 author_gitlab: bikebilly
 level: intermediate
@@ -13,7 +13,7 @@ date: 2017-08-15
 ## Introduction
 
 In this article, we will show how you can leverage the power of [GitLab CI/CD](https://about.gitlab.com/product/continuous-integration/)
-to build a [Maven](https://maven.apache.org/) project, deploy it to [Artifactory](https://www.jfrog.com/artifactory/), and then use it from another Maven application as a dependency.
+to build a [Maven](https://maven.apache.org/) project, deploy it to [Artifactory](https://jfrog.com/artifactory/), and then use it from another Maven application as a dependency.
 
 You'll create two different projects:
 
@@ -39,9 +39,10 @@ project:
 1. Create a new project by selecting **Import project from ➔ Repo by URL**
 1. Add the following URL:
 
-    ```
-    https://gitlab.com/gitlab-examples/maven/simple-maven-dep.git
-    ```
+   ```
+   https://gitlab.com/gitlab-examples/maven/simple-maven-dep.git
+   ```
+
 1. Click **Create project**
 
 This application is nothing more than a basic class with a stub for a JUnit based test suite.
@@ -63,15 +64,15 @@ The application is ready to use, but you need some additional steps to deploy it
 1. Copy the snippet in the `pom.xml` file for your project, just after the
    `dependencies` section. The snippet should look like this:
 
-    ```xml
-    <distributionManagement>
-      <repository>
-        <id>central</id>
-        <name>83d43b5afeb5-releases</name>
-        <url>${env.MAVEN_REPO_URL}/libs-release-local</url>
-      </repository>
-    </distributionManagement>
-    ```
+   ```xml
+   <distributionManagement>
+     <repository>
+       <id>central</id>
+       <name>83d43b5afeb5-releases</name>
+       <url>${env.MAVEN_REPO_URL}/libs-release-local</url>
+     </repository>
+   </distributionManagement>
+   ```
 
 Another step you need to do before you can deploy the dependency to Artifactory
 is to configure the authentication data. It is a simple task, but Maven requires
@@ -86,18 +87,18 @@ parameter in `.gitlab-ci.yml` to use the custom location instead of the default
 1. Create a file called `settings.xml` in the `.m2` folder
 1. Copy the following content into a `settings.xml` file:
 
-    ```xml
-    <settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
-        xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
-      <servers>
-        <server>
-          <id>central</id>
-          <username>${env.MAVEN_REPO_USER}</username>
-          <password>${env.MAVEN_REPO_PASS}</password>
-        </server>
-      </servers>
-    </settings>
-    ```
+   ```xml
+   <settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
+       xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+     <servers>
+       <server>
+         <id>central</id>
+         <username>${env.MAVEN_REPO_USER}</username>
+         <password>${env.MAVEN_REPO_PASS}</password>
+       </server>
+     </servers>
+   </settings>
+   ```
 
     Username and password will be replaced by the correct values using variables.
 
@@ -187,9 +188,10 @@ We'll use again a Maven app that can be cloned from our example project:
 1. Create a new project by selecting **Import project from ➔ Repo by URL**
 1. Add the following URL:
 
-    ```
-    https://gitlab.com/gitlab-examples/maven/simple-maven-app.git
-    ```
+   ```
+   https://gitlab.com/gitlab-examples/maven/simple-maven-app.git
+   ```
+
 1. Click **Create project**
 
 This one is a simple app as well. If you look at the `src/main/java/com/example/app/App.java`
@@ -204,13 +206,13 @@ Since Maven doesn't know how to resolve the dependency, you need to modify the c
 1. Copy the snippet in the `dependencies` section of the `pom.xml` file.
    The snippet should look like this:
 
-    ```xml
-    <dependency>
-      <groupId>com.example.dep</groupId>
-      <artifactId>simple-maven-dep</artifactId>
-      <version>1.0</version>
-    </dependency>
-    ```
+   ```xml
+   <dependency>
+     <groupId>com.example.dep</groupId>
+     <artifactId>simple-maven-dep</artifactId>
+     <version>1.0</version>
+   </dependency>
+   ```
 
 ### Configure the Artifactory repository location
 
diff --git a/doc/ci/examples/browser_performance.md b/doc/ci/examples/browser_performance.md
index 8ecac4a5a4f..3266e5dc62e 100644
--- a/doc/ci/examples/browser_performance.md
+++ b/doc/ci/examples/browser_performance.md
@@ -15,7 +15,7 @@ your code by using GitLab CI/CD and [sitespeed.io](https://www.sitespeed.io)
 using Docker-in-Docker.
 
 First, you need GitLab Runner with
-[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
+[docker-in-docker build](../docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor).
 
 Once you set up the Runner, add a new job to `.gitlab-ci.yml` that
 generates the expected report:
@@ -155,4 +155,4 @@ performance:
     paths:
       - performance.json
       - sitespeed-results/
-```
\ No newline at end of file
+```
diff --git a/doc/ci/examples/code_quality.md b/doc/ci/examples/code_quality.md
index 43f773dab7c..9c65de115b4 100644
--- a/doc/ci/examples/code_quality.md
+++ b/doc/ci/examples/code_quality.md
@@ -1,5 +1,5 @@
 ---
-redirect_from: 'https://docs.gitlab.com/ee/ci/examples/code_climate.html'
+disqus_identifier: 'https://docs.gitlab.com/ee/ci/examples/code_climate.html'
 type: reference, howto
 ---
 
@@ -14,7 +14,7 @@ This example shows how to run Code Quality on your code by using GitLab CI/CD
 and Docker.
 
 First, you need GitLab Runner with
-[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
+[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor).
 
 Once you set up the Runner, include the CodeQuality template in your CI config:
 
@@ -34,6 +34,12 @@ For [GitLab Starter][ee] users, this information will be automatically
 extracted and shown right in the merge request widget.
 [Learn more on Code Quality in merge requests](../../user/project/merge_requests/code_quality.md).
 
+CAUTION: **Caution:**
+On self-managed instances, if a malicious actor compromises the Code Quality job
+definition they will be able to execute privileged docker commands on the Runner
+host. Having proper access control policies mitigates this attack vector by
+allowing access only to trusted actors.
+
 ## Previous job definitions
 
 CAUTION: **Caution:**
diff --git a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md
index 538843ab8dc..1d4c9221cf2 100644
--- a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md
+++ b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md
@@ -79,10 +79,10 @@ image: java:8
 stages:
   - build
   - deploy
-  
+
 before_script:
   - chmod +x mvnw
-  
+
 build:
   stage: build
   script: ./mvnw package
diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md
index 50e61cafeb9..44d3ec8046c 100644
--- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md
+++ b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md
@@ -418,10 +418,14 @@ fully understand [IAM Best Practices in AWS](https://docs.aws.amazon.com/IAM/lat
 
 1. Log into your AWS account and go to the [Security Credentials page](https://console.aws.amazon.com/iam/home#/security_credential)
 1. Click the **Access Keys** section and **Create New Access Key**. Create the key and keep the id and secret around, you'll need them later
-    ![AWS Access Key Config](img/aws_config_window.png)
+
+   ![AWS Access Key Config](img/aws_config_window.png)
+
 1. Go to your GitLab project, click **Settings > CI/CD** on the left sidebar
 1. Expand the **Variables** section
-    ![GitLab Secret Config](img/gitlab_config.png)
+
+   ![GitLab Secret Config](img/gitlab_config.png)
+
 1. Add a key named `AWS_KEY_ID` and copy the key id from Step 2 into the **Value** textbox
 1. Add a key named `AWS_KEY_SECRET` and copy the key secret from Step 2 into the **Value** textbox
 
diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/img/deployed_dependency_update.png b/doc/ci/examples/end_to_end_testing_webdriverio/img/deployed_dependency_update.png
index c45d70d7f7a..9fe1739f37e 100644
--- a/doc/ci/examples/end_to_end_testing_webdriverio/img/deployed_dependency_update.png
+++ b/doc/ci/examples/end_to_end_testing_webdriverio/img/deployed_dependency_update.png
diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/index.md b/doc/ci/examples/end_to_end_testing_webdriverio/index.md
index 7f1beb96bbf..38d0d86ffa2 100644
--- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md
+++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md
@@ -32,7 +32,7 @@ through the process of setting up GitLab CI/CD for end-to-end testing Javascript
 with WebdriverIO, but the general strategy should carry over to other languages.
 We assume you are familiar with GitLab, [GitLab CI/CD](../../README.md), [Review Apps](../../review_apps/index.md), and running your app locally, e.g., on `localhost:8000`.
 
-### What to test
+## What to test
 
 In the widely-used [testing pyramid strategy](https://martinfowler.com/bliki/TestPyramid.html), end-to-end tests act more like a
 safeguard: [most of your code should be covered by
@@ -40,9 +40,9 @@ unit tests](https://vincenttunru.com/100-percent-coverage/) that allow you to ea
 will likely want to
 [limit the number of end-to-end tests](https://testing.googleblog.com/2015/04/just-say-no-to-more-end-to-end-tests.html)
 to just enough to give you the confidence that the deployment went as intended, that your
-infrastructure is up and running, and that your units of code work well together. 
+infrastructure is up and running, and that your units of code work well together.
 
-### Selenium and WebdriverIO
+## Selenium and WebdriverIO
 
 [Selenium](http://www.seleniumhq.org/) is a piece of software that can control web browsers, e.g., to make them
 visit a specific URL or interact with elements on the page. It can be programmatically controlled
@@ -65,7 +65,7 @@ describe('A visitor without account', function(){
         expect(browser.getUrl()).toMatch('page-that-does-not-exist');
 
         browser.element('.content a[href="/"]').click();
-        
+
         expect(browser.getUrl()).not.toMatch('page-that-does-not-exist');
     });
 });
@@ -143,7 +143,7 @@ Which brings us to the exciting part: how do we run this in GitLab CI/CD? There
 need to do for this:
 
 1. Set up [CI/CD jobs](../../yaml/README.md#introduction) that actually have a browser available.
-2. Update our WebdriverIO configuration to use those browsers to visit the review apps.
+1. Update our WebdriverIO configuration to use those browsers to visit the review apps.
 
 For the scope of this article, we've defined an additional [CI/CD stage](../../yaml/README.md#stages)
 `confidence-check` that is executed _after_ the stage that deploys the review app. It uses the `node:latest` [Docker
diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md
index d7308a3a5ec..808e4285f2f 100644
--- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md
+++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md
@@ -1,5 +1,5 @@
 ---
-redirect_from: 'https://docs.gitlab.com/ee/articles/laravel_with_gitlab_and_envoy/index.html'
+disqus_identifier: 'https://docs.gitlab.com/ee/articles/laravel_with_gitlab_and_envoy/index.html'
 author: Mehran Rasulian
 author_gitlab: mehranrasulian
 level: intermediate
@@ -452,6 +452,7 @@ To start using Container Registry on our machine, we first need to login to the
 ```bash
 docker login registry.gitlab.com
 ```
+
 Then we can build and push our image to GitLab:
 
 ```bash
diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md
index c459bb7001f..1dd3049d53d 100644
--- a/doc/ci/examples/php.md
+++ b/doc/ci/examples/php.md
@@ -6,7 +6,7 @@ type: tutorial
 
 This guide covers basic building instructions for PHP projects.
 
-Two testing scenarios are covered: using the Docker executor and 
+Two testing scenarios are covered: using the Docker executor and
 using the Shell executor.
 
 ## Test PHP projects using the Docker executor
@@ -64,7 +64,7 @@ docker-php-ext-install pdo_mysql
 You might wonder what `docker-php-ext-install` is. In short, it is a script
 provided by the official php docker image that you can use to easily install
 extensions. For more information read the documentation at
-<https://hub.docker.com/r/_/php/>.
+<https://hub.docker.com/_/php>.
 
 Now that we created the script that contains all prerequisites for our build
 environment, let's add it in `.gitlab-ci.yml`:
@@ -96,7 +96,7 @@ Finally, commit your files and push them to GitLab to see your build succeeding
 The final `.gitlab-ci.yml` should look similar to this:
 
 ```yaml
-# Select image from https://hub.docker.com/r/_/php/
+# Select image from https://hub.docker.com/_/php
 image: php:5.6
 
 before_script:
@@ -286,7 +286,7 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available
 Want to hack on it? Simply fork it, commit, and push your changes. Within a few
 moments the changes will be picked by a public runner and the job will begin.
 
-[php-hub]: https://hub.docker.com/r/_/php/
+[php-hub]: https://hub.docker.com/_/php
 [phpenv]: https://github.com/phpenv/phpenv
 [phpenv-installation]: https://github.com/phpenv/phpenv#installation
 [php-example-repo]: https://gitlab.com/gitlab-examples/php
diff --git a/doc/ci/examples/test-clojure-application.md b/doc/ci/examples/test-clojure-application.md
index 5cda8702b56..6ea38f22bca 100644
--- a/doc/ci/examples/test-clojure-application.md
+++ b/doc/ci/examples/test-clojure-application.md
@@ -35,7 +35,7 @@ test:
     - lein test
 ```
 
-In `before_script`, we install JRE and [Leiningen](http://leiningen.org/).
+In `before_script`, we install JRE and [Leiningen](https://leiningen.org/).
 
 The sample project uses the [migratus](https://github.com/yogthos/migratus) library to manage database migrations, and
 we have added a database migration as the last step of `before_script`.
diff --git a/doc/ci/examples/test-scala-application.md b/doc/ci/examples/test-scala-application.md
index 0e33a1ba060..7d039ab1aeb 100644
--- a/doc/ci/examples/test-scala-application.md
+++ b/doc/ci/examples/test-scala-application.md
@@ -46,11 +46,11 @@ deploy:
 
 In the above configuration:
 
-- The `before_script` installs [SBT](http://www.scala-sbt.org/) and
-displays the version that is being used.
+- The `before_script` installs [SBT](https://www.scala-sbt.org/) and
+  displays the version that is being used.
 - The `test` stage executes SBT to compile and test the project.
-   - [sbt-scoverage](https://github.com/scoverage/sbt-scoverage) is used as an SBT
-plugin to measure test coverage.
+  - [sbt-scoverage](https://github.com/scoverage/sbt-scoverage) is used as an SBT
+    plugin to measure test coverage.
 - The `deploy` stage automatically deploys the project to Heroku using dpl.
 
 You can use other versions of Scala and SBT by defining them in
diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md
index ec25ca1bfc3..0e595e1a0be 100644
--- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md
+++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md
@@ -188,28 +188,27 @@ when running our Phoenix in our `localhost`.
 - Open `hello_gitlab_ci/config/test.exs` on your favorite code editor
 - Go to **Configure your database** session and edit the block to include `System.get_env`:
 
-    ```elixir
-    # Configure your database
-    config :hello_gitlab_ci, HelloGitlabCi.Repo,
-      adapter: Ecto.Adapters.Postgres,
-      username: System.get_env("POSTGRES_USER") || "postgres",
-      password: System.get_env("POSTGRES_PASSWORD") || "postgres",
-      database: System.get_env("POSTGRES_DB") || "hello_gitlab_ci_test",
-      hostname: System.get_env("POSTGRES_HOST") || "localhost",
-      pool: Ecto.Adapters.SQL.Sandbox
-    ```
-
-    We'll need these system variables later on.
+  ```elixir
+  # Configure your database
+  config :hello_gitlab_ci, HelloGitlabCi.Repo,
+    adapter: Ecto.Adapters.Postgres,
+    username: System.get_env("POSTGRES_USER") || "postgres",
+    password: System.get_env("POSTGRES_PASSWORD") || "postgres",
+    database: System.get_env("POSTGRES_DB") || "hello_gitlab_ci_test",
+    hostname: System.get_env("POSTGRES_HOST") || "localhost",
+    pool: Ecto.Adapters.SQL.Sandbox
+  ```
+
+  We'll need these system variables later on.
 
 - Create an empty file named `.gitkeep` into `hello_gitlab_ci/priv/repo/migrations`
 
-    As our project is still fresh, we don't have any data on our database, so, the `migrations`
-directory will be empty.
-    Without `.gitkeep`, git will not upload this empty directory and we'll got an error when running our
-test on GitLab.
+  As our project is still fresh, we don't have any data on our database, so, the `migrations`
+  directory will be empty.
+  Without `.gitkeep`, git will not upload this empty directory and we'll got an error when running our
+  test on GitLab.
 
-    > **Note:**
-    If we add a folder via the GitLab UI, GitLab itself will add the `.gitkeep` to that new dir.
+  > **Note:** If we add a folder via the GitLab UI, GitLab itself will add the `.gitkeep` to that new dir.
 
 Now, let's run a local test and see if everything we did didn't break anything.
 
@@ -248,64 +247,64 @@ project.
 
 - The fastest and easiest way to do this, is to click on **Set up CI** on project's main page:
 
-    ![Set up CI](img/setup-ci.png)
+  ![Set up CI](img/setup-ci.png)
 
 - On next screen, we can select a template ready to go. Click on **Apply a GitLab CI/CD Yaml
   template** and select **Elixir**:
 
-    ![Select template](img/select-template.png)
+  ![Select template](img/select-template.png)
 
-    This template file tells GitLab CI/CD about what we wish to do every time a new commit is made.
-    However, we have to adapt it to run a Phoenix app.
+  This template file tells GitLab CI/CD about what we wish to do every time a new commit is made.
+  However, we have to adapt it to run a Phoenix app.
 
 - The first line tells GitLab what Docker image will be used.
 
-    Remember when we learn about Runners, the isolated virtual machine where GitLab CI/CD build and test
-    our application? This virtual machine must have all dependencies to run our application. This is
-    where a Docker image is needed. The correct image will provide the entire system for us.
+  Remember when we learn about Runners, the isolated virtual machine where GitLab CI/CD build and test
+  our application? This virtual machine must have all dependencies to run our application. This is
+  where a Docker image is needed. The correct image will provide the entire system for us.
 
-    As a suggestion, you can use [trenpixster's elixir image][docker-image], which already has all
-    dependencies for Phoenix installed, such as Elixir, Erlang, NodeJS and PostgreSQL:
+  As a suggestion, you can use [trenpixster's elixir image][docker-image], which already has all
+  dependencies for Phoenix installed, such as Elixir, Erlang, NodeJS and PostgreSQL:
 
-    ```yml
-    image: trenpixster/elixir:latest
-    ```
+  ```yml
+  image: trenpixster/elixir:latest
+  ```
 
 - At `services` session, we'll only use `postgres`, so we'll delete `mysql` and `redis` lines:
 
-    ```yml
-    services:
-      - postgres:latest
-    ```
+  ```yml
+  services:
+    - postgres:latest
+  ```
 
 - Now, we'll create a new entry called `variables`, before `before_script` session:
 
-    ```yml
-    variables:
-      POSTGRES_DB: hello_gitlab_ci_test
-      POSTGRES_HOST: postgres
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: "postgres"
-      MIX_ENV: "test"
-    ```
+  ```yml
+  variables:
+    POSTGRES_DB: hello_gitlab_ci_test
+    POSTGRES_HOST: postgres
+    POSTGRES_USER: postgres
+    POSTGRES_PASSWORD: "postgres"
+    MIX_ENV: "test"
+  ```
 
-    Here, we are setting up the values for GitLab CI/CD authenticate into PostgreSQL, as we did on
-    `config/test.exs` earlier.
+  Here, we are setting up the values for GitLab CI/CD authenticate into PostgreSQL, as we did on
+  `config/test.exs` earlier.
 
 - In `before_script` session, we'll add some commands to prepare everything to the test:
 
-    ```yml
-    before_script:
-      - apt-get update && apt-get -y install postgresql-client
-      - mix local.hex --force
-      - mix deps.get --only test
-      - mix ecto.create
-      - mix ecto.migrate
-    ```
+  ```yml
+  before_script:
+    - apt-get update && apt-get -y install postgresql-client
+    - mix local.hex --force
+    - mix deps.get --only test
+    - mix ecto.create
+    - mix ecto.migrate
+   ```
 
-    It's important to install `postgresql-client` to let GitLab CI/CD access PostgreSQL and create our
-    database with the login information provided earlier. More important is to respect the indentation,
-    to avoid syntax errors when running the build.
+  It's important to install `postgresql-client` to let GitLab CI/CD access PostgreSQL and create our
+  database with the login information provided earlier. More important is to respect the indentation,
+  to avoid syntax errors when running the build.
 
 - And finally, we'll let `mix` session intact.
 
@@ -404,14 +403,14 @@ other reasons][ci-reasons] to keep using GitLab CI/CD. The benefits to our teams
 [phoenix-learning-guide]: https://hexdocs.pm/phoenix/learning.html "Phoenix Learning Guide"
 [phoenix-install]: https://hexdocs.pm/phoenix/installation.html "Phoenix Installation"
 [phoenix-mysql]: https://hexdocs.pm/phoenix/ecto.html#using-mysql "Phoenix with MySQL"
-[elixir-site]: http://elixir-lang.org/ "Elixir"
-[elixir-mix]: http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html "Introduction to mix"
-[elixir-docs]: http://elixir-lang.org/getting-started/introduction.html "Elixir Documentation"
+[elixir-site]: https://elixir-lang.org/ "Elixir"
+[elixir-mix]: https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html "Introduction to mix"
+[elixir-docs]: https://elixir-lang.org/getting-started/introduction.html "Elixir Documentation"
 [elixir-install]: https://elixir-lang.org/install.html "Elixir Installation"
-[ecto]: http://hexdocs.pm/ecto "Ecto"
+[ecto]: https://hexdocs.pm/ecto/Ecto.html "Ecto"
 [ecto-repo]: https://hexdocs.pm/ecto/Ecto.html#module-repositories "Ecto Repositories"
 [mix-ecto]: https://hexdocs.pm/ecto/Mix.Tasks.Ecto.Create.html "mix and Ecto"
-[iex]: http://elixir-lang.org/getting-started/introduction.html#interactive-mode "Interactive Mode"
+[iex]: https://elixir-lang.org/getting-started/introduction.html#interactive-mode "Interactive Mode"
 [ci-lint]: https://gitlab.com/ci/lint "CI Lint Tool"
 [ci-reasons]: https://about.gitlab.com/2015/02/03/7-reasons-why-you-should-be-using-ci/ "7 Reasons Why You Should Be Using CI"
 [ci-guide]: https://about.gitlab.com/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/ "Getting Started With GitLab And GitLab CI/CD"
diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md
index 551044dd76f..cce33c7a6b4 100644
--- a/doc/ci/git_submodules.md
+++ b/doc/ci/git_submodules.md
@@ -69,24 +69,26 @@ correctly with your CI jobs:
 1. Next, if you are using `gitlab-runner` v1.10+, you can set the
    `GIT_SUBMODULE_STRATEGY` variable to either `normal` or `recursive` to tell
    the runner to fetch your submodules before the job:
-    ```yaml
-    variables:
-      GIT_SUBMODULE_STRATEGY: recursive
-    ```
-    See the [`.gitlab-ci.yml` reference](yaml/README.md#git-submodule-strategy)
-    for more details about `GIT_SUBMODULE_STRATEGY`.
+
+   ```yaml
+   variables:
+     GIT_SUBMODULE_STRATEGY: recursive
+   ```
+
+   See the [`.gitlab-ci.yml` reference](yaml/README.md#git-submodule-strategy)
+   for more details about `GIT_SUBMODULE_STRATEGY`.
 
 1. If you are using an older version of `gitlab-runner`, then use
    `git submodule sync/update` in `before_script`:
 
-    ```yaml
-    before_script:
-      - git submodule sync --recursive
-      - git submodule update --init --recursive
-    ```
+   ```yaml
+   before_script:
+     - git submodule sync --recursive
+     - git submodule update --init --recursive
+   ```
 
-    `--recursive` should be used in either both or none (`sync/update`) depending on
-    whether you have recursive submodules.
+   `--recursive` should be used in either both or none (`sync/update`) depending on
+   whether you have recursive submodules.
 
 The rationale to set the `sync` and `update` in `before_script` is because of
 the way Git submodules work. On a fresh Runner workspace, Git will set the
diff --git a/doc/ci/img/collapsible_log.png b/doc/ci/img/collapsible_log.png
new file mode 100644
index 00000000000..d2a570e246e
--- /dev/null
+++ b/doc/ci/img/collapsible_log.png
diff --git a/doc/ci/img/deployments_view.png b/doc/ci/img/deployments_view.png
index 12090434bef..9e2b7e89577 100644
--- a/doc/ci/img/deployments_view.png
+++ b/doc/ci/img/deployments_view.png
diff --git a/doc/ci/img/environments_available.png b/doc/ci/img/environments_available.png
index 48fc6effc2d..6c64e9398f7 100644
--- a/doc/ci/img/environments_available.png
+++ b/doc/ci/img/environments_available.png
diff --git a/doc/ci/img/environments_mr_review_app.png b/doc/ci/img/environments_mr_review_app.png
index 6a7b7ce5679..86c20d8d3b6 100644
--- a/doc/ci/img/environments_mr_review_app.png
+++ b/doc/ci/img/environments_mr_review_app.png
diff --git a/doc/ci/img/manual_job_variables.png b/doc/ci/img/manual_job_variables.png
new file mode 100644
index 00000000000..a5ed351fdcd
--- /dev/null
+++ b/doc/ci/img/manual_job_variables.png
diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md
index 1387d4df500..58307660e51 100644
--- a/doc/ci/interactive_web_terminal/index.md
+++ b/doc/ci/interactive_web_terminal/index.md
@@ -8,7 +8,7 @@ type: reference
 
 Interactive web terminals give the user access to a terminal in GitLab for
 running one-off commands for their CI pipeline. Since this is giving the user
-shell access to the environment where [GitLab Runner](https://docs.gitlab.com/runner/) 
+shell access to the environment where [GitLab Runner](https://docs.gitlab.com/runner/)
 is deployed, some [security precautions](../../administration/integration/terminal.md#security) were
 taken to protect the users.
 
@@ -59,7 +59,6 @@ close the terminal window.
 
 ![finished job with terminal open](img/finished_job_with_terminal_open.png)
 
-## Interactive Web Terminals for the Web IDE **[ULTIMATE ONLY]**
+## Interactive Web Terminals for the Web IDE **(ULTIMATE ONLY)**
 
 Read the Web IDE docs to learn how to run [Interactive Terminals through the Web IDE](../../user/project/web_ide/index.md).
-
diff --git a/doc/ci/introduction/img/gitlab_workflow_example_11_9.png b/doc/ci/introduction/img/gitlab_workflow_example_11_9.png
index 204e9c462e5..f3fb9444b55 100644
--- a/doc/ci/introduction/img/gitlab_workflow_example_11_9.png
+++ b/doc/ci/introduction/img/gitlab_workflow_example_11_9.png
diff --git a/doc/ci/introduction/img/gitlab_workflow_example_extended_11_11.png b/doc/ci/introduction/img/gitlab_workflow_example_extended_11_11.png
index 5089a1088c5..a0874f66eaa 100644
--- a/doc/ci/introduction/img/gitlab_workflow_example_extended_11_11.png
+++ b/doc/ci/introduction/img/gitlab_workflow_example_extended_11_11.png
diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md
index ef9f9a9973c..366aca3442e 100644
--- a/doc/ci/introduction/index.md
+++ b/doc/ci/introduction/index.md
@@ -9,6 +9,11 @@ In this document we'll present an overview of the concepts of Continuous Integra
 Continuous Delivery, and Continuous Deployment, as well as an introduction to
 GitLab CI/CD.
 
+NOTE: **Out-of-the-box management systems can decrease hours spent on maintaining toolchains by 10% or more.**
+Watch our
+["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/)
+webcast to learn about continuous methods and how GitLab’s built-in CI can help you simplify and scale software development.
+
 ## Introduction to CI/CD methodologies
 
 The continuous methodologies of software development are based on
@@ -146,14 +151,14 @@ so, GitLab CI/CD:
 - Runs automated scripts (sequential or parallel) to:
   - Build and test your app.
   - Preview the changes per merge request with Review Apps, as you
-  would see in your `localhost`.
+    would see in your `localhost`.
 
 Once you're happy with your implementation:
 
 - Get your code reviewed and approved.
 - Merge the feature branch into the default branch.
   - GitLab CI/CD deploys your changes automatically to a production environment.
--  And finally, you and your team can easily roll it back if something goes wrong.
+- And finally, you and your team can easily roll it back if something goes wrong.
 
 ![GitLab workflow example](img/gitlab_workflow_example_11_9.png)
 
@@ -176,24 +181,24 @@ you'll see some of the features available in GitLab
 according to each stage (Verify, Package, Release).
 
 1. **Verify**:
-    - Automatically build and test your application with Continuous Integration.
-    - Analyze your source code quality with [GitLab Code Quality](../../user/project/merge_requests/code_quality.md). **[STARTER]**
-    - Determine the performance impact of code changes with [Browser Performance Testing](../../user/project/merge_requests/browser_performance_testing.md). **[PREMIUM]**
-    - Perform a series of tests, such as [Container Scanning](../../user/application_security/container_scanning/index.md) **[ULTIMATE]**, [Dependency Scanning](../../user/application_security/dependency_scanning/index.md) **[ULTIMATE]**, and [JUnit tests](../junit_test_reports.md).
-    - Deploy your changes with [Review Apps](../review_apps/index.md) to preview the app changes on every branch.
+   - Automatically build and test your application with Continuous Integration.
+   - Analyze your source code quality with [GitLab Code Quality](../../user/project/merge_requests/code_quality.md). **(STARTER)**
+   - Determine the performance impact of code changes with [Browser Performance Testing](../../user/project/merge_requests/browser_performance_testing.md). **(PREMIUM)**
+   - Perform a series of tests, such as [Container Scanning](../../user/application_security/container_scanning/index.md) **(ULTIMATE)**, [Dependency Scanning](../../user/application_security/dependency_scanning/index.md) **(ULTIMATE)**, and [JUnit tests](../junit_test_reports.md).
+   - Deploy your changes with [Review Apps](../review_apps/index.md) to preview the app changes on every branch.
 1. **Package**:
-    - Store Docker images with [Container Registry](../../user/project/container_registry.md).
-    - Store NPM packages with [NPM Registry](../../user/project/packages/npm_registry.md). **[PREMIUM]**
-    - Store Maven artifacts with [Maven Repository](../../user/project/packages/maven_repository.md). **[PREMIUM]**
+   - Store Docker images with [Container Registry](../../user/project/container_registry.md).
+   - Store NPM packages with [NPM Registry](../../user/project/packages/npm_registry.md). **(PREMIUM)**
+   - Store Maven artifacts with [Maven Repository](../../user/project/packages/maven_repository.md). **(PREMIUM)**
 1. **Release**:
-    - Continuous Deployment, automatically deploying your app to production.
-    - Continuous Delivery, manually click to deploy your app to production.
-    - Deploy static websites with [GitLab Pages](../../user/project/pages/index.md).
-    - Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature with [Canary Deployments](../../user/project/canary_deployments.md). **[PREMIUM]**
-    - Deploy your features behind [Feature Flags](../../user/project/operations/feature_flags.md). **[PREMIUM]**
-    - Add release notes to any Git tag with [GitLab Releases](../../user/project/releases/index.md).
-    - View of the current health and status of each CI environment running on Kubernetes with [Deploy Boards](../../user/project/deploy_boards.md). **[PREMIUM]**
-    -  Deploy your application to a production environment in a Kubernetes cluster with [Auto Deploy](../../topics/autodevops/index.md#auto-deploy).
+   - Continuous Deployment, automatically deploying your app to production.
+   - Continuous Delivery, manually click to deploy your app to production.
+   - Deploy static websites with [GitLab Pages](../../user/project/pages/index.md).
+   - Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature with [Canary Deployments](../../user/project/canary_deployments.md). **(PREMIUM)**
+   - Deploy your features behind [Feature Flags](../../user/project/operations/feature_flags.md). **(PREMIUM)**
+   - Add release notes to any Git tag with [GitLab Releases](../../user/project/releases/index.md).
+   - View of the current health and status of each CI environment running on Kubernetes with [Deploy Boards](../../user/project/deploy_boards.md). **(PREMIUM)**
+   - Deploy your application to a production environment in a Kubernetes cluster with [Auto Deploy](../../topics/autodevops/index.md#auto-deploy).
 
 With GitLab CI/CD you can also:
 
@@ -201,7 +206,7 @@ With GitLab CI/CD you can also:
 - Deploy your app to different [environments](../environments.md).
 - Install your own [GitLab Runner](https://docs.gitlab.com/runner/).
 - [Schedule pipelines](../../user/project/pipelines/schedules.md).
-- Check for app vulnerabilities with [Security Test reports](../../user/project/merge_requests/index.md#security-reports-ultimate). **[ULTIMATE]**
+- Check for app vulnerabilities with [Security Test reports](../../user/project/merge_requests/index.md#security-reports-ultimate). **(ULTIMATE)**
 
 To see all CI/CD features, navigate back to the [CI/CD index](../README.md).
 
diff --git a/doc/ci/jenkins/index.md b/doc/ci/jenkins/index.md
new file mode 100644
index 00000000000..f8a3fab88e3
--- /dev/null
+++ b/doc/ci/jenkins/index.md
@@ -0,0 +1,232 @@
+---
+comments: false
+type: index, howto
+---
+
+# Migrating from Jenkins
+
+A lot of GitLab users have successfully migrated to GitLab CI/CD from Jenkins. To make this
+easier if you're just getting started, we've collected several resources here that you might find useful
+before diving in.
+
+First of all, our [Quick Start Guide](../quick_start/README.md) contains a good overview of how GitLab CI/CD works.
+You may also be interested in [Auto DevOps](../../topics/autodevops/index.md) which can potentially be used to build, test,
+and deploy your applications with little to no configuration needed at all.
+
+Otherwise, read on for important information that will help you get the ball rolling. Welcome
+to GitLab!
+
+## Important differences
+
+There are some high level differences between the products worth mentioning:
+
+- With GitLab you don't need a root `pipeline` keyword to wrap everything.
+- All jobs within a single stage always run in parallel, and all stages run in sequence. We are planning
+  to allow certain jobs to break this sequencing as needed with our [directed acyclic graph](https://gitlab.com/gitlab-org/gitlab-ce/issues/47063)
+  feature.
+- The `.gitlab-ci.yml` file is checked in to the root of your repository, much like a Jenkinsfile, but
+  is in the YAML format (see [complete reference](../yaml/README.md)) instead of a Groovy DSL. It's most
+  analagous to the declarative Jenkinsfile format.
+- GitLab comes with a [container registry](../../user/project/container_registry.md), and we recommend using
+  container images to set up your build environment.
+
+## Groovy vs. YAML
+
+Jenkins Pipelines are based on [Groovy](https://groovy-lang.org/), so the pipeline specification is written as code. 
+GitLab works a bit differently, we use the more highly structured [YAML](https://yaml.org/) format, which
+places scripting elements inside of `script:` blocks separate from the pipeline specification itself.
+
+This is a strength of GitLab, in that it helps keep the learning curve much simpler to get up and running
+and avoids some of the problem of unconstrained complexity which can make your Jenkinsfiles hard to understand
+and manage.
+
+That said, we do of course still value DRY (don't repeat yourself) principles and want to ensure that
+behaviors of your jobs can be codified once and applied as needed. You can use the `extends:` syntax to
+[templatize your jobs](../yaml/README.md#extends), and `include:` can be used to [bring in entire sets of behaviors](../yaml/README.md#include)
+to pipelines in different projects.
+
+```yaml
+.in-docker:
+  tags:
+    - docker
+  image: alpine
+
+rspec:
+  extends:
+    - .in-docker
+  script:
+    - rake rspec
+```      
+
+## Artifact publishing
+
+Artifacts may work a bit differently than you've used them with Jenkins. In GitLab, any job can define
+a set of artifacts to be saved by using the `artifacts:` keyword. This can be configured to point to a file
+or set of files that can then be persisted from job to job. Read more on our detailed [artifacts documentation](../../user/project/pipelines/job_artifacts.html)
+
+```yaml
+pdf:
+  script: xelatex mycv.tex
+  artifacts:
+    paths:
+    - ./mycv.pdf
+    - ./output/
+    expire_in: 1 week
+```
+
+Additionally, we have package management features like a built-in container, NPM, and Maven registry that you
+can leverage. You can see the complete list of packaging features (which includes links to documentation)
+in the [Packaging section of our documentation](../../README.md#package).
+
+## Integrated features
+
+Where you may have used plugins to get things like code quality, unit tests, security scanning, and so on working in Jenkins,
+GitLab takes advantage of our connected ecosystem to automatically pull these kinds of results into
+your Merge Requests, pipeline details pages, and other locations. You may find that you actually don't
+need to configure anything to have these appear.
+
+If they aren't working as expected, or if you'd like to see what's available, our [CI feature index](../README.md#feature-set) has the full list
+of bundled features and links to the documentation for each.
+
+## Converting Declarative Jenkinsfiles
+
+Declarative Jenkinsfiles contain "Sections" and "Directives" which are used to control the behavior of your
+pipelines. There are equivalents for all of these in GitLab, which we've documented below.
+
+This section is based on the [Jenkinsfile syntax documentation](https://jenkins.io/doc/book/pipeline/syntax/)
+and is meant to be a mapping of concepts there to concepts in GitLab.
+
+### Sections
+
+#### `agent`
+
+The agent section is used to define how a pipeline will be executed. For GitLab, we use the [GitLab Runner](../runners/README.md)
+to provide this capability. You can configure your own runners in Kubernetes or on any host, or take advantage
+of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users.) The link above will bring you to the documenation which will describe how to get
+up and running quickly. We also support using [tags](../runners/README.md#using-tags) to direct different jobs
+to different Runners (execution agents).
+
+The `agent` section also allows you to define which Docker images should be used for execution, for which we use
+the [`image`](../yaml/README.md#image) keyword. The `image` can be set on a single job or at the top level, in which
+case it will apply to all jobs in the pipeline.
+
+```yaml
+my_job:
+  image: alpine
+  ...
+```
+
+#### `post`
+
+The `post` section defines the actions that should be performed at the end of the pipeline. GitLab also supports
+this through the use of stages. You can define your stages as follows, and any jobs assigned to the `before_pipeline`
+or `after_pipeline` stages will run as expected. You can call these stages anything you like.
+
+```yaml
+stages:
+  - before_pipeline
+  - build
+  - test
+  - deploy
+  - after_pipeline
+```  
+
+Setting a step to be performed before and after any job can be done via the [`before_script` and `after_script` keywords](../yaml/README.md#before_script-and-after_script).
+
+```yaml
+default:
+  before_script:
+    - echo "I run before any jobs starts in the entire pipeline, and can be responsible for setting up the environment."
+```
+
+#### `stages`
+
+GitLab CI also lets you define stages, but is a little bit more free-form to configure. The GitLab [`stages` keyword](../yaml/README.md#stages)
+is a top level setting that enumerates the list of stages, but you are not required to nest individual jobs underneath
+the `stages` section. Any job defined in the `.gitlab-ci.yml` can be made a part of any stage through use of the 
+[`stage:` keyword](../yaml/README.md#stage).
+
+Note that, unless otherwise specified, every pipeline is instantiated with a `build`, `test`, and `deploy` stage
+which are run in that order. Jobs that have no `stage` defined are placed by default in the `test` stage.
+Of course, each job that refers to a stage must refer to a stage that exists in the pipeline configuration.
+
+```yaml
+stages:
+  - build
+  - test
+  - deploy
+
+my_job:
+  stage: build
+  ...
+```
+
+#### `steps`
+
+The `steps` section is equivalent to the [`script` section](../yaml/README.md#script) of an individual job. This is
+a simple YAML array with each line representing an individual command to be run.
+
+```yaml
+my_job:
+  script:
+    - echo "hello! the current time is:"
+    - time
+  ...
+```
+
+### Directives
+
+#### `environment`
+
+In GitLab, we use the [`variables` keyword](../yaml/README.md#variables) to define different variables at runtime.
+These can also be set up through the GitLab UI, under CI/CD settings. See also our [general documentation on variables](../variables/README.md),
+including the section on [protected variables](../variables/README.md#protected-environment-variables) which can be used
+to limit access to certain variables to certain environments or runners.
+
+```yaml
+variables:
+  POSTGRES_USER: user
+  POSTGRES_PASSWORD: testing_password
+```
+
+#### `options`
+
+Here, options for different things exist associated with the object in question itself. For example, options related
+to jobs are defined in relation to the job itself. If you're looking for a certain option, you should be able to find
+where it's located by searching our [complete configuration reference](../yaml/README.md) page.
+
+#### `parameters`
+
+GitLab does not require you to define which variables you want to be available when starting a manual job. A user
+can provide any variables they like.
+
+#### `triggers` / `cron`
+
+Because GitLab is integrated tightly with git, SCM polling options for triggers are not needed. We support an easy to use
+[syntax for scheduling pipelines](../../user/project/pipelines/schedules.md).
+
+#### `tools`
+
+GitLab does not support a separate `tools` directive. Our best-practice reccomendation is to use pre-built
+container images, which can be cached, and can be built to already contain the tools you need for your pipelines. Pipelines can
+be set up to automatically build these images as needed and deploy them to the [container registry](../../user/project/container_registry.md).
+
+If you're not using container images with Docker/Kubernetes, for example on Mac or FreeBSD, then the `shell` executor does require you to
+set up your environment either in advance or as part of the jobs. You could create a `before_script`
+action that handles this for you.
+
+#### `input`
+
+Similar to the `parameters` keyword, this is not needed because a manual job can always be provided runtime
+variable entry.
+
+#### `when`
+
+GitLab does support a [`when` keyword](../yaml/README.md#when) which is used to indicate when a job should be
+run in case of (or despite) failure, but most of the logic for controlling pipelines can be found in
+our very powerful [`only/except` rules system](../yaml/README.md#onlyexcept-basic) (see also our [advanced syntax](../yaml/README.md#onlyexcept-basic))
+
+```yaml
+my_job:
+  only: branches
+```
\ No newline at end of file
diff --git a/doc/ci/merge_request_pipelines/img/merge_request.png b/doc/ci/merge_request_pipelines/img/merge_request.png
index d03fdc6a885..bb64e17cc91 100644
--- a/doc/ci/merge_request_pipelines/img/merge_request.png
+++ b/doc/ci/merge_request_pipelines/img/merge_request.png
diff --git a/doc/ci/merge_request_pipelines/img/merge_request_pipeline.png b/doc/ci/merge_request_pipelines/img/merge_request_pipeline.png
deleted file mode 100644
index 58d5581f628..00000000000
--- a/doc/ci/merge_request_pipelines/img/merge_request_pipeline.png
+++ /dev/null
diff --git a/doc/ci/merge_request_pipelines/img/merge_request_pipeline_config.png b/doc/ci/merge_request_pipelines/img/merge_request_pipeline_config.png
deleted file mode 100644
index 0a84e61d284..00000000000
--- a/doc/ci/merge_request_pipelines/img/merge_request_pipeline_config.png
+++ /dev/null
diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md
index fe2fc790505..72a9a876037 100644
--- a/doc/ci/merge_request_pipelines/index.md
+++ b/doc/ci/merge_request_pipelines/index.md
@@ -1,14 +1,9 @@
 ---
-type: reference
+type: reference, index
+last_update: 2019-07-03
 ---
 
-# Pipelines for merge requests
-
-NOTE: **Note**:
-As of GitLab 11.10, pipelines for merge requests require GitLab Runner 11.9
-or higher due to the [recent refspecs
-changes](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/25504).
-Anything lower will cause the pipeline to fail.
+# Pipelines for Merge Requests
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/15310) in GitLab 11.6.
 
@@ -23,6 +18,16 @@ for when you are running a pipeline in a merge request. This
 could be either adding or removing steps in the pipeline, to make sure that
 your pipelines are as efficient as possible.
 
+## Requirements and limitations
+
+Pipelines for merge requests have the following requirements and limitations:
+
+- As of GitLab 11.10, pipelines for merge requests require GitLab Runner 11.9
+  or higher due to the
+  [recent refspecs changes](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/25504).
+- Pipelines for merge requests are incompatible with
+  [CI/CD for external repositories](../ci_cd_for_external_repos/index.md).
+
 ## Configuring pipelines for merge requests
 
 To configure pipelines for merge requests, add the `only: merge_requests` parameter to
@@ -71,56 +76,13 @@ when a merge request was created or updated. For example:
 
 ![Merge request page](img/merge_request.png)
 
-## Pipelines for Merged Results **[PREMIUM]**
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7380) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
-> This feature is disabled by default until we resolve issues with [contention handling](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186), but [can be enabled manually](#enabling-pipelines-for-merged-results).
-
-It's possible for your source and target branches to diverge, which can result
-in the scenario that source branch's pipeline was green, the target's pipeline was green,
-but the combined output fails.
-
-By having your merge request pipeline automatically
-create a new ref that contains the merge result of the source and target branch
-(then running a pipeline on that ref), we can better test that the combined result
-is also valid.
-
-GitLab can run pipelines for merge requests
-on this merged result. That is, where the source and target branches are combined into a
-new ref and a pipeline for this ref validates the result prior to merging.
-
-![Merge request pipeline as the head pipeline](img/merge_request_pipeline.png)
+## Pipelines for Merged Results **(PREMIUM)**
 
-There are some cases where creating a combined ref is not possible or not wanted.
-For example, a source branch that has conflicts with the target branch
-or a merge request that is still in WIP status. In this case, the merge request pipeline falls back to a "detached" state
-and runs on the source branch ref as if it was a regular pipeline.
+Read the [documentation on Pipelines for Merged Results](pipelines_for_merged_results/index.md).
 
-The detached state serves to warn you that you are working in a situation
-subjected to merge problems, and helps to highlight that you should
-get out of WIP status or resolve merge conflicts as soon as possible.
+### Merge Trains **(PREMIUM)**
 
-### Enabling Pipelines for Merged Results
-
-To enable pipelines on merged results at the project level:
-
-1. Visit your project's **Settings > General** and expand **Merge requests**.
-1. Check **Merge pipelines will try to validate the post-merge result prior to merging**.
-1. Click **Save changes** button.
-
-![Merge request pipeline config](img/merge_request_pipeline_config.png)
-
-CAUTION: **Warning:**
-Make sure your `gitlab-ci.yml` file is [configured properly for pipelines for merge requests](#configuring-pipelines-for-merge-requests),
-otherwise pipelines for merged results won't run and your merge requests will be stuck in an unresolved state.
-
-### Pipelines for Merged Result's limitations
-
-- This feature requires [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer.
-- This feature requires [Gitaly](https://gitlab.com/gitlab-org/gitaly) 1.21.0 or newer.
-- After the merge request pipeline succeeds, if the target branch has moved forward, the result of the pipeline is stale and must be retried. In busy repos, this can become a problem as it is highly probable that the target branch will have moved ahead. Improvements are [planned](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186) for future versions of GitLab.
-- Forking/cross-repo workflows are not currently supported. To follow progress, see [#9713](https://gitlab.com/gitlab-org/gitlab-ee/issues/9713).
-- This feature is not available for [fast forward merges](../../user/project/merge_requests/fast_forward_merge.md) yet. To follow progress, see [#58226](https://gitlab.com/gitlab-org/gitlab-ce/issues/58226).
+Read the [documentation on Merge Trains](pipelines_for_merged_results/merge_trains/index.md).
 
 ## Excluding certain jobs
 
@@ -206,3 +168,15 @@ to integrate your job with [GitLab Merge Request API](../../api/merge_requests.m
 
 You can find the list of available variables in [the reference sheet](../variables/predefined_variables.md).
 The variable names begin with the `CI_MERGE_REQUEST_` prefix.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline.png
new file mode 100644
index 00000000000..6d4b66824e1
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline.png
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline_config.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline_config.png
new file mode 100644
index 00000000000..3ee9d8ec93b
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline_config.png
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md
new file mode 100644
index 00000000000..ad07c662965
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md
@@ -0,0 +1,93 @@
+---
+type: reference
+last_update: 2019-07-03
+---
+
+# Pipelines for Merged Results **(PREMIUM)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7380) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
+
+It's possible for your source and target branches to diverge, which can result
+in the scenario that source branch's pipeline was green, the target's pipeline was green,
+but the combined output fails.
+
+By having your merge request pipeline automatically
+create a new ref that contains the merge result of the source and target branch
+(then running a pipeline on that ref), we can better test that the combined result
+is also valid.
+
+GitLab can run pipelines for merge requests
+on this merged result. That is, where the source and target branches are combined into a
+new ref and a pipeline for this ref validates the result prior to merging.
+
+![Merge request pipeline as the head pipeline](img/merge_request_pipeline.png)
+
+There are some cases where creating a combined ref is not possible or not wanted.
+For example, a source branch that has conflicts with the target branch
+or a merge request that is still in WIP status. In this case,
+GitLab doesn't create a merge commit and the pipeline runs on source branch, instead,
+which is a default behavior of [Pipelines for merge requests](../index.md)
+ i.e. `detached` label is shown to the pipelines.
+
+The detached state serves to warn you that you are working in a situation
+subjected to merge problems, and helps to highlight that you should
+get out of WIP status or resolve merge conflicts as soon as possible.
+
+## Requirements and limitations
+
+Pipelines for merged results require:
+
+- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer.
+- [Gitaly](https://gitlab.com/gitlab-org/gitaly) 1.21.0 or newer.
+
+In addition, pipelines for merged results have the following limitations:
+
+- Forking/cross-repo workflows are not currently supported. To follow progress,
+  see [#11934](https://gitlab.com/gitlab-org/gitlab-ee/issues/11934).
+- This feature is not available for
+  [fast forward merges](../../../user/project/merge_requests/fast_forward_merge.md) yet.
+  To follow progress, see [#58226](https://gitlab.com/gitlab-org/gitlab-ce/issues/58226).
+
+## Enabling Pipelines for Merged Results
+
+To enable pipelines on merged results at the project level:
+
+1. Visit your project's **Settings > General** and expand **Merge requests**.
+1. Check **Merge pipelines will try to validate the post-merge result prior to merging**.
+1. Click **Save changes** button.
+
+![Merge request pipeline config](img/merge_request_pipeline_config.png)
+
+CAUTION: **Warning:**
+Make sure your `gitlab-ci.yml` file is [configured properly for pipelines for merge requests](../index.md#configuring-pipelines-for-merge-requests),
+otherwise pipelines for merged results won't run and your merge requests will be stuck in an unresolved state.
+
+## Troubleshooting
+
+### Pipelines for merged results not created even with new change pushed to merge request
+
+Can be caused by some disabled feature flags. Please make sure that
+the following feature flags are enabled on your GitLab instance:
+
+- `:ci_use_merge_request_ref`
+- `:merge_ref_auto_sync`
+
+To check these feature flag values, please ask administrator to execute the following commands:
+
+```shell
+> sudo gitlab-rails console                         # Login to Rails console of GitLab instance.
+> Feature.enabled?(:ci_use_merge_request_ref)       # Check if it's enabled or not.
+> Feature.enable(:ci_use_merge_request_ref)         # Enable the feature flag.
+```
+
+## Using Merge Trains **(PREMIUM)**
+
+By enabling [Pipelines for merged results](#pipelines-for-merged-results-premium),
+GitLab will [automatically display](merge_trains/index.md#how-to-add-a-merge-request-to-a-merge-train)
+a **Start/Add Merge Train button** as the most recommended merge strategy.
+
+Generally, this is a safer option than merging merge requests immediately as your
+merge request will be evaluated with an expected post-merge result before the actual
+merge happens.
+
+For more information, read the [documentation on Merge Trains](merge_trains/index.md).
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_cancel_v12_0.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_cancel_v12_0.png
new file mode 100644
index 00000000000..d7720ac1143
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_cancel_v12_0.png
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_config_v12_0.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_config_v12_0.png
new file mode 100644
index 00000000000..9da959ad440
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_config_v12_0.png
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_failure.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_failure.png
new file mode 100644
index 00000000000..8a795fff432
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_failure.png
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_immediate_merge.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_immediate_merge.png
new file mode 100644
index 00000000000..03bc61129ba
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_immediate_merge.png
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_position_v12_0.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_position_v12_0.png
new file mode 100644
index 00000000000..ec4b157d428
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_position_v12_0.png
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_v12_0.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_v12_0.png
new file mode 100644
index 00000000000..a4d0c8cf0e6
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_v12_0.png
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_when_pipeline_succeeds_v12_0.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_when_pipeline_succeeds_v12_0.png
new file mode 100644
index 00000000000..45762b8e85e
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_when_pipeline_succeeds_v12_0.png
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md
new file mode 100644
index 00000000000..80a1c264bc4
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md
@@ -0,0 +1,144 @@
+---
+type: reference
+last_update: 2019-07-03
+---
+
+# Merge Trains **(PREMIUM)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.0.
+
+[Pipelines for merged results](../index.md#pipelines-for-merged-results-premium) introduces
+running a build on the result of the merged code prior to merging, as a way to keep master green.
+
+There's a scenario, however, for teams with a high number of changes in the target branch (typically master) where in many or even all cases,
+by the time the merged code is validated another commit has made it to master, invalidating the merged result.
+You'd need some kind of queuing, cancellation or retry mechanism for these scenarios
+in order to ensure an orderly flow of changes into the target branch.
+
+Each MR that joins a merge train joins as the last item in the train,
+just as it works in the current state. However, instead of queuing and waiting,
+each item takes the completed state of the previous (pending) merge ref, adds its own changes,
+and starts the pipeline immediately in parallel under the assumption that everything is going to pass.
+
+In this way, if all the pipelines in the train merge successfully, no pipeline time is wasted either queuing or retrying.
+If the button is subsequently pressed in a different MR, instead of creating a new pipeline for the target branch,
+it creates a new pipeline targeting the merge result of the previous MR plus the target branch.
+Pipelines invalidated through failures are immediately canceled and requeued.
+
+## Requirements and limitations
+
+Merge trains have the following requirements and limitations:
+
+- This feature requires that
+  [pipelines for merged results](../index.md#pipelines-for-merged-results-premium) are
+  **configured properly**.
+- Each merge train can run a maximum of **four** pipelines in parallel.
+  If more than four merge requests are added to the merge train, the merge requests
+  will be queued until a slot in the merge train is free. There is no limit to the
+  number of merge requests that can be queued.
+- This feature does not support [squash and merge](../../../../user/project/merge_requests/squash_and_merge.md).
+
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+Watch this video for a demonstration on [how parallel execution
+of Merge Trains can prevent commits from breaking the default
+branch](https://www.youtube.com/watch?v=D4qCqXgZkHQ).
+
+## How to add a merge request to a merge train
+
+To add a merge request to a merge train:
+
+1. Visit a merge request.
+1. Click the **Start/Add to merge train** button.
+
+![Start merge train](img/merge_train_start_v12_0.png)
+
+## How to remove a merge request from a merge train
+
+1. Visit a merge request.
+1. Click the **Remove from merge train** button.
+
+![Cancel merge train](img/merge_train_cancel_v12_0.png)
+
+## How to view a merge request's current position on the merge train
+
+After a merge request has been added to the merge train, the merge request's
+current position will be displayed under the pipeline widget:
+
+![Merge train position indicator](img/merge_train_position_v12_0.png)
+
+## Start/Add to merge train when pipeline succeeds
+
+You can add a merge request to a merge train only when the latest pipeline in the
+merge request finished. While the pipeline is running or pending, you cannot add
+the merge request to a train because the current change of the merge request may
+be broken thus it could affect the following merge requests.
+
+In this case, you can schedule to add the merge request to a merge train **when the latest
+pipeline succeeds** (This pipeline is [Pipelines for merged results](../index.md), not Pipelines for merge train).
+You can see the following button instead of the regular **Start/Add to merge train**
+button while the latest pipeline is running.
+
+![Add to merge train when pipeline succeeds](img/merge_train_start_when_pipeline_succeeds_v12_0.png)
+
+## Immediately merge a merge request with a merge train
+
+In case, you have a high-priority merge request (e.g. critical patch) to be merged urgently,
+you can use **Merge Immediately** option for bypassing the merge train.
+This is the fastest option to get the change merged into the target branch.
+
+![Merge Immediately](img/merge_train_immediate_merge.png)
+
+However, every time you merge a merge request immediately, it could affect the
+existing merge train to be reconstructed, specifically, it regenerates expected
+merge commits and pipelines. This means, merging immediately essentially wastes
+CI resources.
+
+## Troubleshooting
+
+### Merge request dropped from the merge train immediately
+
+If a merge request is not mergeable (for example, it's WIP, there is a merge
+conflict, etc), your merge request will be dropped from the merge train automatically.
+
+In these cases, the reason for dropping the merge request is in the **system notes**.
+
+To check the reason:
+
+1. Open the merge request that was dropped from the merge train.
+1. Open the **Discussion** tab.
+1. Find a system note that includes either:
+   - The text **... removed this merge request from the merge train because ...**
+   - **... aborted this merge request from the merge train because ...**
+   The reason is given in the text after the **because ...** phrase.
+
+![Merge Train Failure](img/merge_train_failure.png)
+
+### Merge When Pipeline Succeeds cannot be chosen
+
+[Merge When Pipeline Succeeds](../../../../user/project/merge_requests/merge_when_pipeline_succeeds.md)
+is unavailable when
+[Pipelines for Merged Results is enabled](../index.md#enabling-pipelines-for-merged-results).
+
+Follow [this issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/12267) to
+track progress on this issue.
+
+### Merge Train disturbs your workflow
+
+First of all, please check if [merge immediately](#immediately-merge-a-merge-request-with-a-merge-train)
+is available as a workaround in your workflow. This is the most recommended
+workaround you'd be able to take immediately. If it's not available or acceptable,
+please read through this section.
+
+Merge train is enabled by default when you enable [Pipelines for merged results](../index.md),
+however, you can forcibly disable this feature by disabling the feature flag `:merge_trains_enabled`.
+After you disabled this feature, all the existing merge trains will be aborted and
+you will no longer see the **Start/Add Merge Train** button in merge requests.
+
+To check if the feature flag is enabled on your GitLab instance,
+please ask administrator to execute the following commands:
+
+```shell
+> sudo gitlab-rails console                         # Login to Rails console of GitLab instance.
+> Feature.enabled?(:merge_trains_enabled)           # Check if it's enabled or not.
+> Feature.disable(:merge_trains_enabled)            # Disable the feature flag.
+```
\ No newline at end of file
diff --git a/doc/ci/metrics_reports.md b/doc/ci/metrics_reports.md
index f9cfc0892a7..4d3f5a143f7 100644
--- a/doc/ci/metrics_reports.md
+++ b/doc/ci/metrics_reports.md
@@ -2,9 +2,9 @@
 type: reference
 ---
 
-# Metrics Reports **[PREMIUM]**
+# Metrics Reports **(PREMIUM)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9788) in [GitLab Premium](https://about.gitlab.com/pricing) 11.10.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9788) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
 Requires GitLab Runner 11.10 and above.
 
 ## Overview
diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md
index 50c8d82602b..cb8d383f7d9 100644
--- a/doc/ci/multi_project_pipelines.md
+++ b/doc/ci/multi_project_pipelines.md
@@ -2,7 +2,7 @@
 type: reference
 ---
 
-# Multi-project pipelines **[PREMIUM]**
+# Multi-project pipelines **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/2121) in
 [GitLab Premium 9.3](https://about.gitlab.com/2017/06/22/gitlab-9-3-released/#multi-project-pipeline-graphs).
@@ -171,6 +171,26 @@ In this scenario, the `UPSTREAM_BRANCH` variable with a value related to the
 upstream pipeline will be passed to the `downstream-job` job, and will be available
 within the context of all downstream builds.
 
+NOTE: **Tip:**
+Upstream pipelines take precedence over downstream ones. If there are two
+variables with the same name defined in both upstream and downstream projects,
+the ones defined in the upstream project will take precedence.
+
+### Mirroring status from upstream pipeline
+
+You can mirror the pipeline status from an upstream pipeline to a bridge job by
+using the `needs:pipeline` keyword. The latest pipeline status from master is
+replicated to the bridge job.
+
+Example:
+
+```yaml
+upstream_bridge:
+  stage: test
+  needs:
+    pipeline: other/project
+```
+
 ### Limitations
 
 Because bridge jobs are a little different to regular jobs, it is not
diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md
index 1ad3d516df9..ed8d0e3bc35 100644
--- a/doc/ci/pipelines.md
+++ b/doc/ci/pipelines.md
@@ -6,6 +6,11 @@ type: reference
 
 > Introduced in GitLab 8.8.
 
+NOTE: **Tip:**
+Watch our
+["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/)
+webcast to see a comprehensive demo of GitLab CI/CD pipeline.
+
 ## Introduction
 
 Pipelines are the top-level component of continuous integration, delivery, and deployment.
@@ -139,6 +144,20 @@ The union of A, B, and C is (1, 4) and (6, 7). Therefore, the total running time
 (4 - 1) + (7 - 6) => 4
 ```
 
+### Expanding and collapsing job log sections
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/14664) in GitLab
+> 12.0.
+
+Job logs are divided into sections that can be collapsed or expanded.
+
+In the following example:
+
+- Two sections are expanded and can be collapsed.
+- One section is collapsed and can be expanded.
+
+![Collapsible sections](img/collapsible_log.png)
+
 ## Configuring pipelines
 
 Pipelines, and their component jobs and stages, are defined in the [`.gitlab-ci.yml`](yaml/README.md) file for each project.
@@ -220,7 +239,7 @@ Pipeline status and test coverage report badges are available and configurable f
 
 For information on adding pipeline badges to projects, see [Pipeline badges](../user/project/pipelines/settings.md#pipeline-badges).
 
-## Multi-project pipelines **[PREMIUM]**
+## Multi-project pipelines **(PREMIUM)**
 
 Pipelines for different projects can be combined and visualized together.
 
@@ -304,6 +323,20 @@ stage has a job with a manual action.
 
 ![Pipelines example](img/pipelines.png)
 
+### Specifying variables when running manual jobs
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30485) in GitLab 12.2.
+
+When running manual jobs you can supply additional job specific variables.
+
+You can do this from the job page of the manual job you want to run with
+additional variables.
+
+This is useful when you want to alter the execution of a job by using
+environment variables.
+
+![Manual job variables](img/manual_job_variables.png)
+
 ### Delay a job in a pipeline graph
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21767) in GitLab 11.4.
@@ -331,7 +364,7 @@ GitLab provides API endpoints to:
   - [Triggering pipelines through the API](triggers/README.md).
   - [Pipeline triggers API](../api/pipeline_triggers.md).
 
-### Start multiple manual actions in a stage
+### Start multiple manual actions in a stage
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27188) in GitLab 11.11.
 
diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md
index 11bcfd5dc2c..5626428bfc3 100644
--- a/doc/ci/quick_start/README.md
+++ b/doc/ci/quick_start/README.md
@@ -13,6 +13,10 @@ NOTE: **Note:**
 Please keep in mind that only project Maintainers and Admin users have
 the permissions to access a project's settings.
 
+NOTE: **Note:**
+Coming over to GitLab from Jenkins? Check out our [reference](../jenkins/index.md)
+for converting your pre-existing pipelines over to our format.
+
 GitLab offers a [continuous integration][ci] service. If you
 [add a `.gitlab-ci.yml` file][yaml] to the root directory of your repository,
 and configure your GitLab project to use a [Runner], then each commit or
@@ -233,7 +237,7 @@ CI with various languages.
 [runner-install]: https://docs.gitlab.com/runner/install/
 [blog-ci]: https://about.gitlab.com/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/
 [examples]: ../examples/README.md
-[ci]: https://about.gitlab.com/gitlab-ci/
+[ci]: https://about.gitlab.com/product/continuous-integration/
 [yaml]: ../yaml/README.md
 [runner]: ../runners/README.md
 [enabled]: ../enable_or_disable_ci.md
diff --git a/doc/ci/quick_start/img/build_log.png b/doc/ci/quick_start/img/build_log.png
index 2bf0992c50e..16698629edc 100644
--- a/doc/ci/quick_start/img/build_log.png
+++ b/doc/ci/quick_start/img/build_log.png
diff --git a/doc/ci/quick_start/img/builds_status.png b/doc/ci/quick_start/img/builds_status.png
index 58978e23978..b4aeeb988d2 100644
--- a/doc/ci/quick_start/img/builds_status.png
+++ b/doc/ci/quick_start/img/builds_status.png
diff --git a/doc/ci/quick_start/img/pipelines_status.png b/doc/ci/quick_start/img/pipelines_status.png
index 06d1559f5d2..39a77a26b25 100644
--- a/doc/ci/quick_start/img/pipelines_status.png
+++ b/doc/ci/quick_start/img/pipelines_status.png
diff --git a/doc/ci/quick_start/img/runners_activated.png b/doc/ci/quick_start/img/runners_activated.png
index cd83c1a7e4c..ac09e1d0137 100644
--- a/doc/ci/quick_start/img/runners_activated.png
+++ b/doc/ci/quick_start/img/runners_activated.png
diff --git a/doc/ci/review_apps/img/review_button.png b/doc/ci/review_apps/img/review_button.png
new file mode 100644
index 00000000000..4f1cf4d7cfd
--- /dev/null
+++ b/doc/ci/review_apps/img/review_button.png
diff --git a/doc/ci/review_apps/img/toolbar_feeback_form.png b/doc/ci/review_apps/img/toolbar_feeback_form.png
new file mode 100644
index 00000000000..fe1c7e6e611
--- /dev/null
+++ b/doc/ci/review_apps/img/toolbar_feeback_form.png
diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md
index 7b039fe6654..8ab7982fd65 100644
--- a/doc/ci/review_apps/index.md
+++ b/doc/ci/review_apps/index.md
@@ -27,7 +27,7 @@ In the above example:
 - Once the review as passed, `topic branch` is merged into `master` where it's deploy to staging.
 - After been approved in staging, the changes that were merged into `master` are deployed in to production.
 
-### How Review Apps work
+## How Review Apps work
 
 A Review App is a mapping of a branch with an [environment](../environments.md).
 Access to the Review App is made available as a link on the [merge request](../../user/project/merge_requests.md) relevant to the branch.
@@ -41,27 +41,34 @@ In this example, a branch was:
 - Successfully built.
 - Deployed under a dynamic environment that can be reached by clicking on the **View app** button.
 
+After adding Review Apps to your workflow, you follow the branched Git flow. That is:
+
+1. Push a branch and let the Runner deploy the Review App based on the `script` definition of the dynamic environment job.
+1. Wait for the Runner to build and deploy your web application.
+1. Click on the link provided in the merge request related to the branch to see the changes live.
+
 ## Configuring Review Apps
 
 Review Apps are built on [dynamic environments](../environments.md#configuring-dynamic-environments), which allow you to dynamically create a new environment for each branch.
 
 The process of configuring Review Apps is as follows:
 
-1. Set up the infrastructure to host and deploy the Review Apps.
+1. Set up the infrastructure to host and deploy the Review Apps (check the [examples](#review-apps-examples) below).
 1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a Runner to do deployment.
 1. Set up a job in `.gitlab-ci.yml` that uses the [predefined CI environment variable](../variables/README.md) `${CI_COMMIT_REF_NAME}` to create dynamic environments and restrict it to run only on branches.
 1. Optionally, set a job that [manually stops](../environments.md#stopping-an-environment) the Review Apps.
 
-### Examples
+## Review Apps examples
 
 The following are example projects that demonstrate Review App configuration:
 
 - [NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx).
 - [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift).
 
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
 See also the video [Demo: Cloud Native Development with GitLab](https://www.youtube.com/watch?v=jfIyQEwrocw), which includes a Review Apps example.
 
-### Route Maps
+## Route Maps
 
 > Introduced in GitLab 8.17. In GitLab 11.5, the file links are available in the merge request widget.
 
@@ -82,7 +89,7 @@ To set up a route map, add a a file inside the repository at `.gitlab/route-map.
 which contains a YAML array that maps `source` paths (in the repository) to `public`
 paths (on the website).
 
-#### Route Maps example
+### Route Maps example
 
 The following is an example of a route map for [Middleman](https://middlemanapp.com),
 a static site generator (SSG) used to build [GitLab's website](https://about.gitlab.com),
@@ -140,19 +147,108 @@ Once you have the route mapping set up, it will take effect in the following loc
 
 - In the diff for a merge request, comparison, or commit.
 
-    !["View on env" button in merge request diff](img/view_on_env_mr.png)
+  !["View on env" button in merge request diff](img/view_on_env_mr.png)
 
 - In the blob file view.
 
-    !["View on env" button in file view](img/view_on_env_blob.png)
+  !["View on env" button in file view](img/view_on_env_blob.png)
 
-## Working with Review Apps
+## Visual Reviews **(STARTER)**
 
-After adding Review Apps to your workflow, you follow the branched Git flow. That is:
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/10761) in GitLab Starter 12.0.
 
-1. Push a branch and let the Runner deploy the Review App based on the `script` definition of the dynamic environment job.
-1. Wait for the Runner to build and deploy your web application.
-1. Click on the link that provided in the merge request related to the branch to see the changes live.
+With Visual Reviews, you can provide a feedback form to your Review Apps so
+that reviewers can post comments directly from the app back to the merge request
+that spawned the Review App.
+
+### Configuring Visual Reviews
+
+The feedback form is served through a script you add to pages in your Review App.
+If you have [Developer permissions](../../user/permissions.md) to the project,
+you can access it by clicking the **Review** button in the **Pipeline** section
+of the merge request.
+
+![review button](img/review_button.png)
+
+The provided script should be added to the `<head>` of you application and
+consists of some project and merge request specific values. Here's what it
+looks like:
+
+```html
+<script
+  data-project-id='11790219'
+  data-merge-request-id='1'
+  data-mr-url='https://gitlab.example.com'
+  data-project-path='sarah/review-app-tester'
+  id='review-app-toolbar-script'
+  src='https://gitlab.example.com/assets/webpack/visual_review_toolbar.js'>
+</script>
+```
+
+Ideally, you should use [environment variables](../variables/predefined_variables.md)
+to replace those values at runtime when each review app is created:
+
+- `data-project-id` is the project ID, which can be found by the `CI_PROJECT_ID`
+  variable.
+- `data-merge-request-id` is the merge request ID, which can be found by the
+  `CI_MERGE_REQUEST_IID` variable. `CI_MERGE_REQUEST_IID` is available only if
+  [`only: [merge_requests]`](../merge_request_pipelines/index.md)
+  is used and the merge request is created.
+- `data-mr-url` is the URL of the GitLab instance and will be the same for all
+  review apps.
+- `data-project-path` is the project's path, which can be found by `CI_PROJECT_PATH`.
+- `id` is always `review-app-toolbar-script`, you don't need to change that.
+- `src` is the source of the review toolbar script, which resides in the
+  respective GitLab instance and will be the same for all review apps.
+
+For example, in a Ruby application, you would need to have this script:
+
+```html
+<script
+  data-project-id="ENV['CI_PROJECT_ID']"
+  data-merge-request-id="ENV['CI_MERGE_REQUEST_IID']"
+  data-mr-url='https://gitlab.example.com'
+  data-project-path="ENV['CI_PROJECT_PATH']"
+  id='review-app-toolbar-script'
+  src='https://gitlab.example.com/assets/webpack/visual_review_toolbar.js'>
+</script>
+```
+
+Then, when your app is deployed via GitLab CI/CD, those variables should get
+replaced with their real values.
+
+NOTE: **Note:**
+Future enhancements [are planned](https://gitlab.com/gitlab-org/gitlab-ee/issues/11322)
+to make this process even easier.
+
+### Using Visual Reviews
+
+After Visual Reviews has been [enabled](#configuring-visual-reviews) for the
+Review App, the Visual Reviews feedback form is overlaid on the app's pages at
+the bottom-right corner.
+
+![Visual review feedback form](img/toolbar_feeback_form.png)
+
+To use the feedback form:
+
+1. Create a [personal access token](../../user/profile/personal_access_tokens.md)
+   with the API scope selected.
+1. Paste the token into the feedback box when prompted. If you select **Remember me**,
+   your browser stores the token so that future visits to Review Apps at the same URL
+   will not require you to re-enter the token. To clear the token, click **Log out**.
+1. Make a comment on the visual review. You can make use of all the
+   [Markdown annotations](../../user/markdown.md) that are also available in
+   merge request comments.
+1. Finally, click **Send feedback**.
+
+After you make and submit a comment in the visual review box, it will appear
+automatically in the respective merge request.
+
+TIP: **Tip:**
+Because tokens must be entered on a per-domain basis and they can only be accessed
+once, different review apps will not remember your token. You can save the token
+to your password manager specifically for the purpose of Visual Reviews. This way,
+you will not need to create additional tokens for each merge request.
 
 ## Limitations
 
diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md
index b089229ab58..269bd5c3428 100644
--- a/doc/ci/runners/README.md
+++ b/doc/ci/runners/README.md
@@ -62,7 +62,7 @@ You can only register a shared Runner if you are an admin of the GitLab instance
 
 1. Grab the shared-Runner token on the `admin/runners` page
 
-    ![Shared Runners admin area](img/shared_runners_admin.png)
+   ![Shared Runners admin area](img/shared_runners_admin.png)
 
 1. [Register the Runner][register]
 
@@ -88,7 +88,7 @@ visit the project you want to make the Runner work for in GitLab:
 
 ## Registering a group Runner
 
-Creating a group Runner requires Maintainer permissions for the group. To create a
+Creating a group Runner requires Owner permissions for the group. To create a
 group Runner visit the group you want to make the Runner work for in GitLab:
 
 1. Go to **Settings > CI/CD** to obtain the token
@@ -124,9 +124,9 @@ To lock/unlock a Runner:
 
 ## Assigning a Runner to another project
 
-If you are Maintainer on a project where a specific Runner is assigned to, and the
+If you are an Owner on a project where a specific Runner is assigned to, and the
 Runner is not [locked only to that project](#locking-a-specific-runner-from-being-enabled-for-other-projects),
-you can enable the Runner also on any other project where you have Maintainer permissions.
+you can enable the Runner also on any other project where you have Owner permissions.
 
 To enable/disable a Runner in your project:
 
@@ -250,7 +250,7 @@ When you [register a Runner][register], its default behavior is to **only pick**
 [tagged jobs](../yaml/README.md#tags).
 
 NOTE: **Note:**
-Maintainer [permissions](../../user/permissions.md) are required to change the
+Owner [permissions](../../user/permissions.md) are required to change the
 Runner settings.
 
 To make a Runner pick untagged jobs:
@@ -319,21 +319,21 @@ How this feature will work:
 1. You set the _maximum job timeout_ for a Runner to 24 hours
 1. You set the _CI/CD Timeout_ for a project to **2 hours**
 1. You start a job
-1. The job, if running longer, will be timeouted after **2 hours**
+1. The job, if running longer, will be timed out after **2 hours**
 
 **Example 2 - Runner timeout not configured**
 
 1. You remove the _maximum job timeout_ configuration from a Runner
 1. You set the _CI/CD Timeout_ for a project to **2 hours**
 1. You start a job
-1. The job, if running longer, will be timeouted after **2 hours**
+1. The job, if running longer, will be timed out after **2 hours**
 
 **Example 3 - Runner timeout smaller than project timeout**
 
 1. You set the _maximum job timeout_ for a Runner to **30 minutes**
 1. You set the _CI/CD Timeout_ for a project to 2 hours
 1. You start a job
-1. The job, if running longer, will be timeouted after **30 minutes**
+1. The job, if running longer, will be timed out after **30 minutes**
 
 ### Be careful with sensitive information
 
@@ -373,12 +373,12 @@ attacker.
 
 To reset the token:
 
-1. Go to **Settings > CI/CD** for a specified Project
-1. Expand the **General pipelines settings** section
-1. Find the **Runner token** form field and click the **Reveal value** button
-1. Delete the value and save the form
+1. Go to **Settings > CI/CD** for a specified Project.
+1. Expand the **General pipelines settings** section.
+1. Find the **Runner token** form field and click the **Reveal value** button.
+1. Delete the value and save the form.
 1. After the page is refreshed, expand the **Runners settings** section
-    and check the registration token - it should be changed
+   and check the registration token - it should be changed.
 
 From now on the old token is not valid anymore and will not allow to register
 a new Runner to the project. If you are using any tools to provision and
@@ -418,9 +418,9 @@ You can find the IP address of a Runner for a specific project by:
 
 ![specific Runner IP address](img/specific_runner_ip_address.png)
 
-[install]: http://docs.gitlab.com/runner/install/
+[install]: https://docs.gitlab.com/runner/install/
 [fifo]: https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)
-[register]: http://docs.gitlab.com/runner/register/
+[register]: https://docs.gitlab.com/runner/register/
 [protected branches]: ../../user/project/protected_branches.md
 [protected tags]: ../../user/project/protected_tags.md
 [project defined timeout]: ../../user/project/pipelines/settings.html#timeout
diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md
index 697452cee83..9ea113969c8 100644
--- a/doc/ci/services/mysql.md
+++ b/doc/ci/services/mysql.md
@@ -25,6 +25,12 @@ variables:
   MYSQL_ROOT_PASSWORD: "<your_mysql_password>"
 ```
 
+NOTE: **Note:**
+The `MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` variables can't be set in the GitLab UI.
+To set them, assign them to a variable [in the UI](../variables/README.md#via-the-ui), 
+and then assign that variable to the 
+`MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` variables in your `.gitlab-ci.yml`.
+
 And then configure your application to use the database, for example:
 
 ```yaml
diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md
index 211eea26eb0..142f4f262e5 100644
--- a/doc/ci/services/postgres.md
+++ b/doc/ci/services/postgres.md
@@ -25,6 +25,13 @@ variables:
   POSTGRES_PASSWORD: ""
 ```
 
+NOTE: **Note:**
+The `POSTGRES_DB`, `POSTGRES_USER`, and `POSTGRES_PASSWORD` variables can't be set in
+the GitLab UI. To set them, assign them to a variable
+[in the UI](../variables/README.md#via-the-ui), and then assign that
+variable to the `POSTGRES_DB`, `POSTGRES_USER`, and `POSTGRES_PASSWORD` variables in
+your `.gitlab-ci.yml`.
+
 And then configure your application to use the database, for example:
 
 ```yaml
@@ -70,7 +77,7 @@ template1=# CREATE USER runner WITH PASSWORD '$password' CREATEDB;
 ```
 
 *__Note:__ Notice that we created the user with the privilege to be able to
-create databases (`CREATEDB`). In the following steps we will create a database 
+create databases (`CREATEDB`). In the following steps we will create a database
 explicitly for that user but having that privilege can be useful if in your
 testing framework you have tools that drop and create databases.*
 
@@ -114,5 +121,5 @@ available [shared runners](../runners/README.md).
 Want to hack on it? Simply fork it, commit and push  your changes. Within a few
 moments the changes will be picked by a public runner and the job will begin.
 
-[hub-pg]: https://hub.docker.com/r/_/postgres/
+[hub-pg]: https://hub.docker.com/_/postgres
 [postgres-example-repo]: https://gitlab.com/gitlab-examples/postgres
diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md
index 69591ed605c..d9f022a7125 100644
--- a/doc/ci/ssh_keys/README.md
+++ b/doc/ci/ssh_keys/README.md
@@ -57,44 +57,44 @@ to access it. This is where an SSH key pair comes in handy.
 1. Modify your `.gitlab-ci.yml` with a `before_script` action. In the following
    example, a Debian based image is assumed. Edit to your needs:
 
-    ```yaml
-    before_script:
-      ##
-      ## Install ssh-agent if not already installed, it is required by Docker.
-      ## (change apt-get to yum if you use an RPM-based image)
-      ##
-      - 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )'
-
-      ##
-      ## Run ssh-agent (inside the build environment)
-      ##
-      - eval $(ssh-agent -s)
-
-      ##
-      ## Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store
-      ## We're using tr to fix line endings which makes ed25519 keys work
-      ## without extra base64 encoding.
-      ## https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556
-      ##
-      - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - > /dev/null
-
-      ##
-      ## Create the SSH directory and give it the right permissions
-      ##
-      - mkdir -p ~/.ssh
-      - chmod 700 ~/.ssh
-
-      ##
-      ## Optionally, if you will be using any Git commands, set the user name and
-      ## and email.
-      ##
-      #- git config --global user.email "user@example.com"
-      #- git config --global user.name "User name"
-    ```
-
-    NOTE: **Note:**
-    The [`before_script`](../yaml/README.md#before_script-and-after_script) can be set globally
-    or per-job.
+   ```yaml
+   before_script:
+     ##
+     ## Install ssh-agent if not already installed, it is required by Docker.
+     ## (change apt-get to yum if you use an RPM-based image)
+     ##
+     - 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )'
+
+     ##
+     ## Run ssh-agent (inside the build environment)
+     ##
+     - eval $(ssh-agent -s)
+
+     ##
+     ## Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store
+     ## We're using tr to fix line endings which makes ed25519 keys work
+     ## without extra base64 encoding.
+     ## https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556
+     ##
+     - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - > /dev/null
+
+     ##
+     ## Create the SSH directory and give it the right permissions
+     ##
+     - mkdir -p ~/.ssh
+     - chmod 700 ~/.ssh
+
+     ##
+     ## Optionally, if you will be using any Git commands, set the user name and
+     ## and email.
+     ##
+     #- git config --global user.email "user@example.com"
+     #- git config --global user.name "User name"
+   ```
+
+   NOTE: **Note:**
+   The [`before_script`](../yaml/README.md#before_script-and-after_script) can be set globally
+   or per-job.
 
 1. Make sure the private server's [SSH host keys are verified](#verifying-the-ssh-host-keys).
 
@@ -118,9 +118,9 @@ on, and use that key for all projects that are run on this machine.
 
 1. Then from the terminal login as the `gitlab-runner` user:
 
-    ```
-    sudo su - gitlab-runner
-    ```
+   ```
+   sudo su - gitlab-runner
+   ```
 
 1. Generate the SSH key pair as described in the instructions to
    [generate an SSH key](../../ssh/README.md#generating-a-new-ssh-key-pair).
diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md
index 04c541fefe7..2a382f18038 100644
--- a/doc/ci/triggers/README.md
+++ b/doc/ci/triggers/README.md
@@ -32,7 +32,7 @@ to protect trigger tokens.
 You can use the `CI_JOB_TOKEN` [variable][predef] (used to authenticate
 with the [GitLab Container Registry][registry]) in the following cases.
 
-#### When used with multi-project pipelines **[PREMIUM]**
+#### When used with multi-project pipelines **(PREMIUM)**
 
 > **Note**:
 The use of `CI_JOB_TOKEN` for multi-project pipelines was [introduced][ee-2017]
@@ -56,7 +56,7 @@ Pipelines triggered that way also expose a special variable:
 
 Read more about the [pipelines trigger API][trigapi].
 
-#### When a pipeline depends on the artifacts of another pipeline **[PREMIUM]**
+#### When a pipeline depends on the artifacts of another pipeline **(PREMIUM)**
 
 > The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346]
   in [GitLab Premium][ee] 9.5.
@@ -97,17 +97,6 @@ overview of the time the triggers were last used.
 
 ![Triggers page overview](img/triggers_page.png)
 
-## Taking ownership of a trigger
-
-> **Note**:
-GitLab 9.0 introduced a trigger ownership to solve permission problems.
-
-Each created trigger when run will impersonate their associated user including
-their access to projects and their project permissions.
-
-You can take ownership of existing triggers by clicking *Take ownership*.
-From now on the trigger will be run as you.
-
 ## Revoking a trigger
 
 You can revoke a trigger any time by going at your project's
@@ -282,8 +271,7 @@ Old triggers, created before GitLab 9.0 will be marked as legacy.
 
 Triggers with the legacy label do not have an associated user and only have
 access to the current project. They are considered deprecated and will be
-removed with one of the future versions of GitLab. You are advised to
-[take ownership](#taking-ownership-of-a-trigger) of any legacy triggers.
+removed with one of the future versions of GitLab. 
 
 [ee-2017]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2017
 [ee-2346]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2346
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index df455857dee..5a15b907da0 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -27,8 +27,7 @@ CI/CD's pipelines. Using variables means no hardcoded values.
 
 ### Predefined environment variables
 
-GitLab CI/CD has a default set of
-[predefined variables](predefined_variables.md)
+GitLab CI/CD has a [default set of predefined variables](predefined_variables.md)
 which can be used without any specification needed.
 You can call issues numbers, user names, branch names,
 pipeline and commit IDs, and much more.
@@ -36,7 +35,7 @@ pipeline and commit IDs, and much more.
 Predefined environment variables are the ones that GitLab
 provides out of the box for the local environment of the Runner.
 
-GitLab reads the .gitlab-ci.yml file, sends the information
+GitLab reads the `.gitlab-ci.yml` file, sends the information
 to the Runner (which runs the script commands), under which
 the variables are exposed.
 
@@ -44,6 +43,9 @@ For example, two jobs under the same pipeline can share the same
 `CI_PIPELINE_ID` variable, but each one has its own `CI_JOB_ID`
 variable.
 
+NOTE: **Note:**
+Find here the full [**predefined variables reference table**](predefined_variables.md).
+
 ### Custom environment variables
 
 When your use case requires a specific variable, you can
@@ -92,7 +94,10 @@ This means that the value of the variable will be hidden in job logs,
 though it must match certain requirements to do so:
 
 - The value must be in a single line.
-- The value must only consist of characters from the Base64 alphabet, defined in [RFC4648](https://tools.ietf.org/html/rfc4648).
+- The value must only consist of characters from the Base64 alphabet (RFC4648).
+
+  [In GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-ce/issues/63043)
+  and newer, `@` and `:` are also valid values.
 - The value must be at least 8 characters long.
 - The value must not use variables.
 
@@ -271,6 +276,7 @@ export CI_RUNNER_ID="10"
 export CI_RUNNER_DESCRIPTION="my runner"
 export CI_RUNNER_TAGS="docker, linux"
 export CI_SERVER="yes"
+export CI_SERVER_HOST="example.com"
 export CI_SERVER_NAME="GitLab"
 export CI_SERVER_REVISION="70606bf"
 export CI_SERVER_VERSION="8.9.0"
@@ -337,7 +343,7 @@ Group-level variables can be added by:
 
 1. Navigating to your group's **Settings > CI/CD** page.
 1. Inputing variable types, keys, and values in the **Variables** section.
-Any variables of [subgroups](../../user/group/subgroups/index.md) will be inherited recursively.
+   Any variables of [subgroups](../../user/group/subgroups/index.md) will be inherited recursively.
 
 Once you set them, they will be available for all subsequent pipelines.
 
@@ -367,8 +373,11 @@ variables take precedence over those defined in `.gitlab-ci.yml`.
 ## Unsupported variables
 
 There are cases where some variables cannot be used in the context of a
-`.gitlab-ci.yml` definition (for example under `script`). Read more
-about which variables are [not supported](where_variables_can_be_used.md).
+`.gitlab-ci.yml` definition (for example under `script`). Read more about which variables are [not supported](where_variables_can_be_used.md).
+
+## Where variables can be used
+
+Click [here](where_variables_can_be_used.md) for a section that describes where and how the different types of variables can be used.
 
 ## Advanced use
 
@@ -387,7 +396,7 @@ Protected variables can be added by going to your project's
 
 Once you set them, they will be available for all subsequent pipelines.
 
-### Limiting environment scopes of environment variables **[PREMIUM]**
+### Limiting environment scopes of environment variables
 
 You can limit the environment scope of a variable by
 [defining which environments][envs] it can be available for.
@@ -478,81 +487,86 @@ Below you can find supported syntax reference:
 
 1. Equality matching using a string
 
-    > Example: `$VARIABLE == "some value"`
+   Examples:
 
-    > Example: `$VARIABLE != "some value"` _(added in 11.11)_
+   - `$VARIABLE == "some value"`
+   - `$VARIABLE != "some value"` (introduced in GitLab 11.11)
 
-    You can use equality operator `==` or `!=` to compare a variable content to a
-    string. We support both, double quotes and single quotes to define a string
-    value, so both `$VARIABLE == "some value"` and `$VARIABLE == 'some value'`
-    are supported. `"some value" == $VARIABLE` is correct too.
+   You can use equality operator `==` or `!=` to compare a variable content to a
+   string. We support both, double quotes and single quotes to define a string
+   value, so both `$VARIABLE == "some value"` and `$VARIABLE == 'some value'`
+   are supported. `"some value" == $VARIABLE` is correct too.
 
 1. Checking for an undefined value
 
-    > Example: `$VARIABLE == null`
+   Examples:
 
-    > Example: `$VARIABLE != null` _(added in 11.11)_
+   - `$VARIABLE == null`
+   - `$VARIABLE != null` (introduced in GitLab 11.11)
 
-    It sometimes happens that you want to check whether a variable is defined
-    or not. To do that, you can compare a variable to `null` keyword, like
-    `$VARIABLE == null`. This expression is going to evaluate to truth if
-    variable is not defined when `==` is used, or to falsey if `!=` is used.
+   It sometimes happens that you want to check whether a variable is defined
+   or not. To do that, you can compare a variable to `null` keyword, like
+   `$VARIABLE == null`. This expression is going to evaluate to truth if
+   variable is not defined when `==` is used, or to falsey if `!=` is used.
 
 1. Checking for an empty variable
 
-    > Example: `$VARIABLE == ""`
+   Examples:
 
-    > Example: `$VARIABLE != ""` _(added in 11.11)_
+   - `$VARIABLE == ""`
+   - `$VARIABLE != ""` (introduced in GitLab 11.11)
 
-    If you want to check whether a variable is defined, but is empty, you can
-    simply compare it against an empty string, like `$VAR == ''` or non-empty
-    string `$VARIABLE != ""`.
+   If you want to check whether a variable is defined, but is empty, you can
+   simply compare it against an empty string, like `$VAR == ''` or non-empty
+   string `$VARIABLE != ""`.
 
 1. Comparing two variables
 
-    > Example: `$VARIABLE_1 == $VARIABLE_2`
+   Examples:
 
-    > Example: `$VARIABLE_1 != $VARIABLE_2` _(added in 11.11)_
+   - `$VARIABLE_1 == $VARIABLE_2`
+   - `$VARIABLE_1 != $VARIABLE_2` (introduced in GitLab 11.11)
 
-    It is possible to compare two variables. This is going to compare values
-    of these variables.
+   It is possible to compare two variables. This is going to compare values
+   of these variables.
 
 1. Variable presence check
 
-    > Example: `$STAGING`
-
-    If you only want to create a job when there is some variable present,
-    which means that it is defined and non-empty, you can simply use
-    variable name as an expression, like `$STAGING`. If `$STAGING` variable
-    is defined, and is non empty, expression will evaluate to truth.
-    `$STAGING` value needs to a string, with length higher than zero.
-    Variable that contains only whitespace characters is not an empty variable.
+   Example: `$STAGING`
 
-1. Pattern matching  _(added in 11.0)_
+   If you only want to create a job when there is some variable present,
+   which means that it is defined and non-empty, you can simply use
+   variable name as an expression, like `$STAGING`. If `$STAGING` variable
+   is defined, and is non empty, expression will evaluate to truth.
+   `$STAGING` value needs to a string, with length higher than zero.
+   Variable that contains only whitespace characters is not an empty variable.
 
-    > Example: `$VARIABLE =~ /^content.*/`
+1. Pattern matching (introduced in GitLab 11.0)
 
-    > Example: `$VARIABLE_1 !~ /^content.*/` _(added in 11.11)_
+   Examples:
 
-    It is possible perform pattern matching against a variable and regular
-    expression. Expression like this evaluates to truth if matches are found
-    when using `=~`. It evaluates to truth if matches are not found when `!~` is used.
+   - `$VARIABLE =~ /^content.*/`
+   - `$VARIABLE_1 !~ /^content.*/` (introduced in GitLab 11.11)
 
-    Pattern matching is case-sensitive by default. Use `i` flag modifier, like
-    `/pattern/i` to make a pattern case-insensitive.
+   It is possible perform pattern matching against a variable and regular
+   expression. Expression like this evaluates to truth if matches are found
+   when using `=~`. It evaluates to truth if matches are not found when `!~` is used.
 
-1. Conjunction / Disjunction
+   Pattern matching is case-sensitive by default. Use `i` flag modifier, like
+   `/pattern/i` to make a pattern case-insensitive.
 
-    > Example: `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"`
+1. Conjunction / Disjunction ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27925) in GitLab 12.0)
 
-    > Example: `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 =~ /thing$/ && $VARIABLE3`
+   Examples:
 
-    > Example: `$VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/ && $VARIABLE3`
+   - `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"`
+   - `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 =~ /thing$/ && $VARIABLE3`
+   - `$VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/ && $VARIABLE3`
 
-    It is possible to join multiple conditions using `&&` or `||`. Any of the otherwise
-    supported syntax may be used in a conjunctive or disjunctive statement.
-    Precedence of operators follows standard Ruby 2.5 operation
-    [precedence](https://ruby-doc.org/core-2.5.0/doc/syntax/precedence_rdoc.html).
+   It is possible to join multiple conditions using `&&` or `||`. Any of the otherwise
+   supported syntax may be used in a conjunctive or disjunctive statement.
+   Precedence of operators follows standard Ruby 2.5 operation
+   [precedence](https://ruby-doc.org/core-2.5.0/doc/syntax/precedence_rdoc.html).
 
 ## Debug tracing
 
@@ -642,6 +656,8 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach
 ++ CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace
 ++ export CI_SERVER=yes
 ++ CI_SERVER=yes
+++ export 'CI_SERVER_HOST=example.com'
+++ CI_SERVER_HOST='example.com'
 ++ export 'CI_SERVER_NAME=GitLab CI'
 ++ CI_SERVER_NAME='GitLab CI'
 ++ export CI_SERVER_VERSION=
@@ -676,6 +692,8 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach
 ++ CI_JOB_NAME=debug_trace
 ++ export CI_JOB_STAGE=test
 ++ CI_JOB_STAGE=test
+++ export CI_SERVER_HOST=example.com
+++ CI_SERVER_HOST=example.com
 ++ export CI_SERVER_NAME=GitLab
 ++ CI_SERVER_NAME=GitLab
 ++ export CI_SERVER_VERSION=8.14.3-ee
diff --git a/doc/ci/variables/img/custom_variables_output.png b/doc/ci/variables/img/custom_variables_output.png
index 29f5c63b3d9..797e9ec07b9 100644
--- a/doc/ci/variables/img/custom_variables_output.png
+++ b/doc/ci/variables/img/custom_variables_output.png
diff --git a/doc/ci/variables/img/new_custom_variables_example.png b/doc/ci/variables/img/new_custom_variables_example.png
index efe104efe4c..bb60e6bab21 100644
--- a/doc/ci/variables/img/new_custom_variables_example.png
+++ b/doc/ci/variables/img/new_custom_variables_example.png
diff --git a/doc/ci/variables/img/override_variable_manual_pipeline.png b/doc/ci/variables/img/override_variable_manual_pipeline.png
index 3c8c59720cf..c77c5cb7764 100644
--- a/doc/ci/variables/img/override_variable_manual_pipeline.png
+++ b/doc/ci/variables/img/override_variable_manual_pipeline.png
diff --git a/doc/ci/variables/img/variable_types_usage_example.png b/doc/ci/variables/img/variable_types_usage_example.png
index 0e8bde891fe..c2ae32fd048 100644
--- a/doc/ci/variables/img/variable_types_usage_example.png
+++ b/doc/ci/variables/img/variable_types_usage_example.png
diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md
index 4655eec51de..409f7d62538 100644
--- a/doc/ci/variables/predefined_variables.md
+++ b/doc/ci/variables/predefined_variables.md
@@ -30,7 +30,7 @@ future GitLab releases.**
 | `CI_BUILDS_DIR`                         | all    | 11.10  | Top-level directory where builds are executed. |
 | `CI_CONCURRENT_ID`                      | all    | 11.10  | Unique ID of build execution within a single executor. |
 | `CI_CONCURRENT_PROJECT_ID`              | all    | 11.10  | Unique ID of build execution within a single executor and project. |
-| `CI_COMMIT_BEFORE_SHA`                  | 11.2   | all    | The previous latest commit present on a branch before a push request. |
+| `CI_COMMIT_BEFORE_SHA`                  | 11.2   | all    | The previous latest commit present on a branch before a merge request. Only populated when there is a merge request associated with the pipeline. |
 | `CI_COMMIT_DESCRIPTION`                 | 10.8   | all    | The description of the commit: the message without first line, if the title is shorter than 100 characters; full message in other case. |
 | `CI_COMMIT_MESSAGE`                     | 10.8   | all    | The full commit message. |
 | `CI_COMMIT_REF_NAME`                    | 9.0    | all    | The branch or tag name for which project is built |
@@ -78,7 +78,7 @@ future GitLab releases.**
 | `CI_PIPELINE_ID`                        | 8.10   | all    | The unique id of the current pipeline that GitLab CI uses internally |
 | `CI_PIPELINE_IID`                       | 11.0   | all    | The unique id of the current pipeline scoped to project |
 | `CI_PIPELINE_SOURCE`                    | 10.0   | all    | Indicates how the pipeline was triggered. Possible options are: `push`, `web`, `trigger`, `schedule`, `api`, and `pipeline`. For pipelines created before GitLab 9.5, this will show as `unknown` |
-| `CI_PIPELINE_TRIGGERED`                 | all    | all    | The flag to indicate that job was [triggered] |
+| `CI_PIPELINE_TRIGGERED`                 | all    | all    | The flag to indicate that job was [triggered](../triggers/README.md) |
 | `CI_PIPELINE_URL`                       | 11.1   | 0.5    | Pipeline details URL |
 | `CI_PROJECT_DIR`                        | all    | all    | The full path where the repository is cloned and where the job is run. If the GitLab Runner `builds_dir` parameter is set, this variable is set relative to the value of `builds_dir`. For more information, see [Advanced configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) for GitLab Runner. |
 | `CI_PROJECT_ID`                         | all    | all    | The unique id of the current project that GitLab CI uses internally |
@@ -101,6 +101,7 @@ future GitLab releases.**
 | `CI_RUNNER_TAGS`                        | 8.10   | 0.5    | The defined runner tags |
 | `CI_RUNNER_VERSION`                     | all    | 10.6   | GitLab Runner version that is executing the current job |
 | `CI_SERVER`                             | all    | all    | Mark that job is executed in CI environment |
+| `CI_SERVER_HOST`                        | 12.1   | all    | Host component of the GitLab instance URL, without protocol and port (like gitlab.example.com) |
 | `CI_SERVER_NAME`                        | all    | all    | The name of CI server that is used to coordinate jobs |
 | `CI_SERVER_REVISION`                    | all    | all    | GitLab revision that is used to schedule jobs |
 | `CI_SERVER_VERSION`                     | all    | all    | GitLab version that is used to schedule jobs |
diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md
index 7d3f39a8c19..b5296f26269 100644
--- a/doc/ci/variables/where_variables_can_be_used.md
+++ b/doc/ci/variables/where_variables_can_be_used.md
@@ -89,13 +89,14 @@ Supported:
   - In `script`, it will work in the following lines of `script`.
   - In `after_script`, it will work in following lines of `after_script`.
 
-Please notice the specific case of `after_script` scripts, that can:
+In the case of `after_script` scripts, they can:
 
-- Only use variables defined before the script within the same `after_script` section.
+- Only use variables defined before the script within the same `after_script`
+  section.
 - Not use variables defined in `before_script` and `script`.
 
-Both restrictions are caused by the fact, that `after_script` script is executed in a
-[separated shell context](https://docs.gitlab.com/ee/ci/yaml/README.html#before_script-and-after_script).
+These restrictions are because `after_script` scripts are executed in a
+[separated shell context](../yaml/README.md#before_script-and-after_script).
 
 ## Persisted variables
 
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index b3aa1bcfad2..76b73729d0b 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -119,6 +119,35 @@ The following table lists available parameters for jobs:
 NOTE: **Note:**
 Parameters `types` and `type` are [deprecated](#deprecated-parameters).
 
+## Setting default parameters
+
+Some parameters can be set globally as the default for all jobs using the
+`default:` keyword. Default parameters can then be overridden by job-specific
+configuration.
+
+The following job parameters can be defined inside a `default:` block:
+
+- [`image`](#image)
+- [`services`](#services)
+- [`before_script`](#before_script-and-after_script)
+- [`after_script`](#before_script-and-after_script)
+- [`cache`](#cache)
+
+In the following example, the `ruby:2.5` image is set as the default for all
+jobs except the `rspec 2.6` job, which uses the `ruby:2.6` image:
+
+```yaml
+default:
+  image: ruby:2.5
+
+rspec:
+  script: bundle exec rspec
+
+rspec 2.6:
+  image: ruby:2.6
+  script: bundle exec rspec
+```
+
 ## Parameter details
 
 The following are detailed explanations for parameters used to configure CI/CD pipelines.
@@ -215,27 +244,33 @@ This can be an array or a multi-line string.
 `after_script` is used to define the command that will be run after all
 jobs, including failed ones. This has to be an array or a multi-line string.
 
-Script specified in `before_script` is:
+Scripts specified in `before_script` are:
 
-- Concatenated with script specified in the main `script`. Job-level `before_script` definition
-  override global-level `before_script` definition when concatenated with `script` definition.
-- Executed together with main `script` script as one script in a single shell context.
+- Concatenated with scripts specified in the main `script`. Job-level
+  `before_script` definition override global-level `before_script` definition
+  when concatenated with `script` definition.
+- Executed together with main `script` script as one script in a single shell
+  context.
 
-Script specified in `after_script`:
+Scripts specified in `after_script`:
 
 - Have a current working directory set back to the default.
-- Is executed in a shell context separated from `before_script` and `script` scripts.
-- Because of separated context, cannot see changes done by scripts defined in `before_script` or `script` scripts:
-    - in shell - for example, command aliases and variables exported in `script` script,
-    - outside of the working tree (depending on the Runner executor) - for example, software installed
-      by a `before_script` or `script` script.
+- Are executed in a shell context separated from `before_script` and `script`
+  scripts.
+- Because of separated context, cannot see changes done by scripts defined
+  in `before_script` or `script` scripts, either:
+  - In shell. For example, command aliases and variables exported in `script`
+    scripts.
+  - Outside of the working tree (depending on the Runner executor). For example,
+    software installed by a `before_script` or `script` scripts.
 
 It's possible to overwrite the globally defined `before_script` and `after_script`
 if you set it per-job:
 
 ```yaml
-before_script:
-  - global before script
+default:
+  before_script:
+    - global before script
 
 job:
   before_script:
@@ -470,7 +505,7 @@ Feature.enable(:allow_unsafe_ruby_regexp)
 ### `only`/`except` (advanced)
 
 CAUTION: **Warning:**
-This an _alpha_ feature, and it is subject to change at any time without
+This is an _alpha_ feature, and it is subject to change at any time without
 prior notice!
 
 GitLab supports both simple and complex strategies, so it's possible to use an
@@ -968,6 +1003,8 @@ review_app:
 
 stop_review_app:
   stage: deploy
+  variables:
+    GIT_STRATEGY: none
   script: make delete-app
   when: manual
   environment:
@@ -982,6 +1019,10 @@ Once the `review_app` job is successfully finished, it will trigger the
 set it up to `manual` so it will need a [manual action](#whenmanual) via
 GitLab's web interface in order to run.
 
+Also in the example, `GIT_STRATEGY` is set to `none` so that GitLab Runner won’t
+try to check out the code after the branch is deleted when the `stop_review_app`
+job is [automatically triggered](../environments.md#automatically-stopping-an-environment).
+
 The `stop_review_app` job is **required** to have the following keywords defined:
 
 - `when` - [reference](#when)
@@ -1046,7 +1087,7 @@ globally and all jobs will use that definition.
 #### `cache:paths`
 
 Use the `paths` directive to choose which files or directories will be cached.
-Wildcards can be used as well.
+Wildcards can be used that follow the [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and [filepath.Match](https://golang.org/pkg/path/filepath/#Match).
 
 Cache all files in `binaries` that end in `.apk` and the `.config` file:
 
@@ -1208,8 +1249,10 @@ be available for download in the GitLab UI.
 
 #### `artifacts:paths`
 
-You can only use paths that are within the project workspace. To pass artifacts
-between different jobs, see [dependencies](#dependencies).
+You can only use paths that are within the project workspace.
+Wildcards can be used that follow the [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and [filepath.Match](https://golang.org/pkg/path/filepath/#Match).
+
+To pass artifacts between different jobs, see [dependencies](#dependencies).
 
 Send all files in `binaries` and `.config`:
 
@@ -1464,7 +1507,7 @@ concatenated into a single file. Use a filename pattern (`junit: rspec-*.xml`),
 an array of filenames (`junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml]`), or a
 combination thereof (`junit: [rspec.xml, test-results/TEST-*.xml]`).
 
-##### `artifacts:reports:codequality` **[STARTER]**
+##### `artifacts:reports:codequality` **(STARTER)**
 
 > Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above.
 
@@ -1474,7 +1517,7 @@ as artifacts.
 The collected Code Quality report will be uploaded to GitLab as an artifact and will
 be automatically shown in merge requests.
 
-##### `artifacts:reports:sast` **[ULTIMATE]**
+##### `artifacts:reports:sast` **(ULTIMATE)**
 
 > Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above.
 
@@ -1485,7 +1528,7 @@ The collected SAST report will be uploaded to GitLab as an artifact and will
 be automatically shown in merge requests, pipeline view and provide data for security
 dashboards.
 
-##### `artifacts:reports:dependency_scanning` **[ULTIMATE]**
+##### `artifacts:reports:dependency_scanning` **(ULTIMATE)**
 
 > Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above.
 
@@ -1496,7 +1539,7 @@ The collected Dependency Scanning report will be uploaded to GitLab as an artifa
 be automatically shown in merge requests, pipeline view and provide data for security
 dashboards.
 
-##### `artifacts:reports:container_scanning` **[ULTIMATE]**
+##### `artifacts:reports:container_scanning` **(ULTIMATE)**
 
 > Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above.
 
@@ -1507,7 +1550,7 @@ The collected Container Scanning report will be uploaded to GitLab as an artifac
 be automatically shown in merge requests, pipeline view and provide data for security
 dashboards.
 
-##### `artifacts:reports:dast` **[ULTIMATE]**
+##### `artifacts:reports:dast` **(ULTIMATE)**
 
 > Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above.
 
@@ -1518,7 +1561,7 @@ The collected DAST report will be uploaded to GitLab as an artifact and will
 be automatically shown in merge requests, pipeline view and provide data for security
 dashboards.
 
-##### `artifacts:reports:license_management` **[ULTIMATE]**
+##### `artifacts:reports:license_management` **(ULTIMATE)**
 
 > Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above.
 
@@ -1529,7 +1572,7 @@ The collected License Management report will be uploaded to GitLab as an artifac
 be automatically shown in merge requests, pipeline view and provide data for security
 dashboards.
 
-##### `artifacts:reports:performance` **[PREMIUM]**
+##### `artifacts:reports:performance` **(PREMIUM)**
 
 > Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above.
 
@@ -1539,7 +1582,7 @@ as artifacts.
 The collected Performance report will be uploaded to GitLab as an artifact and will
 be automatically shown in merge requests.
 
-##### `artifacts:reports:metrics` **[PREMIUM]**
+##### `artifacts:reports:metrics` **(PREMIUM)**
 
 > Introduced in GitLab 11.10.
 
@@ -1622,6 +1665,84 @@ You can ask your administrator to
 [flip this switch](../../administration/job_artifacts.md#validation-for-dependencies)
 and bring back the old behavior.
 
+### `needs`
+
+> Introduced in GitLab 12.2.
+
+The `needs:` keyword enables executing jobs out-of-order, allowing you to implement
+a [directed acyclic graph](../directed_acyclic_graph/index.md) in your `.gitlab-ci.yml`.
+
+This lets you run some jobs without waiting for other ones, disregarding stage ordering
+so you can have multiple stages running concurrently.
+
+Let's consider the following example:
+
+```yaml
+linux:build:
+  stage: build
+
+mac:build:
+  stage: build
+
+linux:rspec:
+  stage: test
+  needs: [linux:build]
+
+linux:rubocop:
+  stage: test
+  needs: [linux:build]
+
+mac:rspec:
+  stage: test
+  needs: [mac:build]
+
+mac:rubocop:
+  stage: test
+  needs: [mac:build]
+
+production:
+  stage: deploy
+```
+
+This example creates three paths of execution:
+
+- Linux path: the `linux:rspec` and `linux:rubocop` jobs will be run as soon
+  as the `linux:build` job finishes without waiting for `mac:build` to finish.
+
+- macOS path: the `mac:rspec` and `mac:rubocop` jobs will be run as soon
+  as the `mac:build` job finishes, without waiting for `linux:build` to finish.
+
+- The `production` job will be executed as soon as all previous jobs
+  finish; in this case: `linux:build`, `linux:rspec`, `linux:rubocop`,
+  `mac:build`, `mac:rspec`, `mac:rubocop`.
+
+#### Requirements and limitations
+
+1. If `needs:` is set to point to a job that is not instantiated
+   because of `only/except` rules or otherwise does not exist, the
+   job will fail.
+1. Note that on day one of the launch, we are temporarily limiting the 
+   maximum number of jobs that a single job can need in the `needs:` array. Track
+   our [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/7541)
+   for details on the current limit.
+1. If you use `dependencies:` with `needs:`, it's important that you
+   do not mark a job as having a dependency on something that won't
+   have been run at the time it needs it. It's better to use both
+   keywords in this case so that GitLab handles the ordering appropriately.
+1. It is impossible for now to have `needs: []` (empty needs),
+   the job always needs to depend on something, unless this is the job
+   in the first stage (see [gitlab-ce#65504](https://gitlab.com/gitlab-org/gitlab-ce/issues/65504)).
+1. If `needs:` refers to a job that is marked as `parallel:`.
+   the current job will depend on all parallel jobs created.
+1. `needs:` is similar to `dependencies:` in that needs to use jobs from
+   prior stages, this means that it is impossible to create circular
+   dependencies or depend on jobs in the current stage (see [gitlab-ce#65505](https://gitlab.com/gitlab-org/gitlab-ce/issues/65505)).
+1. Related to the above, stages must be explicitly defined for all jobs
+   that have the keyword `needs:` or are referred to by one.
+1. For self-managed users, the feature must be turned on using the `ci_dag_support`
+   feature flag. The `ci_dag_limit_needs` option, if set, will limit the number of
+   jobs that a single job can need to `50`. If unset, the limit is `5`.
+
 ### `coverage`
 
 > [Introduced][ce-7447] in GitLab 8.17.
@@ -1728,15 +1849,42 @@ sequentially from `job_name 1/N` to `job_name N/N`.
 
 For every job, `CI_NODE_INDEX` and `CI_NODE_TOTAL` [environment variables](../variables/README.md#predefined-environment-variables) are set.
 
-A simple example:
+Marking a job to be run in parallel requires only a simple addition to your configuration file:
+
+```diff
+ test:
+   script: rspec
++  parallel: 5
+```
+TIP: **Tip:**
+Parallelize tests suites across parallel jobs.
+Different languages have different tools to facilitate this.
+
+A simple example using [Sempahore Test Boosters](https://github.com/renderedtext/test-boosters) and RSpec to run some Ruby tests:
+
+```ruby
+# Gemfile
+source 'https://rubygems.org'
+
+gem 'rspec'
+gem 'semaphore_test_boosters'
+```
 
 ```yaml
 test:
-  script: rspec
-  parallel: 5
+  parallel: 3
+  script:
+    - bundle
+    - bundle exec rspec_booster --job $CI_NODE_INDEX/$CI_NODE_TOTAL
 ```
 
-### `trigger` **[PREMIUM]**
+CAUTION: **Caution:**
+Please be aware that semaphore_test_boosters reports usages statistics to the author.
+
+You can then navigate to the **Jobs** tab of a new pipeline build and see your RSpec
+job split into three separate jobs.
+
+### `trigger` **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8997) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8.
 
@@ -2208,10 +2356,10 @@ spinach:
   script: rake spinach
 ```
 
-It's also possible to use multiple parents for `extends`.
-The algorithm used for merge is "closest scope wins", so keys
-from the last member will always shadow anything defined on other levels.
-For example:
+In GitLab 12.0 and later, it's also possible to use multiple parents for
+`extends`.  The algorithm used for merge is "closest scope wins", so
+keys from the last member will always shadow anything defined on other
+levels.  For example:
 
 ```yaml
 .only-important:
@@ -2398,20 +2546,20 @@ There are three possible values: `none`, `normal`, and `recursive`:
 - `normal` means that only the top-level submodules will be included. It is
   equivalent to:
 
-    ```
-    git submodule sync
-    git submodule update --init
-    ```
+  ```
+  git submodule sync
+  git submodule update --init
+  ```
 
 - `recursive` means that all submodules (including submodules of submodules)
   will be included. This feature needs Git v1.8.1 and later. When using a
   GitLab Runner with an executor not based on Docker, make sure the Git version
   meets that requirement. It is equivalent to:
 
-    ```
-    git submodule sync --recursive
-    git submodule update --init --recursive
-    ```
+  ```
+  git submodule sync --recursive
+  git submodule update --init --recursive
+  ```
 
 Note that for this feature to work correctly, the submodules must be configured
 (in `.gitmodules`) with either:
@@ -2537,18 +2685,39 @@ You can set it globally or per-job in the [`variables`](#variables) section.
 
 The following parameters are deprecated.
 
-### `types`
+### Globally-defined `types`
 
 CAUTION: **Deprecated:**
 `types` is deprecated, and could be removed in a future release.
 Use [`stages`](#stages) instead.
 
-### `type`
+### Job-defined `type`
 
 CAUTION: **Deprecated:**
 `type` is deprecated, and could be removed in one of the future releases.
 Use [`stage`](#stage) instead.
 
+### Globally-defined `image`, `services`, `cache`, `before_script`, `after_script`
+
+Defining `image`, `services`, `cache`, `before_script`, and
+`after_script` globally is deprecated. Support could be removed
+from a future release.
+
+Use [`default:`](#setting-default-parameters) instead. For example:
+
+```yaml
+default:
+  image: ruby:2.5
+  services:
+    - docker:dind
+  cache:
+    paths: [vendor/]
+  before_script:
+    - bundle install --path vendor/
+  after_script:
+    - rm -rf tmp/
+```
+
 ## Custom build directories
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/merge_requests/1267) in Gitlab Runner 11.10
@@ -2615,6 +2784,24 @@ test:
     - pwd
 ```
 
+### Nested paths
+
+The value of `GIT_CLONE_PATH` is expanded once and nesting variables
+within it is not supported.
+
+For example, you define both the variables below in your
+`.gitlab-ci.yml` file:
+
+```yml
+variables:
+  GOPATH: $CI_BUILDS_DIR/go
+  GIT_CLONE_PATH: $GOPATH/src/namespace/project
+```
+
+The value of `GIT_CLONE_PATH` is expanded once into
+`$CI_BUILDS_DIR/go/src/namespace/project`, and results in failure
+because `$CI_BUILDS_DIR` is not expanded.
+
 ## Special YAML features
 
 It's possible to use special YAML features like anchors (`&`), aliases (`*`)
@@ -2798,7 +2985,8 @@ Alternatively, one can pass the `ci.skip` [Git push option][push-option] if
 using Git 2.10 or newer:
 
 ```sh
-git push -o ci.skip
+git push --push-option=ci.skip    # using git 2.10+
+git push -o ci.skip               # using git 2.18+
 ```
 
 <!-- ## Troubleshooting
diff --git a/doc/customization/branded_login_page.md b/doc/customization/branded_login_page.md
index b892f59d777..afcc2b71284 100644
--- a/doc/customization/branded_login_page.md
+++ b/doc/customization/branded_login_page.md
@@ -1,19 +1,38 @@
-# Changing the appearance of the login page
+---
+type: howto
+---
 
-GitLab offers a way to put your company's identity on the login page of your GitLab server and make it a branded login page.
+# Changing the logo and description on the login page
 
-By default, the page shows the GitLab logo and description.
+You can customize the login page of your GitLab server to show the logo and
+description of your organization.
+
+By default, the page shows the GitLab logo and description:
 
 ![default_login_page](branded_login_page/default_login_page.png)
 
-## Changing the appearance of the login page
+To customize the login page:
 
-Navigate to the **Admin** area and go to the **Appearance** page.
+1. Navigate to the **Admin** area and go to the **Appearance** page.
+1. Fill in your desired Title and Description. You can also choose an image file
+   of the logo for your organization.
 
-Fill in the required details like Title, Description and upload the company logo.
+   ![appearance](branded_login_page/appearance.png)
 
-![appearance](branded_login_page/appearance.png)
+1. Save your changes.
 
-After saving the page, your GitLab login page will have the details you filled in:
+Your GitLab login page will display the details you provided:
 
 ![company_login_page](branded_login_page/custom_sign_in.png)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/customization/branded_page_and_email_header.md b/doc/customization/branded_page_and_email_header.md
index 9a0f0b382fa..370c1461d30 100644
--- a/doc/customization/branded_page_and_email_header.md
+++ b/doc/customization/branded_page_and_email_header.md
@@ -1,15 +1,37 @@
-# Changing the logo on the overall page and email header
+---
+type: howto
+---
 
-Navigate to the **Admin** area and go to the **Appearance** page.
+# Changing the navigation bar and email header logo
 
-Upload the custom logo (**Header logo**) in the section **Navigation bar**.
+You can customize the logo that appears in email headers and in the navigation
+bar on pages that are displayed by your GitLab server.
 
-![appearance](branded_page_and_email_header/appearance.png)
+1. Navigate to the **Admin** area and go to the **Appearance** page, then locate
+   the **Navigation bar** section.
+1. For the **Header Logo**, choose an image file of the logo for your
+   organization.
 
-After saving the page, your GitLab navigation bar will contain the custom logo:
+   ![appearance](branded_page_and_email_header/appearance.png)
+
+1. Save your changes.
+
+Your GitLab navigation bar will display the custom logo:
 
 ![custom_brand_header](branded_page_and_email_header/custom_brand_header.png)
 
-The GitLab pipeline emails will also have the custom logo:
+The GitLab pipeline emails will also display the custom logo:
 
 ![custom_email_header](branded_page_and_email_header/custom_email_header.png)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/customization/favicon.md b/doc/customization/favicon.md
index 45a18159b5e..dbde6e8c03b 100644
--- a/doc/customization/favicon.md
+++ b/doc/customization/favicon.md
@@ -1,16 +1,37 @@
+---
+type: howto
+---
+
 # Changing the favicon
 
 > [Introduced][ce-14497] in GitLab 11.0.
 
 [ce-14497]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14497
 
-Navigate to the **Admin** area and go to the **Appearance** page.
+You can customize the favicon (the icon displayed in your web browser's
+address bar and web page tabs) for your GitLab server.
+
+1. Navigate to the **Admin** area and go to the **Appearance** page, then
+   locate the **Favicon** section.
+1. Upload an image file of your favicon.
 
-Upload the custom favicon (**Favicon**) in the section **Favicon**.
+   ![appearance](favicon/appearance.png)
 
-![appearance](favicon/appearance.png)
+1. Save your changes.
 
-After saving the page, the new favicon will be shown in the browser. The main
-favicon as well as the CI status icons will show the custom icon:
+Your new favicon will display in the browser. The main favicon and the CI
+status icons will show the custom icon:
 
 ![custom_favicon](favicon/custom_favicon.png)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/customization/help_message.md b/doc/customization/help_message.md
index c2e592d03bf..a4d8f295750 100644
--- a/doc/customization/help_message.md
+++ b/doc/customization/help_message.md
@@ -1,13 +1,36 @@
-# GitLab Help custom text
+---
+type: howto
+---
 
-In larger organizations it is useful to have information about who has the responsibility of maintaining the company GitLab server.
+# Customizing the 'Help' and login page messages
 
-1. Navigate to the admin area, click on **Preferences** and expand **Help page**.
+In large organizations, it is useful to have information about who maintains
+the company GitLab server. You can customize and display this information on
+the GitLab login page and on the GitLab server's `/help` page.
 
-1. Under **Help text** fill in the required information about the person(s) administering GitLab or any other information relevant to your needs.
+1. Navigate to the **Admin** area, then click on **Preferences** and expand
+   **Help page**.
+1. Under **Help page text**, fill in the required information about the
+   person(s) administering GitLab. This text can also contain any other
+   information that you wish to display to users.
 
-    ![help message](help_message/help_text.png)
+   ![help message](help_message/help_text.png)
 
-1. After saving the page this information will be shown on the GitLab login page and on the GitLab `/help` page (e.g., <https://gitlab.com/help>).
+1. Save your changes.
 
-    ![help text on help page](help_message/help_text_on_help_page.png)
+The information you entered will be shown on the GitLab login page and on the
+GitLab `/help` page (e.g., <https://gitlab.com/help>).
+
+![help text on help page](help_message/help_text_on_help_page.png)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/customization/help_message/help_text.png b/doc/customization/help_message/help_text.png
index 99697a106bf..5fcabcdb757 100644
--- a/doc/customization/help_message/help_text.png
+++ b/doc/customization/help_message/help_text.png
diff --git a/doc/customization/index.md b/doc/customization/index.md
index 71e87b3f111..f17a2d80e2c 100644
--- a/doc/customization/index.md
+++ b/doc/customization/index.md
@@ -1,18 +1,18 @@
 ---
+type: index
 description: Learn how to customize GitLab's appearance for self-managed installations.
 ---
 
-# Customizing GitLab's appearance **[CORE ONLY]**
+# Customizing GitLab's appearance **(CORE ONLY)**
 
-For GitLab self-managed instances, it's possible to customize
-a few pages.
+For GitLab self-managed instances, you can customize the page logo,
+email headers, favicon, and several other aspects of GitLab's appearance.
 
-Read through the following documents to adjust GitLab's
-look and feel to meet your needs:
+The following pages explain how to customize the appearance of your instance:
 
-- [Custom login page](branded_login_page.md)
-- [Custom header and email logo](branded_page_and_email_header.md)
-- [Custom favicon](favicon.md)
-- [Libravatar](libravatar.md)
-- [New project page](new_project_page.md)
-- [Custom `/help` message](help_message.md)
\ No newline at end of file
+- [Changing the logo and description on the login page](branded_login_page.md)
+- [Changing the navigation bar and email header logo](branded_page_and_email_header.md)
+- [Changing the favicon](favicon.md)
+- [Customizing the new project page](new_project_page.md)
+- [Customizing the `/help` and login page messages](help_message.md)
+- [Using the Libravatar service with GitLab](libravatar.md)
diff --git a/doc/customization/issue_and_merge_request_template.md b/doc/customization/issue_and_merge_request_template.md
index adaa120a37e..ebf711e105b 100644
--- a/doc/customization/issue_and_merge_request_template.md
+++ b/doc/customization/issue_and_merge_request_template.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: '../user/project/description_templates.md#setting-a-default-template-for-issues-and-merge-requests--starter'
+redirect_to: '../user/project/description_templates.md#setting-a-default-template-for-merge-requests-and-issues--starter'
 ---
 
-This document was moved to [description_templates](../user/project/description_templates.md#setting-a-default-template-for-issues-and-merge-requests--starter).
+This document was moved to [description_templates](../user/project/description_templates.md#setting-a-default-template-for-merge-requests-and-issues--starter).
diff --git a/doc/customization/issue_closing.md b/doc/customization/issue_closing.md
index 680c51e7524..9333f55ca9c 100644
--- a/doc/customization/issue_closing.md
+++ b/doc/customization/issue_closing.md
@@ -1,3 +1,5 @@
 ---
-redirect_to: '../user/project/issues/automatic_issue_closing.md'
+redirect_to: '../user/project/issues/managing_issues.md#closing-issues-automatically'
 ---
+
+This document was moved to [another location](../user/project/issues/managing_issues.md#closing-issues-automatically).
diff --git a/doc/customization/libravatar.md b/doc/customization/libravatar.md
index 18aaeb5a712..1c3bf877fa1 100644
--- a/doc/customization/libravatar.md
+++ b/doc/customization/libravatar.md
@@ -1,17 +1,23 @@
-# Use Libravatar service with GitLab
+---
+type: howto
+---
 
-GitLab by default supports [Gravatar](https://gravatar.com) avatar service.
-Libravatar is a service which delivers your avatar (profile picture) to other websites and their API is
-[heavily based on gravatar](https://wiki.libravatar.org/api/).
+# Using the Libravatar service with GitLab
 
-This means that it is not complicated to switch to Libravatar avatar service or even self hosted Libravatar server.
+GitLab by default supports the [Gravatar](https://gravatar.com) avatar service.
 
-# Configuration
+Libravatar is another service that delivers your avatar (profile picture) to
+other websites. The Libravatar API is
+[heavily based on gravatar](https://wiki.libravatar.org/api/), so you can
+easily switch to the Libravatar avatar service or even a self-hosted Libravatar
+server.
 
-In [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122) set
+## Configuration
+
+In the [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122), set
 the configuration options as follows:
 
-## For HTTP
+### For HTTP
 
 ```yml
   gravatar:
@@ -20,7 +26,7 @@ the configuration options as follows:
     plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
 ```
 
-## For HTTPS
+### For HTTPS
 
 ```yml
   gravatar:
@@ -29,50 +35,67 @@ the configuration options as follows:
     ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
 ```
 
-## Self-hosted
+### Self-hosted Libravatar server
 
-If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/) the URL will be different in the configuration
-but the important part is to provide the same placeholders so GitLab can parse the URL correctly.
+If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/),
+the URL will be different in the configuration, but you must provide the same
+placeholders so GitLab can parse the URL correctly.
 
-For example, you host a service on `http://libravatar.example.com` the `plain_url` you need to supply in `gitlab.yml` is
+For example, you host a service on `http://libravatar.example.com` and the
+`plain_url` you need to supply in `gitlab.yml` is
 
 `http://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon`
 
-## Omnibus-gitlab example
+### Omnibus-gitlab example
 
 In `/etc/gitlab/gitlab.rb`:
 
-#### For http
+#### For HTTP
 
 ```ruby
 gitlab_rails['gravatar_enabled'] = true
 gitlab_rails['gravatar_plain_url'] = "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
 ```
 
-#### For https
+#### For HTTPS
 
 ```ruby
 gitlab_rails['gravatar_enabled'] = true
 gitlab_rails['gravatar_ssl_url'] = "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
 ```
 
-Run `sudo gitlab-ctl reconfigure` for changes to take effect.
+Then run `sudo gitlab-ctl reconfigure` for the changes to take effect.
 
 ## Default URL for missing images
 
-[Libravatar supports different sets](https://wiki.libravatar.org/api/) of `missing images` for emails not found on the Libravatar service.
-
-In order to use a different set other than `identicon`, replace `&d=identicon` portion of the URL with another supported set.
-For example, you can use `retro` set in which case the URL would look like: `plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"`
+[Libravatar supports different sets](https://wiki.libravatar.org/api/) of
+missing images for user email addresses that are not found on the Libravatar
+service.
 
-## Usage examples
+In order to use a set other than `identicon`, replace the `&d=identicon`
+portion of the URL with another supported set.
+For example, you can use the `retro` set, in which case the URL would look like:
+`plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"`
 
-#### For Microsoft Office 365
+## Usage examples for Microsoft Office 365
 
-If your users are Office 365-users, the "GetPersonaPhoto" service can be used. Note that this service requires login, so this use case is
-most useful in a corporate installation, where all users have access to Office 365.
+If your users are Office 365 users, the `GetPersonaPhoto` service can be used.
+Note that this service requires a login, so this use case is most useful in a
+corporate installation where all users have access to Office 365.
 
 ```ruby
 gitlab_rails['gravatar_plain_url'] = 'http://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120'
 gitlab_rails['gravatar_ssl_url'] = 'https://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120'
 ```
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/customization/new_project_page.md b/doc/customization/new_project_page.md
index 148bf9512c6..43b95a76d08 100644
--- a/doc/customization/new_project_page.md
+++ b/doc/customization/new_project_page.md
@@ -1,20 +1,38 @@
+---
+type: howto
+---
+
 # Customizing the new project page
 
-It is possible to add a markdown-formatted message to your GitLab
-new project page.
+You can add a markdown-formatted message to your GitLab new project page.
 
 By default, the new project page shows a sidebar with general information:
 
-![](new_project_page/default_new_project_page.png)
+![default_new_project_page](new_project_page/default_new_project_page.png)
+
+To customize the information in the sidebar:
+
+1. Navigate to the **Admin** area and go to the **Appearance** page, then
+   locate the **New project pages** section.
+1. Fill in your new project project guidelines:
+
+   ![appearance_settings](new_project_page/appearance_settings.png)
 
-## Changing the appearance of the new project page
+1. Save the page.
 
-Navigate to the **Admin** area and go to the **Appearance** page.
+Your new project page will show the customized guidelines in the sidebar, below
+the general information:
 
-Fill in your project guidelines:
+![custom_new_project_page](new_project_page/custom_new_project_page.png)
 
-![](new_project_page/appearance_settings.png)
+<!-- ## Troubleshooting
 
-After saving the page, your new project page will show the guidelines in the sidebar, below the general information:
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
 
-![](new_project_page/custom_new_project_page.png)
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/customization/system_header_and_footer_messages.md b/doc/customization/system_header_and_footer_messages.md
index 9d6931c730d..15830be4e8a 100644
--- a/doc/customization/system_header_and_footer_messages.md
+++ b/doc/customization/system_header_and_footer_messages.md
@@ -1,14 +1,15 @@
 # Adding a system message to every page
 
-> [Introduced][ee-1283] in [GitLab Premium][eep] 10.7.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5023) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.7.
+> [Added](https://gitlab.com/gitlab-org/gitlab-ce/issues/55057) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9.
 
 Navigate to the **Admin** area and go to the **Appearance** page.
 
 Under **System header and footer** insert your header message and/or footer message.
 Both background and font color of the header and footer are customizable.
 
-You can also apply the header and footer messages to gitlab emails, 
-by checking the **Enable header and footer in emails** checkbox. 
+You can also apply the header and footer messages to gitlab emails,
+by checking the **Enable header and footer in emails** checkbox.
 Note that color settings will only be applied within the app interface and not to emails
 
 ![appearance](system_header_and_footer_messages/appearance.png)
diff --git a/doc/customization/system_header_and_footer_messages/appearance.png b/doc/customization/system_header_and_footer_messages/appearance.png
index fd315bb6c07..d5a66bcb9f1 100644
--- a/doc/customization/system_header_and_footer_messages/appearance.png
+++ b/doc/customization/system_header_and_footer_messages/appearance.png
diff --git a/doc/development/README.md b/doc/development/README.md
index d2f09fc01de..6281bb809ff 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -3,7 +3,7 @@ comments: false
 description: 'Learn how to contribute to GitLab.'
 ---
 
-# GitLab development guides
+# Contributor and Development Docs
 
 ## Get started!
 
@@ -16,13 +16,14 @@ description: 'Learn how to contribute to GitLab.'
 
 - [GitLab core team & GitLab Inc. contribution process](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/PROCESS.md)
 - [Generate a changelog entry with `bin/changelog`](changelog.md)
-- [Code review guidelines](code_review.md) for reviewing code and having code reviewed.
+- [Code review guidelines](code_review.md) for reviewing code and having code reviewed
+- [Database review guidelines](database_review.md) for reviewing database-related changes and complex SQL queries
 - [Automatic CE->EE merge](automatic_ce_ee_merge.md)
 - [Guidelines for implementing Enterprise Edition features](ee_features.md)
 - [Security process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer)
 - [Requesting access to Chatops on GitLab.com](chatops_on_gitlabcom.md#requesting-access) (for GitLabbers)
 
-## UX and frontend guides
+## UX and Frontend guides
 
 - [GitLab Design System](https://design.gitlab.com/) for building GitLab with existing CSS styles and elements
 - [Frontend guidelines](fe_guide/index.md)
@@ -33,9 +34,9 @@ description: 'Learn how to contribute to GitLab.'
 - [GitLab utilities](utilities.md)
 - [Logging](logging.md)
 - [API styleguide](api_styleguide.md) Use this styleguide if you are
-  contributing to the API.
+  contributing to the API
 - [GraphQL API styleguide](api_graphql_styleguide.md) Use this
-  styleguide if you are contribution to the [GraphQL API](../api/graphql/index.md)
+  styleguide if you are contributing to the [GraphQL API](../api/graphql/index.md)
 - [Sidekiq guidelines](sidekiq_style_guide.md) for working with Sidekiq workers
 - [Working with Gitaly](gitaly.md)
 - [Manage feature flags](feature_flags.md)
@@ -61,6 +62,9 @@ description: 'Learn how to contribute to GitLab.'
 - [How Git object deduplication works in GitLab](git_object_deduplication.md)
 - [Geo development](geo.md)
 - [Routing](routing.md)
+- [Repository mirroring](repository_mirroring.md)
+- [Git LFS](lfs.md)
+- [Developing against interacting components or features](interacting_components.md)
 
 ## Performance guides
 
@@ -80,6 +84,7 @@ description: 'Learn how to contribute to GitLab.'
 - [Understanding EXPLAIN plans](understanding_explain_plans.md)
 - [explain.depesz.com](https://explain.depesz.com/) for visualising the output
   of `EXPLAIN`
+- [pgFormatter](http://sqlformat.darold.net/) a PostgreSQL SQL syntax beautifier
 
 ### Migrations
 
@@ -106,6 +111,11 @@ description: 'Learn how to contribute to GitLab.'
 - [Database Debugging and Troubleshooting](database_debugging.md)
 - [Query Count Limits](query_count_limits.md)
 - [Database helper modules](database_helpers.md)
+- [Code comments](code_comments.md)
+
+## Case studies
+
+- [Database case study: Filtering by label](filtering_by_label.md)
 
 ## Integration guides
 
@@ -140,6 +150,10 @@ description: 'Learn how to contribute to GitLab.'
 
 - [Go Guidelines](go_guide/index.md)
 
+## Shell Scripting guides
+
+- [Shell scripting standards and style guidelines](shell_scripting_guide/index.md)
+
 ## Other GitLab Development Kit (GDK) guides
 
 - [Run full Auto DevOps cycle in a GDK instance](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/auto_devops.md)
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md
index 38270af682e..7569ccc04c1 100644
--- a/doc/development/api_graphql_styleguide.md
+++ b/doc/development/api_graphql_styleguide.md
@@ -1,5 +1,16 @@
 # GraphQL API
 
+## Deep Dive
+
+In March 2019, Nick Thomas hosted a [Deep Dive](https://gitlab.com/gitlab-org/create-stage/issues/1)
+on GitLab's [GraphQL API](../api/graphql/index.md) to share his domain specific knowledge
+with anyone who may work in this part of the code base in the future. You can find the
+[recording on YouTube](https://www.youtube.com/watch?v=-9L_1MWrjkg), and the slides on
+[Google Slides](https://docs.google.com/presentation/d/1qOTxpkTdHIp1CRjuTvO-aXg0_rUtzE3ETfLUdnBB5uQ/edit)
+and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/8e78ea7f326b2ef649e7d7d569c26d56/GraphQL_Deep_Dive__Create_.pdf).
+Everything covered in this deep dive was accurate as of GitLab 11.9, and while specific
+details may have changed since then, it should still serve as a good introduction.
+
 ## Authentication
 
 Authentication happens through the `GraphqlController`, right now this
@@ -188,9 +199,9 @@ abilities as in the Rails app.
 If the:
 
 - Currently authenticated user fails the authorization, the authorized
-resource will be returned as `null`.
+  resource will be returned as `null`.
 - Resource is part of a collection, the collection will be filtered to
-exclude the objects that the user's authorization checks failed against.
+  exclude the objects that the user's authorization checks failed against.
 
 TIP: **Tip:**
 Try to load only what the currently authenticated user is allowed to
@@ -413,12 +424,8 @@ Will generate a field called `mergeRequestSetWip` that
 
 ### Authorizing resources
 
-To authorize resources inside a mutation, we can include the
-`Gitlab::Graphql::Authorize::AuthorizeResource` concern in the
-mutation.
-
-This allows us to provide the required abilities on the mutation like
-this:
+To authorize resources inside a mutation, we first provide the required
+ abilities on the mutation like this:
 
 ```ruby
 module Mutations
@@ -437,7 +444,7 @@ want to validate the abilities for.
 
 Alternatively, we can add a `find_object` method that will load the
 object on the mutation. This would allow you to use the
-`authorized_find!` and `authorized_find!` helper methods.
+`authorized_find!` helper method.
 
 When a user is not allowed to perform the action, or an object is not
 found, we should raise a
diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md
index 4fc38a460f8..0866d3baeeb 100644
--- a/doc/development/api_styleguide.md
+++ b/doc/development/api_styleguide.md
@@ -53,7 +53,7 @@ allowed.
 
 ### Exclude params from parent namespaces!
 
-> By default `declared(params) `includes parameters that were defined in all
+> By default `declared(params)`includes parameters that were defined in all
 parent namespaces.
 
 – <https://github.com/ruby-grape/grape#include-parent-namespaces>
diff --git a/doc/development/architecture.md b/doc/development/architecture.md
index 5f32cd7eba2..5cb2ddf6e52 100644
--- a/doc/development/architecture.md
+++ b/doc/development/architecture.md
@@ -20,7 +20,7 @@ A typical install of GitLab will be on GNU/Linux. It uses Nginx or Apache as a w
 
 We also support deploying GitLab on Kubernetes using our [gitlab Helm chart](https://docs.gitlab.com/charts/).
 
-The GitLab web app uses MySQL or PostgreSQL for persistent database information (e.g. users, permissions, issues, other meta data). GitLab stores the bare git repositories it serves in `/home/git/repositories` by default. It also keeps default branch and hook information with the bare repository.
+The GitLab web app uses PostgreSQL for persistent database information (e.g. users, permissions, issues, other meta data). GitLab stores the bare git repositories it serves in `/home/git/repositories` by default. It also keeps default branch and hook information with the bare repository.
 
 When serving repositories over HTTP/HTTPS GitLab utilizes the GitLab API to resolve authorization and access as well as serving git objects.
 
@@ -40,7 +40,7 @@ A complete architecture diagram is available in our
 
 ![Simplified Component Overview](img/architecture_simplified.png)
 
-<!-- 
+<!--
 To update this diagram, GitLab team members can edit this source file:
 https://docs.google.com/drawings/d/1fBzAyklyveF-i-2q-OHUIqDkYfjjxC4mq5shwKSZHLs/edit.
  -->
@@ -93,8 +93,8 @@ graph TB
   Prometheus --> Alertmanager
   Migrations --> PostgreSQL
   Runner -- TCP 443 --> NGINX
-  Unicorn -- TCP 9200 --> ElasticSearch
-  Sidekiq -- TCP 9200 --> ElasticSearch
+  Unicorn -- TCP 9200 --> Elasticsearch
+  Sidekiq -- TCP 9200 --> Elasticsearch
   Sidekiq -- TCP 80, 443 --> Sentry
   Unicorn -- TCP 80, 443 --> Sentry
   Sidekiq -- UDP 6831 --> Jaeger
@@ -116,10 +116,10 @@ graph TB
 
 ### Component legend
 
-* ✅ - Installed by default
-* ⚙ - Requires additional configuration, or GitLab Managed Apps
-* ⤓ - Manual installation required
-* ❌ - Not supported or no instructions available
+- ✅ - Installed by default
+- ⚙ - Requires additional configuration, or GitLab Managed Apps
+- ⤓ - Manual installation required
+- ❌ - Not supported or no instructions available
 
 Component statuses are linked to configuration documentation for each component.
 
@@ -141,15 +141,15 @@ Component statuses are linked to configuration documentation for each component.
 | [Consul](#consul) | Database node discovery, failover | [⚙][consul-omnibus] | [❌][consul-charts] | [❌][consul-charts] | [✅](../user/gitlab_com/index.md#consul) | ❌ | ❌ | EE Only |
 | [GitLab self-monitoring: Prometheus](#prometheus) | Time-series database, metrics collection, and query service | [✅][prometheus-omnibus] | [✅][prometheus-charts] | [⚙][prometheus-charts] | [✅](../user/gitlab_com/index.md#prometheus) | ❌ | ❌ | CE & EE |
 | [GitLab self-monitoring: Alertmanager](#alertmanager) | Deduplicates, groups, and routes alerts from Prometheus | [⚙][alertmanager-omnibus] | [✅][alertmanager-charts] |  [⚙][alertmanager-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE |
-| [GitLab self-monitoring: Grafana](#grafana) | Metrics dashboard | [⚙][grafana-omnibus] | [⤓][grafana-charts] |  [⤓][grafana-charts] | [✅](https://dashboards.gitlab.com/d/RZmbBr7mk/gitlab-triage?refresh=30s) | ❌ | ❌ | CE & EE |
+| [GitLab self-monitoring: Grafana](#grafana) | Metrics dashboard | [✅][grafana-omnibus] | [⤓][grafana-charts] |  [⤓][grafana-charts] | [✅](https://dashboards.gitlab.com/d/RZmbBr7mk/gitlab-triage?refresh=30s) | ❌ | ❌ | CE & EE |
 | [GitLab self-monitoring: Sentry](#sentry) | Track errors generated by the GitLab instance | [⤓][sentry-omnibus] | [❌][sentry-charts] | [❌][sentry-charts] | [✅](https://about.gitlab.com/handbook/support/workflows/services/gitlab_com/500_errors.html#searching-sentry) | [⤓][gitlab-yml] | [⤓][gitlab-yml] | CE & EE |
 | [GitLab self-monitoring: Jaeger](#jaeger) | View traces generated by the GitLab instance | [❌][jaeger-omnibus] | [❌][jaeger-charts] | [❌][jaeger-charts] | [❌](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/4104) | [⤓][jaeger-source] | [⚙][jaeger-gdk] | CE & EE |
 | [Redis Exporter](#redis-exporter) | Prometheus endpoint with Redis metrics | [✅][redis-exporter-omnibus] | [✅][redis-exporter-charts] | [✅][redis-exporter-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE |
 | [Postgres Exporter](#postgres-exporter) | Prometheus endpoint with PostgreSQL metrics | [✅][postgres-exporter-omnibus] | [✅][postgres-exporter-charts] | [✅][postgres-exporter-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE |
 | [PgBouncer Exporter](#pgbouncer-exporter) | Prometheus endpoint with PgBouncer metrics | [⚙][pgbouncer-exporter-omnibus] | [❌][pgbouncer-exporter-charts] | [❌][pgbouncer-exporter-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE |
-| [GitLab Monitor](#gitlab-monitor) | Generates a variety of GitLab metrics | [✅][gitlab-monitor-omnibus] | [❌][gitab-monitor-charts] | [❌][gitab-monitor-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE |
+| [GitLab Monitor](#gitlab-monitor) | Generates a variety of GitLab metrics | [✅][gitlab-monitor-omnibus] | [✅][gitlab-monitor-charts] | [✅][gitlab-monitor-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE |
 | [Node Exporter](#node-exporter) | Prometheus endpoint with system metrics | [✅][node-exporter-omnibus] | [❌][node-exporter-charts] | [❌][node-exporter-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE |
-| [Mattermost](#mattermost) | Open-source Slack alternative | [⚙][mattermost-omnibus] | [⤓][mattermost-charts] | [⤓][mattermost-charts] | [⤓](../user/project/integrations/mattermost_slash_commands.md#manual-configuration), [⤓](../user/project/integrations/mattermost.html) | ❌ | ❌ | CE & EE |
+| [Mattermost](#mattermost) | Open-source Slack alternative | [⚙][mattermost-omnibus] | [⤓][mattermost-charts] | [⤓][mattermost-charts] | [⤓](../user/project/integrations/mattermost.md) | ❌ | ❌ | CE & EE |
 | [MinIO](#minio) | Object storage service | [⤓][minio-omnibus] | [✅][minio-charts] | [✅][minio-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#storage-architecture) | ❌ | [⚙][minio-gdk] | CE & EE |
 | [Runner](#gitlab-runner) | Executes GitLab CI jobs | [⤓][runner-omnibus] | [✅][runner-charts] | [⚙][runner-charts] | [✅](../user/gitlab_com/index.md#shared-runners) | [⚙][runner-source] | [⚙][runner-gdk] | CE & EE |
 | [Database Migrations](#database-migrations) | Database migrations | [✅][database-migrations-omnibus] | [✅][database-migrations-charts] | [✅][database-migrations-charts] | ✅ | [⚙][database-migrations-source] | ✅ | CE & EE |
@@ -158,7 +158,7 @@ Component statuses are linked to configuration documentation for each component.
 | [LDAP Authentication](#ldap-authentication) | Authenticate users against centralized LDAP directory | [⤓][ldap-omnibus] | [⤓][ldap-charts] | [⤓][ldap-charts] | [❌](https://about.gitlab.com/pricing/#gitlab-com) | [⤓][gitlab-yml] | [⤓][ldap-gdk] | CE & EE |
 | [Outbound email (SMTP)](#outbound-email) | Send email messages to users | [⤓][outbound-email-omnibus] | [⤓][outbound-email-charts] | [⤓][outbound-email-charts] | [✅](../user/gitlab_com/index.md#mail-configuration) | [⤓][gitlab-yml] | [⤓][gitlab-yml] | CE & EE |
 | [Inbound email (SMTP)](#inbound-email) | Receive messages to update issues | [⤓][inbound-email-omnibus] | [⤓][inbound-email-charts] | [⤓][inbound-email-charts] | [✅](../user/gitlab_com/index.md#mail-configuration) | [⤓][gitlab-yml] | [⤓][gitlab-yml] |  CE & EE |
-| [ElasticSearch](#elasticsearch) | Improved search within GitLab | [⤓][elasticsearch-omnibus] | [⤓][elasticsearch-charts] | [⤓][elasticsearch-charts] | [❌](https://gitlab.com/groups/gitlab-org/-/epics/153) | [⤓][elasticsearch-source] | [⤓][elasticsearch-gdk] | EE Only |
+| [Elasticsearch](#elasticsearch) | Improved search within GitLab | [⤓][elasticsearch-omnibus] | [⤓][elasticsearch-charts] | [⤓][elasticsearch-charts] | [❌](https://gitlab.com/groups/gitlab-org/-/epics/153) | [⤓][elasticsearch-source] | [⤓][elasticsearch-gdk] | EE Only |
 | [Sentry integration](#sentry) | Error tracking for deployed apps | [⤓][sentry-integration] | [⤓][sentry-integration] | [⤓][sentry-integration] | [⤓][sentry-integration] | [⤓][sentry-integration] | [⤓][sentry-integration] | CE & EE |
 | [Jaeger integration](#jaeger) | Distributed tracing for deployed apps | [⤓][jaeger-integration] | [⤓][jaeger-integration] | [⤓][jaeger-integration] | [⤓][jaeger-integration] | [⤓][jaeger-integration] | [⤓][jaeger-integration] | EE Only |
 | [GitLab Managed Apps](#gitlab-managed-apps) | Deploy [Helm](https://docs.helm.sh/), [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/), [Cert-Manager](https://docs.cert-manager.io/en/latest/), [Prometheus](https://prometheus.io/docs/introduction/overview/), a [Runner](https://docs.gitlab.com/runner/), [JupyterHub](http://jupyter.org/), [Knative](https://cloud.google.com/knative) to a cluster | [⤓][managed-k8s-apps] | [⤓][managed-k8s-apps] | [⤓][managed-k8s-apps] | [⤓][managed-k8s-apps] | [⤓][managed-k8s-apps] | [⤓][managed-k8s-apps] | CE & EE |
@@ -267,7 +267,7 @@ GitLab CI is the open-source continuous integration service included with GitLab
 #### Gitlab Workhorse
 
 - [Project page](https://gitlab.com/gitlab-org/gitlab-workhorse/blob/master/README.md)
-- Configuration: [Omnibus][gitlab-workhorse-omnibus], [Charts][gitlab-workhorse-charts], [Source][workhorse-source]
+- Configuration: [Omnibus][workhorse-omnibus], [Charts][workhorse-charts], [Source][workhorse-source]
 - Layer: Core Service (Processor)
 - Process: `gitlab-workhorse`
 
@@ -304,7 +304,7 @@ GitLab is comprised of a large number of services that all log. We started bundl
 - Configuration: [Omnibus][mattermost-omnibus], [Charts][mattermost-charts]
 - Layer: Core Service (Processor)
 
-Mattermost is an open source, private cloud, Slack-alternative from https://mattermost.com.
+Mattermost is an open source, private cloud, Slack-alternative from <https://mattermost.com>.
 
 #### MinIO
 
@@ -321,7 +321,7 @@ MinIO is an object storage server released under Apache License v2.0. It is comp
 - Layer: Core Service (Processor)
 - Process: `nginx`
 
-Nginx as an ingress port for all HTTP requests and routes them to the approriate sub-systems within GitLab. We are bundling an unmodified version of the popular open source webserver.
+Nginx as an ingress port for all HTTP requests and routes them to the appropriate sub-systems within GitLab. We are bundling an unmodified version of the popular open source webserver.
 
 #### Node Exporter
 
@@ -484,9 +484,11 @@ When making a request to an HTTP Endpoint (think `/users/sign_in`) the request w
 Below we describe the different pathing that HTTP vs. SSH Git requests will take. There is some overlap with the Web Request Cycle but also some differences.
 
 ### Web Request (80/443)
+
 TODO
 
 ### SSH Request (22)
+
 TODO
 
 ## System Layout
@@ -505,9 +507,19 @@ To summarize here's the [directory structure of the `git` user home directory](.
 
 ### Processes
 
-    ps aux | grep '^git'
+```sh
+ps aux | grep '^git'
+```
+
+GitLab has several components to operate. It requires a persistent database
+(PostgreSQL) and redis database, and uses Apache httpd or Nginx to proxypass
+Unicorn. All these components should run as different system users to GitLab
+(e.g., `postgres`, `redis` and `www-data`, instead of `git`).
 
-GitLab has several components to operate. As a system user (i.e. any user that is not the `git` user) it requires a persistent database (MySQL/PostreSQL) and redis database. It also uses Apache httpd or Nginx to proxypass Unicorn. As the `git` user it starts Sidekiq and Unicorn (a simple ruby HTTP server running on port `8080` by default). Under the GitLab user there are normally 4 processes: `unicorn_rails master` (1 process), `unicorn_rails worker` (2 processes), `sidekiq` (1 process).
+As the `git` user it starts Sidekiq and Unicorn (a simple ruby HTTP server
+running on port `8080` by default). Under the GitLab user there are normally 4
+processes: `unicorn_rails master` (1 process), `unicorn_rails worker`
+(2 processes), `sidekiq` (1 process).
 
 ### Repository access
 
@@ -550,12 +562,9 @@ $ /etc/init.d/nginx
 Usage: nginx {start|stop|restart|reload|force-reload|status|configtest}
 ```
 
-Persistent database (one of the following)
+Persistent database
 
 ```
-/etc/init.d/mysqld
-Usage: /etc/init.d/mysqld {start|stop|status|restart|condrestart|try-restart|reload|force-reload}
-
 $ /etc/init.d/postgresql
 Usage: /etc/init.d/postgresql {start|stop|restart|reload|force-reload|status} [version ..]
 ```
@@ -564,7 +573,7 @@ Usage: /etc/init.d/postgresql {start|stop|restart|reload|force-reload|status} [v
 
 gitlabhq (includes Unicorn and Sidekiq logs)
 
-- `/home/git/gitlab/log/` contains `application.log`, `production.log`, `sidekiq.log`, `unicorn.stdout.log`, `githost.log` and `unicorn.stderr.log` normally.
+- `/home/git/gitlab/log/` contains `application.log`, `production.log`, `sidekiq.log`, `unicorn.stdout.log`, `git_json.log` and `unicorn.stderr.log` normally.
 
 gitlab-shell
 
@@ -593,11 +602,6 @@ PostgreSQL
 
 - `/var/log/postgresql/*`
 
-MySQL
-
-- `/var/log/mysql/*`
-- `/var/log/mysql.*`
-
 ### GitLab specific config files
 
 GitLab has configuration files located in `/home/git/gitlab/config/*`. Commonly referenced config files include:
@@ -681,7 +685,7 @@ We've also detailed [our architecture of GitLab.com](https://about.gitlab.com/ha
 [pgbouncer-exporter-omnibus]: ../administration/monitoring/prometheus/pgbouncer_exporter.md
 [pgbouncer-exporter-charts]: https://docs.gitlab.com/charts/installation/deployment.html#postgresql
 [gitlab-monitor-omnibus]: ../administration/monitoring/prometheus/gitlab_monitor_exporter.md
-[gitab-monitor-charts]: https://gitlab.com/charts/gitlab/issues/319
+[gitlab-monitor-charts]: https://docs.gitlab.com/charts/charts/gitlab/gitlab-monitor/index.html
 [node-exporter-omnibus]: ../administration/monitoring/prometheus/node_exporter.md
 [node-exporter-charts]: https://gitlab.com/charts/gitlab/issues/1332
 [mattermost-omnibus]: https://docs.gitlab.com/omnibus/gitlab-mattermost/
@@ -695,7 +699,7 @@ We've also detailed [our architecture of GitLab.com](https://about.gitlab.com/ha
 [runner-gdk]: https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/runner.md
 [database-migrations-omnibus]: https://docs.gitlab.com/omnibus/settings/database.html#disabling-automatic-database-migration
 [database-migrations-charts]: https://docs.gitlab.com/charts/charts/gitlab/migrations/
-[database-migrations-source]: ../update/upgrading_from_source.md#14-install-libs-migrations-etc
+[database-migrations-source]: ../update/upgrading_from_source.md#13-install-libs-migrations-etc
 [certificate-management-omnibus]: https://docs.gitlab.com/omnibus/settings/ssl.html
 [certificate-management-charts]: https://docs.gitlab.com/charts/installation/tls.html
 [certificate-management-source]: ../install/installation.md#using-https
diff --git a/doc/development/automatic_ce_ee_merge.md b/doc/development/automatic_ce_ee_merge.md
index 3ca841353e6..001a92790e1 100644
--- a/doc/development/automatic_ce_ee_merge.md
+++ b/doc/development/automatic_ce_ee_merge.md
@@ -115,7 +115,7 @@ Now, every time you create an MR for CE and EE:
    1. Continue cherry-picking: `git cherry-pick --continue`
    1. Push to EE: `git push origin branch-example-ee`
 1. Create the EE-equivalent MR and link to the CE MR from the
-   description "Ports [CE-MR-LINK] to EE"
+   description `Ports [CE-MR-LINK] to EE`
 1. Once all the jobs are passing in both CE and EE, you've addressed the
    feedback from your own team, and got them approved, the merge requests can be merged.
 1. When both MRs are ready, the EE merge request will be merged first, and the
@@ -125,42 +125,43 @@ Now, every time you create an MR for CE and EE:
 
 - The commit SHA can be easily found from the GitLab UI. From a merge request,
   open the tab **Commits** and click the copy icon to copy the commit SHA.
-- To cherry-pick a **commit range**, such as [A > B > C > D] use:
+- To cherry-pick a **commit range**, such as (A > B > C > D) use:
 
-    ```shell
-    git cherry-pick "oldest-commit-SHA^..newest-commit-SHA"
-    ```
+  ```shell
+  git cherry-pick "oldest-commit-SHA^..newest-commit-SHA"
+  ```
 
-    For example, suppose the commit A is the oldest, and its SHA is `4f5e4018c09ed797fdf446b3752f82e46f5af502`,
-    and the commit D is the newest, and its SHA is `80e1c9e56783bd57bd7129828ec20b252ebc0538`.
-    The cherry-pick command will be:
+  For example, suppose the commit A is the oldest, and its SHA is `4f5e4018c09ed797fdf446b3752f82e46f5af502`,
+  and the commit D is the newest, and its SHA is `80e1c9e56783bd57bd7129828ec20b252ebc0538`.
+  The cherry-pick command will be:
 
-    ```shell
-    git cherry-pick "4f5e4018c09ed797fdf446b3752f82e46f5af502^..80e1c9e56783bd57bd7129828ec20b252ebc0538"
-    ```
+  ```shell
+  git cherry-pick "4f5e4018c09ed797fdf446b3752f82e46f5af502^..80e1c9e56783bd57bd7129828ec20b252ebc0538"
+  ```
 
 - To cherry-pick a **merge commit**, use the flag `-m 1`. For example, suppose that the
   merge commit SHA is `138f5e2f20289bb376caffa0303adb0cac859ce1`:
 
-    ```shell
-    git cherry-pick -m 1 138f5e2f20289bb376caffa0303adb0cac859ce1
-    ```
-- To cherry-pick multiple commits, such as B and D in a range [A > B > C > D], use:
+  ```shell
+  git cherry-pick -m 1 138f5e2f20289bb376caffa0303adb0cac859ce1
+  ```
 
-    ```shell
-    git cherry-pick commit-B-SHA commit-D-SHA
-    ```
+- To cherry-pick multiple commits, such as B and D in a range (A > B > C > D), use:
 
-    For example, suppose commit B SHA = `4f5e4018c09ed797fdf446b3752f82e46f5af502`,
-    and the commit D SHA = `80e1c9e56783bd57bd7129828ec20b252ebc0538`.
-    The cherry-pick command will be:
+  ```shell
+  git cherry-pick commit-B-SHA commit-D-SHA
+  ```
 
-    ```shell
-    git cherry-pick 4f5e4018c09ed797fdf446b3752f82e46f5af502 80e1c9e56783bd57bd7129828ec20b252ebc0538
-    ```
+  For example, suppose commit B SHA = `4f5e4018c09ed797fdf446b3752f82e46f5af502`,
+  and the commit D SHA = `80e1c9e56783bd57bd7129828ec20b252ebc0538`.
+  The cherry-pick command will be:
 
-    This case is particularly useful when you have a merge commit in a sequence of
-    commits and you want to cherry-pick all but the merge commit.
+  ```shell
+  git cherry-pick 4f5e4018c09ed797fdf446b3752f82e46f5af502 80e1c9e56783bd57bd7129828ec20b252ebc0538
+  ```
+
+  This case is particularly useful when you have a merge commit in a sequence of
+  commits and you want to cherry-pick all but the merge commit.
 
 - If you push more commits to the CE branch, you can safely repeat the procedure
   to cherry-pick them to the EE-equivalent branch. You can do that as many times as
@@ -170,6 +171,19 @@ Now, every time you create an MR for CE and EE:
   job failed, you are required to submit the EE MR so that you can fix the conflicts in EE
   before merging your changes into CE.
 
+## How we run the Automatic CE->EE merge at GitLab
+
+At GitLab, we use the [Merge Train](https://gitlab.com/gitlab-org/merge-train) 
+project to keep our [gitlab-ee](https://gitlab.com/gitlab-org/gitlab-ee) 
+repository updated with commits from 
+[gitlab-ce](https://gitlab.com/gitlab-org/gitlab-ce).
+
+We have a mirror of the [Merge Train](https://gitlab.com/gitlab-org/merge-train)
+project [configured](https://ops.gitlab.net/gitlab-org/merge-train) to run an 
+automatic CE->EE merge job every twenty minutes as a scheduled CI job.  The
+[configured](https://ops.gitlab.net/gitlab-org/merge-train) Merge Train project
+is only accessible to authorized GitLab staff.
+
 ## FAQ
 
 ### How does automatic merging work?
@@ -186,7 +200,7 @@ code.
 ### Why merge automatically?
 
 As we work towards continuous deployments and a single repository for both CE
-and EE, we need to first make sure that all CE changes make their way into CE as
+and EE, we need to first make sure that all CE changes make their way into EE as
 fast as possible. Past experiences and data have shown that periodic CE to EE
 merge requests do not scale, and often take a very long time to complete. For
 example, [in this
diff --git a/doc/development/changelog.md b/doc/development/changelog.md
index 45b3d5a23a1..bd07a01e782 100644
--- a/doc/development/changelog.md
+++ b/doc/development/changelog.md
@@ -35,7 +35,7 @@ the `author` field. GitLab team members **should not**.
 
 - Any user-facing change **should** have a changelog entry. Example: "GitLab now
   uses system fonts for all text."
-- Any change behind a feature flag **should not** have a changelog entry. The entry should be added [in the merge request removing the feature flags](https://docs.gitlab.com/ee/development/feature_flags.html#developing-with-feature-flags).
+- Any change behind a feature flag **should not** have a changelog entry. The entry should be added [in the merge request removing the feature flags](feature_flags/development.md).
 - A fix for a regression introduced and then fixed in the same release (i.e.,
   fixing a bug introduced during a monthly release candidate) **should not**
   have a changelog entry.
@@ -62,7 +62,7 @@ making it both concise and descriptive, err on the side of descriptive.
 The first example provides no context of where the change was made, or why, or
 how it benefits the user.
 
-- **Bad:** Copy [some text] to clipboard.
+- **Bad:** Copy (some text) to clipboard.
 - **Good:** Update the "Copy to clipboard" tooltip to indicate what's being
   copied.
 
@@ -129,6 +129,7 @@ merge_request:
 author:
 type:
 ```
+
 If you're working on the GitLab EE repository, the entry will be added to
 `ee/changelogs/unreleased/` instead.
 
@@ -144,7 +145,7 @@ If you're working on the GitLab EE repository, the entry will be added to
 | [`--type`](#--type-or--t)          | `-t`      | The category of the change, valid options are: `added`, `fixed`, `changed`, `deprecated`, `removed`, `security`, `performance`, `other` |
 | `--help`          | `-h`      | Print help message                                                                                                                      |
 
-##### `--amend`
+#### `--amend`
 
 You can pass the **`--amend`** argument to automatically stage the generated
 file and amend it to the previous commit.
@@ -166,7 +167,7 @@ author:
 type:
 ```
 
-##### `--force` or `-f`
+#### `--force` or `-f`
 
 Use **`--force`** or **`-f`** to overwrite an existing changelog entry if it
 already exists.
@@ -184,7 +185,7 @@ author:
 type:
 ```
 
-##### `--merge-request` or `-m`
+#### `--merge-request` or `-m`
 
 Use the **`--merge-request`** or **`-m`** argument to provide the
 `merge_request` value:
@@ -199,7 +200,7 @@ author:
 type:
 ```
 
-##### `--dry-run` or `-n`
+#### `--dry-run` or `-n`
 
 Use the **`--dry-run`** or **`-n`** argument to prevent actually writing or
 committing anything:
@@ -216,7 +217,7 @@ type:
 $ ls changelogs/unreleased/
 ```
 
-##### `--git-username` or `-u`
+#### `--git-username` or `-u`
 
 Use the **`--git-username`** or **`-u`** argument to automatically fill in the
 `author` value with your configured Git `user.name` value:
@@ -234,7 +235,7 @@ author: Jane Doe
 type:
 ```
 
-##### `--type` or `-t`
+#### `--type` or `-t`
 
 Use the **`--type`** or **`-t`** argument to provide the `type` value:
 
diff --git a/doc/development/chaos_endpoints.md b/doc/development/chaos_endpoints.md
index 403a5b21827..961520db7d8 100644
--- a/doc/development/chaos_endpoints.md
+++ b/doc/development/chaos_endpoints.md
@@ -15,23 +15,19 @@ Currently, there are four endpoints for simulating the following conditions:
 
 ## Enabling chaos endpoints
 
-For obvious reasons, these endpoints are not enabled by default. They can be enabled by setting the `GITLAB_ENABLE_CHAOS_ENDPOINTS` environment variable to `1`.
-
-For example, if you're using the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) this can be done with the following command:
-
-```bash
-GITLAB_ENABLE_CHAOS_ENDPOINTS=1 gdk run
-```
-
-## Securing the chaos endpoints
+For obvious reasons, these endpoints are not enabled by default on `production`.
+They are enabled by default on **development** environments.
 
 DANGER: **Danger:**
-It is highly recommended that you secure access to the chaos endpoints using a secret token. This is recommended when enabling these endpoints locally and essential when running in a staging or other shared environment. You should not enable them in production unless you absolutely know what you're doing.
+It is required that you secure access to the chaos endpoints using a secret token.
+You should not enable them in production unless you absolutely know what you're doing.
 
-A secret token can be set through the `GITLAB_CHAOS_SECRET` environment variable. For example, when using the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) this can be done with the following command:
+A secret token can be set through the `GITLAB_CHAOS_SECRET` environment variable.
+For example, when using the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit)
+this can be done with the following command:
 
 ```bash
-GITLAB_ENABLE_CHAOS_ENDPOINTS=1 GITLAB_CHAOS_SECRET=secret gdk run
+GITLAB_CHAOS_SECRET=secret gdk run
 ```
 
 Replace `secret` with your own secret token.
@@ -40,6 +36,10 @@ Replace `secret` with your own secret token.
 
 Once you have enabled the chaos endpoints and restarted the application, you can start testing using the endpoints.
 
+By default, when invoking a chaos endpoint, the web worker process which receives the request will handle it. This means, for example, that if the Kill
+operation is invoked, the Puma or Unicorn worker process handling the request will be killed. To test these operations in Sidekiq, the `async` parameter on
+each endpoint can be set to `true`. This will run the chaos process in a Sidekiq worker.
+
 ## Memory leaks
 
 To simulate a memory leak in your application, use the `/-/chaos/leakmem` endpoint.
@@ -51,54 +51,88 @@ The memory is not retained after the request finishes. Once the request has comp
 GET /-/chaos/leakmem
 GET /-/chaos/leakmem?memory_mb=1024
 GET /-/chaos/leakmem?memory_mb=1024&duration_s=50
+GET /-/chaos/leakmem?memory_mb=1024&duration_s=50&async=true
 ```
 
-| Attribute    | Type    | Required | Description                                                                        |
-| ------------ | ------- | -------- | ---------------------------------------------------------------------------------- |
-| `memory_mb`  | integer | no       | How much memory, in MB, should be leaked. Defaults to 100MB.                       |
-| `duration_s` | integer | no       | Minimum duration, in seconds, that the memory should be retained. Defaults to 30s. |
+| Attribute    | Type    | Required | Description                                                                          |
+| ------------ | ------- | -------- | ------------------------------------------------------------------------------------ |
+| `memory_mb`  | integer | no       | How much memory, in MB, should be leaked. Defaults to 100MB.                         |
+| `duration_s` | integer | no       | Minimum duration_s, in seconds, that the memory should be retained. Defaults to 30s. |
+| `async`      | boolean | no       | Set to true to leak memory in a Sidekiq background worker process                    |
 
 ```bash
 curl http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10 --header 'X-Chaos-Secret: secret'
+curl http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10&token=secret
 ```
 
 ## CPU spin
 
 This endpoint attempts to fully utilise a single core, at 100%, for the given period.
 
-Depending on your rack server setup, your request may timeout after a predermined period (normally 60 seconds).
+Depending on your rack server setup, your request may timeout after a predetermined period (normally 60 seconds).
 If you're using Unicorn, this is done by killing the worker process.
 
 ```
-GET /-/chaos/cpuspin
-GET /-/chaos/cpuspin?duration_s=50
+GET /-/chaos/cpu_spin
+GET /-/chaos/cpu_spin?duration_s=50
+GET /-/chaos/cpu_spin?duration_s=50&async=true
 ```
 
 | Attribute    | Type    | Required | Description                                                           |
 | ------------ | ------- | -------- | --------------------------------------------------------------------- |
-| `duration_s` | integer | no       | Duration, in seconds, that the core will be utilised. Defaults to 30s |
+| `duration_s` | integer | no       | Duration, in seconds, that the core will be utilized. Defaults to 30s |
+| `async`      | boolean | no       | Set to true to consume CPU in a Sidekiq background worker process     |
+
+```bash
+curl http://localhost:3000/-/chaos/cpu_spin?duration_s=60 --header 'X-Chaos-Secret: secret'
+curl http://localhost:3000/-/chaos/cpu_spin?duration_s=60&token=secret
+```
+
+## DB spin
+
+This endpoint attempts to fully utilise a single core, and interleave it with DB request, for the given period.
+This endpoint can be used to model yielding execution to another threads when running concurrently.
+
+Depending on your rack server setup, your request may timeout after a predetermined period (normally 60 seconds).
+If you're using Unicorn, this is done by killing the worker process.
+
+```
+GET /-/chaos/db_spin
+GET /-/chaos/db_spin?duration_s=50
+GET /-/chaos/db_spin?duration_s=50&async=true
+```
+
+| Attribute    | Type    | Required | Description                                                                 |
+| ------------ | ------- | -------- | --------------------------------------------------------------------------- |
+| `interval_s` | float   | no       | Interval, in seconds, for every DB request. Defaults to 1s                  |
+| `duration_s` | integer | no       | Duration, in seconds, that the core will be utilized. Defaults to 30s       |
+| `async`      | boolean | no       | Set to true to perform the operation in a Sidekiq background worker process |
 
 ```bash
-curl http://localhost:3000/-/chaos/cpuspin?duration_s=60 --header 'X-Chaos-Secret: secret'
+curl http://localhost:3000/-/chaos/db_spin?interval_s=1&duration_s=60 --header 'X-Chaos-Secret: secret'
+curl http://localhost:3000/-/chaos/db_spin?interval_s=1&duration_s=60&token=secret
 ```
 
 ## Sleep
 
-This endpoint is similar to the CPU Spin endpoint but simulates off-processor activity, such as network calls to backend services. It will sleep for a given duration.
+This endpoint is similar to the CPU Spin endpoint but simulates off-processor activity, such as network calls to backend services. It will sleep for a given duration_s.
 
-As with the CPU Spin endpoint, this may lead to your request timing out if duration exceeds the configured limit.
+As with the CPU Spin endpoint, this may lead to your request timing out if duration_s exceeds the configured limit.
 
 ```
 GET /-/chaos/sleep
 GET /-/chaos/sleep?duration_s=50
+GET /-/chaos/sleep?duration_s=50&async=true
 ```
 
 | Attribute    | Type    | Required | Description                                                            |
 | ------------ | ------- | -------- | ---------------------------------------------------------------------- |
 | `duration_s` | integer | no       | Duration, in seconds, that the request will sleep for. Defaults to 30s |
+| `async`      | boolean | no       | Set to true to sleep in a Sidekiq background worker process            |
 
 ```bash
 curl http://localhost:3000/-/chaos/sleep?duration_s=60 --header 'X-Chaos-Secret: secret'
+curl http://localhost:3000/-/chaos/sleep?duration_s=60&token=secret
 ```
 
 ## Kill
@@ -110,8 +144,14 @@ Since this endpoint uses the `KILL` signal, the worker is not given a chance to
 
 ```
 GET /-/chaos/kill
+GET /-/chaos/kill?async=true
 ```
 
+| Attribute    | Type    | Required | Description                                                            |
+| ------------ | ------- | -------- | ---------------------------------------------------------------------- |
+| `async`      | boolean | no       | Set to true to kill a Sidekiq background worker process                |
+
 ```bash
 curl http://localhost:3000/-/chaos/kill --header 'X-Chaos-Secret: secret'
+curl http://localhost:3000/-/chaos/kill?token=secret
 ```
diff --git a/doc/development/chatops_on_gitlabcom.md b/doc/development/chatops_on_gitlabcom.md
index c63ec53414c..3b681880401 100644
--- a/doc/development/chatops_on_gitlabcom.md
+++ b/doc/development/chatops_on_gitlabcom.md
@@ -1,21 +1,22 @@
 # Chatops on GitLab.com
 
-Chatops on GitLab.com allows GitLabbers to run various automation tasks on GitLab.com using Slack.
+ChatOps on GitLab.com allows GitLab team members to run various automation tasks on GitLab.com using Slack.
 
 ## Requesting access
 
-GitLabbers may need access to Chatops on GitLab.com for administration tasks such as:
+GitLab team-members may need access to Chatops on GitLab.com for administration
+tasks such as:
 
-- Configuring feature flags on staging.	
+- Configuring feature flags.
 - Running `EXPLAIN` queries against the GitLab.com production replica.
 
 To request access to Chatops on GitLab.com:
 
 1. Log into <https://ops.gitlab.net/users/sign_in> using the same username as for GitLab.com.
-1. Ask [anyone in the `chatops` project](https://gitlab.com/gitlab-com/chatops/project_members) to add you by running `/chatops run member add <username> gitlab-com/chatops --ops`.
+1. Ask [anyone in the `chatops` project](https://gitlab.com/gitlab-com/chatops/-/project_members) to add you by running `/chatops run member add <username> gitlab-com/chatops --ops`.
 
 ## See also
 
- - [Chatops Usage](https://docs.gitlab.com/ee/ci/chatops/README.html)
- - [Understanding EXPLAIN plans](understanding_explain_plans.md)
- - [Feature Groups](feature_flags.md#feature-groups)
+- [Chatops Usage](../ci/chatops/README.md)
+- [Understanding EXPLAIN plans](understanding_explain_plans.md)
+- [Feature Groups](feature_flags/development.md#feature-groups)
diff --git a/doc/development/code_comments.md b/doc/development/code_comments.md
new file mode 100644
index 00000000000..827a610efa2
--- /dev/null
+++ b/doc/development/code_comments.md
@@ -0,0 +1,14 @@
+# Code comments
+
+Whenever you add comment to the code that is expected to be addressed at any time
+in future, please create a technical debt issue for it. Then put a link to it
+to the code comment you've created. This will allow other developers to quickly
+check if a comment is still relevant and what needs to be done to address it.
+
+Examples:
+
+```rb
+# Deprecated scope until code_owner column has been migrated to rule_type.
+# To be removed with https://gitlab.com/gitlab-org/gitlab-ee/issues/11834.
+scope :code_owner, -> { where(code_owner: true).or(where(rule_type: :code_owner)) }
+```
diff --git a/doc/development/code_review.md b/doc/development/code_review.md
index 29e2aa1a581..b7d74b17eb3 100644
--- a/doc/development/code_review.md
+++ b/doc/development/code_review.md
@@ -45,9 +45,9 @@ page, with these behaviours:
 
 1. It will not pick people whose [GitLab status](../user/profile/index.md#current-status)
    contains the string 'OOO'.
-2. [Trainee maintainers](https://about.gitlab.com/handbook/engineering/workflow/code-review/#trainee-maintainer)
+1. [Trainee maintainers](https://about.gitlab.com/handbook/engineering/workflow/code-review/#trainee-maintainer)
    are three times as likely to be picked as other reviewers.
-3. It always picks the same reviewers and maintainers for the same
+1. It always picks the same reviewers and maintainers for the same
    branch name (unless their OOO status changes, as in point 1). It
    removes leading `ce-` and `ee-`, and trailing `-ce` and `-ee`, so
    that it can be stable for backport branches.
@@ -58,18 +58,21 @@ As described in the section on the responsibility of the maintainer below, you
 are recommended to get your merge request approved and merged by maintainer(s)
 from teams other than your own.
 
-   1. If your merge request includes backend changes [^1], it must be
-      **approved by a [backend maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce_maintainers_backend)**.
-   1. If your merge request includes frontend changes [^1], it must be
-      **approved by a [frontend maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce_maintainers_frontend)**.
-   1. If your merge request includes UX changes [^1], it must be
-      **approved by a [UX team member][team]**.
-   1. If your merge request includes adding a new JavaScript library [^1], it must be
-      **approved by a [frontend lead][team]**.
-   1. If your merge request includes adding a new UI/UX paradigm [^1], it must be
-      **approved by a [UX lead][team]**.
-   1. If your merge request includes a new dependency or a filesystem change, it must be
-      **approved by a [Distribution team member][team]**. See how to work with the [Distribution team](https://about.gitlab.com/handbook/engineering/dev-backend/distribution/) for more details.
+1. If your merge request includes backend changes [^1], it must be
+   **approved by a [backend maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce_maintainers_backend)**.
+1. If your merge request includes database migrations or changes to expensive queries [^2], it must be
+   **approved by a [database maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce_maintainers_database)**.
+   Read the [database review guidelines](database_review.md) for more details.
+1. If your merge request includes frontend changes [^1], it must be
+   **approved by a [frontend maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce_maintainers_frontend)**.
+1. If your merge request includes UX changes [^1], it must be
+   **approved by a [UX team member][team]**.
+1. If your merge request includes adding a new JavaScript library [^1], it must be
+   **approved by a [frontend lead][team]**.
+1. If your merge request includes adding a new UI/UX paradigm [^1], it must be
+   **approved by a [UX lead][team]**.
+1. If your merge request includes a new dependency or a filesystem change, it must be
+   **approved by a [Distribution team member][team]**. See how to work with the [Distribution team](https://about.gitlab.com/handbook/engineering/dev-backend/distribution/) for more details.
 
 #### Security requirements
 
@@ -205,9 +208,9 @@ first time.
 - Extract unrelated changes and refactorings into future merge requests/issues.
 - Seek to understand the reviewer's perspective.
 - Try to respond to every comment.
-- The merge request author resolves only the discussions they have fully
-  addressed. If there's an open reply, an open discussion, a suggestion,
-  a question, or anything else, the discussion should be left to be resolved
+- The merge request author resolves only the threads they have fully
+  addressed. If there's an open reply, an open thread, a suggestion,
+  a question, or anything else, the thread should be left to be resolved
   by the reviewer.
 - Push commits based on earlier rounds of feedback as isolated commits to the
   branch. Do not squash until the branch is ready to merge. Reviewers should be
@@ -317,7 +320,7 @@ reviewee.
 ### GitLab-specific concerns
 
 GitLab is used in a lot of places. Many users use
-our [Omnibus packages](https://about.gitlab.com/installation/), but some use
+our [Omnibus packages](https://about.gitlab.com/install/), but some use
 the [Docker images](https://docs.gitlab.com/omnibus/docker/), some are
 [installed from source](../install/installation.md),
 and there are other installation methods available. GitLab.com itself is a large
@@ -339,8 +342,7 @@ Enterprise Edition instance. This has some implications:
       - [Background migrations](background_migrations.md) run in Sidekiq, and
         should only be done for migrations that would take an extreme amount of
         time at GitLab.com scale.
-1. **Sidekiq workers**
-   [cannot change in a backwards-incompatible way](sidekiq_style_guide.md#removing-or-renaming-queues):
+1. **Sidekiq workers** [cannot change in a backwards-incompatible way](sidekiq_style_guide.md#removing-or-renaming-queues):
    1. Sidekiq queues are not drained before a deploy happens, so there will be
       workers in the queue from the previous version of GitLab.
    1. If you need to change a method signature, try to do so across two releases,
@@ -363,6 +365,31 @@ Enterprise Edition instance. This has some implications:
 1. **Filesystem access** can be slow, so try to avoid
    [shared files](shared_files.md) when an alternative solution is available.
 
+## Examples
+
+How code reviews are conducted can surprise new contributors. Here are some examples of code reviews that should help to orient you as to what to expect.
+
+**["Modify `DiffNote` to reuse it for Designs"](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/13703):**
+It contained everything from nitpicks around newlines to reasoning
+about what versions for designs are, how we should compare them
+if there was no previous version of a certain file (parent vs.
+blank `sha` vs empty tree).
+
+**["Support multi-line suggestions"](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/25211)**:
+The MR itself consists of a collaboration between FE and BE,
+and documenting comments from the author for the reviewer.
+There's some nitpicks, some questions for information, and
+towards the end, a security vulnerability.
+
+**["Allow multiple repositories per project"](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/10251)**:
+ZJ referred to the other projects (workhorse) this might impact,
+suggested some improvements for consistency. And James' comments
+helped us with overall code quality (using delegation, `&.` those
+types of things), and making the code more robust.
+
+**["Support multiple assignees for merge requests"](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/10161)**:
+A  good example of collaboration on an MR touching multiple parts of the codebase. Nick pointed out interesting edge cases, James Lopes also joined in raising concerns on import/export feature.
+
 ### Credits
 
 Largely based on the [thoughtbot code review guide].
@@ -377,3 +404,4 @@ Largely based on the [thoughtbot code review guide].
 [team]: https://about.gitlab.com/team/
 [build handbook]: https://about.gitlab.com/handbook/build/handbook/build#how-to-work-with-build
 [^1]: Please note that specs other than JavaScript specs are considered backend code.
+[^2]: We encourage you to seek guidance from a database maintainer if your merge request is potentially introducing expensive queries. It is most efficient to comment on the line of code in question with the SQL queries so they can give their advice.
diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md
index b9c369286d2..7d2d1b77a0e 100644
--- a/doc/development/contributing/community_roles.md
+++ b/doc/development/contributing/community_roles.md
@@ -1,11 +1,11 @@
-### Community members & roles
+# Community members & roles
 
 GitLab community members and their privileges/responsibilities.
 
 | Roles | Responsibilities | Requirements |
 |-------|------------------|--------------|
-| Maintainer | Accepts merge requests on several GitLab projects | Added to the [team page](https://about.gitlab.com/team/). An expert on code reviews and knows the product/code base |
-| Reviewer | Performs code reviews on MRs | Added to the [team page](https://about.gitlab.com/team/) |
+| Maintainer | Accepts merge requests on several GitLab projects | Added to the [team page](https://about.gitlab.com/company/team/). An expert on code reviews and knows the product/code base |
+| Reviewer | Performs code reviews on MRs | Added to the [team page](https://about.gitlab.com/company/team/) |
 | Developer |Has access to GitLab internal infrastructure & issues (e.g. HR-related) | GitLab employee or a Core Team member (with an NDA) |
 | Contributor | Can make contributions to all GitLab public projects | Have a GitLab.com account |
 
diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md
index 59cf5014da4..853882e8642 100644
--- a/doc/development/contributing/index.md
+++ b/doc/development/contributing/index.md
@@ -4,7 +4,7 @@ Thank you for your interest in contributing to GitLab. This guide details how
 to contribute to GitLab in a way that is easy for everyone.
 
 For a first-time step-by-step guide to the contribution process, please see
-["Contributing to GitLab"](https://about.gitlab.com/contributing/).
+["Contributing to GitLab"](https://about.gitlab.com/community/contribute/).
 
 Looking for something to work on? Look for issues with the label [`Accepting merge requests`](#i-want-to-contribute).
 
diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md
index 0396f7ebc45..b2e3ef7bf63 100644
--- a/doc/development/contributing/issue_workflow.md
+++ b/doc/development/contributing/issue_workflow.md
@@ -1,21 +1,24 @@
 # Workflow labels
 
 To allow for asynchronous issue handling, we use [milestones][milestones-page]
-and [labels][labels-page]. Leads and product managers handle most of the
+and [labels](https://gitlab.com/gitlab-org/gitlab-ce/-/labels). Leads and product managers handle most of the
 scheduling into milestones. Labelling is a task for everyone.
 
 Most issues will have labels for at least one of the following:
 
-- Type: ~feature, ~bug, ~customer, etc.
-- Subject: ~wiki, ~"Container Registry", ~ldap, ~api, ~frontend, etc.
-- Team: ~Plan, ~Manage, ~Quality, etc.
-- Stage: ~"devops:plan", ~"devops:create", etc.
+- Type: ~feature, ~bug, ~backstage, etc.
+- Subject: ~wiki, ~"Container Registry", ~ldap, ~api, etc.
+- Team: ~Documentation, ~Delivery, etc.
+- Stage: ~"devops::plan", ~"devops::create", etc.
+- Group: ~"group::source code" ~"group::knowledge" ~"group::editor", etc.
+- Department: ~UX, ~Quality
+- Specialization: ~frontend, ~backend
 - Release Scoping: ~Deliverable, ~Stretch, ~"Next Patch Release"
 - Priority: ~P1, ~P2, ~P3, ~P4
 - Severity: ~S1, ~S2, ~S3, ~S4
 
 All labels, their meaning and priority are defined on the
-[labels page][labels-page].
+[labels page](https://gitlab.com/gitlab-org/gitlab-ce/-/labels).
 
 If you come across an issue that has none of these, and you're allowed to set
 labels, you can _always_ add the team and type, and often also the subject.
@@ -27,8 +30,7 @@ labels, you can _always_ add the team and type, and often also the subject.
 Type labels are very important. They define what kind of issue this is. Every
 issue should have one or more.
 
-Examples of type labels are ~feature, ~bug, ~customer, ~security,
-and ~direction.
+Examples of type labels are ~feature, ~bug, ~backstage and ~security
 
 A number of type labels have a priority assigned to them, which automatically
 makes them float to the top, depending on their importance.
@@ -36,13 +38,17 @@ makes them float to the top, depending on their importance.
 Type labels are always lowercase, and can have any color, besides blue (which is
 already reserved for subject labels).
 
-The descriptions on the [labels page][labels-page] explain what falls under each type label.
+The descriptions on the [labels page](https://gitlab.com/gitlab-org/gitlab-ce/-/labels) explain what falls under each type label.
 
 ## Subject labels
 
 Subject labels are labels that define what area or feature of GitLab this issue
 hits. They are not always necessary, but very convenient.
 
+Subject labels are now used to infer and apply relevant group and devops stage
+labels. Please apply them whenever possible to facilitate accurate matching.
+Please refer to [this merge request][inferred-labels] for more information.
+
 Examples of subject labels are ~wiki, ~ldap, ~api,
 ~issues, ~"merge requests", ~labels, and ~"Container Registry".
 
@@ -54,34 +60,18 @@ Subject labels are always all-lowercase.
 
 ## Team labels
 
+**Important**: Most of the historical team labels (e.g. Manage, Plan etc.) are
+now deprecated in favor of [Group labels](#group-labels) and [Stage labels](#stage-labels).
+
 Team labels specify what team is responsible for this issue.
 Assigning a team label makes sure issues get the attention of the appropriate
 people.
 
 The current team labels are:
 
-- ~Configure
-- ~Create
-- ~Defend
-- ~Distribution
+- ~Delivery
 - ~Documentation
-- ~Geo
-- ~Gitaly
-- ~Growth
-- ~Manage
-- ~Monitor
-- ~Plan
 - ~Quality
-- ~Release
-- ~Secure
-- ~UX
-- ~Verify
-
-The descriptions on the [labels page][labels-page] explain what falls under the
-responsibility of each team.
-
-Within those team labels, we also have the ~backend and ~frontend labels to
-indicate if an issue needs backend work, frontend work, or both.
 
 Team labels are always capitalized so that they show up as the first label for
 any issue.
@@ -90,33 +80,11 @@ any issue.
 
 Stage labels specify which [DevOps stage][devops-stages] the issue belongs to.
 
-The current stage labels are:
-
-- ~"devops::manage"
-- ~"devops::plan"
-- ~"devops::create"
-- ~"devops::verify"
-- ~"devops::package"
-- ~"devops::release"
-- ~"devops::configure"
-- ~"devops::monitor"
-- ~"devops::secure"
-- ~"devops::defend"
-- ~"devops::growth"
-- ~"devops::enablement"
+The current stage labels can be found by [searching the labels list for `devops::`](https://gitlab.com/groups/gitlab-org/-/labels?search=devops%3A%3A).
 
 These labels are [scoped labels](../../user/project/labels.md#scoped-labels-premium)
 and thus are mutually exclusive.
 
-They differ from the [Team labels](#team-labels) because teams may work on
-issues outside their stage.
-
-Normally there is a 1:1 relationship between Stage labels and Team labels, but
-any issue can be picked up by any team, depending on current priorities.
-So, an issue labeled ~"devops:create" may be scheduled by the ~Plan team, for
-example. In such cases, it's usual to include both team labels so each team can
-be aware of the progress.
-
 The Stage labels are used to generate the [direction pages][direction-pages] automatically.
 
 [devops-stages]: https://about.gitlab.com/direction/#devops-stages
@@ -126,21 +94,39 @@ The Stage labels are used to generate the [direction pages][direction-pages] aut
 
 Group labels specify which [groups][structure-groups] the issue belongs to.
 
-Examples include:
-
-- ~"group::control"
-- ~"group::editor"
+The current group labels can be found by [searching the labels list for `group::`](https://gitlab.com/groups/gitlab-org/-/labels?search=group%3A%3A).
 
 These labels are [scoped labels](../../user/project/labels.md#scoped-labels-premium)
 and thus are mutually exclusive.
 
-Groups are nested beneath a particular stage, so only one stage label and one group label
-can be applied to a single issue. You can find the groups listed in the
-[Product Categories pages][product-categories].
+You can find the groups listed in the [Product Stages, Groups, and Categories][product-categories] page.
+
+We use the term group to map down product requirements from our product stages.
+As a team needs some way to collect the work their members are planning to be assigned to, we use the `~group::` labels to do so.
+
+Normally there is a 1:1 relationship between Stage labels and Group labels. In the spirit of "Everyone can contribute",
+any issue can be picked up by any group, depending on current priorities. For example, an issue labeled ~"devops::create" may be picked up by the ~"group::access" group.
+
+We also use stage and group labels to help quantify our [throughput](https://about.gitlab.com/handbook/engineering/management/throughput).
+Please read [Stage and Group labels in Throughtput](https://about.gitlab.com/handbook/engineering/management/throughput/#stage-and-group-labels-in-throughput) for more information on how the labels are used in this context.
 
 [structure-groups]: https://about.gitlab.com/company/team/structure/#groups
 [product-categories]: https://about.gitlab.com/handbook/product/categories/
 
+## Department labels
+
+The current department labels are:
+
+- ~UX
+- ~Quality
+
+## Specialization labels
+
+These labels narrow the [specialization](https://about.gitlab.com/company/team/structure/#specialist) on a unit of work.
+
+- ~frontend
+- ~backend
+
 ## Release Scoping labels
 
 Release Scoping labels help us clearly communicate expectations of the work for the
@@ -172,34 +158,34 @@ This label documents the planned timeline & urgency which is used to measure aga
 | ~P3   | Medium Priority | Within the next 3 releases (approx one quarter or 90 days)                 |
 | ~P4   | Low Priority    | Anything outside the next 3 releases (more than one quarter or 120 days)   |
 
-If an issue seems to fall between two priority labels, assign it to the higher-
-priority label.
-
 ## Severity labels
 
 Severity labels help us clearly communicate the impact of a ~bug on users.
-
-| Label | Meaning           | Impact on Functionality                               | Example |
-|-------|-------------------|-------------------------------------------------------|---------|
-| ~S1   | Blocker           | Outage, broken feature with no workaround             | Unable to create an issue. Data corruption/loss. Security breach. |
-| ~S2   | Critical Severity | Broken Feature, workaround too complex & unacceptable | Can push commits, but only via the command line. |
-| ~S3   | Major Severity    | Broken Feature, workaround acceptable                 | Can create merge requests only from the Merge Requests page, not through the Issue. |
-| ~S4   | Low Severity      | Functionality inconvenience or cosmetic issue         | Label colors are incorrect / not being displayed. |
-
-If an issue seems to fall between two severity labels, even taking the
-[severity impact guidance](#severity-impact-guidance) into account, assign
-it to the higher-severity label.
-
-### Severity impact guidance
-
-Severity levels can be applied further depending on the facet of the impact; e.g. Affected customers, GitLab.com availability, performance and etc. The below is a guideline.
-
-| Severity | Affected Customers/Users                                            | GitLab.com Availability                            |  Performance Degradation     |
-|----------|---------------------------------------------------------------------|----------------------------------------------------|------------------------------|
-| ~S1      | >50% users affected (possible company extinction level event)       | Significant impact on all of GitLab.com            |                              |
-| ~S2      | Many users or multiple paid customers affected (but not apocalyptic)| Significant impact on large portions of GitLab.com | Degradation is guaranteed to occur in the near future |
-| ~S3      | A few users or a single paid customer affected                      | Limited impact on important portions of GitLab.com | Degradation is likely to occur in the near future     |
-| ~S4      | No paid users/customer affected, or expected to in the near future  | Minor impact on GitLab.com                         | Degradation _may_ occur but it's not likely           |
+There can be multiple facets of the impact. The below is a guideline.
+
+| Label | Meaning           | Functionality                                         | Affected Users                   | GitLab.com Availability                            | Performance Degradation      |
+|-------|-------------------|-------------------------------------------------------|----------------------------------|----------------------------------------------------|------------------------------|
+| ~S1   | Blocker           | Unusable feature with no workaround, user is blocked  | Impacts 50% or more of users     | Outage, Significant impact on all of GitLab.com    |                                                       |
+| ~S2   | Critical Severity | Broken Feature, workaround too complex & unacceptable | Impacts between 25%-50% of users | Significant impact on large portions of GitLab.com | Degradation is guaranteed to occur in the near future |
+| ~S3   | Major Severity    | Broken feature with an acceptable workaround          | Impacts up to 25% of users       | Limited impact on important portions of GitLab.com | Degradation is likely to occur in the near future     |
+| ~S4   | Low Severity      | Functionality inconvenience or cosmetic issue         | Impacts less than 5% of users    | Minor impact on GitLab.com                         | Degradation _may_ occur but it's not likely           |
+
+If a bug seems to fall between two severity labels, assign it to the higher-severity label.
+
+- Example(s) of ~S1
+  - Data corruption/loss.
+  - Security breach.
+  - Unable to create an issue or merge request.
+  - Unable to add a comment or thread to the issue or merge request.
+- Example(s) of ~S2
+  - Cannot submit changes through the web IDE but the commandline works.
+  - A status widget on the merge request page is not working but information can be seen in the test pipeline page.
+- Example(s) of ~S3
+  - Can create merge requests only from the Merge Requests list view, not from an Issue page.
+  - Status is not updated in real time and needs a page refresh.
+- Example(s) of ~S4
+  - Label colors are incorrect.
+  - UI elements are not fully aligned.
 
 ## Label for community contributors
 
@@ -235,7 +221,7 @@ know how difficult the issue is. Additionally:
   as suitable for people that have never contributed to GitLab before on the
   [Up For Grabs campaign](http://up-for-grabs.net)
 - We encourage people that have never contributed to any open source project to
-  look for [`Accepting merge requests` issues with a weight of 1][firt-timers]
+  look for [`Accepting merge requests` issues with a weight of 1][first-timers]
 
 If you've decided that you would like to work on an issue, please @-mention
 the [appropriate product manager](https://about.gitlab.com/handbook/product/#who-to-talk-to-for-what)
@@ -248,8 +234,8 @@ GitLab team members who apply the ~"Accepting merge requests" label to an issue
 should update the issue description with a responsible product manager, inviting
 any potential community contributor to @-mention per above.
 
-[up-for-grabs]: https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=0&sort=weight
-[firt-timers]: https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=0&sort=weight&weight=1
+[up-for-grabs]: https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight
+[first-timers]: https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight&weight=1
 
 ## Issue triaging
 
@@ -284,7 +270,7 @@ For feature proposals for EE, open an issue on the
 
 In order to help track the feature proposals, we have created a
 [`feature`][fl] label. For the time being, users that are not members
-of the project cannot add labels. You can instead ask one of the [core team]
+of the project cannot add labels. You can instead ask one of the [core team](https://about.gitlab.com/community/core-team/)
 members to add the label ~feature to the issue or add the following
 code snippet right after your description in a new line: `~feature`.
 
@@ -295,7 +281,7 @@ Please submit Feature Proposals using the ['Feature Proposal' issue template](ht
 
 For changes in the interface, it is helpful to include a mockup. Issues that add to, or change, the interface should
 be given the ~"UX" label. This will allow the UX team to provide input and guidance. You may
-need to ask one of the [core team] members to add the label, if you do not have permissions to do it by yourself.
+need to ask one of the [core team](https://about.gitlab.com/community/core-team/) members to add the label, if you do not have permissions to do it by yourself.
 
 If you want to create something yourself, consider opening an issue first to
 discuss whether it is interesting to include this in GitLab.
@@ -439,6 +425,6 @@ A recent example of this was the issue for
 
 [Return to Contributing documentation](index.md)
 
-[labels-page]: https://gitlab.com/gitlab-org/gitlab-ce/labels
 [ce-tracker]: https://gitlab.com/gitlab-org/gitlab-ce/issues
 [ee-tracker]: https://gitlab.com/gitlab-org/gitlab-ee/issues
+[inferred-labels]: https://gitlab.com/gitlab-org/quality/triage-ops/merge_requests/155
diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md
index 8a4aa5dfa7f..4e9c5c81379 100644
--- a/doc/development/contributing/merge_request_workflow.md
+++ b/doc/development/contributing/merge_request_workflow.md
@@ -65,7 +65,7 @@ request is as follows:
    1. If you are contributing documentation, choose `Documentation` from the
       "Choose a template" menu and fill in the description according to the template.
    1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or
-      `Closes #XXX` syntax to [auto-close](../../user/project/issues/automatic_issue_closing.md)
+      `Closes #XXX` syntax to [auto-close](../../user/project/issues/managing_issues.md#closing-issues-automatically)
       the issue(s) once the merge request is merged.
 1. If you're allowed to (Core team members, for example), set a relevant milestone
    and [labels](issue_workflow.md).
@@ -74,10 +74,10 @@ request is as follows:
    can be found by running `grep css-class ./app -R`.
 1. Be prepared to answer questions and incorporate feedback into your MR with new
    commits. Once you have fully addressed a suggestion from a reviewer, click the
-   "Resolve discussion" button beneath it to mark it resolved.
-   1. The merge request author resolves only the discussions they have fully addressed.
-      If there's an open reply or discussion, a suggestion, a question, or anything else,
-      the discussion should be left to be resolved by the reviewer.
+   "Resolve thread" button beneath it to mark it resolved.
+   1. The merge request author resolves only the threads they have fully addressed.
+      If there's an open reply or thread, a suggestion, a question, or anything else,
+      the thread should be left to be resolved by the reviewer.
 1. If your MR touches code that executes shell commands, reads or opens files, or
    handles paths to files on disk, make sure it adheres to the
    [shell command guidelines](../shell_commands.md)
@@ -103,7 +103,8 @@ If you would like quick feedback on your merge request feel free to mention some
 from the [core team](https://about.gitlab.com/community/core-team/) or one of the
 [merge request coaches](https://about.gitlab.com/team/). When having your code reviewed
 and when reviewing merge requests, please keep the [code review guidelines](../code_review.md)
-in mind.
+in mind. And if your code also makes changes to the database, or does expensive queries,
+check the [database review guidelines](../database_review.md).
 
 ### Keep it simple
 
@@ -126,22 +127,53 @@ When writing commit messages, please follow the guidelines below:
 
 - The commit subject must contain at least 3 words.
 - The commit subject should ideally contain up to 50 characters,
-and must not be longer than 72 characters.
+  and must not be longer than 72 characters.
 - The commit subject must start with a capital letter.
 - The commit subject must not end with a period.
 - The commit subject and body must be separated by a blank line.
 - The commit body must not contain more than 72 characters per line.
 - Commits that change 30 or more lines across at least 3 files must
-describe these changes in the commit body.
+  describe these changes in the commit body.
 - The commit subject or body must not contain Emojis.
 - Use issues and merge requests' full URLs instead of short references,
-as they are displayed as plain text outside of GitLab.
+  as they are displayed as plain text outside of GitLab.
 - The merge request must not contain more than 10 commit messages.
 
 If the guidelines are not met, the MR will not pass the
 [Danger checks](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/danger/commit_messages/Dangerfile).
 For more information see [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/).
 
+Example commit message template that can be used on your machine that embodies the above (guide for [how to apply template](https://codeinthehole.com/tips/a-useful-template-for-commit-messages/)):
+
+```text
+# (If applied, this commit will...) <subject> (Max 50 char)
+# |<----  Using a Maximum Of 50 Characters  ---->|
+
+
+# Explain why this change is being made
+# |<----   Try To Limit Each Line to a Maximum Of 72 Characters   ---->|
+
+# Provide links or keys to any relevant tickets, articles or other resources
+# Use issues and merge requests' full URLs instead of short references,
+# as they are displayed as plain text outside of GitLab
+
+# --- COMMIT END ---
+# --------------------
+# Remember to
+#    Capitalize the subject line
+#    Use the imperative mood in the subject line
+#    Do not end the subject line with a period
+#    Subject must contain at least 3 words
+#    Separate subject from body with a blank line
+#    Commits that change 30 or more lines across at least 3 files must
+#    describe these changes in the commit body
+#    Do not use Emojis
+#    Use the body to explain what and why vs. how
+#    Can use multiple lines with "-" for bullet points in body
+#    For more information: https://chris.beams.io/posts/git-commit/
+# --------------------
+```
+
 ## Contribution acceptance criteria
 
 To make sure that your merge request can be approved, please ensure that it meets
@@ -193,6 +225,7 @@ requirements.
 1. [Changelog entry added](../changelog.md), if necessary.
 1. Reviewed by relevant (UX/FE/BE/tech writing) reviewers and all concerns are addressed.
 1. Merged by a project maintainer.
+1. Confirmed to be working in the [Canary stage](https://about.gitlab.com/handbook/engineering/#canary-testing) or on GitLab.com once the contribution is deployed.
 1. Added to the [release post](https://about.gitlab.com/handbook/marketing/blog/release-posts/),
    if relevant.
 1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml), if relevant.
diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md
index f319d00d7fe..7832850a9f0 100644
--- a/doc/development/contributing/style_guides.md
+++ b/doc/development/contributing/style_guides.md
@@ -1,11 +1,11 @@
 # Style guides
 
-1. [Ruby](https://github.com/bbatsov/ruby-style-guide).
+1. [Ruby](https://github.com/rubocop-hq/ruby-style-guide).
    Important sections include [Source Code Layout][rss-source] and
    [Naming][rss-naming]. Use:
    - multi-line method chaining style **Option A**: dot `.` on the second line
    - string literal quoting style **Option A**: single quoted by default
-1. [Rails](https://github.com/bbatsov/rails-style-guide)
+1. [Rails](https://github.com/rubocop-hq/rails-style-guide)
 1. [Newlines styleguide][newlines-styleguide]
 1. [Testing][testing]
 1. [JavaScript styleguide][js-styleguide]
@@ -13,7 +13,7 @@
 1. [Shell commands (Ruby)](../shell_commands.md) created by GitLab
    contributors to enhance security
 1. [Database Migrations](../migration_style_guide.md)
-1. [Markdown](http://www.cirosantilli.com/markdown-styleguide)
+1. [Markdown](https://cirosantilli.com/markdown-style-guide/)
 1. [Documentation styleguide](../documentation/styleguide.md)
 1. Interface text should be written subjectively instead of objectively. It
    should be the GitLab core team addressing a person. It should be written in
@@ -23,16 +23,17 @@
 1. Code should be written in [US English][us-english]
 1. [Go](../go_guide/index.md)
 1. [Python](../python_guide/index.md)
+1. [Shell scripting](../shell_scripting_guide/index.md)
 
 This is also the style used by linting tools such as
-[RuboCop](https://github.com/bbatsov/rubocop) and [Hound CI](https://houndci.com).
+[RuboCop](https://github.com/rubocop-hq/rubocop) and [Hound CI](https://houndci.com).
 
 ---
 
 [Return to Contributing documentation](index.md)
 
-[rss-source]: https://github.com/bbatsov/ruby-style-guide/blob/master/README.md#source-code-layout
-[rss-naming]: https://github.com/bbatsov/ruby-style-guide/blob/master/README.md#naming
+[rss-source]: https://github.com/rubocop-hq/ruby-style-guide/blob/master/README.adoc#source-code-layout
+[rss-naming]: https://github.com/rubocop-hq/ruby-style-guide/blob/master/README.adoc#naming-conventions
 [doc-guidelines]: ../documentation/index.md "Documentation guidelines"
 [js-styleguide]: ../fe_guide/style_guide_js.md "JavaScript styleguide"
 [scss-styleguide]: ../fe_guide/style_guide_scss.md "SCSS styleguide"
diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md
index 68d33a9d8e0..eb3b227473b 100644
--- a/doc/development/database_debugging.md
+++ b/doc/development/database_debugging.md
@@ -3,37 +3,37 @@
 This section is to help give some copy-pasta you can use as a reference when you
 run into some head-banging database problems.
 
-An easy first step is to search for your error in Slack or google "GitLab <my error>".
+An easy first step is to search for your error in Slack or google "GitLab (my error)".
 
 ---
 
 Available `RAILS_ENV`
 
- - `production` (generally not for your main GDK db, but you may need this for e.g. omnibus)
- - `development` (this is your main GDK db)
- - `test` (used for tests like rspec)
+- `production` (generally not for your main GDK db, but you may need this for e.g. omnibus)
+- `development` (this is your main GDK db)
+- `test` (used for tests like rspec)
 
 ## Nuke everything and start over
 
 If you just want to delete everything and start over with an empty DB (~1 minute):
 
- - `bundle exec rake db:reset RAILS_ENV=development`
+- `bundle exec rake db:reset RAILS_ENV=development`
 
 If you just want to delete everything and start over with dummy data (~40 minutes). This also does `db:reset` and runs DB-specific migrations:
 
- - `bundle exec rake dev:setup RAILS_ENV=development`
+- `bundle exec rake dev:setup RAILS_ENV=development`
 
 If your test DB is giving you problems, it is safe to nuke it because it doesn't contain important data:
 
- - `bundle exec rake db:reset RAILS_ENV=test`
+- `bundle exec rake db:reset RAILS_ENV=test`
 
 ## Migration wrangling
 
- - `bundle exec rake db:migrate RAILS_ENV=development`: Execute any pending migrations that you may have picked up from a MR
- - `bundle exec rake db:migrate:status RAILS_ENV=development`: Check if all migrations are `up` or `down`
- - `bundle exec rake db:migrate:down VERSION=20170926203418 RAILS_ENV=development`: Tear down a migration
- - `bundle exec rake db:migrate:up VERSION=20170926203418 RAILS_ENV=development`: Set up a migration
- - `bundle exec rake db:migrate:redo VERSION=20170926203418 RAILS_ENV=development`: Re-run a specific migration
+- `bundle exec rake db:migrate RAILS_ENV=development`: Execute any pending migrations that you may have picked up from a MR
+- `bundle exec rake db:migrate:status RAILS_ENV=development`: Check if all migrations are `up` or `down`
+- `bundle exec rake db:migrate:down VERSION=20170926203418 RAILS_ENV=development`: Tear down a migration
+- `bundle exec rake db:migrate:up VERSION=20170926203418 RAILS_ENV=development`: Set up a migration
+- `bundle exec rake db:migrate:redo VERSION=20170926203418 RAILS_ENV=development`: Re-run a specific migration
 
 ## Manually access the database
 
@@ -45,12 +45,12 @@ bundle exec rails dbconsole RAILS_ENV=development
 bundle exec rails db RAILS_ENV=development
 ```
 
- - `\q`: Quit/exit
- - `\dt`: List all tables
- - `\d+ issues`: List columns for `issues` table
- - `CREATE TABLE board_labels();`: Create a table called `board_labels`
- - `SELECT * FROM schema_migrations WHERE version = '20170926203418';`: Check if a migration was run
- - `DELETE FROM schema_migrations WHERE version = '20170926203418';`: Manually remove a migration
+- `\q`: Quit/exit
+- `\dt`: List all tables
+- `\d+ issues`: List columns for `issues` table
+- `CREATE TABLE board_labels();`: Create a table called `board_labels`
+- `SELECT * FROM schema_migrations WHERE version = '20170926203418';`: Check if a migration was run
+- `DELETE FROM schema_migrations WHERE version = '20170926203418';`: Manually remove a migration
 
 ## FAQ
 
@@ -85,3 +85,21 @@ eric             37709   0.0  0.0  2518640   7524 s006  S    Wed11AM   0:00.79 s
 $ kill 87304
 $ kill 37709
 ```
+
+### db:migrate `database version is too old to be migrated` error
+
+Users receive this error when `db:migrate` detects that the current schema version
+is older than the `MIN_SCHEMA_VERSION` defined in the `Gitlab::Database` library
+module.
+
+Over time we cleanup/combine old migrations in the codebase, so it is not always
+possible to migrate GitLab from every previous version.
+
+In some cases you may want to bypass this check. For example, if you were on a version
+of GitLab schema later than the `MIN_SCHEMA_VERSION`, and then rolled back the
+to an older migration, from before. In this case, in order to migrate forward again,
+you should set the `SKIP_SCHEMA_VERSION_CHECK` environment variable.
+
+```sh
+bundle exec rake db:migrate SKIP_SCHEMA_VERSION_CHECK=true
+```
diff --git a/doc/development/database_review.md b/doc/development/database_review.md
new file mode 100644
index 00000000000..3f1b359cb0b
--- /dev/null
+++ b/doc/development/database_review.md
@@ -0,0 +1,134 @@
+# Database Review Guidelines
+
+This page is specific to database reviews. Please refer to our
+[code review guide](code_review.md) for broader advice and best
+practices for code review in general.
+
+## General process
+
+A database review is required for:
+
+- Changes that touch the database schema or perform data migrations,
+  including files in:
+  - `db/`
+  - `lib/gitlab/background_migration/`
+- Changes to the database tooling, e.g.:
+  - migration or ActiveRecord helpers in `lib/gitlab/database/`
+  - load balancing
+- Changes that produce SQL queries that are beyond the obvious. It is
+  generally up to the author of a merge request to decide whether or
+  not complex queries are being introduced and if they require a
+  database review.
+
+A database reviewer is expected to look out for obviously complex
+queries in the change and review those closer. If the author does not
+point out specific queries for review and there are no obviously
+complex queries, it is enough to concentrate on reviewing the
+migration only.
+
+It is preferable to review queries in SQL form and generally accepted
+to ask the author to translate any ActiveRecord queries in SQL form
+for review.
+
+### Roles and process
+
+A Merge Request author's role is to:
+
+- Decide whether a database review is needed.
+- If database review is needed, add the ~database label.
+- Use the [database changes](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/merge_request_templates/Database%20changes.md)
+  merge request template, or include the appropriate items in the MR description.
+
+A database **reviewer**'s role is to:
+
+- Perform a first-pass review on the MR and suggest improvements to the author.
+- Once satisfied, relabel the MR with ~"database::reviewed", approve it, and
+  reassign MR to the database **maintainer** suggested by Reviewer
+  Roulette.
+
+A database **maintainer**'s role is to:
+
+- Perform the final database review on the MR.
+- Discuss further improvements or other relevant changes with the
+  database reviewer and the MR author.
+- Finally approve the MR and relabel the MR with ~"database::approved"
+- Merge the MR if no other approvals are pending or pass it on to
+  other maintainers as required (frontend, backend, docs).
+
+### Distributing review workload
+
+Review workload is distributed using [reviewer roulette](code_review.md#reviewer-roulette)
+([example](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/25181#note_147551725)).
+The MR author should then co-assign the suggested database
+**reviewer**. When they give their sign-off, they will hand over to
+the suggested database **maintainer**.
+
+If reviewer roulette didn't suggest a database reviewer & maintainer,
+make sure you have applied the ~database label and rerun the
+`danger-review` CI job, or pick someone from the
+[`@gl-database` team](https://gitlab.com/groups/gl-database/-/group_members).
+
+### How to prepare for speedy database reviews
+
+In order to make reviewing easier and therefore faster, please consider preparing a comment
+and details for a database reviewer:
+
+- Provide queries in SQL form rather than ActiveRecord.
+- Format any queries with a SQL query formatter, for example with [sqlformat.darold.net](http://sqlformat.darold.net).
+- Consider providing query plans via a link to [explain.depesz.com](https://explain.depesz.com) or another tool instead of textual form.
+- For query changes, it is best to provide the SQL query along with a plan *before* and *after* the change. This helps to spot differences quickly.
+- When providing query plans, make sure to use good parameter values, so that the query executed is a good example and also hits enough data. Usually, the `gitlab-org` namespace (`namespace_id = 9970`) and the `gitlab-org/gitlab-ce` project (`project_id = 13083`) provides enough data to serve as a good example.
+
+### How to review for database
+
+- Check migrations
+  - Review relational modeling and design choices
+  - Review migrations follow [database migration style guide](migration_style_guide.md),
+    for example
+    - [Check ordering of columns](ordering_table_columns.md)
+    - [Check indexes are present for foreign keys](migration_style_guide.md#adding-foreign-key-constraints)
+  - Ensure that migrations execute in a transaction or only contain
+    concurrent index/foreign key helpers (with transactions disabled)
+  - Check consistency with `db/schema.rb` and that migrations are [reversible](migration_style_guide.md#reversibility)
+  - Check queries timing (If any): Queries executed in a migration
+    need to fit comfortable within `15s` - preferably much less than that - on GitLab.com.
+- Check [background migrations](background_migrations.md):
+  - For data migrations, establish a time estimate for execution
+  - They should only be used when migrating data in larger tables.
+    - If a single `update` is below than `1s` the query can be placed
+      directly in a regular migration (inside `db/migrate`).
+  - Review queries (for example, make sure batch sizes are fine)
+  - Establish a time estimate for execution
+  - Because execution time can be longer than for a regular migration,
+    it's suggested to treat background migrations as post migrations:
+    place them in `db/post_migrate` instead of `db/migrate`. Keep in mind
+    that post migrations are executed post-deployment in production.
+- Check [timing guidelines for migrations](#timing-guidelines-for-migrations)
+- Query performance
+  - Check for any obviously complex queries and queries the author specifically
+    points out for review (if any)
+  - If not present yet, ask the author to provide SQL queries and query plans
+    (e.g. by using [chatops](understanding_explain_plans.md#chatops) or direct
+    database access)
+  - For given queries, review parameters regarding data distribution
+  - [Check query plans](understanding_explain_plans.md) and suggest improvements
+    to queries (changing the query, schema or adding indexes and similar)
+  - General guideline is for queries to come in below 100ms execution time
+  - If queries rely on prior migrations that are not present yet on production
+    (eg indexes, columns), you can use a [one-off instance from the restore
+    pipeline](https://ops.gitlab.net/gitlab-com/gl-infra/gitlab-restore/postgres-gprd)
+    in order to establish a proper testing environment.
+
+### Timing guidelines for migrations
+
+In general, migrations for a single deploy shouldn't take longer than
+1 hour for GitLab.com. The following guidelines are not hard rules, they were
+estimated to keep migration timing to a minimum.
+
+NOTE: **Note:** Keep in mind that all runtimes should be measured against GitLab.com.
+
+| Migration Type | Execution Time Recommended | Notes |
+|----|----|---|
+| Regular migrations on `db/migrate` | `3 minutes` | A valid exception  are index creation as this can take a long time. |
+| Post migrations on `db/post_migrate` | `10 minutes` | |
+| Background migrations | --- | Since these are suitable for larger tables, it's not possible to set a precise timing guideline, however, any query must stay well below `10s` of execution time. |
diff --git a/doc/development/diffs.md b/doc/development/diffs.md
index 56e869c21f8..ac0b8555360 100644
--- a/doc/development/diffs.md
+++ b/doc/development/diffs.md
@@ -6,6 +6,15 @@ Currently we rely on different sources to present diffs, these include:
 - Database (through `merge_request_diff_files`)
 - Redis (cached highlighted diffs)
 
+## Deep Dive
+
+In Jaunary 2019, Oswaldo Ferreira hosted a [Deep Dive] on GitLab's Diffs and Commenting on Diffs functionality to share his domain specific knowledge with anyone who may work in this part of the code base in the future. You can find the [recording on YouTube], and the slides on [Google Slides] and in [PDF]. Everything covered in this deep dive was accurate as of GitLab 11.7, and while specific details may have changed since then, it should still serve as a good introduction.
+
+[Deep Dive]: https://gitlab.com/gitlab-org/create-stage/issues/1
+[recording on YouTube]: https://www.youtube.com/watch?v=K6G3gMcFyek
+[Google Slides]: https://docs.google.com/presentation/d/1bGutFH2AT3bxOPZuLMGl1ANWHqFnrxwQwjiwAZkF-TU/edit
+[PDF]: https://gitlab.com/gitlab-org/create-stage/uploads/b5ad2f336e0afcfe0f99db0af0ccc71a/Create_Deep_Dive__Diffs_and_commenting_on_diffs.pdf
+
 ## Architecture overview
 
 ### Merge request diffs
diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md
index ca29353ecbe..ac93ada5a4b 100644
--- a/doc/development/documentation/feature-change-workflow.md
+++ b/doc/development/documentation/feature-change-workflow.md
@@ -121,27 +121,27 @@ All reviewers can help ensure accuracy, clarity, completeness, and adherence to
 
 - **Prior to merging**, documentation changes committed by the developer must be reviewed by:
 
-   1. **The code reviewer** for the MR, to confirm accuracy, clarity, and completeness.
-   1. Optionally: Others involved in the work, such as other devs or the PM.
-   1. Optionally: The technical writer for the DevOps stage. If not prior to merging, the technical writer will review after the merge.
-      This helps us ensure that the developer has time to merge good content by the freeze, and that it can be further refined by the release, if needed.
-      - To decide whether to request this review before the merge, consider the amount of time left before the code freeze, the size of the change,
-        and your degree of confidence in having users of an RC use your docs as written.
-      - Pre-merge tech writer reviews should be most common when the code is complete well in advance of the freeze and/or for larger documentation changes.
-      - You can request a review and if there is not sufficient time to complete it prior to the freeze,
-        the maintainer can merge the current doc changes (if complete) and create a follow-up doc review issue.
-      - The technical writer can also help decide what docs to merge before the freeze and whether to work on further changes in a follow up MR.
-      - **To request a pre-merge technical writer review**, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
-      - **To request a post-merge technical writer review**, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR that makes the doc change.
-   1. **The maintainer** who is assigned to merge the MR, to verify clarity, completeness, and quality, to the best of their ability.
+  1. **The code reviewer** for the MR, to confirm accuracy, clarity, and completeness.
+  1. Optionally: Others involved in the work, such as other devs or the PM.
+  1. Optionally: The technical writer for the DevOps stage. If not prior to merging, the technical writer will review after the merge.
+     This helps us ensure that the developer has time to merge good content by the freeze, and that it can be further refined by the release, if needed.
+     - To decide whether to request this review before the merge, consider the amount of time left before the code freeze, the size of the change,
+       and your degree of confidence in having users of an RC use your docs as written.
+     - Pre-merge tech writer reviews should be most common when the code is complete well in advance of the freeze and/or for larger documentation changes.
+     - You can request a review and if there is not sufficient time to complete it prior to the freeze,
+       the maintainer can merge the current doc changes (if complete) and create a follow-up doc review issue.
+     - The technical writer can also help decide what docs to merge before the freeze and whether to work on further changes in a follow up MR.
+     - **To request a pre-merge technical writer review**, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
+     - **To request a post-merge technical writer review**, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR that makes the doc change.
+  1. **The maintainer** who is assigned to merge the MR, to verify clarity, completeness, and quality, to the best of their ability.
 
 - Upon merging, if a technical writer review has not been performed and there is not yet a linked issue for a follow-up review, the maintainer should [create an issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review), link it from the MR, and
   mention the original MR author in the new issue. Alternatively, the maintainer can ask the MR author to create and link this issue before the MR is merged.
 
 - After merging, documentation changes are reviewed by:
 
-   1. The technical writer--**if** their review was not performed prior to the merge.
-   2. Optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used).
+  1. The technical writer -- **if** their review was not performed prior to the merge.
+  1. Optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used).
       Any party can raise the item to the PM for review at any point: the dev, the technical writer, or the PM, who can request/plan a review at the outset.
 
 ### Technical Writer role
diff --git a/doc/development/documentation/improvement-workflow.md b/doc/development/documentation/improvement-workflow.md
index a12c3d5ea7b..80fbd4b6427 100644
--- a/doc/development/documentation/improvement-workflow.md
+++ b/doc/development/documentation/improvement-workflow.md
@@ -52,9 +52,9 @@ To request a post-merge review, [create an issue for one using the Doc Review te
 **3. Maintainer**
 
 1. Review by assigned maintainer, who can always request/require the above reviews. Maintainer review can occur before or after a technical writer review.
-2. Ensure a release milestone of the format XX.Y is set. If the freeze for that release has begun, add the label `pick into <XX.Y>` unless this change is not required for the release. In that case, simply change the milestone.
-3. If EE and CE MRs exist, merge the EE MR first, then the CE MR.
-4. After merging, if there has not been a technical writer review and an issue for a follow-up review was not already created and linked from the MR, [create the issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR.
+1. Ensure a release milestone of the format XX.Y is set. If the freeze for that release has begun, add the label `pick into <XX.Y>` unless this change is not required for the release. In that case, simply change the milestone.
+1. If EE and CE MRs exist, merge the EE MR first, then the CE MR.
+1. After merging, if there has not been a technical writer review and an issue for a follow-up review was not already created and linked from the MR, [create the issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR.
 
 ## Other ways to help
 
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index c7fa40af930..c9ae00d148a 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -18,7 +18,7 @@ In addition to this page, the following resources to help craft and contribute d
 
 ## Source files and rendered web locations
 
-Documentation for GitLab Community Edition (CE) and Enterprise Edition (EE), along with GitLab Runner and Omnibus, is published to [docs.gitlab.com](https://docs.gitlab.com). The documentation for CE and EE is also published within the application at `/help` on the domain of the GitLab instance.
+Documentation for GitLab Community Edition (CE) and Enterprise Edition (EE), along with GitLab Runner and Omnibus, is published to [docs.gitlab.com](https://docs.gitlab.com). The documentation for CE and EE is also published within the application at `/help` on the domain of the GitLab instance, though there are [plans](https://gitlab.com/groups/gitlab-org/-/epics/693) to end this practice and instead link out from the GitLab application to docs.gitlab.com URLs.
 
 At `/help`, only content for your current edition and version is included, whereas multiple versions' content is available at docs.gitlab.com.
 
@@ -43,7 +43,7 @@ Meanwhile, anyone can contribute [documentation improvements](improvement-workfl
 
 ## Markdown and styles
 
-[GitLab docs](https://gitlab.com/gitlab-com/gitlab-docs) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown)
+[GitLab docs](https://gitlab.com/gitlab-org/gitlab-docs) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown)
 as its markdown rendering engine. See the [GitLab Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) for a complete Kramdown reference.
 
 Adhere to the [Documentation Style Guide](styleguide.md). If a style standard is missing, you are welcome to suggest one via a merge request.
@@ -57,35 +57,22 @@ See the [Structure](styleguide.md#structure) section of the [Documentation Style
 We currently maintain two sets of docs: one in the
 [gitlab-ce](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc) repo and
 one in [gitlab-ee](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/doc).
-They are similar, and most pages are identical, but they are different repositories.
-With the single codebase effort, we want to make those two sets identical, so when the
-time comes to have only one codebase, we'll be ready.
-
-Here are some links to get you up to speed with the current effort:
-
-- [CE/EE codebases blueprint](https://about.gitlab.com/handbook/engineering/infrastructure/blueprint/ce-ee-codebases/)
-- [CE/EE codebases merge design](https://about.gitlab.com/handbook/engineering/infrastructure/design/merge-ce-ee-codebases/)
-- [Single docs codebase epic](https://gitlab.com/groups/gitlab-org/-/epics/199)
-- [Issue board of related issues](https://gitlab.com/groups/gitlab-org/-/boards/981090?&label_name[]=Documentation&label_name[]=single%20codebase)
-- [Related merge requests](https://gitlab.com/groups/gitlab-org/-/merge_requests?scope=all&utf8=%E2%9C%93&state=all&label_name[]=Documentation&label_name[]=single%20codebase)
-- [Visualize the existing diffs](https://leipert-projects.gitlab.io/is-gitlab-pretty-yet/diff/?search=%5Edoc)
+They are identical, but they are different repositories. When the
+time comes to have only one codebase for the GitLab project, we'll be ready.
 
 ### CE first
 
-After a given documentation path is aligned across CE and EE, all merge requests
-affecting that path must be submitted to CE, regardless of the content it has.
-This means that:
+All merge requests for documentation must be submitted to CE, regardless of the content
+it has. This means that:
 
-* For **EE-only docs changes**, you only have to submit a CE MR.
-* For **EE-only features** that touch both the code and the docs, you have to submit
-an EE MR containing all changes, and a CE MR containing only the docs changes
-and without a changelog entry.
+- For **EE-only docs changes**, you only have to submit an MR in the CE project.
+- For **EE-only features** that touch both the code and the docs, you have to submit
+  an EE MR containing all code changes, and a CE MR containing only the docs changes
+  and without a changelog entry.
 
 This might seem like a duplicate effort, but it's only for the short term.
-A list of the already aligned docs can be found in
-[the epic description](https://gitlab.com/groups/gitlab-org/-/epics/199#ee-specific-lines-check).
 
-Since the docs will be combined, it's crucial to add the relevant
+Since the CE and EE docs are combined, it's crucial to add the relevant
 [product badges](styleguide.md#product-badges) for all EE documentation, so that
 we can discern which features belong to which tier.
 
@@ -94,19 +81,9 @@ we can discern which features belong to which tier.
 There's a special test in place
 ([`ee_specific_check.rb`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/scripts/ee_specific_check/ee_specific_check.rb)),
 which, among others, checks and prevents creating/editing new files and directories
-in EE under `doc/`.
-
-We have a long list of documentation paths that are either whitelisted or not.
-Paths in the whitelist (not commented out) will not be subject to the test,
-which means you are allowed to create/change docs content in EE for the time
-being. The goal is to not have any doc whitelisted.
-
-At the time of this writing, the only items left to be aligned are the API docs:
-
-- `doc/api/*` ([issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/60045) / [merge request](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27491))
-
-Eventually, once all docs are aligned, we'll remove any doc reference from that
-script, so it catches everything.
+in EE under `doc/`. This should fail when changes to anything in `/doc` are submitted
+in an EE MR. To pass the test, simply remove the docs changes from the EE MR, and
+[submit them in CE](#ce-first).
 
 ## Changing document location
 
@@ -134,18 +111,18 @@ For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to
 1. Copy `doc/workflow/lfs/lfs_administration.md` to `doc/administration/lfs.md`
 1. Replace the contents of `doc/workflow/lfs/lfs_administration.md` with:
 
-    ```md
-    This document was moved to [another location](../../administration/lfs.md).
-    ```
+   ```md
+   This document was moved to [another location](../../administration/lfs.md).
+   ```
 
 1. Find and replace any occurrences of the old location with the new one.
    A quick way to find them is to use `git grep`. First go to the root directory
    where you cloned the `gitlab-ce` repository and then do:
 
-    ```sh
-    git grep -n "workflow/lfs/lfs_administration"
-    git grep -n "lfs/lfs_administration"
-    ```
+   ```sh
+   git grep -n "workflow/lfs/lfs_administration"
+   git grep -n "lfs/lfs_administration"
+   ```
 
 NOTE: **Note:**
 If the document being moved has any Disqus comments on it, there are extra steps
@@ -193,7 +170,7 @@ Disqus uses an identifier per page, and for docs.gitlab.com, the page identifier
 is configured to be the page URL. Therefore, when we change the document location,
 we need to preserve the old URL as the same Disqus identifier.
 
-To do that, add to the frontmatter the variable `redirect_from`,
+To do that, add to the frontmatter the variable `disqus_identifier`,
 using the old URL as value. For example, let's say I moved the document
 available under `https://docs.gitlab.com/my-old-location/README.html` to a new location,
 `https://docs.gitlab.com/my-new-location/index.html`.
@@ -202,11 +179,11 @@ Into the **new document** frontmatter add the following:
 
 ```yaml
 ---
-redirect_from: 'https://docs.gitlab.com/my-old-location/README.html'
+disqus_identifier: 'https://docs.gitlab.com/my-old-location/README.html'
 ---
 ```
 
-Note: it is necessary to include the file name in the `redirect_from` URL,
+Note: it is necessary to include the file name in the `disqus_identifier` URL,
 even if it's `index.html` or `README.html`.
 
 ## Branch naming
@@ -274,8 +251,11 @@ Follow this [method for cherry-picking from CE to EE](../automatic_ce_ee_merge.m
 
 ## GitLab `/help`
 
-Every GitLab instance includes the documentation, which is available from `/help`
-(`http://my-instance.com/help`), e.g., <https://gitlab.com/help>.
+Every GitLab instance includes the documentation, which is available at `/help`
+(`https://gitlab.example.com/help`). For example, <https://gitlab.com/help>.
+
+There are [plans](https://gitlab.com/groups/gitlab-org/-/epics/693) to end this
+practice and instead link out from the GitLab application to docs.gitlab.com URLs.
 
 The documentation available online on docs.gitlab.com is continuously
 deployed every hour from the `master` branch of CE, EE, Omnibus, and Runner. Therefore,
@@ -316,45 +296,45 @@ You can combine one or more of the following:
 1. **Linking to an anchor link.** Use `anchor` as part of the `help_page_path`
    method:
 
-    ```haml
-    = link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link')
-    ```
+   ```haml
+   = link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link')
+   ```
 
 1. **Opening links in a new tab.** This should be the default behavior:
 
-    ```haml
-    = link_to 'Help page', help_page_path('user/permissions'), target: '_blank'
-    ```
+   ```haml
+   = link_to 'Help page', help_page_path('user/permissions'), target: '_blank'
+   ```
 
 1. **Linking to a circle icon.** Usually used in settings where a long
    description cannot be used, like near checkboxes. You can basically use
    any font awesome icon, but prefer the `question-circle`:
 
-    ```haml
-    = link_to icon('question-circle'), help_page_path('user/permissions')
-    ```
+   ```haml
+   = link_to icon('question-circle'), help_page_path('user/permissions')
+   ```
 
 1. **Using a button link.** Useful in places where text would be out of context
    with the rest of the page layout:
 
-    ```haml
-    = link_to 'Help page', help_page_path('user/permissions'),  class: 'btn btn-info'
-    ```
+   ```haml
+   = link_to 'Help page', help_page_path('user/permissions'),  class: 'btn btn-info'
+   ```
 
 1. **Using links inline of some text.**
 
-    ```haml
-    Description to #{link_to 'Help page', help_page_path('user/permissions')}.
-    ```
+   ```haml
+   Description to #{link_to 'Help page', help_page_path('user/permissions')}.
+   ```
 
 1. **Adding a period at the end of the sentence.** Useful when you don't want
    the period to be part of the link:
 
-    ```haml
-    = succeed '.' do
-      Learn more in the
-      = link_to 'Help page', help_page_path('user/permissions')
-    ```
+   ```haml
+   = succeed '.' do
+     Learn more in the
+     = link_to 'Help page', help_page_path('user/permissions')
+   ```
 
 ### GitLab `/help` tests
 
@@ -381,7 +361,7 @@ on how the left-side navigation menu is built and updated.
 
 NOTE: **Note:**
 To preview your changes to documentation locally, follow this
-[development guide](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md).
+[development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md).
 
 The live preview is currently enabled for the following projects:
 
@@ -405,7 +385,7 @@ You will need to push a branch to those repositories, it doesn't work for forks.
 
 The `review-docs-deploy*` job will:
 
-1. Create a new branch in the [gitlab-docs](https://gitlab.com/gitlab-com/gitlab-docs)
+1. Create a new branch in the [gitlab-docs](https://gitlab.com/gitlab-org/gitlab-docs)
    project named after the scheme: `$DOCS_GITLAB_REPO_SUFFIX-$CI_ENVIRONMENT_SLUG`,
    where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ce` for
    CE, etc.
@@ -461,7 +441,7 @@ If you want to know the in-depth details, here's what's really happening:
    1. The preview URL is shown both at the job output and in the merge request
       widget. You also get the link to the remote pipeline.
 1. In the docs project, the pipeline is created and it
-   [skips the test jobs](https://gitlab.com/gitlab-com/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55)
+   [skips the test jobs](https://gitlab.com/gitlab-org/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55)
    to lower the build time.
 1. Once the docs site is built, the HTML files are uploaded as artifacts.
 1. A specific Runner tied only to the docs project, runs the Review App job
@@ -485,15 +465,17 @@ Currently, the following tests are in place:
    that all cURL examples in API docs use the full switches. It's recommended
    to [check locally](#previewing-the-changes-live) before pushing to GitLab by executing the command
    `bundle exec nanoc check internal_links` on your local
-   [`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs) directory.
+   [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. In addition,
+   `docs-lint` also runs [markdownlint](styleguide.md#markdown-rules) to ensure the
+   markdown is consistent across all documentation.
 1. [`ee_compat_check`](../automatic_ce_ee_merge.md#avoiding-ce-ee-merge-conflicts-beforehand) (runs on CE only):
-    When you submit a merge request to GitLab Community Edition (CE),
-    there is this additional job that runs against Enterprise Edition (EE)
-    and checks if your changes can apply cleanly to the EE codebase.
-    If that job fails, read the instructions in the job log for what to do next.
-    As CE is merged into EE once a day, it's important to avoid merge conflicts.
-    Submitting an EE-equivalent merge request cherry-picking all commits from CE to EE is
-    essential to avoid them.
+   When you submit a merge request to GitLab Community Edition (CE),
+   there is this additional job that runs against Enterprise Edition (EE)
+   and checks if your changes can apply cleanly to the EE codebase.
+   If that job fails, read the instructions in the job log for what to do next.
+   As CE is merged into EE once a day, it's important to avoid merge conflicts.
+   Submitting an EE-equivalent merge request cherry-picking all commits from CE to EE is
+   essential to avoid them.
 1. [`ee-files-location-check`/`ee-specific-lines-check`](#ee-specific-lines-check) (runs on EE only):
    This test ensures that no new files/directories are created/changed in EE.
    All docs should be submitted in CE instead, regardless the tier they are on.
@@ -556,15 +538,16 @@ A file with `proselint` configuration must be placed in a
 #### `markdownlint`
 
 `markdownlint` checks that certain rules ([example](https://github.com/DavidAnson/markdownlint/blob/master/README.md#rules--aliases))
- are followed for Markdown syntax.
- Our [Documentation Style Guide](styleguide.md) and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/)
- elaborate on which choices must be made when selecting Markdown syntax for
- GitLab documentation. This tool helps catch deviations from those guidelines.
+are followed for Markdown syntax. Our [Documentation Style Guide](styleguide.md) and
+[Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/)
+elaborate on which choices must be made when selecting Markdown syntax for GitLab
+documentation. This tool helps catch deviations from those guidelines, and matches the
+tests run on the documentation by [`docs-lint`](#testing).
 
 `markdownlint` can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--),
- either on a single Markdown file or on all Markdown files in a project. For example, to run
- `markdownlint` on all documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce),
- run the following commands from within the `gitlab-ce` project:
+either on a single Markdown file or on all Markdown files in a project. For example, to run
+`markdownlint` on all documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce),
+run the following commands from within the `gitlab-ce` project:
 
 ```sh
 cd doc
@@ -594,7 +577,7 @@ The following sample `markdownlint` configuration modifies the available default
   "line-length": false,
   "no-trailing-punctuation": false,
   "ol-prefix": { "style": "one" },
-  "blanks-around-fences": false,
+  "blanks-around-fences": true,
   "no-inline-html": {
     "allowed_elements": [
       "table",
@@ -609,11 +592,15 @@ The following sample `markdownlint` configuration modifies the available default
       "a",
       "strong",
       "i",
-      "div"
+      "div",
+      "b"
     ]
   },
   "hr-style": { "style": "---" },
-  "fenced-code-language": false
+  "code-block-style": { "style": "fenced" },
+  "fenced-code-language": false,
+  "no-duplicate-header": { "allow_different_nesting": true },
+  "commands-show-output": false
 }
 ```
 
diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md
index f2f4f5f0e1c..753a636a779 100644
--- a/doc/development/documentation/site_architecture/global_nav.md
+++ b/doc/development/documentation/site_architecture/global_nav.md
@@ -4,8 +4,9 @@ description: "Learn how GitLab docs' global navigation works and how to add new
 
 # Global navigation
 
-> [Introduced](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/362)
-in November 2018 for GitLab 11.6.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/362)
+in GitLab 11.6.
+> - [Updated](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/482) in GitLab 12.1.
 
 The global nav adds to the left sidebar the ability to
 navigate and explore the contents of GitLab's documentation.
@@ -24,7 +25,7 @@ To add a new doc to the nav, first and foremost, check with the technical writin
 Once you get their approval and their guidance in regards to the position on the nav,
 read trhough this page to understand how it works, and submit a merge request to the
 docs site, adding the doc you wish to include in the nav into the
-[global nav data file](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/content/_data/global-nav.yaml).
+[global nav data file](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/global-nav.yaml).
 
 Don't forget to ask a technical writer to review your changes before merging.
 
@@ -69,7 +70,7 @@ the data among the nav in containers properly [styled](#css-classes).
 
 ### Data file
 
-The [data file](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/content/_data/global-nav.yaml)
+The [data file](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/global-nav.yaml)
 is structured in three components: sections, categories, and docs.
 
 #### Sections
@@ -217,13 +218,13 @@ and the following syntax rules.
 - Always use relative paths against the home of CE and EE. Examples:
   - For `https://docs.gitlab.com/ee/README.html`, the relative URL is `README.html`.
   - For `https://docs.gitlab.com/ee/user/project/cycle_analytics.html`, the relative
-    URL is `user/project/cycle_analytics.html`
+    URL is `user/project/cycle_analytics.html`.
 - For `README.html` files, add the complete path `path/to/README.html`.
 - For `index.html` files, use the clean (canonical) URL: `path/to/`.
 - For EE-only docs, use the same relative path, but add the attribute `ee_only: true` below
-  the `doc_url` or `category_url`, as explained above. This will guarantee that when
-  the user is looking at the CE docs, it will link to the EE docs. It also displays
-  an "info" icon on the CE nav to make the user aware that it's a different link.
+  the `doc_url` or `category_url`, as explained above. This displays
+  an "info" icon on the nav to make the user aware that the feature is
+  EE-only.
 
 DANGER: **Important!**
 All links present on the data file must end in `.html`, not `.md`. Do not
@@ -247,9 +248,9 @@ Examples:
 
 ### Layout file (logic)
 
-The [layout](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/layouts/global_nav.html)
+The [layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/global_nav.html)
 is fed by the [data file](#data-file), builds the global nav, and is rendered by the
-[default](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/layouts/default.html) layout.
+[default](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/default.html) layout.
 
 There are three main considerations on the logic built for the nav:
 
@@ -283,7 +284,7 @@ For instance, for `https://docs.gitlab.com/ce/user/index.html`,
 #### Default URL
 
 The default and canonical URL for GitLab documentation is
-`http://docs.gitlab.com/ee/`, thus, all links
+`https://docs.gitlab.com/ee/`, thus, all links
 in the docs site should link to `/ee/` except when linking
 among `/ce/` docs themselves.
 
@@ -293,7 +294,7 @@ point to `/ee/` docs.
 
 On the other hand, if the user is looking at `/ce/` docs,
 all the links in the CE nav should link internally to `/ce/`
-files, except for [`ee-only` docs](#ee-only-docs).
+files.
 
 ```html
 <% if dir != 'ce' %>
@@ -314,21 +315,12 @@ categories (`cat[:category_url]`), and docs (`doc[:doc_url]`) URLs.
 
 #### `ee-only` docs
 
-If the user is looking at the CE nav, a given doc is present only
-in `/ee/`, it's tagged in the data file by `ee-only`, linking it
-directly to `/ee/`.
+Docs for features present only in GitLab EE are tagged
+in the data file by `ee-only` and an icon is displayed on the nav
+link indicating that the `ee-only` feature is not available in CE.
 
-```html
-<% if dir == 'ce' && cat[:ee_only] %>
-   <a href="/ee/<%= cat[:category_url] %>">...</a>
-<% end %>
-```
-
-To make it clear that it it's a different link, an icon is displayed
-on the nav link indicating that the `ee-only` doc is not available in CE.
-
-The `ee-only` attribute is available for `categories` (`<% if dir == 'ce' && cat[:ee_only] %>`)
-and `docs` (`<% if dir == 'ce' && doc[:ee_only] %>`), but not for `sections`.
+The `ee-only` attribute is available for `categories` (`<% if cat[:ee_only] %>`)
+and `docs` (`<% if doc[:ee_only] %>`), but not for `sections`.
 
 ### CSS classes
 
diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md
index ee3a9caf9a0..1aef0ed855c 100644
--- a/doc/development/documentation/site_architecture/index.md
+++ b/doc/development/documentation/site_architecture/index.md
@@ -4,15 +4,47 @@ description: "Learn how GitLab's documentation website is architectured."
 
 # Documentation site architecture
 
-Learn how we build and architecture [`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs)
+Learn how we build and architecture [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs)
 and deploy it to <https://docs.gitlab.com>.
 
 ## Repository
 
 While the source of the documentation content is stored in GitLab's respective product
 repositories, the source that is used to build the documentation site _from that content_
-is located at <https://gitlab.com/gitlab-com/gitlab-docs>. See the README there for
-detailed information.
+is located at <https://gitlab.com/gitlab-org/gitlab-docs>.
+
+The following diagram illustrates the relationship between the repositories
+from where content is sourced, the `gitlab-docs` project, and the published output.
+
+```mermaid
+  graph LR
+    A[gitlab-ce/doc]
+    B[gitlab-ee/doc]
+    C[gitlab-runner/docs]
+    D[omnibus-gitlab/doc]
+    E[charts/doc]
+    F[gitlab-docs]
+    A --> F
+    B --> F
+    C --> F
+    D --> F
+    E --> F
+    F -- Build pipeline --> G
+    G[docs.gitlab.com]
+    H[/ce/]
+    I[/ee/]
+    J[/runner/]
+    K[/omnibus/]
+    L[/charts/]
+    G --> H
+    G --> I
+    G --> J
+    G --> K
+    G --> L
+```
+
+See the [README there](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md)
+for detailed information.
 
 ## Assets
 
@@ -22,9 +54,9 @@ the GitLab Documentation website.
 
 ### Libraries
 
-- [Bootstrap 3.3 components](https://getbootstrap.com/docs/3.3/components/)
-- [Bootstrap 3.3 JS](https://getbootstrap.com/docs/3.3/javascript/)
-- [jQuery](https://jquery.com/) 3.2.1
+- [Bootstrap 4.3.1 components](https://getbootstrap.com/docs/4.3/components/)
+- [Bootstrap 4.3.1 JS](https://getbootstrap.com/docs/4.3/getting-started/javascript/)
+- [jQuery](https://jquery.com/) 3.3.1
 - [Clipboard JS](https://clipboardjs.com/)
 - [Font Awesome 4.7.0](https://fontawesome.com/v4.7.0/icons/)
 
@@ -44,7 +76,7 @@ read through the [global navigation](global_nav.md) doc.
 The docs site is deployed to production with GitLab Pages, and previewed in
 merge requests with Review Apps.
 
-The deployment aspects will be soon transferred from the [original document](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md)
+The deployment aspects will be soon transferred from the [original document](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md)
 to this page.
 
 <!--
diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md
index fe676efa94d..025a946da0e 100644
--- a/doc/development/documentation/structure.md
+++ b/doc/development/documentation/structure.md
@@ -127,7 +127,7 @@ Notes:
 
 ## Help and feedback section
 
-The "help and feedback" section (introduced by [!319](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/319)) displayed at the end of each document
+The "help and feedback" section (introduced by [!319](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/319)) displayed at the end of each document
 can be omitted from the doc by adding a key into the its frontmatter:
 
 ```yaml
@@ -142,7 +142,7 @@ you must check with a technical writer before doing so.
 ### Disqus
 
 We also have integrated the docs site with Disqus (introduced by
-[!151](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/151)),
+[!151](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/151)),
 allowing our users to post comments.
 
 To omit only the comments from the feedback section, use the following
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 5caca846cc9..c1e3eb9680b 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -36,17 +36,17 @@ For the Troubleshooting sections, people in GitLab Support can merge additions t
 
 Include any media types/sources if the content is relevant to readers. You can freely include or link presentations, diagrams, videos, etc.; no matter who it was originally composed for, if it is helpful to any of our audiences, we can include it.
 
-   - If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone.
-   - Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source.
+- If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone.
+- Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source.
 
 ### No special types
 
-In the software industry, it is a best practice to organize documentatioin in different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/):
+In the software industry, it is a best practice to organize documentation in different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/):
 
 1. Tutorials
-2. How-to guides
-3. Explanation
-4. Reference (for example, a glossary)
+1. How-to guides
+1. Explanation
+1. Reference (for example, a glossary)
 
 At GitLab, we have so many product changes in our monthly releases that we can't afford to continually update multiple types of information.
 If we have multiple types, the information will become outdated. Therefore, we have a [single template](structure.md) for documentation.
@@ -76,8 +76,8 @@ and cross-link between any related content.
 
 We employ a **docs-first methodology** to help ensure that the docs remain a complete and trusted resource, and to make communicating about the use of GitLab more efficient.
 
-* If the answer to a question exists in documentation, share the link to the docs instead of rephrasing the information.
-* When you encounter new information not available in GitLab’s documentation (for example, when working on a support case or testing a feature), your first step should be to create a merge request to add this information to the docs. You can then share the MR in order to communicate this information.
+- If the answer to a question exists in documentation, share the link to the docs instead of rephrasing the information.
+- When you encounter new information not available in GitLab’s documentation (for example, when working on a support case or testing a feature), your first step should be to create a merge request to add this information to the docs. You can then share the MR in order to communicate this information.
 
 New information that would be useful toward the future usage or troubleshooting of GitLab should not be written directly in a forum or other messaging system, but added to a docs MR and then referenced, as described above. Note that among any other doc changes, you can always add a Troubleshooting section to a doc if none exists, or un-comment and use the placeholder Troubleshooting section included as part of our [doc template](structure.md#template-for-new-docs), if present.
 
@@ -100,6 +100,29 @@ use regular Markdown markup, following the rules in the linked style guide.
 
 Note that Kramdown-specific markup (e.g., `{:.class}`) will not render properly on GitLab instances under [`/help`](index.md#gitlab-help).
 
+Hard-coded HTML is valid, although it's discouraged to be used while we have `/help`. HTML is permitted as long as:
+
+- There's no equivalent markup in markdown.
+- Advanced tables are necessary.
+- Special styling is required.
+- Reviewed and approved by a technical writer.
+
+### Markdown Rules
+
+GitLab ensures that the Markdown used across all documentation is consistent, as
+well as easy to review and maintain, by testing documentation changes with
+[Markdownlint (mdl)](https://github.com/markdownlint/markdownlint). This lint test
+checks many common problems with Markdown, and fails when any document has an issue
+with Markdown formatting that may cause the page to render incorrectly within GitLab.
+It will also fail when a document is using non-standard Markdown (which may render
+correctly, but is not the current standard in GitLab documentation).
+
+Each formatting issue that mdl checks has an associated [rule](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md),
+and the rules that are currently enabled for GitLab documentation are listed in the
+[`.mdlrc.style`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.mdlrc.style) file.
+Configuration options are set in the [`.mdlrc`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.mdlrc.style)
+file.
+
 ## Structure
 
 ### Organize by topic, not by type
@@ -135,15 +158,16 @@ The table below shows what kind of documentation goes where.
 ### Working with directories and files
 
 1. When you create a new directory, always start with an `index.md` file.
-  Do not use another file name and **do not** create `README.md` files.
+   Do not use another file name and **do not** create `README.md` files.
 1. **Do not** use special characters and spaces, or capital letters in file names,
-  directory names, branch names, and anything that generates a path.
+   directory names, branch names, and anything that generates a path.
 1. When creating a new document and it has more than one word in its name,
    make sure to use underscores instead of spaces or dashes (`-`). For example,
    a proper naming would be `import_projects_from_github.md`. The same rule
    applies to images.
 1. For image files, do not exceed 100KB.
-1. We do not yet support embedded videos. Please link out.
+1. Do not upload video files to the product repositories.
+   [Link or embed videos](#videos) instead.
 1. There are four main directories, `user`, `administration`, `api` and `development`.
 1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`,
    `profile/`, `dashboard/` and `admin_area/`.
@@ -165,13 +189,13 @@ The table below shows what kind of documentation goes where.
    `doc/topics/topic-name/subtopic-name/index.md` when subtopics become necessary.
    General user- and admin- related documentation, should be placed accordingly.
 1. The directories `/workflow/`, `/university/`, and `/articles/` have
-been **deprecated** and the majority their docs have been moved to their correct location
-in small iterations.
+   been **deprecated** and the majority their docs have been moved to their correct location
+   in small iterations.
 
 If you are unsure where a document or a content addition should live, this should
 not stop you from authoring and contributing. You can use your best judgment and
 then ask the reviewer of your MR to confirm your decision, and/or ask a technical writer
-at any stage in the process. The techncial writing team will review all documentation
+at any stage in the process. The technical writing team will review all documentation
 changes, regardless, and can move content if there is a better place for it.
 
 ### Avoid duplication
@@ -207,19 +231,20 @@ Do not include the same information in multiple places. [Link to a SSOT instead.
 
 ## Text
 
+- [Write in markdown](#markdown).
 - Splitting long lines (preferably up to 100 characters) can make it easier to provide feedback on small chunks of text.
 - Insert an empty line for new paragraphs.
 - Use sentence case for titles, headings, labels, menu items, and buttons.
 - Insert an empty line between different markups (e.g., after every paragraph, header, list, etc). Example:
 
-    ```md
-    ## Header
+  ```md
+  ## Header
 
-    Paragraph.
+  Paragraph.
 
-    - List item 1
-    - List item 2
-    ```
+  - List item 1
+  - List item 2
+  ```
 
 ### Tables overlapping the TOC
 
@@ -258,32 +283,52 @@ Check specific punctuation rules for [list items](#list-items) below.
 
 ## List items
 
-- Always start list items with a capital letter.
+- Always start list items with a capital letter, unless they are parameters or commands
+  that are in backticks, or similar.
 - Always leave a blank line before and after a list.
-- Begin a line with spaces (not tabs) to denote a subitem.
-- To nest subitems, indent them with two spaces.
-- To nest code blocks, indent them with four spaces.
-- Only use ordered lists when their items describe a sequence of steps to follow.
+- Begin a line with spaces (not tabs) to denote a [nested subitem](#nesting-inside-a-list-item).
+- Only use ordered lists when their items describe a sequence of steps to follow:
+
+  Do:
+
+  These are the steps to do something:
+
+  1. First, do step 1
+  1. Then, do step 2
+  1. Finally, do step 3
+
+  Don't:
+
+  This is a list of different features:
+
+  1. Feature 1
+  1. Feature 2
+  1. Feature 3
 
 **Markup:**
 
 - Use dashes (`-`) for unordered lists instead of asterisks (`*`).
-- Use the number one (`1`) for each item in an ordered list.
-  When rendered, the list items will appear with sequential numbering.
+- Prefix `1.` to each item in an ordered list.
+  When rendered, the list items will appear with sequential numbering automatically.
 
 **Punctuation:**
 
-- Do not add commas (`,`) or semicolons (`;`) to the end of a list item.
-- Only add periods to the end of a list item if the item consists of a complete sentence. The [definition of full sentence](https://www2.le.ac.uk/offices/ld/resources/writing/grammar/grammar-guides/sentence) is: _"a complete sentence always contains a verb, expresses a complete idea, and makes sense standing alone"_.
-- Be consistent throughout the list: if the majority of the items do not end in a period, do not end any of the items in a period, even if they consist of a complete sentence. The opposite is also valid: if the majority of the items end with a period, end all with a period.
+- Do not add commas (`,`) or semicolons (`;`) to the end of list items.
+- Only add periods to the end of a list item if the item consists of a complete sentence.
+  The [definition of full sentence](https://www2.le.ac.uk/offices/ld/resources/writing/grammar/grammar-guides/sentence)
+  is: _"a complete sentence always contains a verb, expresses a complete idea, and makes sense standing alone"_.
+- Be consistent throughout the list: if the majority of the items do not end in a period,
+  do not end any of the items in a period, even if they consist of a complete sentence.
+  The opposite is also valid: if the majority of the items end with a period, end
+  all with a period.
 - Separate list items from explanatory text with a colon (`:`). For example:
 
-    ```md
-    The list is as follows:
+  ```md
+  The list is as follows:
 
-    - First item: this explains the first item.
-    - Second item: this explains the second item.
-    ```
+  - First item: this explains the first item.
+  - Second item: this explains the second item.
+  ```
 
 **Examples:**
 
@@ -305,12 +350,86 @@ Do:
 - Let's say this is also a complete sentence.
 - Not a complete sentence.
 
-Don't:
+Don't (third item should have a `.` to match the first and second items):
 
 - Let's say this is a complete sentence.
 - Let's say this is also a complete sentence.
 - Not a complete sentence
 
+### Nesting inside a list item
+
+It is possible to nest items under a list item, so that they render with the same indentation
+as the list item. This can be done with:
+
+- [Code blocks](#code-blocks)
+- [Blockquotes](#blockquotes)
+- [Alert boxes](#alert-boxes)
+- [Images](#images)
+
+Items nested in lists should always align with the first character of the list item.
+In unordered lists (using `-`), this means two spaces for each level of indentation:
+
+~~~md
+- Unordered list item 1
+
+  A line nested using 2 spaces to align with the `U` above.
+
+- Unordered list item 2
+
+  > A quote block that will nest
+  > inside list item 2.
+
+- Unordered list item 3
+
+  ```text
+  a codeblock that will next inside list item 3
+  ```
+
+- Unordered list item 4
+
+  ![an image that will nest inside list item 4](image.png)
+~~~
+
+For ordered lists, use three spaces for each level of indentation:
+
+~~~md
+1. Ordered list item 1
+
+   A line nested using 3 spaces to align with the `O` above.
+
+1. Ordered list item 2
+
+   > A quote block that will nest
+   > inside list item 2.
+
+1. Ordered list item 3
+
+   ```text
+   a codeblock that will next inside list item 3
+   ```
+
+1. Ordered list item 4
+
+   ![an image that will nest inside list item 4](image.png)
+~~~
+
+You can nest full lists inside other lists using the same rules as above. If you wish
+to mix types, that is also possible, as long as you don't mix items at the same level:
+
+```
+1. Ordered list item one.
+1. Ordered list item two.
+   - Nested unordered list item one.
+   - Nested unordered list item two.
+1. Ordered list item three.
+
+- Unordered list item one.
+- Unordered list item two.
+  1. Nested ordered list item one.
+  1. Nested ordered list item two.
+- Unordered list item three.
+```
+
 ## Quotes
 
 Valid for markdown content only, not for frontmatter entries:
@@ -331,7 +450,7 @@ For other punctuation rules, please refer to the
   links shift too, which eventually leads to dead links. If you think it is
   compelling to add numbers in headings, make sure to at least discuss it with
   someone in the Merge Request.
-- [Avoid using symbols and special chars](https://gitlab.com/gitlab-com/gitlab-docs/issues/84)
+- [Avoid using symbols and special chars](https://gitlab.com/gitlab-org/gitlab-docs/issues/84)
   in headers. Whenever possible, they should be plain and short text.
 - Avoid adding things that show ephemeral statuses. For example, if a feature is
   considered beta or experimental, put this info in a note, not in the heading.
@@ -384,7 +503,7 @@ Instead:
 Example:
 
 ```md
-For more information, see the [confidential issue](https://docs.gitlab.com/ee/user/project/issues/confidential_issues.html) `https://gitlab.com/gitlab-org/gitlab-ce/issues/<issue_number>`.
+For more information, see the [confidential issue](../../user/project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab-ce/issues/<issue_number>`.
 ```
 
 ### Unlinking emails
@@ -409,11 +528,20 @@ To indicate the steps of navigation through the UI:
 ## Images
 
 - Place images in a separate directory named `img/` in the same directory where
-  the `.md` document that you're working on is located. Always prepend their
-  names with the name of the document that they will be included in. For
-  example, if there is a document called `twitter.md`, then a valid image name
-  could be `twitter_login_screen.png`.
-- Images should have a specific, non-generic name that will differentiate and describe them properly.
+  the `.md` document that you're working on is located.
+- Images should have a specific, non-generic name that will
+  differentiate and describe them properly.
+- Always add to the end of the file name the GitLab release version
+  number corresponding to the release milestone the image was added to,
+  or corresponding to the release the screenshot was taken from, using the
+  format `image_name_vX_Y.png`.
+  ([Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/61027) in GitLab 12.1.)
+- For example, for a screenshot taken from the pipelines page of
+  GitLab 11.1, a valid name is `pipelines_v11_1.png`. If you're
+  adding an illustration that does not include parts of the UI,
+  add the release number corresponding to the release the image
+  was added to. Example, for an MR added to 11.1's milestone,
+  a valid name for an illustration is `devops_diagram_v11_1.png`.
 - Keep all file names in lower case.
 - Consider using PNG images instead of JPEG.
 - Compress all images with <https://tinypng.com/> or similar tool.
@@ -421,12 +549,12 @@ To indicate the steps of navigation through the UI:
 - Images should be used (only when necessary) to _illustrate_ the description
   of a process, not to _replace_ it.
 - Max image size: 100KB (gifs included).
-- The GitLab docs do not support videos yet.
+- See also how to link and embed [videos](#videos) to illustrate the docs.
 
 Inside the document:
 
 - The Markdown way of using an image inside a document is:
-  `![Proper description what the image is about](img/document_image_title.png)`
+  `![Proper description what the image is about](img/document_image_title_vX_Y.png)`
 - Always use a proper description for what the image is about. That way, when a
   browser fails to show the image, this text will be used as an alternative
   description.
@@ -446,17 +574,97 @@ directly to an HTML `img` tag:
 <img src="path/to/image.jpg" alt="Alt text (required)" class="image-noshadow">
 ```
 
+## Videos
+
+Adding GitLab's existing YouTube video tutorials to the documentation is
+highly encouraged, unless the video is outdated. Videos should not
+replace documentation, but complement or illustrate it. If content in a video is
+fundamental to a feature and its key use cases, but this is not adequately covered in the documentation,
+add this detail to the documentation text or create an issue to review the video and do so.
+
+Do not upload videos to the product repositories. [Link](#link-to-video) or [embed](#embed-videos) them instead.
+
+### Link to video
+
+To link out to a video, include a YouTube icon so that readers can
+quickly and easily scan the page for videos before reading:
+
+```md
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For an overview, see [Video Title](link-to-video).
+```
+
+You can link any up-to-date video that is useful to the GitLab user.
+
+### Embed videos
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/472) in GitLab 12.1.
+
+GitLab docs (docs.gitlab.com) support embedded videos.
+
+You can only embed videos from
+[GitLab's official YouTube account](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg).
+For videos from other sources, [link](#link-to-video) them instead.
+
+In most cases, it is better to [link to video](#link-to-video) instead,
+because an embed takes up a lot of space on the page and can be distracting
+to readers.
+
+To embed a video, follow the instructions below and make sure
+you have your MR reviewed and approved by a technical writer.
+
+1. Copy the code below and paste it into your markdown file.
+   Leave a blank line above and below it. Do NOT edit the code
+   (don't remove or add any spaces, etc).
+1. On YouTube, visit the video URL you want to display. Copy
+   the regular URL from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`)
+   and replace the video title and link in the line under `<div class="video-fallback">`.
+1. On YouTube, click **Share**, then **Embed**.
+1. Copy the `<iframe>` source (`src`) **URL only**
+   (`https://www.youtube.com/embed/VIDEO-ID`),
+   and paste it, replacing the content of the `src` field in the
+   `iframe` tag.
+
+```html
+leave a blank line here
+<div class="video-fallback">
+  See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>.
+</div>
+<figure class="video-container">
+  <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe>
+</figure>
+leave a blank line here
+```
+
+This is how it renders on docs.gitlab.com:
+
+<div class="video-fallback">
+  See the video: <a href="https://www.youtube.com/watch?v=enMumwvLAug">What is GitLab</a>.
+</div>
+<figure class="video-container">
+  <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe>
+</figure>
+
+> Notes:
+>
+> - The `figure` tag is required for semantic SEO and the `video_container`
+class is necessary to make sure the video is responsive and displays
+nicely on different mobile devices.
+> - The `<div class="video-fallback">` is a fallback necessary for GitLab's
+`/help`, as GitLab's markdown processor does not support iframes. It's hidden on the docs site but will be displayed on GitLab's `/help`.
+
 ## Code blocks
 
-- Always wrap code added to a sentence in inline code blocks (``` ` ```).
+- Always wrap code added to a sentence in inline code blocks (`` ` ``).
   E.g., `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, `only: master`.
   File names, commands, entries, and anything that refers to code should be added to code blocks.
   To make things easier for the user, always add a full code block for things that can be
   useful to copy and paste, as they can easily do it with the button on code blocks.
+- Add a blank line above and below code blocks.
 - For regular code blocks, always use a highlighting class corresponding to the
   language for better readability. Examples:
 
-  ````md
+  ~~~md
   ```ruby
   Ruby code
   ```
@@ -466,21 +674,22 @@ directly to an HTML `img` tag:
   ```
 
   ```md
-  Markdown code
+  [Markdown code example](example.md)
   ```
 
   ```text
-  Code for which no specific highlighting class is available.
+  Code or text for which no specific highlighting class is available.
   ```
-  ````
+  ~~~
 
-- To display raw markdown instead of rendered markdown, use four backticks on their own lines around the
-  markdown to display. See [example](https://gitlab.com/gitlab-org/gitlab-ce/blob/8c1991b9bb7e3b8d606481fdea316d633cfa5eb7/doc/development/documentation/styleguide.md#L275-287).
+- To display raw markdown instead of rendered markdown, you can use triple backticks
+  with `md`, like the `Markdown code` example above, unless you want to include triple
+  backticks in the code block as well. In that case, use triple tildes (`~~~`) instead.
 - For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks).
 
 ## Alert boxes
 
-Whenever you want to call the attention to a particular sentence,
+Whenever you need to call special attention to particular sentences,
 use the following markup for highlighting.
 
 _Note that the alert boxes only work for one paragraph only. Multiple paragraphs,
@@ -488,6 +697,23 @@ lists, headers, etc will not render correctly. For multiple lines, use blockquot
 
 ### Note
 
+Notes catch the eye of most readers, and therefore should be used very sparingly.
+In most cases, content considered for a note should be included:
+
+- As just another sentence in the previous paragraph or the most-relevant paragraph.
+- As its own standalone paragraph.
+- As content under a new subheading that introduces the topic, making it more visible/findable.
+
+#### When to use
+
+Use a note when there is a reason that most or all readers who browse the
+section should see the content. That is, if missed, it’s likely to cause
+major trouble for a minority of users or significant trouble for a majority
+of users.
+
+Weigh the costs of distracting users to whom the content is not relevant against
+the cost of users missing the content if it were not expressed as a note.
+
 ```md
 NOTE: **Note:**
 This is something to note.
@@ -617,24 +843,24 @@ a helpful link back to how the feature was developed.
 - For features that need to declare the GitLab version that the feature was introduced. Text similar
   to the following should be added immediately below the heading as a blockquote:
 
-    ```md
-    > Introduced in GitLab 11.3.
-    ```
+  ```md
+  > Introduced in GitLab 11.3.
+  ```
 
 - Whenever possible, version text should have a link to the issue, merge request, or epic that introduced the feature.
   An issue is preferred over a merge request, and a merge request is preferred over an epic. For example:
 
-    ```md
-    > [Introduced](<link-to-issue>) in GitLab 11.3.
-    ```
+  ```md
+  > [Introduced](<link-to-issue>) in GitLab 11.3.
+  ```
 
 - If the feature is only available in GitLab Enterprise Edition, mention
   the [paid tier](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers)
   the feature is available in:
 
-    ```md
-    > [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.
-    ```
+  ```md
+  > [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.
+  ```
 
 ### Removing version text
 
@@ -653,24 +879,25 @@ Other text includes deprecation notices and version-specific how-to information.
 When a feature is available in EE-only tiers, add the corresponding tier according to the
 feature availability:
 
-- For GitLab Starter and GitLab.com Bronze: `**[STARTER]**`.
-- For GitLab Premium and GitLab.com Silver: `**[PREMIUM]**`.
-- For GitLab Ultimate and GitLab.com Gold: `**[ULTIMATE]**`.
-- For GitLab Core and GitLab.com Free: `**[CORE]**`.
+- For GitLab Core and GitLab.com Free: `**(CORE)**`.
+- For GitLab Starter and GitLab.com Bronze: `**(STARTER)**`.
+- For GitLab Premium and GitLab.com Silver: `**(PREMIUM)**`.
+- For GitLab Ultimate and GitLab.com Gold: `**(ULTIMATE)**`.
 
 To exclude GitLab.com tiers (when the feature is not available in GitLab.com), add the
 keyword "only":
 
-- For GitLab Core: `**[CORE ONLY]**`.
-- For GitLab Starter: `**[STARTER ONLY]**`.
-- For GitLab Premium: `**[PREMIUM ONLY]**`.
-- For GitLab Ultimate: `**[ULTIMATE ONLY]**`.
+- For GitLab Core: `**(CORE ONLY)**`.
+- For GitLab Starter: `**(STARTER ONLY)**`.
+- For GitLab Premium: `**(PREMIUM ONLY)**`.
+- For GitLab Ultimate: `**(ULTIMATE ONLY)**`.
 
 For GitLab.com only tiers (when the feature is not available for self-hosted instances):
 
-- For GitLab Bronze and higher tiers: `**[BRONZE ONLY]**`.
-- For GitLab Silver and higher tiers: `**[SILVER ONLY]**`.
-- For GitLab Gold: `**[GOLD ONLY]**`.
+- For GitLab Free and higher tiers: `**(FREE ONLY)**`.
+- For GitLab Bronze and higher tiers: `**(BRONZE ONLY)**`.
+- For GitLab Silver and higher tiers: `**(SILVER ONLY)**`.
+- For GitLab Gold: `**(GOLD ONLY)**`.
 
 The tier should be ideally added to headers, so that the full badge will be displayed.
 However, it can be also mentioned from paragraphs, list items, and table cells. For these cases,
@@ -678,17 +905,17 @@ the tier mention will be represented by an orange question mark that will show t
 
 For example:
 
-- `**[STARTER]**` renders as **[STARTER]**
-- `**[STARTER ONLY]**` renders as **[STARTER ONLY]**
-- `**[SILVER ONLY]**` renders as **[SILVER ONLY]**
+- `**(STARTER)**` renders as **(STARTER)**
+- `**(STARTER ONLY)**` renders as **(STARTER ONLY)**
+- `**(SILVER ONLY)**` renders as **(SILVER ONLY)**
 
 The absence of tiers' mentions mean that the feature is available in GitLab Core,
 GitLab.com Free, and all higher tiers.
 
 ### How it works
 
-Introduced by [!244](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/244),
-the special markup `**[STARTER]**` will generate a `span` element to trigger the
+Introduced by [!244](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/244),
+the special markup `**(STARTER)**` will generate a `span` element to trigger the
 badges and tooltips (`<span class="badge-trigger starter">`). When the keyword
 "only" is added, the corresponding GitLab.com badge will not be displayed.
 
@@ -710,7 +937,7 @@ for the changes to take effect.
 
 If the document you are editing resides in a place other than the GitLab CE/EE
 `doc/` directory, instead of the relative link, use the full path:
-`http://docs.gitlab.com/ce/administration/restart_gitlab.html`.
+`https://docs.gitlab.com/ce/administration/restart_gitlab.html`.
 Replace `reconfigure` with `restart` where appropriate.
 
 ### Installation guide
@@ -741,14 +968,14 @@ When there is a list of steps to perform, usually that entails editing the
 configuration file and reconfiguring/restarting GitLab. In such case, follow
 the style below as a guide:
 
-```md
+````md
 **For Omnibus installations**
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    external_url "https://gitlab.example.com"
-    ```
+   ```ruby
+   external_url "https://gitlab.example.com"
+   ```
 
 1. Save the file and [reconfigure] GitLab for the changes to take effect.
 
@@ -758,17 +985,16 @@ the style below as a guide:
 
 1. Edit `config/gitlab.yml`:
 
-    ```yaml
-    gitlab:
-      host: "gitlab.example.com"
-    ```
+   ```yaml
+   gitlab:
+     host: "gitlab.example.com"
+   ```
 
 1. Save the file and [restart] GitLab for the changes to take effect.
 
-
 [reconfigure]: path/to/administration/restart_gitlab.md#omnibus-gitlab-reconfigure
 [restart]: path/to/administration/restart_gitlab.md#installations-from-source
-```
+````
 
 In this case:
 
@@ -787,9 +1013,9 @@ on this document. Further explanation is given below.
 
 - Every method must have the REST API request. For example:
 
-    ```
-    GET /projects/:id/repository/branches
-    ```
+  ```
+  GET /projects/:id/repository/branches
+  ```
 
 - Every method must have a detailed
   [description of the parameters](#method-description).
@@ -800,7 +1026,7 @@ on this document. Further explanation is given below.
 
 The following can be used as a template to get started:
 
-````md
+~~~md
 ## Descriptive title
 
 One or two sentence description of what endpoint does.
@@ -828,7 +1054,7 @@ Example response:
   }
 ]
 ```
-````
+~~~
 
 ### Fake tokens
 
@@ -841,7 +1067,7 @@ You can use the following fake tokens as examples.
 
 | Token type            | Token value                                                        |
 |:----------------------|:-------------------------------------------------------------------|
-| Private user token    | `<your_access_token>`                                             |
+| Private user token    | `<your_access_token>`                                              |
 | Personal access token | `n671WNGecHugsdEDPsyo`                                             |
 | Application ID        | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` |
 | Application secret    | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` |
@@ -856,7 +1082,7 @@ You can use the following fake tokens as examples.
 ### Method description
 
 Use the following table headers to describe the methods. Attributes should
-always be in code blocks using backticks (``` ` ```).
+always be in code blocks using backticks (`` ` ``).
 
 ```md
 | Attribute | Type | Required | Description |
@@ -962,6 +1188,6 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "domain_
 
 [cURL]: http://curl.haxx.se/ "cURL website"
 [single spaces]: http://www.slate.com/articles/technology/technology/2011/01/space_invaders.html
-[gfm]: http://docs.gitlab.com/ce/user/markdown.html#newlines "GitLab flavored markdown documentation"
+[gfm]: ../../user/markdown.md#newlines "GitLab flavored markdown documentation"
 [ce-1242]: https://gitlab.com/gitlab-org/gitlab-ce/issues/1242
 [doc-restart]: ../../administration/restart_gitlab.md "GitLab restart documentation"
diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md
index 0abfe4b82a4..9f488fac7d0 100644
--- a/doc/development/documentation/workflow.md
+++ b/doc/development/documentation/workflow.md
@@ -6,5 +6,5 @@ description: Learn the processes for contributing to GitLab's documentation.
 
 Documentation workflows at GitLab differ depending on the reason for the change:
 
-- [Documentation process for feature changes](feature-change-workflow.md) - The documentation is being created or updated as part of the development and release of a new or enhanced feature. This process involves the developer of the feature (who includes new/updated documentation files as part of the same merge request containing the feature's code) and also involves the product manager and technical writer who are listed for the feature's [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). 
+- [Documentation process for feature changes](feature-change-workflow.md) - The documentation is being created or updated as part of the development and release of a new or enhanced feature. This process involves the developer of the feature (who includes new/updated documentation files as part of the same merge request containing the feature's code) and also involves the product manager and technical writer who are listed for the feature's [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
 - [Documentation improvement workflow](improvement-workflow.md) - All documentation additions not associated with a feature release. Documentation is being created or updated to improve accuracy, completeness, ease of use, or any reason other than a feature change. Anyone (and everyone) can contribute a merge request for this type of change at any time.
diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md
index cca52706ddc..2217dedccd3 100644
--- a/doc/development/ee_features.md
+++ b/doc/development/ee_features.md
@@ -125,20 +125,24 @@ This also applies to views.
 ### EE features based on CE features
 
 For features that build on existing CE features, write a module in the `EE`
-namespace and `prepend` it in the CE class, on the last line of the file that
-the class resides in. This makes conflicts less likely to happen during CE to EE
-merges because only one line is added to the CE class - the `prepend` line. For
-example, to prepend a module into the `User` class you would use the following
-approach:
+namespace and inject it in the CE class, on the last line of the file that the
+class resides in. This makes conflicts less likely to happen during CE to EE
+merges because only one line is added to the CE class - the line that injects
+the module. For example, to prepend a module into the `User` class you would use
+the following approach:
 
 ```ruby
 class User < ActiveRecord::Base
   # ... lots of code here ...
 end
 
-User.prepend(EE::User)
+User.prepend_if_ee('EE::User')
 ```
 
+Do not use methods such as `prepend`, `extend`, and `include`. Instead, use
+`prepend_if_ee`, `extend_if_ee`, or `include_if_ee`. These methods take a
+_String_ containing the full module name as the argument, not the module itself.
+
 Since the module would require an `EE` namespace, the file should also be
 put in an `ee/` sub-directory. For example, we want to extend the user model
 in EE, so we have a module called `::EE::User` put inside
@@ -182,52 +186,52 @@ There are a few gotchas with it:
   pattern](https://en.wikipedia.org/wiki/Template_method_pattern).
   For example, given this base:
 
-    ```ruby
-      class Base
-        def execute
-          return unless enabled?
+  ```ruby
+    class Base
+      def execute
+        return unless enabled?
 
-          # ...
-          # ...
-        end
+        # ...
+        # ...
       end
-    ```
+    end
+  ```
 
-    Instead of just overriding `Base#execute`, we should update it and extract
-    the behaviour into another method:
+  Instead of just overriding `Base#execute`, we should update it and extract
+  the behaviour into another method:
 
-    ```ruby
-      class Base
-        def execute
-          return unless enabled?
+  ```ruby
+    class Base
+      def execute
+        return unless enabled?
 
-          do_something
-        end
+        do_something
+      end
 
-        private
+      private
 
-        def do_something
-          # ...
-          # ...
-        end
+      def do_something
+        # ...
+        # ...
       end
-    ```
+    end
+  ```
 
-    Then we're free to override that `do_something` without worrying about the
-    guards:
+  Then we're free to override that `do_something` without worrying about the
+  guards:
 
-    ```ruby
-      module EE::Base
-        extend ::Gitlab::Utils::Override
+  ```ruby
+    module EE::Base
+      extend ::Gitlab::Utils::Override
 
-        override :do_something
-        def do_something
-          # Follow the above pattern to call super and extend it
-        end
+      override :do_something
+      def do_something
+        # Follow the above pattern to call super and extend it
       end
-    ```
+    end
+  ```
 
-    This would require updating CE first, or make sure this is back ported to CE.
+  This would require updating CE first, or make sure this is back ported to CE.
 
 When prepending, place them in the `ee/` specific sub-directory, and
 wrap class or module in `module EE` to avoid naming conflicts.
@@ -255,7 +259,7 @@ class ApplicationController < ActionController::Base
   # ...
 end
 
-ApplicationController.prepend(EE::ApplicationController)
+ApplicationController.prepend_if_ee('EE::ApplicationController')
 ```
 
 And create a new file in the `ee/` sub-directory with the altered
@@ -446,7 +450,6 @@ The disadvantage of this:
   port `render_if_exists` to CE.
 - If we have typos in the partial name, it would be silently ignored.
 
-
 ##### Caveats
 
 The `render_if_exists` view path argument must be relative to `app/views/` and `ee/app/views`.
@@ -505,9 +508,9 @@ EE-specific LDAP classes in `ee/lib/ee/gitlab/ldap`.
 
 ### Code in `lib/api/`
 
-It can be very tricky to extend EE features by a single line of `prepend`,
-and for each different [Grape](https://github.com/ruby-grape/grape) feature,
-we might need different strategies to extend it. To apply different strategies
+It can be very tricky to extend EE features by a single line of `prepend_if_ee`,
+and for each different [Grape](https://github.com/ruby-grape/grape) feature, we
+might need different strategies to extend it. To apply different strategies
 easily, we would use `extend ActiveSupport::Concern` in the EE module.
 
 Put the EE module files following
@@ -544,12 +547,12 @@ constants.
 We can define `params` and utilize `use` in another `params` definition to
 include params defined in EE. However, we need to define the "interface" first
 in CE in order for EE to override it. We don't have to do this in other places
-due to `prepend`, but Grape is complex internally and we couldn't easily do
-that, so we'll follow regular object-oriented practices that we define the
+due to `prepend_if_ee`, but Grape is complex internally and we couldn't easily
+do that, so we'll follow regular object-oriented practices that we define the
 interface first here.
 
 For example, suppose we have a few more optional params for EE. We can move the
-params out of the `Grape::API` class to a helper module, so we can `prepend` it
+params out of the `Grape::API` class to a helper module, so we can inject it
 before it would be used in the class.
 
 ```ruby
@@ -584,7 +587,7 @@ module API
   end
 end
 
-API::Helpers::ProjectsHelpers.prepend(EE::API::Helpers::ProjectsHelpers)
+API::Helpers::ProjectsHelpers.prepend_if_ee('EE::API::Helpers::ProjectsHelpers')
 ```
 
 We could override it in EE module:
@@ -625,7 +628,7 @@ module API
   end
 end
 
-API::JobArtifacts.prepend(EE::API::JobArtifacts)
+API::JobArtifacts.prepend_if_ee('EE::API::JobArtifacts')
 ```
 
 And then we can follow regular object-oriented practices to override it:
@@ -678,7 +681,7 @@ module API
   end
 end
 
-API::MergeRequests.prepend(EE::API::MergeRequests)
+API::MergeRequests.prepend_if_ee('EE::API::MergeRequests')
 ```
 
 Note that `update_merge_request_ee` doesn't do anything in CE, but
@@ -718,8 +721,8 @@ Sometimes we need to use different arguments for a particular API route, and we
 can't easily extend it with an EE module because Grape has different context in
 different blocks. In order to overcome this, we need to move the data to a class
 method that resides in a separate module or class. This allows us to extend that
-module or class before its data is used, without having to place a `prepend` in
-the middle of CE code.
+module or class before its data is used, without having to place a
+`prepend_if_ee` in the middle of CE code.
 
 For example, in one place we need to pass an extra argument to
 `at_least_one_of` so that the API could consider an EE-only argument as the
@@ -740,7 +743,7 @@ module API
   end
 end
 
-API::MergeRequests::Parameters.prepend(EE::API::MergeRequests::Parameters)
+API::MergeRequests::Parameters.prepend_if_ee('EE::API::MergeRequests::Parameters')
 
 # api/merge_requests.rb
 module API
@@ -790,7 +793,7 @@ class Identity < ActiveRecord::Base
     [:provider]
   end
 
-  prepend EE::Identity
+  prepend_if_ee('EE::Identity')
 
   validates :extern_uid,
     allow_blank: true,
@@ -842,7 +845,7 @@ class Identity < ActiveRecord::Base
   end
 end
 
-Identity::UniquenessScopes.prepend(EE::Identity::UniquenessScopes)
+Identity::UniquenessScopes.prepend_if_ee('EE::Identity::UniquenessScopes')
 
 # app/models/identity.rb
 class Identity < ActiveRecord::Base
@@ -909,11 +912,12 @@ import bundle from 'ee_else_ce/protected_branches/protected_branches_bundle.js';
 See the frontend guide [performance section](fe_guide/performance.md) for
 information on managing page-specific javascript within EE.
 
-
 ## Vue code in `assets/javascript`
+
 ### script tag
 
 #### Child Component only used in EE
+
 To separate Vue template differences we should [async import the components](https://vuejs.org/v2/guide/components-dynamic-async.html#Async-Components).
 
 Doing this allows for us to load the correct component in EE whilst in CE
@@ -937,10 +941,12 @@ export default {
 ```
 
 #### For JS code that is EE only, like props, computed properties, methods, etc, we will keep the current approach
- - Since we [can't async load a mixin](https://github.com/vuejs/vue-loader/issues/418#issuecomment-254032223) we will use the [`ee_else_ce`](../development/ee_features.md#javascript-code-in-assetsjavascripts) alias we already have for webpack.
+
+- Since we [can't async load a mixin](https://github.com/vuejs/vue-loader/issues/418#issuecomment-254032223) we will use the [`ee_else_ce`](../development/ee_features.md#javascript-code-in-assetsjavascripts) alias we already have for webpack.
   - This means all the EE specific props, computed properties, methods, etc that are EE only should be in a mixin in the `ee/` folder and we need to create a CE counterpart of the mixin
 
 ##### Example:
+
 ```javascript
 import mixin from 'ee_else_ce/path/mixin';
 
@@ -955,20 +961,22 @@ import mixin from 'ee_else_ce/path/mixin';
 - You can see an MR with an example [here](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9762)
 
 #### `template` tag
-* **EE Child components**
+
+- **EE Child components**
   - Since we are using the async loading to check which component to load, we'd still use the component's name, check [this example](#child-component-only-used-in-ee).
 
-* **EE extra HTML**
+- **EE extra HTML**
   - For the templates that have extra HTML in EE we should move it into a new component and use the `ee_else_ce` dynamic import
 
 ### Non Vue Files
+
 For regular JS files, the approach is similar.
 
 1. We will keep using the [`ee_else_ce`](../development/ee_features.md#javascript-code-in-assetsjavascripts) helper, this means that EE only code should be inside the `ee/` folder.
-  1. An EE file should be created with the EE only code, and it should extend the CE counterpart.
-  1. For code inside functions that can't be extended, the code should be moved into a new file and we should use `ee_else_ce` helper:
+   1. An EE file should be created with the EE only code, and it should extend the CE counterpart.
+   1. For code inside functions that can't be extended, the code should be moved into a new file and we should use `ee_else_ce` helper:
 
-##### Example:
+#### Example:
 
 ```javascript
   import eeCode from 'ee_else_ce/ee_code';
@@ -995,7 +1003,8 @@ styles are usually kept in stylesheet that is common for both CE and EE, and it
 to isolate such ruleset from rest of CE rules (along with adding comment describing the same)
 to avoid conflicts during CE to EE merge.
 
-#### Bad
+### Bad
+
 ```scss
 .section-body {
   .section-title {
@@ -1010,7 +1019,8 @@ to avoid conflicts during CE to EE merge.
 }
 ```
 
-#### Good
+### Good
+
 ```scss
 .section-body {
   .section-title {
@@ -1027,9 +1037,16 @@ to avoid conflicts during CE to EE merge.
 // EE-specific end
 ```
 
-### Backporting changes from EE to CE
+## Backporting changes from EE to CE
+
+Until the work completed to merge the ce and ee codebases, which is tracked on [epic &802](https://gitlab.com/groups/gitlab-org/-/epics/802), there exists times in which some changes for EE require specific changes to the CE
+code base.  Examples of backports include the following:
+
+- Features intended or originally built for EE that are later decided to move to CE
+- Sometimes some code in CE may impact the EE feature
+
+Here is a workflow to make sure those changes end up backported safely into CE too.
 
-When working in EE-specific features, you might have to tweak a few files that are not EE-specific. Here is a workflow to make sure those changes end up backported safely into CE too.
 (This approach does not refer to changes introduced via [csslab](https://gitlab.com/gitlab-org/csslab/).)
 
 1. **Make your changes in the EE branch.** If possible, keep a separated commit (to be squashed) to help backporting and review.
diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md
index 8b0f4f02d19..635895051bc 100644
--- a/doc/development/elasticsearch.md
+++ b/doc/development/elasticsearch.md
@@ -1,8 +1,18 @@
-# Elasticsearch knowledge **[STARTER ONLY]**
+# Elasticsearch knowledge **(STARTER ONLY)**
 
 This area is to maintain a compendium of useful information when working with elasticsearch.
 
-Information on how to enable ElasticSearch and perform the initial indexing is kept in ../integration/elasticsearch.md#enabling-elasticsearch
+Information on how to enable Elasticsearch and perform the initial indexing is kept in ../integration/elasticsearch.md#enabling-elasticsearch
+
+## Deep Dive
+
+In June 2019, Mario de la Ossa hosted a [Deep Dive] on GitLab's [Elasticsearch integration] to share his domain specific knowledge with anyone who may work in this part of the code base in the future. You can find the [recording on YouTube], and the slides on [Google Slides] and in [PDF]. Everything covered in this deep dive was accurate as of GitLab 12.0, and while specific details may have changed since then, it should still serve as a good introduction.
+
+[Deep Dive]: https://gitlab.com/gitlab-org/create-stage/issues/1
+[Elasticsearch integration]: ../integration/elasticsearch.md
+[recording on YouTube]: https://www.youtube.com/watch?v=vrvl-tN2EaA
+[Google Slides]: https://docs.google.com/presentation/d/1H-pCzI_LNrgrL5pJAIQgvLX8Ji0-jIKOg1QeJQzChug/edit
+[PDF]: https://gitlab.com/gitlab-org/create-stage/uploads/c5aa32b6b07476fa8b597004899ec538/Elasticsearch_Deep_Dive.pdf
 
 ## Initial installation on OS X
 
@@ -47,27 +57,32 @@ Additionally, if you need large repos or multiple forks for testing, please cons
 
 ## How does it work?
 
-The ElasticSearch integration depends on an external indexer. We ship a [ruby indexer](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/bin/elastic_repo_indexer) by default but are also working on an [indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). The user must trigger the initial indexing via a rake task, but after this is done GitLab itself will trigger reindexing when required via `after_` callbacks on create, update, and destroy that are inherited from [/ee/app/models/concerns/elastic/application_search.rb](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/app/models/concerns/elastic/application_search.rb).
+The Elasticsearch integration depends on an external indexer. We ship a [ruby indexer](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/bin/elastic_repo_indexer) by default but are also working on an [indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). The user must trigger the initial indexing via a rake task, but after this is done GitLab itself will trigger reindexing when required via `after_` callbacks on create, update, and destroy that are inherited from [/ee/app/models/concerns/elastic/application_search.rb](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/app/models/concerns/elastic/application_search.rb).
 
 All indexing after the initial one is done via `ElasticIndexerWorker` (sidekiq jobs).
 
 Search queries are generated by the concerns found in [ee/app/models/concerns/elastic](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/ee/app/models/concerns/elastic). These concerns are also in charge of access control, and have been a historic source of security bugs so please pay close attention to them!
 
 ## Existing Analyzers/Tokenizers/Filters
-These are all defined in https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/elasticsearch/git/model.rb
+
+These are all defined in <https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/elasticsearch/git/model.rb>
 
 ### Analyzers
+
 #### `path_analyzer`
+
 Used when indexing blobs' paths. Uses the `path_tokenizer` and the `lowercase` and `asciifolding` filters.
 
 Please see the `path_tokenizer` explanation below for an example.
 
 #### `sha_analyzer`
+
 Used in blobs and commits. Uses the `sha_tokenizer` and the `lowercase` and `asciifolding` filters.
 
 Please see the `sha_tokenizer` explanation later below for an example.
 
 #### `code_analyzer`
+
 Used when indexing a blob's filename and content. Uses the `whitespace` tokenizer and the filters: `code`, `edgeNGram_filter`, `lowercase`, and `asciifolding`
 
 The `whitespace` tokenizer was selected in order to have more control over how tokens are split. For example the string `Foo::bar(4)` needs to generate tokens like `Foo` and `bar(4)` in order to be properly searched.
@@ -75,15 +90,19 @@ The `whitespace` tokenizer was selected in order to have more control over how t
 Please see the `code` filter for an explanation on how tokens are split.
 
 #### `code_search_analyzer`
+
 Not directly used for indexing, but rather used to transform a search input. Uses the `whitespace` tokenizer and the `lowercase` and `asciifolding` filters.
 
 ### Tokenizers
+
 #### `sha_tokenizer`
+
 This is a custom tokenizer that uses the [`edgeNGram` tokenizer](https://www.elastic.co/guide/en/elasticsearch/reference/5.5/analysis-edgengram-tokenizer.html) to allow SHAs to be searcheable by any sub-set of it (minimum of 5 chars).
 
-example:
+Example:
 
 `240c29dc7e` becomes:
+
 - `240c2`
 - `240c29`
 - `240c29d`
@@ -92,21 +111,26 @@ example:
 - `240c29dc7e`
 
 #### `path_tokenizer`
+
 This is a custom tokenizer that uses the [`path_hierarchy` tokenizer](https://www.elastic.co/guide/en/elasticsearch/reference/5.5/analysis-pathhierarchy-tokenizer.html) with `reverse: true` in order to allow searches to find paths no matter how much or how little of the path is given as input.
 
-example:
+Example:
 
 `'/some/path/application.js'` becomes:
+
 - `'/some/path/application.js'`
 - `'some/path/application.js'`
 - `'path/application.js'`
 - `'application.js'`
 
 ### Filters
+
 #### `code`
-Uses a [Pattern Capture token filter](https://www.elastic.co/guide/en/elasticsearch/reference/5.5/analysis-pattern-capture-tokenfilter.html) to split tokens into more easily searched versions of themselves. 
+
+Uses a [Pattern Capture token filter](https://www.elastic.co/guide/en/elasticsearch/reference/5.5/analysis-pattern-capture-tokenfilter.html) to split tokens into more easily searched versions of themselves.
 
 Patterns:
+
 - `"(\\p{Ll}+|\\p{Lu}\\p{Ll}+|\\p{Lu}+)"`: captures CamelCased and lowedCameCased strings as separate tokens
 - `"(\\d+)"`: extracts digits
 - `"(?=([\\p{Lu}]+[\\p{L}]+))"`: captures CamelCased strings recursively. Ex: `ThisIsATest` => `[ThisIsATest, IsATest, ATest, Test]`
@@ -116,6 +140,7 @@ Patterns:
 - `'\/?([^\/]+)(?=\/|\b)'`: separate path terms `like/this/one`
 
 #### `edgeNGram_filter`
+
 Uses an [Edge NGram token filter](https://www.elastic.co/guide/en/elasticsearch/reference/5.5/analysis-edgengram-tokenfilter.html) to allow inputs with only parts of a token to find the token. For example it would turn `glasses` into permutations starting with `gl` and ending with `glasses`, which would allow a search for "`glass`" to find the original token `glasses`
 
 ## Gotchas
@@ -123,20 +148,50 @@ Uses an [Edge NGram token filter](https://www.elastic.co/guide/en/elasticsearch/
 - Searches can have their own analyzers. Remember to check when editing analyzers
 - `Character` filters (as opposed to token filters) always replace the original character, so they're not a good choice as they can hinder exact searches
 
+## Architecture
+
+GitLab uses `elasticsearch-rails` for handling communication with Elasticsearch server. However, in order to achieve zero-downtime deployment during schema changes, an extra abstraction layer is built to allow:
+
+* Indexing (writes) to multiple indexes, with different mappings
+* Switching to different index for searches (reads) on the fly
+
+Currently we are on the process of migrating models to this new design (e.g. `Snippet`), and it is hardwired to work with a single version for now.
+
+Traditionally, `elasticsearch-rails` provides class and instance level `__elasticsearch__` proxy methods. If you call `Issue.__elasticsearch__`, you will get an instance of `Elasticsearch::Model::Proxy::ClassMethodsProxy`, and if you call `Issue.first.__elasticsearch__`, you will get an instance of `Elasticsearch::Model::Proxy::InstanceMethodsProxy`. These proxy objects would talk to Elasticsearch server directly.
+
+In the new design, `__elasticsearch__` instead represents one extra layer of proxy. It would keep multiple versions of the actual proxy objects, and it would forward read and write calls to the proxy of the intended version.
+
+The `elasticsearch-rails`'s way of specifying each model's mappings and other settings is to create a module for the model to include. However in the new design, each model would have its own corresponding subclassed proxy object, where the settings reside in. For example, snippet related setting in the past reside in `SnippetsSearch` module, but in the new design would reside in `SnippetClassProxy` (which is a subclass of `Elasticsearch::Model::Proxy::ClassMethodsProxy`). This reduces namespace pollution in model classes.
+
+The global configurations per version are now in the `Elastic::(Version)::Config` class. You can change mappings there.
+
+### Creating new version of schema
+
+Currently GitLab would still work with a single version of setting. Once it is implemented, multiple versions of setting can exists in different folders (e.g. `ee/lib/elastic/v12p1` and `ee/lib/elastic/v12p3`). To keep a continuous git history, the latest version lives under the `/latest` folder, but is aliased as the latest version.
+
+If the current version is `v12p1`, and we need to create a new version for `v12p3`, the steps are as follows:
+
+1. Copy the entire folder of `v12p1` as `v12p3`
+1. Change the namespace for files under `v12p3` folder from `V12p1` to `V12p3` (which are still aliased to `Latest`)
+1. Delete `v12p1` folder
+1. Copy the entire folder of `latest` as `v12p1`
+1. Change the namespace for files under `v12p1` folder from `Latest` to `V12p1`
+1. Make changes to `Latest` as needed
+
 ## Troubleshooting
 
-### Getting "flood stage disk watermark [95%] exceeded"
+### Getting `flood stage disk watermark [95%] exceeded`
 
 You might get an error such as
 
 ```
-[2018-10-31T15:54:19,762][WARN ][o.e.c.r.a.DiskThresholdMonitor] [pval5Ct] 
-   flood stage disk watermark [95%] exceeded on 
-   [pval5Ct7SieH90t5MykM5w][pval5Ct][/usr/local/var/lib/elasticsearch/nodes/0] free: 56.2gb[3%], 
+[2018-10-31T15:54:19,762][WARN ][o.e.c.r.a.DiskThresholdMonitor] [pval5Ct]
+   flood stage disk watermark [95%] exceeded on
+   [pval5Ct7SieH90t5MykM5w][pval5Ct][/usr/local/var/lib/elasticsearch/nodes/0] free: 56.2gb[3%],
    all indices on this node will be marked read-only
 ```
 
-This is because you've exceeded the disk space threshold - it thinks you don't have enough disk space left, based on the default 95% threshold.  
+This is because you've exceeded the disk space threshold - it thinks you don't have enough disk space left, based on the default 95% threshold.
 
 In addition, the `read_only_allow_delete` setting will be set to `true`.  It will block indexing, `forcemerge`, etc
 
@@ -148,19 +203,19 @@ Add this to your `elasticsearch.yml` file:
 
 ```
 # turn off the disk allocator
-cluster.routing.allocation.disk.threshold_enabled: false 
+cluster.routing.allocation.disk.threshold_enabled: false
 ```
 
 _or_
 
 ```
 # set your own limits
-cluster.routing.allocation.disk.threshold_enabled: true 
+cluster.routing.allocation.disk.threshold_enabled: true
 cluster.routing.allocation.disk.watermark.flood_stage: 5gb   # ES 6.x only
-cluster.routing.allocation.disk.watermark.low: 15gb 
+cluster.routing.allocation.disk.watermark.low: 15gb
 cluster.routing.allocation.disk.watermark.high: 10gb
 ```
 
-Restart ElasticSearch, and the `read_only_allow_delete` will clear on it's own.
+Restart Elasticsearch, and the `read_only_allow_delete` will clear on it's own.
 
 _from "Disk-based Shard Allocation | Elasticsearch Reference" [5.6](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/disk-allocator.html#disk-allocator) and [6.x](https://www.elastic.co/guide/en/elasticsearch/reference/6.x/disk-allocator.html)_
diff --git a/doc/development/emails.md b/doc/development/emails.md
index 8baf343b133..e6af075a282 100644
--- a/doc/development/emails.md
+++ b/doc/development/emails.md
@@ -26,57 +26,57 @@ See the [Rails guides] for more info.
    feature and fill in the details for your specific IMAP server and email
    account:
 
-    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
-    ```
-
-    As mentioned, the part after `+` is ignored, and this will end up in the mailbox for `gitlab-incoming@gmail.com`.
+   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
+   ```
+
+   As mentioned, the part after `+` is ignored, and this will end up in the mailbox for `gitlab-incoming@gmail.com`.
 
 1. Run this command in the GitLab root directory to launch `mail_room`:
 
-    ```sh
-    bundle exec mail_room -q -c config/mail_room.yml
-    ```
+   ```sh
+   bundle exec mail_room -q -c config/mail_room.yml
+   ```
 
 1. Verify that everything is configured correctly:
 
-    ```sh
-    bundle exec rake gitlab:incoming_email:check RAILS_ENV=development
-    ```
+   ```sh
+   bundle exec rake gitlab:incoming_email:check RAILS_ENV=development
+   ```
 
 1. Reply by email should now be working.
 
 ## Email namespace
 
-As of GitLab 11.7, we support a new format for email handler addresses.  This was done to 
+As of GitLab 11.7, we support a new format for email handler addresses.  This was done to
 support catch-all mailboxes.
 
 If you need to implement a feature which requires a new email handler, follow these rules
@@ -91,10 +91,10 @@ for the format of the email key:
 
 Examples of valid email keys:
 
- - `gitlab-org-gitlab-ce-20-Author_Token12345678-issue` (create a new issue)
- - `gitlab-org-gitlab-ce-20-Author_Token12345678-merge-request` (create a new merge request)
- - `1234567890abcdef1234567890abcdef-unsubscribe` (unsubscribe from a conversation)
- - `1234567890abcdef1234567890abcdef` (reply to a conversation)
+- `gitlab-org-gitlab-ce-20-Author_Token12345678-issue` (create a new issue)
+- `gitlab-org-gitlab-ce-20-Author_Token12345678-merge-request` (create a new merge request)
+- `1234567890abcdef1234567890abcdef-unsubscribe` (unsubscribe from a conversation)
+- `1234567890abcdef1234567890abcdef` (reply to a conversation)
 
 Please note that the action `-issue-` is used in GitLab Premium as the handler for the Service Desk feature.
 
@@ -103,10 +103,10 @@ Please note that the action `-issue-` is used in GitLab Premium as the handler f
 Although we continue to support the older legacy format, no new features should use a legacy format.
 These are the only valid legacy formats for an email handler:
 
- - `path/to/project+namespace`
- - `path/to/project+namespace+action`
- - `namespace`
- - `namespace+action`
+- `path/to/project+namespace`
+- `path/to/project+namespace+action`
+- `namespace`
+- `namespace+action`
 
 Please note that `path/to/project` is used in GitLab Premium as handler for the Service Desk feature.
 
diff --git a/doc/development/fe_guide/accessibility.md b/doc/development/fe_guide/accessibility.md
index df32242a522..64c793cfd64 100644
--- a/doc/development/fe_guide/accessibility.md
+++ b/doc/development/fe_guide/accessibility.md
@@ -5,8 +5,16 @@
 [Chrome Accessibility Developer Tools][chrome-accessibility-developer-tools]
 are useful for testing for potential accessibility problems in GitLab.
 
-Accessibility best-practices and more in-depth information is available on
-[the Audit Rules page][audit-rules] for the Chrome Accessibility Developer Tools.
+The [axe][axe-website] browser extension (available for [Firefox][axe-firefox-extension] and [Chrome][axe-chrome-extension]) is
+also a handy tool for running audits and getting feedback on markup, CSS and even potentially problematic color usages.
+
+Accessibility best-practices and more in-depth information are available on
+[the Audit Rules page][audit-rules] for the Chrome Accessibility Developer Tools. The "[awesome a11y][awesome-a11y]" list is also a
+useful compilation of accessibility-related material.
 
 [chrome-accessibility-developer-tools]: https://github.com/GoogleChrome/accessibility-developer-tools
 [audit-rules]: https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules
+[axe-website]: https://www.deque.com/axe/
+[axe-firefox-extension]: https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/
+[axe-chrome-extension]: https://chrome.google.com/webstore/detail/axe/lhdoppojpmngadmnindnejefpokejbdd
+[awesome-a11y]: https://github.com/brunopulis/awesome-a11y
diff --git a/doc/development/fe_guide/architecture.md b/doc/development/fe_guide/architecture.md
index c67389b169e..3d27f67a8a6 100644
--- a/doc/development/fe_guide/architecture.md
+++ b/doc/development/fe_guide/architecture.md
@@ -11,7 +11,7 @@ Architectural decisions should be accessible to everyone, so please document
 them in the relevant Merge Request discussion or by updating our documentation
 when appropriate.
 
-You can find the Frontend Architecture experts on the [team page](https://about.gitlab.com/team).
+You can find the Frontend Architecture experts on the [team page](https://about.gitlab.com/company/team/).
 
 ## Examples
 
diff --git a/doc/development/fe_guide/axios.md b/doc/development/fe_guide/axios.md
index 0d9397c3bd5..6e7cf523f36 100644
--- a/doc/development/fe_guide/axios.md
+++ b/doc/development/fe_guide/axios.md
@@ -1,15 +1,18 @@
 # Axios
+
 We use [axios][axios] to communicate with the server in Vue applications and most new code.
 
 In order to guarantee all defaults are set you *should not use `axios` directly*, you should import `axios` from `axios_utils`.
 
 ## CSRF token
+
 All our request require a CSRF token.
 To guarantee this token is set, we are importing [axios][axios], setting the token, and exporting `axios` .
 
 This exported module should be used instead of directly using `axios` to ensure the token is set.
 
 ## Usage
+
 ```javascript
   import axios from './lib/utils/axios_utils';
 
@@ -35,7 +38,7 @@ Advantages over [`spyOn()`]:
 
 - no need to create response objects
 - does not allow call through (which we want to avoid)
-- simple API to test error cases 
+- simple API to test error cases
 - provides `replyOnce()` to allow for different responses
 
 We have also decided against using [axios interceptors] because they are not suitable for mocking.
diff --git a/doc/development/fe_guide/components.md b/doc/development/fe_guide/components.md
index 52462a4bec9..096ce8ca25a 100644
--- a/doc/development/fe_guide/components.md
+++ b/doc/development/fe_guide/components.md
@@ -14,28 +14,29 @@ See also the [corresponding UX guide](https://design.gitlab.com/#/components/dro
 1. Use the HTML structure provided by the [docs][bootstrap-dropdowns]
 1. Add a specific class to the top level `.dropdown` element
 
-    ```Haml
-    .dropdown.my-dropdown
-      %button{ type: 'button', data: { toggle: 'dropdown' }, 'aria-haspopup': true, 'aria-expanded': false }
-        %span.dropdown-toggle-text
-          Toggle Dropdown
-        = icon('chevron-down')
-
-      %ul.dropdown-menu
-        %li
-          %a
-            item!
-    ```
-
-    Or use the helpers
-    ```Haml
-    .dropdown.my-dropdown
-      = dropdown_toggle('Toogle!', { toggle: 'dropdown' })
-      = dropdown_content
-        %li
-          %a
-            item!
-    ```
+   ```Haml
+   .dropdown.my-dropdown
+     %button{ type: 'button', data: { toggle: 'dropdown' }, 'aria-haspopup': true, 'aria-expanded': false }
+       %span.dropdown-toggle-text
+         Toggle Dropdown
+       = icon('chevron-down')
+
+     %ul.dropdown-menu
+       %li
+         %a
+           item!
+   ```
+
+   Or use the helpers
+
+   ```Haml
+   .dropdown.my-dropdown
+     = dropdown_toggle('Toogle!', { toggle: 'dropdown' })
+     = dropdown_content
+       %li
+         %a
+           item!
+   ```
 
 [bootstrap-dropdowns]: https://getbootstrap.com/docs/3.3/javascript/#dropdowns
 
diff --git a/doc/development/fe_guide/design_patterns.md b/doc/development/fe_guide/design_patterns.md
index 0342d16a87c..2f372f783f5 100644
--- a/doc/development/fe_guide/design_patterns.md
+++ b/doc/development/fe_guide/design_patterns.md
@@ -53,6 +53,7 @@ When writing a class that needs to manipulate the DOM guarantee a container opti
 This is useful when we need that class to be instantiated more than once in the same page.
 
 Bad:
+
 ```javascript
 class Foo {
   constructor() {
@@ -63,6 +64,7 @@ new Foo();
 ```
 
 Good:
+
 ```javascript
 class Foo {
   constructor(opts) {
@@ -72,6 +74,7 @@ class Foo {
 
 new Foo({ container: '.my-element' });
 ```
+
 You can find an example of the above in this [class][container-class-example];
 
 [container-class-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/mini_pipeline_graph_dropdown.js
diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md
index f3fdaa3b883..ae0e2361840 100644
--- a/doc/development/fe_guide/development_process.md
+++ b/doc/development/fe_guide/development_process.md
@@ -12,8 +12,7 @@ This checklist is intended to help us during development of bigger features/refa
 
 Please use your best judgement when to use it and please contribute new points through merge requests if something comes to your mind.
 
----
-
+```
 ### Frontend development
 
 #### Planning development
@@ -24,15 +23,15 @@ Please use your best judgement when to use it and please contribute new points t
 - [ ] Are all necessary UX specifications available that you will need in order to implement? Are there new UX components/patterns in the designs? Then contact the UI component team early on. How should error messages or validation be handled?
 - [ ] **Library usage** Use Vuex as soon as you have even a medium state to manage, use Vue router if you need to have different views internally and want to link from the outside. Check what libraries we already have for which occasions.
 - [ ] **Plan your implementation:**
-    - [ ] **Architecture plan:** Create a plan aligned with GitLab's architecture, how you are going to do the implementation, for example Vue application setup and its components (through [onion skinning](https://gitlab.com/gitlab-org/gitlab-ce/issues/35873#note_39994091)), Store structure and data flow, which existing Vue components can you reuse. It's a good idea to go through your plan with another engineer to refine it.
-    - [ ] **Backend:** The best way is to kickoff the implementation in a call and discuss with the assigned Backend engineer what you will need from the backend and also when. Can you reuse existing API's? How is the performance with the planned architecture? Maybe create together a JSON mock object to already start with development.
-    - [ ] **Communication:** It also makes sense to have for bigger features an own slack channel (normally called #f_{feature_name}) and even weekly demo calls with all people involved.
-    - [ ] **Dependency Plan:** Are there big dependencies in the plan between you and others, then maybe create an execution diagram to show what is blocking which part and the order of the different parts.
-    - [ ] **Task list:** Create a simple checklist of the subtasks that are needed for the implementation, also consider creating even sub issues. (for example show a comment, delete a comment, update a comment, etc.). This helps you and also everyone else following the implementation
+  - [ ] **Architecture plan:** Create a plan aligned with GitLab's architecture, how you are going to do the implementation, for example Vue application setup and its components (through [onion skinning](https://gitlab.com/gitlab-org/gitlab-ce/issues/35873#note_39994091)), Store structure and data flow, which existing Vue components can you reuse. It's a good idea to go through your plan with another engineer to refine it.
+  - [ ] **Backend:** The best way is to kickoff the implementation in a call and discuss with the assigned Backend engineer what you will need from the backend and also when. Can you reuse existing API's? How is the performance with the planned architecture? Maybe create together a JSON mock object to already start with development.
+  - [ ] **Communication:** It also makes sense to have for bigger features an own slack channel (normally called #f_{feature_name}) and even weekly demo calls with all people involved.
+  - [ ] **Dependency Plan:** Are there big dependencies in the plan between you and others, then maybe create an execution diagram to show what is blocking which part and the order of the different parts.
+  - [ ] **Task list:** Create a simple checklist of the subtasks that are needed for the implementation, also consider creating even sub issues. (for example show a comment, delete a comment, update a comment, etc.). This helps you and also everyone else following the implementation
 - [ ] **Keep it small** To make it easier for you and also all reviewers try to keep merge requests small and merge into a feature branch if needed. To accomplish that you need to plan that from the start. Different methods are:
-    - [ ] **Skeleton based plan** Start with an MR that has the skeleton of the components with placeholder content. In following MRs you can fill the components with interactivity. This also makes it easier to spread out development on multiple people.
-    - [ ] **Cookie Mode** Think about hiding the feature behind a cookie flag if the implementation is on top of existing features
-    - [ ] **New route** Are you refactoring something big then you might consider adding a new route where you implement the new feature and when finished delete the current route and rename the new one. (for example 'merge_request' and 'new_merge_request')
+  - [ ] **Skeleton based plan** Start with an MR that has the skeleton of the components with placeholder content. In following MRs you can fill the components with interactivity. This also makes it easier to spread out development on multiple people.
+  - [ ] **Cookie Mode** Think about hiding the feature behind a cookie flag if the implementation is on top of existing features
+  - [ ] **New route** Are you refactoring something big then you might consider adding a new route where you implement the new feature and when finished delete the current route and rename the new one. (for example 'merge_request' and 'new_merge_request')
 - [ ] **Setup** Is there any specific setup needed for your implementation (for example a kubernetes cluster)? Then let everyone know if it is not already mentioned where they can find documentation (if it doesn't exist - create it)
 - [ ] **Security** Are there any new security relevant implementations? Then please contact the security team for an app security review. If you are not sure ask our [domain expert](https://about.gitlab.com/handbook/engineering/frontend/#frontend-domain-experts)
 
@@ -57,8 +56,7 @@ Please use your best judgement when to use it and please contribute new points t
 - [ ] Are there any big changes on how and especially how frequently we use the API then let production know about it
 - [ ] Smoke test of the RC on dev., staging., canary deployments and .com
 - [ ] Follow up on issues that came out of the review. Create issues for discovered edge cases that should be covered in future iterations.
-
----
+```
 
 ### Share your work early
 
@@ -66,7 +64,7 @@ Please use your best judgement when to use it and please contribute new points t
    GitLab's architecture.
 1. Add a diagram to the issue and ask a frontend architect in the slack channel `#fe_architectural` about it.
 
-  ![Diagram of Issue Boards Architecture](img/boards_diagram.png)
+   ![Diagram of Issue Boards Architecture](img/boards_diagram.png)
 
 1. Don't take more than one week between starting work on a feature and
    sharing a Merge Request with a reviewer or a maintainer.
diff --git a/doc/development/fe_guide/droplab/droplab.md b/doc/development/fe_guide/droplab/droplab.md
index 2f8c79abde1..1c6d895b3ab 100644
--- a/doc/development/fe_guide/droplab/droplab.md
+++ b/doc/development/fe_guide/droplab/droplab.md
@@ -25,6 +25,7 @@ If you do not provide any arguments, it will globally query and instantiate all
   <!-- ... -->
 <ul>
 ```
+
 ```js
 const droplab = new DropLab();
 droplab.init();
@@ -45,6 +46,7 @@ You can add static list items.
   <li>Static value 2</li>
 <ul>
 ```
+
 ```js
 const droplab = new DropLab();
 droplab.init();
@@ -62,6 +64,7 @@ a non-global instance of DropLab using the `DropLab.prototype.init` method.
   <!-- ... -->
 <ul>
 ```
+
 ```js
 const trigger = document.getElementById('trigger');
 const list = document.getElementById('list');
@@ -79,6 +82,7 @@ You can also add hooks to an existing DropLab instance using `DropLab.prototype.
 <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
 <ul id="list" data-dropdown><!-- ... --><ul>
 ```
+
 ```js
 const droplab = new DropLab();
 
@@ -109,6 +113,7 @@ for all `data-dynamic` dropdown lists tracked by that DropLab instance.
   <li><a href="#" data-id="{{id}}">{{text}}</a></li>
 </ul>
 ```
+
 ```js
 const droplab = new DropLab();
 
@@ -131,6 +136,7 @@ the data as the second argument and the `id` of the trigger element as the first
   <li><a href="#" data-id="{{id}}">{{text}}</a></li>
 </ul>
 ```
+
 ```js
 const droplab = new DropLab();
 
@@ -160,6 +166,7 @@ dropdown lists, one of which is dynamic.
   </ul>
 </div>
 ```
+
 ```js
 const droplab = new DropLab();
 
@@ -216,6 +223,7 @@ Some plugins require configuration values, the config object can be passed as th
 <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
 <ul id="list" data-dropdown><!-- ... --><ul>
 ```
+
 ```js
 const droplab = new DropLab();
 
diff --git a/doc/development/fe_guide/droplab/plugins/ajax.md b/doc/development/fe_guide/droplab/plugins/ajax.md
index b6a883ce6c4..4b76b207d88 100644
--- a/doc/development/fe_guide/droplab/plugins/ajax.md
+++ b/doc/development/fe_guide/droplab/plugins/ajax.md
@@ -17,18 +17,19 @@ Add the `Ajax` object to the plugins array of a `DropLab.prototype.init` or `Dro
 <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
 <ul id="list" data-dropdown><!-- ... --><ul>
 ```
+
 ```js
-  const droplab = new DropLab();
+const droplab = new DropLab();
 
-  const trigger = document.getElementById('trigger');
-  const list = document.getElementById('list');
+const trigger = document.getElementById('trigger');
+const list = document.getElementById('list');
 
-  droplab.addHook(trigger, list, [Ajax], {
-    Ajax: {
-      endpoint: '/some-endpoint',
-      method: 'setData',
-    },
-  });
+droplab.addHook(trigger, list, [Ajax], {
+  Ajax: {
+    endpoint: '/some-endpoint',
+    method: 'setData',
+  },
+});
 ```
 
 Optionally you can set `loadingTemplate` to a HTML string. This HTML string will
diff --git a/doc/development/fe_guide/droplab/plugins/filter.md b/doc/development/fe_guide/droplab/plugins/filter.md
index 1f188c64fe4..b867394a241 100644
--- a/doc/development/fe_guide/droplab/plugins/filter.md
+++ b/doc/development/fe_guide/droplab/plugins/filter.md
@@ -17,25 +17,26 @@ Add the `Filter` object to the plugins array of a `DropLab.prototype.init` or `D
   <li><a href="#" data-id="{{id}}">{{text}}</a></li>
 <ul>
 ```
+
 ```js
-  const droplab = new DropLab();
-
-  const trigger = document.getElementById('trigger');
-  const list = document.getElementById('list');
-
-  droplab.init(trigger, list, [Filter], {
-    Filter: {
-      template: 'text',
-    },
-  });
-
-  droplab.addData('trigger', [{
-    id: 0,
-    text: 'Jacob',
-  }, {
-    id: 1,
-    text: 'Jeff',
-  }]);
+const droplab = new DropLab();
+
+const trigger = document.getElementById('trigger');
+const list = document.getElementById('list');
+
+droplab.init(trigger, list, [Filter], {
+  Filter: {
+    template: 'text',
+  },
+});
+
+droplab.addData('trigger', [{
+  id: 0,
+  text: 'Jacob',
+}, {
+  id: 1,
+  text: 'Jeff',
+}]);
 ```
 
 Above, the input string will be compared against the `test` key of the passed data objects.
diff --git a/doc/development/fe_guide/droplab/plugins/input_setter.md b/doc/development/fe_guide/droplab/plugins/input_setter.md
index e4050213869..db492da478a 100644
--- a/doc/development/fe_guide/droplab/plugins/input_setter.md
+++ b/doc/development/fe_guide/droplab/plugins/input_setter.md
@@ -22,33 +22,34 @@ You can also set the `InputSetter` config to an array of objects, which will all
   <li><a href="#" data-id="{{id}}">{{text}}</a></li>
 <ul>
 ```
+
 ```js
-  const droplab = new DropLab();
-
-  const trigger = document.getElementById('trigger');
-  const list = document.getElementById('list');
-
-  const input = document.getElementById('input');
-  const div = document.getElementById('div');
-
-  droplab.init(trigger, list, [InputSetter], {
-    InputSetter: [{
-      input: input,
-      valueAttribute: 'data-id',
-    } {
-      input: div,
-      valueAttribute: 'data-id',
-      inputAttribute: 'data-selected-id',
-    }],
-  });
-
-  droplab.addData('trigger', [{
-    id: 0,
-    text: 'Jacob',
-  }, {
-    id: 1,
-    text: 'Jeff',
-  }]);
+const droplab = new DropLab();
+
+const trigger = document.getElementById('trigger');
+const list = document.getElementById('list');
+
+const input = document.getElementById('input');
+const div = document.getElementById('div');
+
+droplab.init(trigger, list, [InputSetter], {
+  InputSetter: [{
+    input: input,
+    valueAttribute: 'data-id',
+  } {
+    input: div,
+    valueAttribute: 'data-id',
+    inputAttribute: 'data-selected-id',
+  }],
+});
+
+droplab.addData('trigger', [{
+  id: 0,
+  text: 'Jacob',
+}, {
+  id: 1,
+  text: 'Jeff',
+}]);
 ```
 
 Above, if the second list item was clicked, it would update the `#input` element
diff --git a/doc/development/fe_guide/emojis.md b/doc/development/fe_guide/emojis.md
index 38794c47965..6d324d4c4a0 100644
--- a/doc/development/fe_guide/emojis.md
+++ b/doc/development/fe_guide/emojis.md
@@ -3,10 +3,10 @@
 GitLab supports native unicode emojis and fallsback to image-based emojis selectively
 when your platform does not support it.
 
-# How to update Emojis
+## How to update Emojis
 
  1. Update the `gemojione` gem
- 1. Update `fixtures/emojis/index.json` from [Gemojione](https://github.com/jonathanwiesel/gemojione/blob/master/config/index.json).
+ 1. Update `fixtures/emojis/index.json` from [Gemojione](https://github.com/bonusly/gemojione/blob/master/config/index.json).
     In the future, we could grab the file directly from the gem.
     We should probably make a PR on the Gemojione project to get access to
     all emojis after being parsed or just a raw path to the `json` file itself.
diff --git a/doc/development/fe_guide/event_tracking.md b/doc/development/fe_guide/event_tracking.md
index 6ab3fa4acf3..1b417d4c8c2 100644
--- a/doc/development/fe_guide/event_tracking.md
+++ b/doc/development/fe_guide/event_tracking.md
@@ -1,79 +1,76 @@
-# Event Tracking
+# Event tracking
 
-We use [Snowplow](https://github.com/snowplow/snowplow) for tracking custom events (available in GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) only).
+GitLab provides `Tracking`, an interface that wraps
+[Snowplow](https://github.com/snowplow/snowplow) for tracking custom events.
+It uses Snowplow's custom event tracking functions.
 
-## Generic tracking function
-
-In addition to Snowplow's built-in method for tracking page views, we use a generic tracking function which enables us to selectively apply listeners to events.
-
-The generic tracking function can be imported in EE-specific JS files as follows:
+The tracking interface can be imported in JS files as follows:
 
 ```javascript
-import { trackEvent } from `ee/stats`;
+import Tracking from `~/tracking`;
 ```
 
-This gives the user access to the `trackEvent` method, which takes the following parameters:
+## Tracking in HAML or Vue templates
 
-| parameter        | type   | description                                                                                                                                                                                                                                                                                                                            | required |
-| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-| `category`       | string | Describes the page that you're capturing click events on. Unless infeasible, please use the Rails page attribute `document.body.dataset.page` by default.                                                                                                                                                                              | true     |
-| `eventName`      | string | Describes the action the user is taking. The first word should always describe the action. For example, clicks should be `click` and activations should be `activate`. Use underscores to describe what was acted on. For example, activating a form field would be `activate_form_input`. Clicking on a dropdown is `click_dropdown`. | true     |
-| `additionalData` | object | Additional data such as `label`, `property`, and `value` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy).                                                                                                                                          | false    |
+To avoid having to do create a bunch of custom javascript event handlers, when working within HAML or Vue templates, we can add `data-track-*` attributes to elements of interest. This way, all elements that have a `data-track-event` attribute to automatically have event tracking bound.
 
-Read more about instrumentation and the taxonomy in the [Product Handbook](https://about.gitlab.com/handbook/product/feature-instrumentation).
-
-### Tracking in `.js` and `.vue` files
+Below is an example of `data-track-*` attributes assigned to a button in HAML:
 
-The most simple use case is to add tracking programmatically to an event of interest in Javascript.
+```haml
+%button.btn{ data: { track_event: "click_button", track_label: "template_preview", track_property: "my-template", track_value: "" } }
+```
 
-The following example demonstrates how to track a click on a button in Javascript by calling the `trackEvent` method explicitly:
+We can then setup tracking for large sections of a page, or an entire page by telling the Tracking interface to bind to it.
 
 ```javascript
-import { trackEvent } from `ee/stats`;
+import Tracking from '~/tracking';
 
-trackEvent('dashboard:projects:index', 'click_button', {
-    label: 'create_from_template',
-    property: 'template_preview',
-    value: 'rails',
+// for the entire document
+new Tracking().bind();
+
+// for a container element
+document.addEventListener('DOMContentLoaded', () => {
+  new Tracking('my_category').bind(document.getElementById('my-container'));
 });
+
 ```
 
-### Tracking in HAML templates
+When you instantiate a Tracking instance you can provide a category. If none is provided, `document.body.dataset.page` will be used. When you bind the Tracking instance you can provide an element. If no element is provided to bind to, the `document` is assumed.
 
-Sometimes we want to track clicks for multiple elements on a page. Creating event handlers for all elements could soon turn into a tedious task.
+Below is a list of supported `data-track-*` attributes:
 
-There's a more convenient solution to this problem. When working with HAML templates, we can add `data-track-*` attributes to elements of interest. This way, all elements that have both `data-track-label` and `data-track-event` attributes assigned get marked for event tracking. All we have to do is call the `bindTrackableContainer` method on a container which allows for better scoping.
+| attribute             | required | description |
+|:----------------------|:---------|:------------|
+| `data-track-event`    | true     | Action the user is taking. Clicks should be `click` and activations should be `activate`, so for example, focusing a form field would be `activate_form_input`, and clicking a button would be `click_button`. |
+| `data-track-label`    | false    | The `label` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). |
+| `data-track-property` | false    | The `property` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). |
+| `data-track-value`    | false    | The `value` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). If omitted, this will be the elements `value` property or an empty string. For checkboxes, the default value will be the element's checked attribute or `false` when unchecked. |
 
-Below is an example of `data-track-*` attributes assigned to a button in HAML:
+## Tracking in raw Javascript
 
-```ruby
-%button.btn{ data: { track_label: "create_from_template", track_property: "template_preview", track_event: "click_button", track_value: "my-template" } }
-```
+Custom events can be tracked by directly calling the `Tracking.event` static function, which accepts the following arguments:
+
+| argument   | type   | default value              | description |
+|:-----------|:-------|:---------------------------|:------------|
+| `category` | string | document.body.dataset.page | Page or subsection of a page that events are being captured within. |
+| `event`    | string | 'generic'                  | Action the user is taking. Clicks should be `click` and activations should be `activate`, so for example, focusing a form field would be `activate_form_input`, and clicking a button would be `click_button`. |
+| `data`     | object | {}                         | Additional data such as `label`, `property`, and `value` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). These will be set as empty strings if you don't provide them. |
 
-By calling `bindTrackableContainer('.my-container')`, click handlers get bound to all elements located in `.my-container` provided that they have the necessary `data-track-*` attributes assigned to them.
+Tracking can be programmatically added to an event of interest in Javascript, and the following example demonstrates tracking a click on a button by calling `Tracking.event` manually.
 
 ```javascript
-import Stats from 'ee/stats';
+import Tracking from `~/tracking`;
 
-document.addEventListener('DOMContentLoaded', () => {
-  Stats.bindTrackableContainer('.my-container', 'category');
-});
+document.getElementById('my_button').addEventListener('click', () => {
+  Tracking.event('dashboard:projects:index', 'click_button', {
+    label: 'create_from_template',
+    property: 'template_preview',
+    value: 'rails',
+  });
+})
 ```
 
-The second parameter in `bindTrackableContainer` is optional. If omitted, the value of `document.body.dataset.page` will be used as category instead.
-
-Below is a list of supported `data-track-*` attributes:
-
-| attribute             | description                                                                                                                                                                                                     | required |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-| `data-track-label`    | The `label` in `trackEvent`                                                                                                                                                                                     | true     |
-| `data-track-event`    | The `eventName` in `trackEvent`                                                                                                                                                                                 | true     |
-| `data-track-property` | The `property` in `trackEvent`. If omitted, an empty string will be used as a default value.                                                                                                                    | false    |
-| `data-track-value`    | The `value` in `trackEvent`. If omitted, this will be `target.value` or empty string. For checkboxes, the default value being tracked will be the element's checked attribute if `data-track-value` is omitted. | false    |
-
-Since Snowplow is an Enterprise Edition feature, it's necessary to create a CE backport when adding `data-track-*` attributes to HAML templates in most cases.
-
-## Testing
+## Toggling tracking on or off
 
 Snowplow can be enabled by navigating to:
 
diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md
index e4225f2bc39..0d2aeffeac0 100644
--- a/doc/development/fe_guide/frontend_faq.md
+++ b/doc/development/fe_guide/frontend_faq.md
@@ -5,12 +5,12 @@
 1. **You talk about Frontend FAQ.**
    Please share links to it whenever applicable, so more eyes catch when content
    gets outdated.
-2. **Keep it short and simple.**
+1. **Keep it short and simple.**
    Whenever an answer needs more than two sentences it does not belong here.
-3. **Provide background when possible.**
+1. **Provide background when possible.**
    Linking to relevant source code, issue / epic, or other documentation helps
    to understand the answer.
-4. **If you see something, do something.**
+1. **If you see something, do something.**
    Please remove or update any content that is outdated as soon as you see it.
 
 ## FAQ
diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md
index 9fcd32fddfa..4fc5dfc8c3d 100644
--- a/doc/development/fe_guide/graphql.md
+++ b/doc/development/fe_guide/graphql.md
@@ -47,7 +47,7 @@ new Vue({
 });
 ```
 
-Read more about [Vue Apollo][vue-apollo] in the [Vue Apollo documentation][vue-apollo-docs].
+Read more about [Vue Apollo][vue-apollo] in the [Vue Apollo documentation](https://vue-apollo.netlify.com/guide/).
 
 ### Local state with Apollo
 
@@ -55,7 +55,6 @@ It is possible to manage an application state with Apollo by passing
 in a resolvers object when creating the default client. The default state can be set by writing
 to the cache after setting up the default client.
 
-
 ```javascript
 import Vue from 'vue';
 import VueApollo from 'vue-apollo';
@@ -115,13 +114,11 @@ defaultClient.query(query)
   .then(result => console.log(result));
 ```
 
-Read more about the [Apollo] client in the [Apollo documentation][apollo-client-docs].
+Read more about the [Apollo] client in the [Apollo documentation](https://www.apollographql.com/docs/tutorial/client/).
 
 [Apollo]: https://www.apollographql.com/
 [vue-apollo]: https://github.com/Akryum/vue-apollo/
-[vue-apollo-docs]: https://akryum.github.io/vue-apollo/
 [feature-flags]: ../feature_flags.md
 [default-client]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/lib/graphql.js
-[apollo-client-docs]: https://www.apollographql.com/docs/tutorial/client.html
 [vue-test-utils]: https://vue-test-utils.vuejs.org/
 [apollo-link-state]: https://www.apollographql.com/docs/link/links/state.html
diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md
index 533e2001300..4f687d8642e 100644
--- a/doc/development/fe_guide/icons.md
+++ b/doc/development/fe_guide/icons.md
@@ -21,10 +21,10 @@ To use a sprite Icon in HAML or Rails we use a specific helper function :
 sprite_icon(icon_name, size: nil, css_class: '')
 ```
 
--   **icon_name** Use the icon_name that you can find in the SVG Sprite
-    ([Overview is available here][svg-preview]).
--   **size (optional)** Use one of the following sizes : 16, 24, 32, 48, 72 (this will be translated into a `s16` class)
--   **css_class (optional)** If you want to add additional css classes
+- **icon_name** Use the icon_name that you can find in the SVG Sprite
+  ([Overview is available here][svg-preview]).
+- **size (optional)** Use one of the following sizes : 16, 24, 32, 48, 72 (this will be translated into a `s16` class)
+- **css_class (optional)** If you want to add additional css classes
 
 **Example**
 
@@ -65,10 +65,10 @@ export default {
 </template>
 ```
 
--   **name** Name of the Icon in the SVG Sprite  ([Overview is available here][svg-preview]).
--   **size (optional)** Number value for the size which is then mapped to a specific CSS class
-    (Available Sizes: 8, 12, 16, 18, 24, 32, 48, 72 are mapped to `sXX` css classes)
--   **css-classes (optional)** Additional CSS Classes to add to the svg tag.
+- **name** Name of the Icon in the SVG Sprite  ([Overview is available here][svg-preview]).
+- **size (optional)** Number value for the size which is then mapped to a specific CSS class
+  (Available Sizes: 8, 12, 16, 18, 24, 32, 48, 72 are mapped to `sXX` css classes)
+- **css-classes (optional)** Additional CSS Classes to add to the svg tag.
 
 ### Usage in HTML/JS
 
diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md
index 36d5e4ab96b..deaef8e768b 100644
--- a/doc/development/fe_guide/index.md
+++ b/doc/development/fe_guide/index.md
@@ -17,7 +17,7 @@ Working with our frontend assets requires Node (v8.10.0 or greater) and Yarn
 
 For our currently-supported browsers, see our [requirements][requirements].
 
----
+Use [BrowserStack](https://www.browserstack.com/) to test with our supported browsers. Login to BrowserStack with the credentials saved in GitLab's [shared 1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams).
 
 ## Initiatives
 
@@ -77,8 +77,6 @@ How we use Snowplow to track custom events.
 
 Read the [frontend's FAQ](frontend_faq.md) for common small pieces of helpful information.
 
----
-
 ## Style Guides
 
 ### [JavaScript Style Guide](style_guide_js.md)
@@ -91,20 +89,14 @@ changes.
 
 Our SCSS conventions which are enforced through [scss-lint][scss-lint].
 
----
-
 ## [Performance](performance.md)
 
 Best practices for monitoring and maximizing frontend performance.
 
----
-
 ## [Security](security.md)
 
 Frontend security practices.
 
----
-
 ## [Accessibility](accessibility.md)
 
 Our accessibility standards and resources.
diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md
index 2628e95dbc1..676bce32998 100644
--- a/doc/development/fe_guide/performance.md
+++ b/doc/development/fe_guide/performance.md
@@ -30,8 +30,8 @@ To improve the time to first render we are using lazy loading for images. This w
 the actual image source on the `data-src` attribute. After the HTML is rendered and JavaScript is loaded,
 the value of `data-src` will be moved to `src` automatically if the image is in the current viewport.
 
--  Prepare images in HTML for lazy loading by renaming the `src` attribute to `data-src` AND adding the class `lazy`.
--  If you are using the Rails `image_tag` helper, all images will be lazy-loaded by default unless `lazy: false` is provided.
+- Prepare images in HTML for lazy loading by renaming the `src` attribute to `data-src` AND adding the class `lazy`.
+- If you are using the Rails `image_tag` helper, all images will be lazy-loaded by default unless `lazy: false` is provided.
 
 If you are asynchronously adding content which contains lazy images then you need to call the function
 `gl.lazyLoader.searchLazyImages()` which will search for lazy images and load them if needed.
@@ -96,26 +96,26 @@ bundle and included on the page.
   DOM has loaded, you should attach an event handler to the `DOMContentLoaded`
   event with:
 
-    ```javascript
-    import initMyWidget from './my_widget';
+  ```javascript
+  import initMyWidget from './my_widget';
 
-    document.addEventListener('DOMContentLoaded', () => {
-      initMyWidget();
-    });
-    ```
+  document.addEventListener('DOMContentLoaded', () => {
+    initMyWidget();
+  });
+  ```
 
 - **Supporting Module Placement:**
-    - If a class or a module is _specific to a particular route_, try to locate
-      it close to the entry point it will be used. For instance, if
-      `my_widget.js` is only imported within `pages/widget/show/index.js`, you
-      should place the module at `pages/widget/show/my_widget.js` and import it
-      with a relative path (e.g. `import initMyWidget from './my_widget';`).
-    - If a class or module is _used by multiple routes_, place it within a
-      shared directory at the closest common parent directory for the entry
-      points that import it.  For example, if `my_widget.js` is imported within
-      both `pages/widget/show/index.js` and `pages/widget/run/index.js`, then
-      place the module at `pages/widget/shared/my_widget.js` and import it with
-      a relative path if possible (e.g. `../shared/my_widget`).
+  - If a class or a module is _specific to a particular route_, try to locate
+    it close to the entry point it will be used. For instance, if
+    `my_widget.js` is only imported within `pages/widget/show/index.js`, you
+    should place the module at `pages/widget/show/my_widget.js` and import it
+    with a relative path (e.g. `import initMyWidget from './my_widget';`).
+  - If a class or module is _used by multiple routes_, place it within a
+    shared directory at the closest common parent directory for the entry
+    points that import it.  For example, if `my_widget.js` is imported within
+    both `pages/widget/show/index.js` and `pages/widget/run/index.js`, then
+    place the module at `pages/widget/shared/my_widget.js` and import it with
+    a relative path if possible (e.g. `../shared/my_widget`).
 
 - **Enterprise Edition Caveats:**
   For GitLab Enterprise Edition, page-specific entry points will override their
@@ -161,7 +161,7 @@ General tips:
 - Use code-splitting dynamic imports wherever possible to lazy-load code that is not needed initially.
 - [High Performance Animations][high-perf-animations]
 
--------
+---
 
 ## Additional Resources
 
diff --git a/doc/development/fe_guide/security.md b/doc/development/fe_guide/security.md
index 83bb449e54d..47ac87fc895 100644
--- a/doc/development/fe_guide/security.md
+++ b/doc/development/fe_guide/security.md
@@ -1,5 +1,6 @@
 # Security
-### Resources
+
+## Resources
 
 [Mozilla’s HTTP Observatory CLI][observatory-cli] and the
 [Qualys SSL Labs Server Test][qualys-ssl] are good resources for finding
@@ -56,7 +57,7 @@ Some resources on implementing Subresource Integrity:
 
 -->
 
-### Including external resources
+## Including external resources
 
 External fonts, CSS, and JavaScript should never be used with the exception of
 Google Analytics and Piwik - and only when the instance has enabled it. Assets
@@ -64,7 +65,7 @@ should always be hosted and served locally from the GitLab instance. Embedded
 resources via `iframes` should never be used except in certain circumstances
 such as with ReCaptcha, which cannot be used without an `iframe`.
 
-### Avoiding inline scripts and styles
+## Avoiding inline scripts and styles
 
 In order to protect users from [XSS vulnerabilities][xss], we will disable
 inline scripts in the future using Content Security Policy.
diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md
index b50159c2b75..125b11afcd0 100644
--- a/doc/development/fe_guide/style_guide_js.md
+++ b/doc/development/fe_guide/style_guide_js.md
@@ -20,148 +20,148 @@ See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/
 
 1. **Never Ever EVER** disable eslint globally for a file
 
-    ```javascript
-      // bad
-      /* eslint-disable */
+   ```javascript
+   // bad
+   /* eslint-disable */
 
-      // better
-      /* eslint-disable some-rule, some-other-rule */
+   // better
+   /* eslint-disable some-rule, some-other-rule */
 
-      // best
-      // nothing :)
-    ```
+   // best
+   // nothing :)
+   ```
 
 1. If you do need to disable a rule for a single violation, try to do it as locally as possible
 
-    ```javascript
-      // bad
-      /* eslint-disable no-new */
+   ```javascript
+   // bad
+   /* eslint-disable no-new */
 
-      import Foo from 'foo';
+   import Foo from 'foo';
 
-      new Foo();
+   new Foo();
 
-      // better
-      import Foo from 'foo';
+   // better
+   import Foo from 'foo';
 
-      // eslint-disable-next-line no-new
-      new Foo();
-    ```
+   // eslint-disable-next-line no-new
+   new Foo();
+   ```
 
 1. There are few rules that we need to disable due to technical debt. Which are:
-   1. [no-new][eslint-new]
-   1. [class-methods-use-this][eslint-this]
+   1. [no-new](https://eslint.org/docs/rules/no-new)
+   1. [class-methods-use-this](https://eslint.org/docs/rules/class-methods-use-this)
 
 1. When they are needed _always_ place ESlint directive comment blocks on the first line of a script,
    followed by any global declarations, then a blank newline prior to any imports or code.
 
-    ```javascript
-      // bad
-      /* global Foo */
-      /* eslint-disable no-new */
-      import Bar from './bar';
+   ```javascript
+   // bad
+   /* global Foo */
+   /* eslint-disable no-new */
+   import Bar from './bar';
 
-      // good
-      /* eslint-disable no-new */
-      /* global Foo */
+   // good
+   /* eslint-disable no-new */
+   /* global Foo */
 
-      import Bar from './bar';
-    ```
+   import Bar from './bar';
+   ```
 
 1. **Never** disable the `no-undef` rule. Declare globals with `/* global Foo */` instead.
 
 1. When declaring multiple globals, always use one `/* global [name] */` line per variable.
 
-    ```javascript
-      // bad
-      /* globals Flash, Cookies, jQuery */
+   ```javascript
+   // bad
+   /* globals Flash, Cookies, jQuery */
 
-      // good
-      /* global Flash */
-      /* global Cookies */
-      /* global jQuery */
-    ```
+   // good
+   /* global Flash */
+   /* global Cookies */
+   /* global jQuery */
+   ```
 
 1. Use up to 3 parameters for a function or class. If you need more accept an Object instead.
 
-    ```javascript
-      // bad
-      fn(p1, p2, p3, p4) {}
+   ```javascript
+   // bad
+   fn(p1, p2, p3, p4) {}
 
-      // good
-      fn(options) {}
-    ```
+   // good
+   fn(options) {}
+   ```
 
 #### Modules, Imports, and Exports
 
 1. Use ES module syntax to import modules
 
-    ```javascript
-      // bad
-      const SomeClass = require('some_class');
+   ```javascript
+   // bad
+   const SomeClass = require('some_class');
 
-      // good
-      import SomeClass from 'some_class';
+   // good
+   import SomeClass from 'some_class';
 
-      // bad
-      module.exports = SomeClass;
+   // bad
+   module.exports = SomeClass;
 
-      // good
-      export default SomeClass;
-    ```
+   // good
+   export default SomeClass;
+   ```
 
-    Import statements are following usual naming guidelines, for example object literals use camel case:
+   Import statements are following usual naming guidelines, for example object literals use camel case:
 
-    ```javascript
-      // some_object file
-      export default {
-        key: 'value',
-      };
+   ```javascript
+   // some_object file
+   export default {
+     key: 'value',
+   };
 
-      // bad
-      import ObjectLiteral from 'some_object';
+   // bad
+   import ObjectLiteral from 'some_object';
 
-      // good
-      import objectLiteral from 'some_object';
-    ```
+   // good
+   import objectLiteral from 'some_object';
+   ```
 
 1. Relative paths: when importing a module in the same directory, a child
    directory, or an immediate parent directory prefer relative paths.  When
    importing a module which is two or more levels up, prefer either `~/` or `ee/`.
 
-    In **app/assets/javascripts/my-feature/subdir**:
+   In **app/assets/javascripts/my-feature/subdir**:
 
-    ```javascript
-    // bad
-    import Foo from '~/my-feature/foo';
-    import Bar from '~/my-feature/subdir/bar';
-    import Bin from '~/my-feature/subdir/lib/bin';
+   ```javascript
+   // bad
+   import Foo from '~/my-feature/foo';
+   import Bar from '~/my-feature/subdir/bar';
+   import Bin from '~/my-feature/subdir/lib/bin';
 
-    // good
-    import Foo from '../foo';
-    import Bar from './bar';
-    import Bin from './lib/bin';
-    ```
+   // good
+   import Foo from '../foo';
+   import Bar from './bar';
+   import Bin from './lib/bin';
+   ```
 
-    In **spec/javascripts**:
+   In **spec/javascripts**:
 
-    ```javascript
-    // bad
-    import Foo from '../../app/assets/javascripts/my-feature/foo';
+   ```javascript
+   // bad
+   import Foo from '../../app/assets/javascripts/my-feature/foo';
 
-    // good
-    import Foo from '~/my-feature/foo';
-    ```
+   // good
+   import Foo from '~/my-feature/foo';
+   ```
 
-    When referencing an **EE component**:
+   When referencing an **EE component**:
 
-    ```javascript
-    // bad
-    import Foo from '../../../../../ee/app/assets/javascripts/my-feature/ee-foo';
+   ```javascript
+   // bad
+   import Foo from '../../../../../ee/app/assets/javascripts/my-feature/ee-foo';
 
-    // good
-    import Foo from 'ee/my-feature/foo';
-    ```
+   // good
+   import Foo from 'ee/my-feature/foo';
+   ```
 
 1. Avoid using IIFE. Although we have a lot of examples of files which wrap their
    contents in IIFEs (immediately-invoked function expressions),
@@ -170,136 +170,136 @@ See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/
 
 1. Avoid adding to the global namespace.
 
-    ```javascript
-      // bad
-      window.MyClass = class { /* ... */ };
+   ```javascript
+   // bad
+   window.MyClass = class { /* ... */ };
 
-      // good
-      export default class MyClass { /* ... */ }
-    ```
+   // good
+   export default class MyClass { /* ... */ }
+   ```
 
 1. Side effects are forbidden in any script which contains export
 
-    ```javascript
-      // bad
-      export default class MyClass { /* ... */ }
+   ```javascript
+   // bad
+   export default class MyClass { /* ... */ }
 
-      document.addEventListener("DOMContentLoaded", function(event) {
-        new MyClass();
-      }
-    ```
+   document.addEventListener("DOMContentLoaded", function(event) {
+     new MyClass();
+   }
+   ```
 
 #### Data Mutation and Pure functions
 
 1. Strive to write many small pure functions, and minimize where mutations occur.
 
-    ```javascript
-    // bad
-    const values = {foo: 1};
+   ```javascript
+   // bad
+   const values = {foo: 1};
 
-    function impureFunction(items) {
-      const bar = 1;
+   function impureFunction(items) {
+     const bar = 1;
 
-      items.foo = items.a * bar + 2;
+     items.foo = items.a * bar + 2;
 
-      return items.a;
-    }
+     return items.a;
+   }
 
-    const c = impureFunction(values);
+   const c = impureFunction(values);
 
-    // good
-    var values = {foo: 1};
+   // good
+   var values = {foo: 1};
 
-    function pureFunction (foo) {
-      var bar = 1;
+   function pureFunction (foo) {
+     var bar = 1;
 
-      foo = foo * bar + 2;
+     foo = foo * bar + 2;
 
-      return foo;
-    }
+     return foo;
+   }
 
-    var c = pureFunction(values.foo);
+   var c = pureFunction(values.foo);
     ```
 
 1. Avoid constructors with side-effects.
    Although we aim for code without side-effects we need some side-effects for our code to run.
 
-    If the class won't do anything if we only instantiate it, it's ok to add side effects into the constructor (_Note:_ The following is just an example. If the only purpose of the class is to add an event listener and handle the callback a function will be more suitable.)
-
-    ```javascript
-    // Bad
-    export class Foo {
-      constructor() {
-        this.init();
-      }
-      init() {
-        document.addEventListener('click', this.handleCallback)
-      },
-      handleCallback() {
-
-      }
-    }
-
-    // Good
-    export class Foo {
-      constructor() {
-        document.addEventListener()
-      }
-      handleCallback() {
-      }
-    }
-    ```
-
-    On the other hand, if a class only needs to extend a third party/add event listeners in some specific cases, they should be initialized outside of the constructor.
+   If the class won't do anything if we only instantiate it, it's ok to add side effects into the constructor (_Note:_ The following is just an example. If the only purpose of the class is to add an event listener and handle the callback a function will be more suitable.)
+
+   ```javascript
+   // Bad
+   export class Foo {
+     constructor() {
+       this.init();
+     }
+     init() {
+       document.addEventListener('click', this.handleCallback)
+     },
+     handleCallback() {
+
+     }
+   }
+
+   // Good
+   export class Foo {
+     constructor() {
+       document.addEventListener()
+     }
+     handleCallback() {
+     }
+   }
+   ```
+
+   On the other hand, if a class only needs to extend a third party/add event listeners in some specific cases, they should be initialized outside of the constructor.
 
 1. Prefer `.map`, `.reduce` or `.filter` over `.forEach`
    A forEach will most likely cause side effects, it will be mutating the array being iterated. Prefer using `.map`,
    `.reduce` or `.filter`
 
-    ```javascript
-      const users = [ { name: 'Foo' }, { name: 'Bar' } ];
+   ```javascript
+   const users = [ { name: 'Foo' }, { name: 'Bar' } ];
 
-      // bad
-      users.forEach((user, index) => {
-        user.id = index;
-      });
+   // bad
+   users.forEach((user, index) => {
+     user.id = index;
+   });
 
-      // good
-      const usersWithId = users.map((user, index) => {
-        return Object.assign({}, user, { id: index });
-      });
-    ```
+   // good
+   const usersWithId = users.map((user, index) => {
+     return Object.assign({}, user, { id: index });
+   });
+   ```
 
 #### Parse Strings into Numbers
 
 1. `parseInt()` is preferable over `Number()` or `+`
 
-    ```javascript
-      // bad
-      +'10' // 10
+   ```javascript
+   // bad
+   +'10' // 10
 
-      // good
-      Number('10') // 10
+   // good
+   Number('10') // 10
 
-      // better
-      parseInt('10', 10);
-    ```
+   // better
+   parseInt('10', 10);
+   ```
 
 #### CSS classes used for JavaScript
 
 1. If the class is being used in Javascript it needs to be prepend with `js-`
 
-    ```html
-      // bad
-      <button class="add-user">
-        Add User
-      </button>
+   ```html
+   // bad
+   <button class="add-user">
+     Add User
+   </button>
 
-      // good
-      <button class="js-add-user">
-        Add User
-      </button>
-    ```
+   // good
+   <button class="js-add-user">
+     Add User
+   </button>
+   ```
 
 ### Vue.js
 
@@ -314,43 +314,44 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
 1. The store has it's own file
 1. Use a function in the bundle file to instantiate the Vue component:
 
-    ```javascript
-      // bad
-      class {
-        init() {
-          new Component({})
-        }
-      }
-
-      // good
-      document.addEventListener('DOMContentLoaded', () => new Vue({
-        el: '#element',
-        components: {
-          componentName
-        },
-        render: createElement => createElement('component-name'),
-      }));
-    ```
+   ```javascript
+   // bad
+   class {
+     init() {
+       new Component({})
+     }
+   }
+
+   // good
+   document.addEventListener('DOMContentLoaded', () => new Vue({
+     el: '#element',
+     components: {
+       componentName
+     },
+     render: createElement => createElement('component-name'),
+   }));
+   ```
 
 1. Do not use a singleton for the service or the store
 
-    ```javascript
-      // bad
-      class Store {
-        constructor() {
-          if (!this.prototype.singleton) {
-            // do something
-          }
-        }
-      }
+   ```javascript
+   // bad
+   class Store {
+     constructor() {
+       if (!this.prototype.singleton) {
+         // do something
+       }
+     }
+   }
+
+   // good
+   class Store {
+     constructor() {
+       // do something
+     }
+   }
+   ```
 
-      // good
-      class Store {
-        constructor() {
-          // do something
-        }
-      }
-    ```
 1. Use `.vue` for Vue templates. Do not use `%template` in HAML.
 
 #### Naming
@@ -358,38 +359,38 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
 1. **Extensions**: Use `.vue` extension for Vue components. Do not use `.js` as file extension ([#34371]).
 1. **Reference Naming**: Use PascalCase for their instances:
 
-    ```javascript
-      // bad
-      import cardBoard from 'cardBoard.vue'
+   ```javascript
+   // bad
+   import cardBoard from 'cardBoard.vue'
 
-      components: {
-        cardBoard,
-      };
+   components: {
+     cardBoard,
+   };
 
-      // good
-      import CardBoard from 'cardBoard.vue'
+   // good
+   import CardBoard from 'cardBoard.vue'
 
-      components: {
-        CardBoard,
-      };
-    ```
+   components: {
+     CardBoard,
+   };
+   ```
 
 1. **Props Naming:**  Avoid using DOM component prop names.
 1. **Props Naming:** Use kebab-case instead of camelCase to provide props in templates.
 
-    ```javascript
-      // bad
-      <component class="btn">
+   ```javascript
+   // bad
+   <component class="btn">
 
-      // good
-      <component css-class="btn">
+   // good
+   <component css-class="btn">
 
-      // bad
-      <component myProp="prop" />
+   // bad
+   <component myProp="prop" />
 
-      // good
-      <component my-prop="prop" />
-    ```
+   // good
+   <component my-prop="prop" />
+   ```
 
 [#34371]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34371
 
@@ -399,205 +400,205 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
 
    1. With more than one attribute, all attributes should be on a new line:
 
-        ```javascript
-          // bad
-          <component v-if="bar"
-              param="baz" />
+      ```javascript
+      // bad
+      <component v-if="bar"
+          param="baz" />
 
-          <button class="btn">Click me</button>
+      <button class="btn">Click me</button>
 
-          // good
-          <component
-            v-if="bar"
-            param="baz"
-          />
+      // good
+      <component
+        v-if="bar"
+        param="baz"
+      />
 
-          <button class="btn">
-            Click me
-          </button>
-        ```
+      <button class="btn">
+        Click me
+      </button>
+      ```
 
    1. The tag can be inline if there is only one attribute:
 
-        ```javascript
-          // good
-            <component bar="bar" />
+      ```javascript
+      // good
+        <component bar="bar" />
 
-          // good
-            <component
-              bar="bar"
-              />
+      // good
+        <component
+          bar="bar"
+          />
 
-          // bad
-           <component
-              bar="bar" />
-        ```
+      // bad
+       <component
+          bar="bar" />
+      ```
 
 #### Quotes
 
 1. Always use double quotes `"` inside templates and single quotes `'` for all other JS.
 
-    ```javascript
-      // bad
-      template: `
-        <button :class='style'>Button</button>
-      `
+   ```javascript
+   // bad
+   template: `
+     <button :class='style'>Button</button>
+   `
 
-      // good
-      template: `
-        <button :class="style">Button</button>
-      `
-    ```
+   // good
+   template: `
+     <button :class="style">Button</button>
+   `
+   ```
 
 #### Props
 
 1. Props should be declared as an object
 
-    ```javascript
-      // bad
-      props: ['foo']
+   ```javascript
+   // bad
+   props: ['foo']
 
-      // good
-      props: {
-        foo: {
-          type: String,
-          required: false,
-          default: 'bar'
-        }
-      }
-    ```
+   // good
+   props: {
+     foo: {
+       type: String,
+       required: false,
+       default: 'bar'
+     }
+   }
+   ```
 
 1. Required key should always be provided when declaring a prop
 
-    ```javascript
-      // bad
-      props: {
-        foo: {
-          type: String,
-        }
-      }
-
-      // good
-      props: {
-        foo: {
-          type: String,
-          required: false,
-          default: 'bar'
-        }
-      }
-    ```
+   ```javascript
+   // bad
+   props: {
+     foo: {
+       type: String,
+     }
+   }
+
+   // good
+   props: {
+     foo: {
+       type: String,
+       required: false,
+       default: 'bar'
+     }
+   }
+   ```
 
 1. Default key should be provided if the prop is not required.
    _Note:_ There are some scenarios where we need to check for the existence of the property.
    On those a default key should not be provided.
 
-    ```javascript
-      // good
-      props: {
-        foo: {
-          type: String,
-          required: false,
-        }
-      }
-
-      // good
-      props: {
-        foo: {
-          type: String,
-          required: false,
-          default: 'bar'
-        }
-      }
-
-      // good
-      props: {
-        foo: {
-          type: String,
-          required: true
-        }
-      }
-    ```
+   ```javascript
+   // good
+   props: {
+     foo: {
+       type: String,
+       required: false,
+     }
+   }
+
+   // good
+   props: {
+     foo: {
+       type: String,
+       required: false,
+       default: 'bar'
+     }
+   }
+
+   // good
+   props: {
+     foo: {
+       type: String,
+       required: true
+     }
+   }
+   ```
 
 #### Data
 
 1. `data` method should always be a function
 
-    ```javascript
-      // bad
-      data: {
-        foo: 'foo'
-      }
+   ```javascript
+   // bad
+   data: {
+     foo: 'foo'
+   }
 
-      // good
-      data() {
-        return {
-          foo: 'foo'
-        };
-      }
-    ```
+   // good
+   data() {
+     return {
+       foo: 'foo'
+     };
+   }
+   ```
 
 #### Directives
 
 1. Shorthand `@` is preferable over `v-on`
 
-    ```javascript
-      // bad
-      <component v-on:click="eventHandler"/>
+   ```javascript
+   // bad
+   <component v-on:click="eventHandler"/>
 
-      // good
-      <component @click="eventHandler"/>
-    ```
+   // good
+   <component @click="eventHandler"/>
+   ```
 
-2. Shorthand `:` is preferable over `v-bind`
+1. Shorthand `:` is preferable over `v-bind`
 
-    ```javascript
-      // bad
-      <component v-bind:class="btn"/>
+   ```javascript
+   // bad
+   <component v-bind:class="btn"/>
 
-      // good
-      <component :class="btn"/>
-    ```
+   // good
+   <component :class="btn"/>
+   ```
 
-3. Shorthand `#` is preferable over `v-slot`
+1. Shorthand `#` is preferable over `v-slot`
 
-    ```javascript
-      // bad
-      <template v-slot:header></template>
+   ```javascript
+   // bad
+   <template v-slot:header></template>
 
-      // good
-      <template #header></template>
-    ```
+   // good
+   <template #header></template>
+   ```
 
 #### Closing tags
 
 1. Prefer self closing component tags
 
-    ```javascript
-      // bad
-      <component></component>
+   ```javascript
+   // bad
+   <component></component>
 
-      // good
-      <component />
-    ```
+   // good
+   <component />
+   ```
 
 #### Ordering
 
 1. Tag order in `.vue` file
 
-    ```
-    <script>
-      // ...
-    </script>
-
-    <template>
-      // ...
-    </template>
-
-    // We don't use scoped styles but there are few instances of this
-    <style>
-      // ...
-    </style>
-    ```
+   ```
+   <script>
+     // ...
+   </script>
+
+   <template>
+     // ...
+   </template>
+
+   // We don't use scoped styles but there are few instances of this
+   <style>
+     // ...
+   </style>
+   ```
 
 1. Properties in a Vue Component:
    Check [order of properties in components rule][vue-order].
@@ -608,50 +609,50 @@ When using `v-for` you need to provide a *unique* `:key` attribute for each item
 
 1. If the elements of the array being iterated have an unique `id` it is advised to use it:
 
-    ```html
-      <div
-        v-for="item in items"
-        :key="item.id"
-      >
-        <!-- content -->
-      </div>
-    ```
+   ```html
+   <div
+     v-for="item in items"
+     :key="item.id"
+   >
+     <!-- content -->
+   </div>
+   ```
 
 1. When the elements being iterated don't have a unique id, you can use the array index as the `:key` attribute
 
-    ```html
-      <div
-        v-for="(item, index) in items"
-        :key="index"
-      >
-        <!-- content -->
-      </div>
-    ```
+   ```html
+   <div
+     v-for="(item, index) in items"
+     :key="index"
+   >
+     <!-- content -->
+   </div>
+   ```
 
 1. When using `v-for` with `template` and there is more than one child element, the `:key` values must be unique. It's advised to use `kebab-case` namespaces.
 
-    ```html
-      <template v-for="(item, index) in items">
-        <span :key="`span-${index}`"></span>
-        <button :key="`button-${index}`"></button>
-      </template>
-    ```
+   ```html
+   <template v-for="(item, index) in items">
+     <span :key="`span-${index}`"></span>
+     <button :key="`button-${index}`"></button>
+   </template>
+   ```
 
 1. When dealing with nested `v-for` use the same guidelines as above.
 
-    ```html
-      <div
-        v-for="item in items"
-        :key="item.id"
-      >
-        <span
-          v-for="element in array"
-          :key="element.id"
-        >
-          <!-- content -->
-        </span>
-      </div>
-    ```
+   ```html
+   <div
+     v-for="item in items"
+     :key="item.id"
+   >
+     <span
+       v-for="element in array"
+       :key="element.id"
+     >
+       <!-- content -->
+     </span>
+   </div>
+   ```
 
 Useful links:
 
@@ -662,35 +663,35 @@ Useful links:
 
 1. Tooltips: Do not rely on `has-tooltip` class name for Vue components
 
-    ```javascript
-      // bad
-      <span
-        class="has-tooltip"
-        title="Some tooltip text">
-        Text
-      </span>
-
-      // good
-      <span
-        v-tooltip
-        title="Some tooltip text">
-        Text
-      </span>
-    ```
+   ```javascript
+   // bad
+   <span
+     class="has-tooltip"
+     title="Some tooltip text">
+     Text
+   </span>
+
+   // good
+   <span
+     v-tooltip
+     title="Some tooltip text">
+     Text
+   </span>
+   ```
 
 1. Tooltips: When using a tooltip, include the tooltip directive, `./app/assets/javascripts/vue_shared/directives/tooltip.js`
 
 1. Don't change `data-original-title`.
 
-    ```javascript
-      // bad
-      <span data-original-title="tooltip text">Foo</span>
+   ```javascript
+   // bad
+   <span data-original-title="tooltip text">Foo</span>
 
-      // good
-      <span title="tooltip text">Foo</span>
+   // good
+   <span title="tooltip text">Foo</span>
 
-      $('span').tooltip('_fixTitle');
-    ```
+   $('span').tooltip('_fixTitle');
+   ```
 
 ### The Javascript/Vue Accord
 
@@ -713,8 +714,6 @@ The goal of this accord is to make sure we are all on the same page.
 
 [airbnb-js-style-guide]: https://github.com/airbnb/javascript
 [eslintrc]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.eslintrc
-[eslint-this]: http://eslint.org/docs/rules/class-methods-use-this
-[eslint-new]: http://eslint.org/docs/rules/no-new
 [eslint-plugin-vue]: https://github.com/vuejs/eslint-plugin-vue
 [eslint-plugin-vue-rules]: https://github.com/vuejs/eslint-plugin-vue#bulb-rules
 [vue-order]: https://github.com/vuejs/eslint-plugin-vue/blob/master/docs/rules/order-in-components.md
diff --git a/doc/development/fe_guide/style_guide_scss.md b/doc/development/fe_guide/style_guide_scss.md
index b25dce65ffe..95c4a094c04 100644
--- a/doc/development/fe_guide/style_guide_scss.md
+++ b/doc/development/fe_guide/style_guide_scss.md
@@ -6,6 +6,7 @@ easy to maintain, and performant for the end-user.
 ## Rules
 
 ### Utility Classes
+
 As part of the effort for [cleaning up our CSS and moving our components into GitLab-UI](https://gitlab.com/groups/gitlab-org/-/epics/950)
 led by the [GitLab UI WG](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/20623) we prefer the use of utility classes over adding new CSS. However, complex CSS can be addressed by adding component classes.
 
@@ -31,12 +32,12 @@ New utility classes should be added to [`utilities.scss`](https://gitlab.com/git
 
 #### When should I create component classes?
 
-We recommend a "utility-first" approach. 
+We recommend a "utility-first" approach.
 
 1. Start with utility classes.
-2. If composing utility classes into a component class removes code duplication and encapsulates a clear responsibility, do it.
+1. If composing utility classes into a component class removes code duplication and encapsulates a clear responsibility, do it.
 
-This encourages an organic growth of component classes and prevents the creation of one-off unreusable classes. Also, the kind of classes that emerge from "utility-first" tend to be design-centered (e.g. `.button`, `.alert`, `.card`) rather than domain-centered (e.g. `.security-report-widget`, `.commit-header-icon`). 
+This encourages an organic growth of component classes and prevents the creation of one-off unreusable classes. Also, the kind of classes that emerge from "utility-first" tend to be design-centered (e.g. `.button`, `.alert`, `.card`) rather than domain-centered (e.g. `.security-report-widget`, `.commit-header-icon`).
 
 Examples of component classes that were created using "utility-first" include:
 
@@ -45,8 +46,8 @@ Examples of component classes that were created using "utility-first" include:
 
 Inspiration:
 
-- https://tailwindcss.com/docs/utility-first
-- https://tailwindcss.com/docs/extracting-components 
+- <https://tailwindcss.com/docs/utility-first>
+- <https://tailwindcss.com/docs/extracting-components>
 
 ### Naming
 
@@ -211,6 +212,7 @@ selectors are intended for use only with JavaScript to allow for removal or
 renaming without breaking styling.
 
 ### IDs
+
 Don't use ID selectors in CSS.
 
 ```scss
diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md
index 8c6a73c6824..421b7265613 100644
--- a/doc/development/fe_guide/vue.md
+++ b/doc/development/fe_guide/vue.md
@@ -34,6 +34,7 @@ new_feature
 │  └── new_feature_store.js
 ├── index.js
 ```
+
 _For consistency purposes, we recommend you to follow the same structure._
 
 Let's look into each of them:
@@ -49,7 +50,9 @@ provided as a prop to the main component.
 Be sure to read about [page-specific JavaScript][page_specific_javascript].
 
 ### Bootstrapping Gotchas
+
 #### Providing data from HAML to JavaScript
+
 While mounting a Vue application may be a need to provide data from Rails to JavaScript.
 To do that, provide the data through `data` attributes in the HTML element and query them while mounting the application.
 
@@ -83,7 +86,8 @@ document.addEventListener('DOMContentLoaded', () => new Vue({
 ```
 
 #### Accessing the `gl` object
-When we need to query the `gl` object for data that won't change during the application's life cyle, we should do it in the same place where we query the DOM.
+
+When we need to query the `gl` object for data that won't change during the application's life cycle, we should do it in the same place where we query the DOM.
 By following this practice, we can avoid the need to mock the `gl` object, which will make tests easier.
 It should be done while initializing our Vue instance, and the data should be provided as `props` to the main component:
 
@@ -118,12 +122,13 @@ You can read more about components in Vue.js site, [Component System][component-
 ### A folder for the Store
 
 #### Vuex
+
 Check this [page](vuex.md) for more details.
 
 ### Mixing Vue and jQuery
 
 - Mixing Vue and jQuery is not recommended.
-- If you need to use a specific jQuery plugin in Vue, [create a wrapper around it][https://vuejs.org/v2/examples/select2.html].
+- If you need to use a specific jQuery plugin in Vue, [create a wrapper around it](https://vuejs.org/v2/examples/select2.html).
 - It is acceptable for Vue to listen to existing jQuery events using jQuery event listeners.
 - It is not recommended to add new jQuery events for Vue to interact with jQuery.
 
@@ -212,6 +217,7 @@ describe('Todos App', () => {
 ```
 
 ### `mountComponent` helper
+
 There is a helper in `spec/javascripts/helpers/vue_mount_component_helper.js` that allows you to mount a component with the given props:
 
 ```javascript
@@ -225,10 +231,12 @@ const vm = mountComponent(Component, data);
 ```
 
 ### Test the component's output
+
 The main return value of a Vue component is the rendered output. In order to test the component we
 need to test the rendered output. [Vue][vue-test] guide's to unit test show us exactly that:
 
 ## Vue.js Expert Role
+
 One should apply to be a Vue.js expert by opening an MR when the Merge Request's they create and review show:
 
 - Deep understanding of Vue and Vuex reactivy
diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md
index bf248b7f8af..557d3132d71 100644
--- a/doc/development/fe_guide/vuex.md
+++ b/doc/development/fe_guide/vuex.md
@@ -1,15 +1,18 @@
 # Vuex
+
 To manage the state of an application you should use [Vuex][vuex-docs].
 
 _Note:_ All of the below is explained in more detail in the official [Vuex documentation][vuex-docs].
 
 ## Separation of concerns
+
 Vuex is composed of State, Getters, Mutations, Actions and Modules.
 
 When a user clicks on an action, we need to `dispatch` it. This action will `commit` a mutation that will change the state.
 _Note:_ The action itself will not update the state, only a mutation should update the state.
 
 ## File structure
+
 When using Vuex at GitLab, separate this concerns into different files to improve readability:
 
 ```
@@ -21,10 +24,12 @@ When using Vuex at GitLab, separate this concerns into different files to improv
   ├── state.js          # state
   └── mutation_types.js # mutation types
 ```
+
 The following example shows an application that lists and adds users to the state.
 (For a more complex example implementation take a look at the security applications store in [here](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/ee/app/assets/javascripts/vue_shared/security_reports/store))
 
 ### `index.js`
+
 This is the entry point for our store. You can use the following as a guide:
 
 ```javascript
@@ -47,6 +52,7 @@ export default createStore();
 ```
 
 ### `state.js`
+
 The first thing you should do before writing any code is to design the state.
 
 Often we need to provide data from haml to our Vue application. Let's store it in the state for better access.
@@ -66,9 +72,11 @@ Often we need to provide data from haml to our Vue application. Let's store it i
 ```
 
 #### Access `state` properties
+
 You can use `mapState` to access state properties in the components.
 
 ### `actions.js`
+
 An action is a payload of information to send data from our application to our store.
 
 An action is usually composed by a `type` and a `payload` and they describe what happened.
@@ -110,6 +118,7 @@ In this file, we will write the actions that will call the respective mutations:
 ```
 
 #### Actions Pattern: `request` and `receive` namespaces
+
 When a request is made we often want to show a loading state to the user.
 
 Instead of creating an action to toggle the loading state and dispatch it in the component,
@@ -136,6 +145,7 @@ By following this pattern we guarantee:
 1. Actions are simple and straightforward
 
 #### Dispatching actions
+
 To dispatch an action from a component, use the `mapActions` helper:
 
 ```javascript
@@ -154,6 +164,7 @@ import { mapActions } from 'vuex';
 ```
 
 ### `mutations.js`
+
 The mutations specify how the application state changes in response to actions sent to the store.
 The only way to change state in a Vuex store should be by committing a mutation.
 
@@ -193,6 +204,7 @@ Remember that actions only describe that something happened, they don't describe
 ```
 
 ### `getters.js`
+
 Sometimes we may need to get derived state based on store state, like filtering for a specific prop.
 Using a getter will also cache the result based on dependencies due to [how computed props work](https://vuejs.org/v2/guide/computed.html#Computed-Caching-vs-Methods)
 This can be done through the `getters`:
@@ -219,6 +231,7 @@ import { mapGetters } from 'vuex';
 ```
 
 ### `mutation_types.js`
+
 From [vuex mutations docs][vuex-mutations]:
 > It is a commonly seen pattern to use constants for mutation types in various Flux implementations. This allows the code to take advantage of tooling like linters, and putting all constants in a single file allows your collaborators to get an at-a-glance view of what mutations are possible in the entire application.
 
@@ -227,6 +240,7 @@ export const ADD_USER = 'ADD_USER';
 ```
 
 ### How to include the store in your application
+
 The store should be included in the main component of your application:
 
 ```javascript
@@ -241,6 +255,7 @@ The store should be included in the main component of your application:
 ```
 
 ### Communicating with the Store
+
 ```javascript
 <script>
 import { mapActions, mapState, mapGetters } from 'vuex';
@@ -298,29 +313,33 @@ export default {
 
 1. Do not call a mutation directly. Always use an action to commit a mutation. Doing so will keep consistency throughout the application. From Vuex docs:
 
-    >  why don't we just call store.commit('action') directly? Well, remember that mutations must be synchronous? Actions aren't. We can perform asynchronous operations inside an action.
+   > Why don't we just call store.commit('action') directly? Well, remember that mutations must be synchronous? Actions aren't. We can perform asynchronous operations inside an action.
 
-    ```javascript
-      // component.vue
+   ```javascript
+     // component.vue
 
-      // bad
-      created() {
-        this.$store.commit('mutation');
-      }
+     // bad
+     created() {
+       this.$store.commit('mutation');
+     }
+
+     // good
+     created() {
+       this.$store.dispatch('action');
+     }
+   ```
 
-      // good
-      created() {
-        this.$store.dispatch('action');
-      }
-    ```
 1. Use mutation types instead of hardcoding strings. It will be less error prone.
 1. The State will be accessible in all components descending from the use where the store is instantiated.
 
 ### Testing Vuex
+
 #### Testing Vuex concerns
+
 Refer to [vuex docs][vuex-testing] regarding testing Actions, Getters and Mutations.
 
 #### Testing components that need a store
+
 Smaller components might use `store` properties to access the data.
 In order to write unit tests for those components, we need to include the store and provide the correct state:
 
@@ -363,6 +382,7 @@ describe('component', () => {
 ```
 
 #### Testing Vuex actions and getters
+
 Because we're currently using [`babel-plugin-rewire`](https://github.com/speedskater/babel-plugin-rewire), you may encounter the following error when testing your Vuex actions and getters:
 `[vuex] actions should be function or object with "handler" function`
 
diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md
index 13f0c5cc33e..6bad91d6287 100644
--- a/doc/development/feature_flags.md
+++ b/doc/development/feature_flags.md
@@ -1,127 +1 @@
-# Manage feature flags
-
-Starting from GitLab 9.3 we support feature flags for features in GitLab via
-[Flipper](https://github.com/jnunemaker/flipper/). You should use the `Feature`
-class (defined in `lib/feature.rb`) in your code to get, set and list feature
-flags.
-
-During runtime you can set the values for the gates via the
-[features API](../api/features.md) (accessible to admins only).
-
-## Feature groups
-
-Starting from GitLab 9.4 we support feature groups via
-[Flipper groups](https://github.com/jnunemaker/flipper/blob/v0.10.2/docs/Gates.md#2-group).
-
-Feature groups must be defined statically in `lib/feature.rb` (in the
-`.register_feature_groups` method), but their implementation can obviously be
-dynamic (querying the DB etc.).
-
-Once defined in `lib/feature.rb`, you will be able to activate a
-feature for a given feature group via the [`feature_group` param of the features API](../api/features.md#set-or-create-a-feature)
-
-For GitLab.com, [team members have access to feature flags through Chatops](chatops_on_gitlabcom.md). Only
-percentage gates are supported at this time. Setting a feature to be used 50% of
-the time, you should execute `/chatops run feature set my_feature_flag 50`.
-
-## Feature flags for user applications
-
-This document only covers feature flags used in the development of GitLab 
-itself. Feature flags in deployed user applications can be found at 
-[Feature Flags](../user/project/operations/feature_flags.md)
-
-## Developing with feature flags
-
-In general, it's better to have a group- or user-based gate, and you should prefer
-it over the use of percentage gates. This would make debugging easier, as you
-filter for example logs and errors based on actors too. Furthermore, this allows
-for enabling for the `gitlab-org` group first, while the rest of the users
-aren't impacted.
-
-```ruby
-# Good
-Feature.enabled?(:feature_flag, project)
-
-# Avoid, if possible
-Feature.enabled?(:feature_flag)
-```
-
-To use feature gates based on actors, the model needs to respond to
-`flipper_id`. For example, to enable for the Foo model:
-
-```ruby
-class Foo < ActiveRecord::Base
-  include FeatureGate
-end
-```
-
-Features that are developed and are intended to be merged behind a feature flag
-should not include a changelog entry. The entry should be added in the merge
-request removing the feature flags.
-
-In the rare case that you need the feature flag to be on automatically, use
-`default_enabled: true` when checking:
-
-```ruby
-Feature.enabled?(:feature_flag, project, default_enabled: true)
-```
-
-For more information about rolling out changes using feature flags, refer to the
-[Rolling out changes using feature flags](rolling_out_changes_using_feature_flags.md)
-guide.
-
-### Frontend
-
-For frontend code you can use the method `push_frontend_feature_flag`, which is
-available to all controllers that inherit from `ApplicationController`. Using
-this method you can expose the state of a feature flag as follows:
-
-```ruby
-before_action do
-  push_frontend_feature_flag(:vim_bindings)
-end
-
-def index
-  # ...
-end
-
-def edit
-  # ...
-end
-```
-
-You can then check for the state of the feature flag in JavaScript as follows:
-
-```javascript
-if ( gon.features.vimBindings ) {
-  // ...
-}
-```
-
-The name of the feature flag in JavaScript will always be camelCased, meaning
-that checking for `gon.features.vim_bindings` would not work.
-
-### Specs
-
-In the test environment `Feature.enabled?` is stubbed to always respond to `true`,
-so we make sure behavior under feature flag doesn't go untested in some non-specific
-contexts.
-
-Whenever a feature flag is present, make sure to test _both_ states of the
-feature flag.
-
-See the
-[testing guide](testing_guide/best_practices.md#feature-flags-in-tests)
-for information and examples on how to stub feature flags in tests.
-
-## Enabling a feature flag (in development)
-
-In the rails console (`rails c`), enter the following command to enable your feature flag
-
-```ruby
-Feature.enable(:feature_flag_name)
-```
-
-## Enabling a feature flag (in production)
-
-Check how to [roll out changes using feature flags](rolling_out_changes_using_feature_flags.md).
+This document was moved to [another location](feature_flags/index.md).
diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md
new file mode 100644
index 00000000000..739f4207e27
--- /dev/null
+++ b/doc/development/feature_flags/controls.md
@@ -0,0 +1,123 @@
+# Access for enabling a feature flag in production
+
+In order to be able to turn on/off features behind feature flags in any of the
+GitLab Inc. provided environments such as staging and production, you need to
+have access to the chatops bot. Chatops bot is currently running on the ops instance,
+which is different from GitLab.com or dev.gitlab.org.
+
+Follow the Chatops document to [request access](../chatops_on_gitlabcom.md#requesting-access).
+
+Once you are added to the project test if your access propagated,
+run:
+
+```
+/chatops run feature --help
+```
+
+## Rolling out changes
+
+When the changes are deployed to the environments it is time to start
+rolling out the feature to our users. The exact procedure of rolling out a
+change is unspecified, as this can vary from change to change. However, in
+general we recommend rolling out changes incrementally, instead of enabling them
+for everybody right away. We also recommend you to _not_ enable a feature
+_before_ the code is being deployed.
+This allows you to separate rolling out a feature from a deploy, making it
+easier to measure the impact of both separately.
+
+GitLab's feature library (using
+[Flipper](https://github.com/jnunemaker/flipper), and covered in the [Feature
+Flags process](process.md) guide) supports rolling out changes to a percentage of
+users. This in turn can be controlled using [GitLab chatops](../../ci/chatops/README.md).
+
+For an up to date list of feature flag commands please see [the source
+code](https://gitlab.com/gitlab-com/chatops/blob/master/lib/chatops/commands/feature.rb).
+Note that all the examples in that file must be preceded by
+`/chatops run`.
+
+If you get an error "Whoops! This action is not allowed. This incident
+will be reported." that means your Slack account is not allowed to
+change feature flags or you do not [have access](#access-for-enabling-a-feature-flag-in-production).
+
+### Enabling feature for staging and dev.gitlab.org
+
+As a first step in a feature rollout, you should enable the feature on <https://staging.gitlab.com>
+and <https://dev.gitlab.org>.
+
+For example, to enable a feature for 25% of all users, run the following in
+Slack:
+
+```
+/chatops run feature set new_navigation_bar 25 --dev
+/chatops run feature set new_navigation_bar 25 --staging
+```
+
+These two environments have different scopes.
+`dev.gitlab.org` is a production CE environment that has internal GitLab Inc.
+traffic and is used for some development and other related work.
+`staging.gitlab.com` has a smaller subset of GitLab.com database and repositories
+and does not have regular traffic. Staging is an EE instance and can give you
+a (very) rough estimate of how your feature will look/behave on GitLab.com.
+Both of these instances are connected to Sentry so make sure you check the projects
+there for any exceptions while testing your feature after enabling the feature flag.
+
+Once you are confident enough that these environments are in a good state with your
+feature enabled, you can roll out the change to GitLab.com.
+
+## Enabling feature for GitLab.com
+
+Similar to above, to enable a feature for 25% of all users, run the following in
+Slack:
+
+```
+/chatops run feature set new_navigation_bar 25
+```
+
+This will enable the feature for GitLab.com, with `new_navigation_bar` being the
+name of the feature.
+
+If you are not certain what percentages to use, simply use the following steps:
+
+1. 25%
+1. 50%
+1. 75%
+1. 100%
+
+Between every step you'll want to wait a little while and monitor the
+appropriate graphs on <https://dashboards.gitlab.net>. The exact time to wait
+may differ. For some features a few minutes is enough, while for others you may
+want to wait several hours or even days. This is entirely up to you, just make
+sure it is clearly communicated to your team, and the Production team if you
+anticipate any potential problems.
+
+Feature gates can also be actor based, for example a feature could first be
+enabled for only the `gitlab-ce` project. The project is passed by supplying a
+`--project` flag:
+
+```
+/chatops run feature set --project=gitlab-org/gitlab-ce some_feature true
+```
+
+For groups the `--group` flag is available:
+
+```
+/chatops run feature set --group=gitlab-org some_feature true
+```
+
+## Cleaning up
+
+Once the change is deemed stable, submit a new merge request to remove the
+feature flag. This ensures the change is available to all users and self-hosted
+instances. Make sure to add the ~"feature flag" label to this merge request so
+release managers are aware the changes are hidden behind a feature flag. If the
+merge request has to be picked into a stable branch, make sure to also add the
+appropriate "Pick into X" label (e.g. "Pick into XX.X").
+See [the process document](process.md#including-a-feature-behind-feature-flag-in-the-final-release) for further details.
+
+When a feature gate has been removed from the code base, the value still exists
+in the database.
+This can be removed through ChatOps:
+
+```
+/chatops run feature delete some_feature
+```
diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md
new file mode 100644
index 00000000000..98773026122
--- /dev/null
+++ b/doc/development/feature_flags/development.md
@@ -0,0 +1,131 @@
+# Developing with feature flags
+
+In general, it's better to have a group- or user-based gate, and you should prefer
+it over the use of percentage gates. This would make debugging easier, as you
+filter for example logs and errors based on actors too. Furthermore, this allows
+for enabling for the `gitlab-org` or `gitlab-com` group first, while the rest of
+the users aren't impacted.
+
+```ruby
+# Good
+Feature.enabled?(:feature_flag, project)
+
+# Avoid, if possible
+Feature.enabled?(:feature_flag)
+```
+
+To use feature gates based on actors, the model needs to respond to
+`flipper_id`. For example, to enable for the Foo model:
+
+```ruby
+class Foo < ActiveRecord::Base
+  include FeatureGate
+end
+```
+
+Features that are developed and are intended to be merged behind a feature flag
+should not include a changelog entry. The entry should be added in the merge
+request removing the feature flags.
+
+In the rare case that you need the feature flag to be on automatically, use
+`default_enabled: true` when checking:
+
+```ruby
+Feature.enabled?(:feature_flag, project, default_enabled: true)
+```
+
+The [`Project#feature_available?`][project-fa],
+[`Namespace#feature_available?`][namespace-fa] (EE), and
+[`License.feature_available?`][license-fa] (EE) methods all implicitly check for
+a feature flag by the same name as the provided argument.
+
+For example if a feature is license-gated, there's no need to add an additional
+explicit feature flag check since the flag will be checked as part of the
+`License.feature_available?` call. Similarly, there's no need to "clean up" a
+feature flag once the feature has reached general availability.
+
+You'd still want to use an explicit `Feature.enabled?` check if your new feature
+isn't gated by a License or Plan.
+
+[project-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/app/models/project_feature.rb#L63-68
+[namespace-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/ee/namespace.rb#L71-85
+[license-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/license.rb#L293-300
+
+An important side-effect of the implicit feature flags mentioned above is that
+unless the feature is explicitly disabled or limited to a percentage of users,
+the feature flag check will default to `true`.
+
+As an example, if you were to ship the backend half of a feature behind a flag,
+you'd want to explicitly disable that flag until the frontend half is also ready
+to be shipped. [You can do this via Chatops](controls.md):
+
+```
+/chatops run feature set some_feature 0
+```
+
+Note that you can do this at any time, even before the merge request using the
+flag has been merged!
+
+## Feature groups
+
+Starting from GitLab 9.4 we support feature groups via
+[Flipper groups](https://github.com/jnunemaker/flipper/blob/v0.10.2/docs/Gates.md#2-group).
+
+Feature groups must be defined statically in `lib/feature.rb` (in the
+`.register_feature_groups` method), but their implementation can obviously be
+dynamic (querying the DB etc.).
+
+Once defined in `lib/feature.rb`, you will be able to activate a
+feature for a given feature group via the [`feature_group` param of the features API](../../api/features.md#set-or-create-a-feature)
+
+### Frontend
+
+For frontend code you can use the method `push_frontend_feature_flag`, which is
+available to all controllers that inherit from `ApplicationController`. Using
+this method you can expose the state of a feature flag as follows:
+
+```ruby
+before_action do
+  push_frontend_feature_flag(:vim_bindings)
+end
+
+def index
+  # ...
+end
+
+def edit
+  # ...
+end
+```
+
+You can then check for the state of the feature flag in JavaScript as follows:
+
+```javascript
+if ( gon.features.vimBindings ) {
+  // ...
+}
+```
+
+The name of the feature flag in JavaScript will always be camelCased, meaning
+that checking for `gon.features.vim_bindings` would not work.
+
+### Specs
+
+In the test environment `Feature.enabled?` is stubbed to always respond to `true`,
+so we make sure behavior under feature flag doesn't go untested in some non-specific
+contexts.
+
+Whenever a feature flag is present, make sure to test _both_ states of the
+feature flag.
+
+See the
+[testing guide](../testing_guide/best_practices.md#feature-flags-in-tests)
+for information and examples on how to stub feature flags in tests.
+
+### Enabling a feature flag (in development)
+
+In the rails console (`rails c`), enter the following command to enable your feature flag
+
+```ruby
+Feature.enable(:feature_flag_name)
+```
diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md
new file mode 100644
index 00000000000..56872f8c075
--- /dev/null
+++ b/doc/development/feature_flags/index.md
@@ -0,0 +1,12 @@
+# Feature flags in development of GitLab
+
+Feature flags can be used to gradually roll out changes, be
+it a new feature, or a performance improvement. By using feature flags, we can
+comfortably measure the impact of our changes, while still being able to easily
+disable those changes, without having to revert an entire release.
+
+Before using feature flags for GitLab's development, read through the following:
+
+- [Process for using features flags](process.md).
+- [Developing with feature flags documentation](development.md).
+- [Controlling feature flags documentation](controls.md).
diff --git a/doc/development/feature_flags/process.md b/doc/development/feature_flags/process.md
new file mode 100644
index 00000000000..28d6080ce87
--- /dev/null
+++ b/doc/development/feature_flags/process.md
@@ -0,0 +1,131 @@
+# Feature flags process
+
+## Feature flags for user applications
+
+This document only covers feature flags used in the development of GitLab
+itself. Feature flags in deployed user applications can be found at
+[Feature Flags feature documentation](../../user/project/operations/feature_flags.md).
+
+## Feature flags in GitLab development
+
+The following highlights should be considered when deciding if feature flags
+should be leveraged:
+
+- By default, the feature flags should be **off**.
+- Feature flags should remain in the codebase for as short period as possible
+  to reduce the need for feature flag accounting.
+- The person operating with feature flags is responsible for clearly communicating
+  the status of a feature behind the feature flag with responsible stakeholders.
+- Merge requests that make changes hidden behind a feature flag, or remove an
+  existing feature flag because a feature is deemed stable must have the
+  ~"feature flag" label assigned.
+
+One might be tempted to think that feature flags will delay the release of a
+feature by at least one month (= one release). This is not the case. A feature
+flag does not have to stick around for a specific amount of time
+(e.g. at least one release), instead they should stick around until the feature
+is deemed stable. Stable means it works on GitLab.com without causing any
+problems, such as outages.
+
+### When to use feature flags
+
+Starting with GitLab 11.4, developers are required to use feature flags for
+non-trivial changes. Such changes include:
+
+- New features (e.g. a new merge request widget, epics, etc).
+- Complex performance improvements that may require additional testing in
+  production, such as rewriting complex queries.
+- Invasive changes to the user interface, such as a new navigation bar or the
+  removal of a sidebar.
+- Adding support for importing projects from a third-party service.
+
+In all cases, those working on the changes can best decide if a feature flag is
+necessary. For example, changing the color of a button doesn't need a feature
+flag, while changing the navigation bar definitely needs one. In case you are
+uncertain if a feature flag is necessary, simply ask about this in the merge
+request, and those reviewing the changes will likely provide you with an answer.
+
+When using a feature flag for UI elements, make sure to _also_ use a feature
+flag for the underlying backend code, if there is any. This ensures there is
+absolutely no way to use the feature until it is enabled.
+
+### Including a feature behind feature flag in the final release
+
+In order to build a final release and present the feature for self-hosted
+users, the feature flag should be at least defaulted to **on**. If the feature
+is deemed stable and there is confidence that removing the feature flag is safe,
+consider removing the feature flag altogether. Take into consideration that such
+action can make the feature available on GitLab.com shortly after the change to
+the feature flag is merged.
+
+Changing the default state or removing the feature flag has to be done before
+the 22nd of the month, _at least_ 2 working days before, in order for the change
+to be included in the final self-managed release.
+
+In addition to this, the feature behind feature flag should:
+
+- Run in all GitLab.com environments for a sufficient period of time. This time
+  period depends on the feature behind the feature flag, but as a general rule of
+  thumb 2-4 working days should be sufficient to gather enough feedback.
+- The feature should be exposed to all users within the GitLab.com plan during
+  the above mentioned period of time. Exposing the feature to a smaller percentage
+  or only a group of users might not expose a sufficient amount of information to aid in
+  making a decision on feature stability.
+
+While rare, release managers may decide to reject picking or revert a change in
+a stable branch, even when feature flags are used. This might be necessary if
+the changes are deemed problematic, too invasive, or there simply isn't enough
+time to properly measure how the changes behave on GitLab.com.
+
+### The cost of feature flags
+
+When reading the above, one might be tempted to think this procedure is going to
+add a lot of work. Fortunately, this is not the case, and we'll show why. For
+this example we'll specify the cost of the work to do as a number, ranging from
+0 to infinity. The greater the number, the more expensive the work is. The cost
+does _not_ translate to time, it's just a way of measuring complexity of one
+change relative to another.
+
+Let's say we are building a new feature, and we have determined that the cost of
+this is 10. We have also determined that the cost of adding a feature flag check
+in a variety of places is 1. If we do not use feature flags, and our feature
+works as intended, our total cost is 10. This however is the best case scenario.
+Optimizing for the best case scenario is guaranteed to lead to trouble, whereas
+optimizing for the worst case scenario is almost always better.
+
+To illustrate this, let's say our feature causes an outage, and there's no
+immediate way to resolve it. This means we'd have to take the following steps to
+resolve the outage:
+
+1. Revert the release.
+1. Perform any cleanups that might be necessary, depending on the changes that
+   were made.
+1. Revert the commit, ensuring the "master" branch remains stable. This is
+   especially necessary if solving the problem can take days or even weeks.
+1. Pick the revert commit into the appropriate stable branches, ensuring we
+   don't block any future releases until the problem is resolved.
+
+As history has shown, these steps are time consuming, complex, often involve
+many developers, and worst of all: our users will have a bad experience using
+GitLab.com until the problem is resolved.
+
+Now let's say that all of this has an associated cost of 10. This means that in
+the worst case scenario, which we should optimize for, our total cost is now 20.
+
+If we had used a feature flag, things would have been very different. We don't
+need to revert a release, and because feature flags are disabled by default we
+don't need to revert and pick any Git commits. In fact, all we have to do is
+disable the feature, and in the worst case, perform cleanup. Let's say that
+the cost of this is 2. In this case, our best case cost is 11: 10 to build the
+feature, and 1 to add the feature flag. The worst case cost is now 13: 10 to
+build the feature, 1 to add the feature flag, and 2 to disable and clean up.
+
+Here we can see that in the best case scenario the work necessary is only a tiny
+bit more compared to not using a feature flag. Meanwhile, the process of
+reverting our changes has been made significantly and reliably cheaper.
+
+In other words, feature flags do not slow down the development process. Instead,
+they speed up the process as managing incidents now becomes _much_ easier. Once
+continuous deployments are easier to perform, the time to iterate on a feature
+is reduced even further, as you no longer need to wait weeks before your changes
+are available on GitLab.com.
diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md
index 18e4dc2ca0c..475d1c1611e 100644
--- a/doc/development/file_storage.md
+++ b/doc/development/file_storage.md
@@ -33,9 +33,9 @@ they are still not 100% standardized. You can see them below:
 | User avatars                          | yes    | uploads/-/system/user/avatar/:id/:filename                  | `AvatarUploader`       | User       |
 | User snippet attachments              | yes    | uploads/-/system/personal_snippet/:id/:random_hex/:filename | `PersonalFileUploader` | Snippet    |
 | Project avatars                       | yes    | uploads/-/system/project/avatar/:id/:filename               | `AvatarUploader`       | Project    |
-| Issues/MR/Notes Markdown attachments        | yes    | uploads/:project_path_with_namespace/:random_hex/:filename  | `FileUploader`         | Project    |
-| Issues/MR/Notes Legacy Markdown attachments | no     | uploads/-/system/note/attachment/:id/:filename              | `AttachmentUploader`   | Note       |
-| CI Artifacts (CE)                     | yes    | shared/artifacts/:disk_hash[0..1]/:disk_hash[2..3]/:disk_hash/:year_:month_:date/:job_id/:job_artifact_id (:disk_hash is SHA256 digest of project_id) | `JobArtifactUploader`  | Ci::JobArtifact  |
+| Issues/MR/Notes Markdown attachments  | yes    | uploads/:project_path_with_namespace/:random_hex/:filename  | `FileUploader`         | Project    |
+| Issues/MR/Notes Legacy Markdown attachments | no | uploads/-/system/note/attachment/:id/:filename            | `AttachmentUploader`   | Note       |
+| CI Artifacts (CE)                     | yes    | `shared/artifacts/:disk_hash[0..1]/:disk_hash[2..3]/:disk_hash/:year_:month_:date/:job_id/:job_artifact_id` (:disk_hash is SHA256 digest of project_id) | `JobArtifactUploader`  | Ci::JobArtifact  |
 | LFS Objects  (CE)                     | yes    | shared/lfs-objects/:hex/:hex/:object_hash                   | `LfsObjectUploader`    | LfsObject  |
 | External merge request diffs          | yes    | shared/external-diffs/merge_request_diffs/mr-:parent_id/diff-:id | `ExternalDiffUploader` | MergeRequestDiff |
 
@@ -92,8 +92,8 @@ in your uploader, you need to either 1) include `RecordsUpload::Concern` and pre
 
 The `CarrierWave::Uploader#store_dir` is overridden to
 
- - `GitlabUploader.base_dir` + `GitlabUploader.dynamic_segment` when the store is LOCAL
- - `GitlabUploader.dynamic_segment` when the store is REMOTE (the bucket name is used to namespace)
+- `GitlabUploader.base_dir` + `GitlabUploader.dynamic_segment` when the store is LOCAL
+- `GitlabUploader.dynamic_segment` when the store is REMOTE (the bucket name is used to namespace)
 
 ### Using `ObjectStorage::Extension::RecordsUploads`
 
diff --git a/doc/development/filtering_by_label.md b/doc/development/filtering_by_label.md
new file mode 100644
index 00000000000..5e7376db725
--- /dev/null
+++ b/doc/development/filtering_by_label.md
@@ -0,0 +1,166 @@
+# Filtering by label
+
+## Introduction
+
+GitLab has [labels](../user/project/labels.md) that can be assigned to issues,
+merge requests, and epics. Labels on those objects are a many-to-many relation
+through the polymorphic `label_links` table.
+
+To filter these objects by multiple labels - for instance, 'all open
+issues with the label ~Plan and the label ~backend' - we generate a
+query containing a `GROUP BY` clause. In a simple form, this looks like:
+
+```sql
+SELECT
+    issues.*
+FROM
+    issues
+    INNER JOIN label_links ON label_links.target_id = issues.id
+        AND label_links.target_type = 'Issue'
+    INNER JOIN labels ON labels.id = label_links.label_id
+WHERE
+    issues.project_id = 13083
+    AND (issues.state IN ('opened'))
+    AND labels.title IN ('Plan',
+        'backend')
+GROUP BY
+    issues.id
+HAVING (COUNT(DISTINCT labels.title) = 2)
+ORDER BY
+    issues.updated_at DESC,
+    issues.id DESC
+LIMIT 20 OFFSET 0
+```
+
+In particular, note that:
+
+1. We `GROUP BY issues.id` so that we can ...
+1. Use the `HAVING (COUNT(DISTINCT labels.title) = 2)` condition to ensure that
+   all matched issues have both labels.
+
+This is more complicated than is ideal. It makes the query construction more
+prone to errors (such as
+[gitlab-org/gitlab-ce#15557](https://gitlab.com/gitlab-org/gitlab-ce/issues/15557)).
+
+## Attempt A: WHERE EXISTS
+
+### Attempt A1: use multiple subqueries with WHERE EXISTS
+
+In
+[gitlab-org/gitlab-ce#37137](https://gitlab.com/gitlab-org/gitlab-ce/issues/37137)
+and its associated merge request
+[gitlab-org/gitlab-ce!14022](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14022),
+we tried to replace the `GROUP BY` with multiple uses of `WHERE EXISTS`. For the
+example above, this would give:
+
+```sql
+WHERE (EXISTS (
+        SELECT
+            TRUE
+        FROM
+            label_links
+            INNER JOIN labels ON labels.id = label_links.label_id
+        WHERE
+            labels.title = 'Plan'
+            AND target_type = 'Issue'
+            AND target_id = issues.id))
+AND (EXISTS (
+        SELECT
+            TRUE
+        FROM
+            label_links
+            INNER JOIN labels ON labels.id = label_links.label_id
+        WHERE
+            labels.title = 'backend'
+            AND target_type = 'Issue'
+            AND target_id = issues.id))
+```
+
+While this worked without schema changes, and did improve readability somewhat,
+it did not improve query performance.
+
+## Attempt B: Denormalize using an array column
+
+Having [removed MySQL support in GitLab
+12.1](https://about.gitlab.com/2019/06/27/removing-mysql-support/), using
+[Postgres's arrays](https://www.postgresql.org/docs/9.6/arrays.html) became more
+tractable as we didn't have to support two databases. We discussed denormalizing
+the `label_links` table for querying in
+[gitlab-org/gitlab-ce#49651](https://gitlab.com/gitlab-org/gitlab-ce/issues/49651),
+with two options: label IDs and titles.
+
+We can think of both of those as array columns on `issues`, `merge_requests`,
+and `epics`: `issues.label_ids` would be an array column of label IDs, and
+`issues.label_titles` would be an array of label titles.
+
+These array columns can be complemented with [GIN
+indexes](https://www.postgresql.org/docs/9.6/gin-intro.html) to improve
+matching.
+
+### Attempt B1: store label IDs for each object
+
+This has some strong advantages over titles:
+
+1. Unless a label is deleted, or a project is moved, we never need to
+   bulk-update the denormalized column.
+1. It uses less storage than the titles.
+
+Unfortunately, our application design makes this hard. If we were able to query
+just by label ID easily, we wouldn't need the `INNER JOIN labels` in the initial
+query at the start of this document. GitLab allows users to filter by label
+title across projects and even across groups, so a filter by the label ~Plan may
+include labels with multiple distinct IDs.
+
+We do not want users to have to know about the different IDs, which means that
+given this data set:
+
+| Project | ~Plan label ID | ~backend label ID |
+| ------- | -------------- | ----------------- |
+| A       | 11             | 12                |
+| B       | 21             | 22                |
+| C       | 31             | 32                |
+
+We would need something like:
+
+```sql
+WHERE
+    label_ids @> ARRAY[11, 12]
+    OR label_ids @> ARRAY[21, 22]
+    OR label_ids @> ARRAY[31, 32]
+```
+
+This can get even more complicated when we consider that in some cases, there
+might be two ~backend labels - with different IDs - that could apply to the same
+object, so the number of combinations would balloon further.
+
+### Attempt B2: store label titles for each object
+
+From the perspective of updating the labelable object, this is the worst
+option. We have to bulk update the objects when:
+
+1. The objects are moved from one project to another.
+1. The project is moved from one group to another.
+1. The label is renamed.
+1. The label is deleted.
+
+It also uses much more storage. Querying is simple, though:
+
+```sql
+WHERE
+    label_titles @> ARRAY['Plan', 'backend']
+```
+
+And our [tests in
+gitlab-org/gitlab-ce#49651](https://gitlab.com/gitlab-org/gitlab-ce/issues/49651#note_188777346)
+showed that this could be fast.
+
+However, at present, the disadvantages outweigh the advantages.
+
+## Conclusion
+
+We have yet to find a method that is demonstratably better than the current
+method, when considering:
+
+1. Query performance.
+1. Readability.
+1. Ease of maintaining schema consistency.
diff --git a/doc/development/geo.md b/doc/development/geo.md
index 6e59fab34c7..24f16eae9fa 100644
--- a/doc/development/geo.md
+++ b/doc/development/geo.md
@@ -1,4 +1,4 @@
-# Geo (development) **[PREMIUM ONLY]**
+# Geo (development) **(PREMIUM ONLY)**
 
 Geo connects GitLab instances together. One GitLab instance is
 designated as a **primary** node and can be run with multiple
@@ -14,10 +14,10 @@ Geo handles replication for different components:
 - [Database](#database-replication): includes the entire application, except cache and jobs.
 - [Git repositories](#repository-replication): includes both projects and wikis.
 - [Uploaded blobs](#uploads-replication): includes anything from images attached on issues
-to raw logs and assets from CI.
+  to raw logs and assets from CI.
 
 With the exception of the Database replication, on a *secondary* node, everything is coordinated
-by the [Geo Log Cursor](#geo-log-cursor). 
+by the [Geo Log Cursor](#geo-log-cursor).
 
 ### Geo Log Cursor daemon
 
@@ -31,8 +31,8 @@ picks the event up and schedules a `Geo::ProjectSyncWorker` job which will
 use the `Geo::RepositorySyncService` and `Geo::WikiSyncService` classes
 to update the repository and the wiki respectively.
 
-The Geo Log Cursor daemon can operate in High Availability mode automatically. 
-The daemon will try to acquire a lock from time to time and once acquired, it 
+The Geo Log Cursor daemon can operate in High Availability mode automatically.
+The daemon will try to acquire a lock from time to time and once acquired, it
 will behave as the *active* daemon.
 
 Any additional running daemons on the same node, will be in standby
@@ -164,20 +164,20 @@ The Git Push Proxy exists as a functionality built inside the `gitlab-shell` com
 It is active on a **secondary** node only. It allows the user that has cloned a repository
 from the secondary node to push to the same URL.
 
-Git `push` requests directed to a **secondary** node will be sent over to the **primary** node, 
+Git `push` requests directed to a **secondary** node will be sent over to the **primary** node,
 while `pull` requests will continue to be served by the **secondary** node for maximum efficiency.
 
 HTTPS and SSH requests are handled differently:
 
 - With HTTPS, we will give the user a `HTTP 302 Redirect` pointing to the project on the **primary** node.
-The git client is wise enough to understand that status code and process the redirection.
+  The git client is wise enough to understand that status code and process the redirection.
 - With SSH, because there is no equivalent way to perform a redirect, we have to proxy the request.
-This is done inside [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell), by first translating the request 
-to the HTTP protocol, and then proxying it to the **primary** node.
+  This is done inside [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell), by first translating the request
+  to the HTTP protocol, and then proxying it to the **primary** node.
 
-The [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell) daemon knows when to proxy based on the response 
-from `/api/v4/allowed`. A special `HTTP 300` status code is returned and we execute a "custom action", 
-specified in the response body. The response contains additional data that allows the proxied `push` operation 
+The [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell) daemon knows when to proxy based on the response
+from `/api/v4/allowed`. A special `HTTP 300` status code is returned and we execute a "custom action",
+specified in the response body. The response contains additional data that allows the proxied `push` operation
 to happen on the **primary** node.
 
 ## Using the Tracking Database
@@ -229,17 +229,17 @@ named `gitlab_secondary`. This configuration exists within the database's user
 context only. To access the `gitlab_secondary`, GitLab needs to use the
 same database user that had previously been configured.
 
-The Geo Tracking Database accesses the readonly database replica via FDW as a regular user, 
-limited by its own restrictions. The credentials are configured as a 
-`USER MAPPING` associated with the `SERVER` mapped previously 
+The Geo Tracking Database accesses the readonly database replica via FDW as a regular user,
+limited by its own restrictions. The credentials are configured as a
+`USER MAPPING` associated with the `SERVER` mapped previously
 (`gitlab_secondary`).
 
 FDW configuration and credentials definition are managed automatically by the
-Omnibus GitLab `gitlab-ctl reconfigure` command. 
+Omnibus GitLab `gitlab-ctl reconfigure` command.
 
 #### Refeshing the Foreign Tables
 
-Whenever a new Geo node is configured or the database schema changes on the 
+Whenever a new Geo node is configured or the database schema changes on the
 **primary** node, you must refresh the foreign tables on the **secondary** node
 by running the following:
 
@@ -279,11 +279,11 @@ on the Tracking Database:
 SELECT project_registry.*
   FROM project_registry
   JOIN gitlab_secondary.projects
-    ON (project_registry.project_id = gitlab_secondary.projects.id 
+    ON (project_registry.project_id = gitlab_secondary.projects.id
    AND gitlab_secondary.projects.archived IS FALSE)
 ```
 
-At the ActiveRecord level, we have additional Models that represent the 
+At the ActiveRecord level, we have additional Models that represent the
 foreign tables. They must be mapped in a slightly different way, and they are read-only.
 
 Check the existing FDW models in `ee/app/models/geo/fdw` for reference.
@@ -341,9 +341,9 @@ not used, so sessions etc. aren't shared between nodes.
 GitLab can optionally use Object Storage to store data it would
 otherwise store on disk. These things can be:
 
- - LFS Objects
- - CI Job Artifacts
- - Uploads
+- LFS Objects
+- CI Job Artifacts
+- Uploads
 
 Objects that are stored in object storage, are not handled by Geo. Geo
 ignores items in object storage. Either:
@@ -412,15 +412,15 @@ The Geo **primary** stores events in the `geo_event_log` table. Each
 entry in the log contains a specific type of event. These type of
 events include:
 
- - Repository Deleted event
- - Repository Renamed event
- - Repositories Changed event
- - Repository Created event
- - Hashed Storage Migrated event
- - Lfs Object Deleted event
- - Hashed Storage Attachments event
- - Job Artifact Deleted event
- - Upload Deleted event
+- Repository Deleted event
+- Repository Renamed event
+- Repositories Changed event
+- Repository Created event
+- Hashed Storage Migrated event
+- Lfs Object Deleted event
+- Hashed Storage Attachments event
+- Job Artifact Deleted event
+- Upload Deleted event
 
 ### Geo Log Cursor
 
@@ -526,4 +526,4 @@ old method:
 
 - Replication is synchronous and we preserve the order of events.
 - Replication of the events happen at the same time as the changes in the
-   database.
+  database.
diff --git a/doc/development/git_object_deduplication.md b/doc/development/git_object_deduplication.md
index b512d7611d3..5ce59891afa 100644
--- a/doc/development/git_object_deduplication.md
+++ b/doc/development/git_object_deduplication.md
@@ -79,11 +79,11 @@ at the Rails application level in SQL.
 In conclusion, we need three things for effective object deduplication
 across a collection of GitLab project repositories at the Git level:
 
-1.  A pool repository must exist.
-2.  The participating project repositories must be linked to the pool
-    repository via their respective `objects/info/alternates` files.
-3.  The pool repository must contain Git object data common to the
-    participating project repositories.
+1. A pool repository must exist.
+1. The participating project repositories must be linked to the pool
+   repository via their respective `objects/info/alternates` files.
+1. The pool repository must contain Git object data common to the
+   participating project repositories.
 
 ### Deduplication factor
 
@@ -105,71 +105,71 @@ With pool repositories we made a fresh start. These live in their own
 `pool_repositories` SQL table. The relations between these two tables
 are as follows:
 
--   a `Project` belongs to at most one `PoolRepository`
-    (`project.pool_repository`)
--   as an automatic consequence of the above, a `PoolRepository` has
-    many `Project`s
--   a `PoolRepository` has exactly one "source `Project`"
-    (`pool.source_project`)
+- a `Project` belongs to at most one `PoolRepository`
+  (`project.pool_repository`)
+- as an automatic consequence of the above, a `PoolRepository` has
+  many `Project`s
+- a `PoolRepository` has exactly one "source `Project`"
+  (`pool.source_project`)
 
 > TODO Fix invalid SQL data for pools created prior to GitLab 11.11
-> https://gitlab.com/gitlab-org/gitaly/issues/1653.
+> <https://gitlab.com/gitlab-org/gitaly/issues/1653>.
 
 ### Assumptions
 
--   All repositories in a pool must use [hashed
-    storage](../administration/repository_storage_types.md). This is so
-    that we don't have to ever worry about updating paths in
-    `object/info/alternates` files.
--   All repositories in a pool must be on the same Gitaly storage shard.
-    The Git alternates mechanism relies on direct disk access across
-    multiple repositories, and we can only assume direct disk access to
-    be possible within a Gitaly storage shard.
--   The only two ways to remove a member project from a pool are (1) to
-    delete the project or (2) to move the project to another Gitaly
-    storage shard.
+- All repositories in a pool must use [hashed
+  storage](../administration/repository_storage_types.md). This is so
+  that we don't have to ever worry about updating paths in
+  `object/info/alternates` files.
+- All repositories in a pool must be on the same Gitaly storage shard.
+  The Git alternates mechanism relies on direct disk access across
+  multiple repositories, and we can only assume direct disk access to
+  be possible within a Gitaly storage shard.
+- The only two ways to remove a member project from a pool are (1) to
+  delete the project or (2) to move the project to another Gitaly
+  storage shard.
 
 ### Creating pools and pool memberships
 
--   When a pool gets created, it must have a source project. The initial
-    contents of the pool repository are a Git clone of the source
-    project repository.
--   The occasion for creating a pool is when an existing eligible
-    (public, hashed storage, non-forked) GitLab project gets forked and
-    this project does not belong to a pool repository yet. The fork
-    parent project becomes the source project of the new pool, and both
-    the fork parent and the fork child project become members of the new
-    pool.
--   Once project A has become the source project of a pool, all future
-    eligible forks of A will become pool members.
--   If the fork source is itself a fork, the resulting repository will
-    neither join the repository nor will a new pool repository be
-    seeded.
-
-    eg:
-
-    Suppose fork A is part of a pool repository, any forks created off
-    of fork A *will not* be a part of the pool repository that fork A is
-    a part of.
-
-    Suppose B is a fork of A, and A does not belong to an object pool.
-    Now C gets created as a fork of B. C will not be part of a pool
-    repository.
+- When a pool gets created, it must have a source project. The initial
+  contents of the pool repository are a Git clone of the source
+  project repository.
+- The occasion for creating a pool is when an existing eligible
+  (public, hashed storage, non-forked) GitLab project gets forked and
+  this project does not belong to a pool repository yet. The fork
+  parent project becomes the source project of the new pool, and both
+  the fork parent and the fork child project become members of the new
+  pool.
+- Once project A has become the source project of a pool, all future
+  eligible forks of A will become pool members.
+- If the fork source is itself a fork, the resulting repository will
+  neither join the repository nor will a new pool repository be
+  seeded.
+
+  eg:
+
+  Suppose fork A is part of a pool repository, any forks created off
+  of fork A *will not* be a part of the pool repository that fork A is
+  a part of.
+
+  Suppose B is a fork of A, and A does not belong to an object pool.
+  Now C gets created as a fork of B. C will not be part of a pool
+  repository.
 
 > TODO should forks of forks be deduplicated?
-> https://gitlab.com/gitlab-org/gitaly/issues/1532
+> <https://gitlab.com/gitlab-org/gitaly/issues/1532>
 
 ### Consequences
 
--   If a normal Project participating in a pool gets moved to another
-    Gitaly storage shard, its "belongs to PoolRepository" relation will
-    be broken. Because of the way moving repositories between shard is
-    implemented, we will automatically get a fresh self-contained copy
-    of the project's repository on the new storage shard.
--   If the source project of a pool gets moved to another Gitaly storage
-    shard or is deleted the "source project" relation is not broken.
-    However, as of GitLab 12.0 a pool will not fetch from a source
-    unless the source is on the same Gitaly shard.
+- If a normal Project participating in a pool gets moved to another
+  Gitaly storage shard, its "belongs to PoolRepository" relation will
+  be broken. Because of the way moving repositories between shard is
+  implemented, we will automatically get a fresh self-contained copy
+  of the project's repository on the new storage shard.
+- If the source project of a pool gets moved to another Gitaly storage
+  shard or is deleted the "source project" relation is not broken.
+  However, as of GitLab 12.0 a pool will not fetch from a source
+  unless the source is on the same Gitaly shard.
 
 ## Consistency between the SQL pool relation and Gitaly
 
@@ -215,4 +215,4 @@ the secondary, at which stage Git objects will get deduplicated.
 
 > TODO How do we handle the edge case where at the time the Geo
 > secondary tries to create the pool repository, the source project does
-> not exist? https://gitlab.com/gitlab-org/gitaly/issues/1533
+> not exist? <https://gitlab.com/gitlab-org/gitaly/issues/1533>
diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md
index c8beb808a54..2ade59b76ed 100644
--- a/doc/development/gitaly.md
+++ b/doc/development/gitaly.md
@@ -3,6 +3,16 @@
 [Gitaly](https://gitlab.com/gitlab-org/gitaly) is a high-level Git RPC service used by GitLab CE/EE,
 Workhorse and GitLab-Shell.
 
+## Deep Dive
+
+In May 2019, Bob Van Landuyt hosted a [Deep Dive] on GitLab's [Gitaly project] and how to contribute to it as a Ruby developer, to share his domain specific knowledge with anyone who may work in this part of the code base in the future. You can find the [recording on YouTube], and the slides on [Google Slides] and in [PDF]. Everything covered in this deep dive was accurate as of GitLab 11.11, and while specific details may have changed since then, it should still serve as a good introduction.
+
+[Deep Dive]: https://gitlab.com/gitlab-org/create-stage/issues/1
+[Gitaly project]: https://gitlab.com/gitlab-org/gitaly
+[recording on YouTube]: https://www.youtube.com/watch?v=BmlEWFS8ORo
+[Google Slides]: https://docs.google.com/presentation/d/1VgRbiYih9ODhcPnL8dS0W98EwFYpJ7GXMPpX-1TM6YE/edit
+[PDF]: https://gitlab.com/gitlab-org/create-stage/uploads/a4fdb1026278bda5c1c5bb574379cf80/Create_Deep_Dive__Gitaly_for_Create_Ruby_Devs.pdf
+
 ## Beginner's guide
 
 Start by reading the gitaly repository's
@@ -78,12 +88,12 @@ Until GitLab has eliminated most of these inefficiencies or the use of
 NFS is discontinued for Git data, Rugged implementations of some of the
 most commonly-used RPCs can be enabled via feature flags:
 
-* `rugged_find_commit`
-* `rugged_get_tree_entries`
-* `rugged_tree_entry`
-* `rugged_commit_is_ancestor`
-* `rugged_commit_tree_entry`
-* `rugged_list_commits_by_oid`
+- `rugged_find_commit`
+- `rugged_get_tree_entries`
+- `rugged_tree_entry`
+- `rugged_commit_is_ancestor`
+- `rugged_commit_tree_entry`
+- `rugged_list_commits_by_oid`
 
 A convenience Rake task can be used to enable or disable these flags
 all together. To enable:
@@ -227,24 +237,23 @@ Here are the steps to gate a new feature in Gitaly behind a feature flag.
 1. Create prometheus metrics:
 
    ```go
-   var	findAllTagsRequests = prometheus.NewCounterVec(
-   		prometheus.CounterOpts{
-   			Name: "gitaly_find_all_tags_requests_total",
-   			Help: "Counter of go vs ruby implementation of FindAllTags",
-   		},
-   		[]string{"implementation"},
-   	)
+   var findAllTagsRequests = prometheus.NewCounterVec(
+     prometheus.CounterOpts{
+       Name: "gitaly_find_all_tags_requests_total",
+       Help: "Counter of go vs ruby implementation of FindAllTags",
+     },
+     []string{"implementation"},
    )
 
    func init() {
-   	prometheus.Register(findAllTagsRequests)
+     prometheus.Register(findAllTagsRequests)
    }
 
    if featureflag.IsEnabled(ctx, findAllTagsFeatureFlag) {
-   	findAllTagsRequests.WithLabelValues("go").Inc()
+     findAllTagsRequests.WithLabelValues("go").Inc()
      // go implementation
    } else {
-   	findAllTagsRequests.WithLabelValues("ruby").Inc()
+     findAllTagsRequests.WithLabelValues("ruby").Inc()
      // ruby implementation
    }
    ```
diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md
index 4dad8815fcb..83444093f9c 100644
--- a/doc/development/go_guide/index.md
+++ b/doc/development/go_guide/index.md
@@ -41,7 +41,7 @@ of possible security breaches in our code:
 
 Remember to run
 [SAST](../../user/application_security/sast/index.md)
-**[ULTIMATE]** on your project (or at least the [gosec
+**(ULTIMATE)** on your project (or at least the [gosec
 analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/gosec)),
 and to follow our [Security
 requirements](../code_review.md#security-requirements).
@@ -82,7 +82,7 @@ go lint:
   image: golang:1.11
   script:
     - go get -u golang.org/x/lint/golint
-    - golint -set_exit_status
+    - golint -set_exit_status $(go list ./... | grep -v "vendor/")
 ```
 
 Once [recursive includes](https://gitlab.com/gitlab-org/gitlab-ce/issues/56836)
@@ -95,9 +95,9 @@ Dependencies should be kept to the minimum. The introduction of a new
 dependency should be argued in the merge request, as per our [Approval
 Guidelines](../code_review.md#approval-guidelines). Both [License
 Management](../../user/project/merge_requests/license_management.md)
-**[ULTIMATE]** and [Dependency
+**(ULTIMATE)** and [Dependency
 Scanning](../../user/application_security/dependency_scanning/index.md)
-**[ULTIMATE]** should be activated on all projects to ensure new dependencies
+**(ULTIMATE)** should be activated on all projects to ensure new dependencies
 security status and license compatibility.
 
 ### Modules
@@ -107,6 +107,32 @@ Modules](https://github.com/golang/go/wiki/Modules). It provides a way to
 define and lock dependencies for reproducible builds. It should be used
 whenever possible.
 
+When Go Modules are in use, there should not be a `vendor/` directory. Instead,
+Go will automatically download dependencies when they are needed to build the
+project. This is in line with how dependencies are handled with Bundler in Ruby
+projects, and makes merge requests easier to review.
+
+In some cases, such as building a Go project for it to act as a dependency of a
+CI run for another project, removing the `vendor/` directory means the code must
+be downloaded repeatedly, which can lead to intermittent problems due to rate
+limiting or network failures. In these circumstances, you should cache the
+downloaded code between runs with a `.gitlab-ci.yml` snippet like this:
+
+```yaml
+.go-cache:
+  variables:
+    GOPATH: $CI_PROJECT_DIR/.go
+  before_script:
+    - mkdir -p .go
+  cache:
+    paths:
+      - .go/pkg/mod/
+
+test:
+  extends: .go-cache
+  # ...
+```
+
 There was a [bug on modules
 checksums](https://github.com/golang/go/issues/29278) in Go < v1.11.4, so make
 sure to use at least this version to avoid `checksum mismatch` errors.
@@ -129,17 +155,89 @@ deploy a new pod, migrating the data automatically.
 
 ## Testing
 
+### Testing frameworks
+
 We should not use any specific library or framework for testing, as the
 [standard library](https://golang.org/pkg/) provides already everything to get
-started. For example, some external dependencies might be worth considering in
-case we decide to use a specific library or framework:
+started. If there is a need for more sophisticated testing tools, the following
+external dependencies might be worth considering in case we decide to use a specific
+library or framework:
 
 - [Testify](https://github.com/stretchr/testify)
 - [httpexpect](https://github.com/gavv/httpexpect)
 
+### Subtests
+
 Use [subtests](https://blog.golang.org/subtests) whenever possible to improve
 code readability and test output.
 
+### Better output in tests
+
+When comparing expected and actual values in tests, use
+[testify/require.Equal](https://godoc.org/github.com/stretchr/testify/require#Equal),
+[testify/require.EqualError](https://godoc.org/github.com/stretchr/testify/require#EqualError),
+[testify/require.EqualValues](https://godoc.org/github.com/stretchr/testify/require#EqualValues),
+and others to improve readability when comparing structs, errors,
+large portions of text, or JSON documents:
+
+```go
+type TestData struct {
+    // ...
+}
+
+func FuncUnderTest() TestData {
+    // ...
+}
+
+func Test(t *testing.T) {
+    t.Run("FuncUnderTest", func(t *testing.T) {
+        want := TestData{}
+        got := FuncUnderTest()
+
+        require.Equal(t, want, got) // note that expected value comes first, then comes the actual one ("diff" semantics)
+    })
+}
+```
+
+### Table-Driven Tests
+
+Using [Table-Driven Tests](https://github.com/golang/go/wiki/TableDrivenTests)
+is generally good practice when you have multiple entries of
+inputs/outputs for the same function. Below are some guidelines one can
+follow when writing table-driven test. These guidelines are mostly
+extracted from Go standard library source code. Keep in mind it's OK not
+to follow these guidelines when it makes sense.
+
+#### Defining test cases
+
+Each table entry is a complete test case with inputs and expected
+results, and sometimes with additional information such as a test name
+to make the test output easily readable.
+
+- [Define a slice of anonymous struct](https://github.com/golang/go/blob/50bd1c4d4eb4fac8ddeb5f063c099daccfb71b26/src/encoding/csv/reader_test.go#L16)
+  inside of the test.
+- [Define a slice of anonymous struct](https://github.com/golang/go/blob/55d31e16c12c38d36811bdee65ac1f7772148250/src/cmd/go/internal/module/module_test.go#L9-L66)
+  outside of the test.
+- [Named structs](https://github.com/golang/go/blob/2e0cd2aef5924e48e1ceb74e3d52e76c56dd34cc/src/cmd/go/internal/modfetch/coderepo_test.go#L54-L69)
+  for code reuse.
+- [Using `map[string]struct{}`](https://github.com/golang/go/blob/6d5caf38e37bf9aeba3291f1f0b0081f934b1187/src/cmd/trace/annotations_test.go#L180-L235).
+
+#### Contents of the test case
+
+- Ideally, each test case should have a field with a unique identifier
+  to use for naming subtests. In the Go standard library, this is commonly the
+  `name string` field.
+- Use `want`/`expect`/`actual` when you are specifcing something in the
+  test case that will be used for assertion.
+
+#### Variable names
+
+- Each table-driven test map/slice of struct can be named `tests`.
+- When looping through `tests` the anonymous struct can be referred
+  to as `tt` or `tc`.
+- The description of the test can be referred to as
+  `name`/`testName`/`tn`.
+
 ### Benchmarks
 
 Programs handling a lot of IO or complex operations should always include
diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md
index 1b9ebb50c29..941eea2609e 100644
--- a/doc/development/gotchas.md
+++ b/doc/development/gotchas.md
@@ -53,7 +53,7 @@ When run, this spec doesn't do what we might expect:
      (compared using ==)
 ```
 
-That's because FactoryBot sequences are not reseted for each example.
+This is because FactoryBot sequences are not reset for each example.
 
 Please remember that sequence-generated values exist only to avoid having to
 explicitly set attributes that have a uniqueness constraint when using a factory.
@@ -101,10 +101,10 @@ end
   in a prepended module, which is very likely the case in EE. We could see
   error like this:
 
-    ```
-    1.1) Failure/Error: expect_any_instance_of(ApplicationSetting).to receive_messages(messages)
-         Using `any_instance` to stub a method (elasticsearch_indexing) that has been defined on a prepended module (EE::ApplicationSetting) is not supported.
-    ```
+  ```
+  1.1) Failure/Error: expect_any_instance_of(ApplicationSetting).to receive_messages(messages)
+       Using `any_instance` to stub a method (elasticsearch_indexing) that has been defined on a prepended module (EE::ApplicationSetting) is not supported.
+  ```
 
 ### Alternative: `expect_next_instance_of`
 
diff --git a/doc/development/hash_indexes.md b/doc/development/hash_indexes.md
index e6c1b3590b1..417ea18e22f 100644
--- a/doc/development/hash_indexes.md
+++ b/doc/development/hash_indexes.md
@@ -1,6 +1,6 @@
 # Hash Indexes
 
-Both PostgreSQL and MySQL support hash indexes besides the regular btree
+PostgreSQL supports hash indexes besides the regular btree
 indexes. Hash indexes however are to be avoided at all costs. While they may
 _sometimes_ provide better performance the cost of rehashing can be very high.
 More importantly: at least until PostgreSQL 10.0 hash indexes are not
diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md
index 9fb8ea542d9..141f5a8d6d9 100644
--- a/doc/development/i18n/externalization.md
+++ b/doc/development/i18n/externalization.md
@@ -21,18 +21,18 @@ The following tools are used:
 1. [`gettext_i18n_rails`](https://github.com/grosser/gettext_i18n_rails): this
    gem allow us to translate content from models, views and controllers. Also
    it gives us access to the following raketasks:
-    - `rake gettext:find`: Parses almost all the files from the
-      Rails application looking for content that has been marked for
-      translation. Finally, it updates the PO files with the new content that
-      it has found.
-    - `rake gettext:pack`: Processes the PO files and generates the
-      MO files that are binary and are finally used by the application.
+   - `rake gettext:find`: Parses almost all the files from the
+     Rails application looking for content that has been marked for
+     translation. Finally, it updates the PO files with the new content that
+     it has found.
+   - `rake gettext:pack`: Processes the PO files and generates the
+     MO files that are binary and are finally used by the application.
 
 1. [`gettext_i18n_rails_js`](https://github.com/webhippie/gettext_i18n_rails_js):
    this gem is useful to make the translations available in JavaScript. It
    provides the following raketask:
-    - `rake gettext:po_to_json`: Reads the contents from the PO files and
-      generates JSON files containing all the available translations.
+   - `rake gettext:po_to_json`: Reads the contents from the PO files and
+     generates JSON files containing all the available translations.
 
 1. PO editor: there are multiple applications that can help us to work with PO
    files, a good option is [Poedit](https://poedit.net/download) which is
@@ -77,6 +77,9 @@ Or:
 hello = _("Hello world!")
 ```
 
+NOTE: **Note:** Messages in the API (`lib/api/` or `app/graphql`) do
+not need to be externalised.
+
 ### HAML files
 
 Given the following content in HAML:
@@ -132,64 +135,65 @@ There is also and alternative method to [translate messages from validation erro
 ### Interpolation
 
 Placeholders in translated text should match the code style of the respective source file.
-For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript.
+For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. Make sure to [avoid splitting sentences when adding links](#avoid-splitting-sentences-when-adding-links).
 
 - In Ruby/HAML:
 
-    ```ruby
-    _("Hello %{name}") % { name: 'Joe' } => 'Hello Joe'
-    ```
+  ```ruby
+  _("Hello %{name}") % { name: 'Joe' } => 'Hello Joe'
+  ```
 
 - In JavaScript:
 
-    ```js
-    import { __, sprintf } from '~/locale';
+  ```js
+  import { __, sprintf } from '~/locale';
 
-    sprintf(__('Hello %{username}'), { username: 'Joe' }); // => 'Hello Joe'
-    ```
+  sprintf(__('Hello %{username}'), { username: 'Joe' }); // => 'Hello Joe'
+  ```
 
-    By default, `sprintf` escapes the placeholder values.
-    If you want to take care of that yourself, you can pass `false` as third argument.
+  By default, `sprintf` escapes the placeholder values.
+  If you want to take care of that yourself, you can pass `false` as third argument.
 
-    ```js
-    import { __, sprintf } from '~/locale';
+  ```js
+  import { __, sprintf } from '~/locale';
 
-    sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }); // => 'This is &lt;strong&gt;bold&lt;/strong&gt;'
-    sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }, false); // => 'This is <strong>bold</strong>'
-    ```
+  sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }); // => 'This is &lt;strong&gt;bold&lt;/strong&gt;'
+  sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }, false); // => 'This is <strong>bold</strong>'
+  ```
 
 ### Plurals
 
 - In Ruby/HAML:
 
-    ```ruby
-    n_('Apple', 'Apples', 3)
-    # => 'Apples'
-    ```
+  ```ruby
+  n_('Apple', 'Apples', 3)
+  # => 'Apples'
+  ```
+
+  Using interpolation:
 
-    Using interpolation:
-    ```ruby
-    n_("There is a mouse.", "There are %d mice.", size) % size
-    # => When size == 1: 'There is a mouse.'
-    # => When size == 2: 'There are 2 mice.'
-    ```
+  ```ruby
+  n_("There is a mouse.", "There are %d mice.", size) % size
+  # => When size == 1: 'There is a mouse.'
+  # => When size == 2: 'There are 2 mice.'
+  ```
 
-    Avoid using `%d` or count variables in singular strings. This allows more natural translation in some languages.
+  Avoid using `%d` or count variables in singular strings. This allows more natural translation in some languages.
 
 - In JavaScript:
 
-    ```js
-    n__('Apple', 'Apples', 3)
-    // => 'Apples'
-    ```
+  ```js
+  n__('Apple', 'Apples', 3)
+  // => 'Apples'
+  ```
 
-    Using interpolation:
+  Using interpolation:
 
-    ```js
-    n__('Last day', 'Last %d days', x)
-    // => When x == 1: 'Last day'
-    // => When x == 2: 'Last 2 days'
-    ```
+  ```js
+  n__('Last day', 'Last %d days', x)
+  // => When x == 1: 'Last day'
+  // => When x == 2: 'Last 2 days'
+  ```
 
 ### Namespaces
 
@@ -199,17 +203,17 @@ Namespaces should be PascalCase.
 
 - In Ruby/HAML:
 
-    ```ruby
-    s_('OpenedNDaysAgo|Opened')
-    ```
+  ```ruby
+  s_('OpenedNDaysAgo|Opened')
+  ```
 
-    In case the translation is not found it will return `Opened`.
+  In case the translation is not found it will return `Opened`.
 
 - In JavaScript:
 
-    ```js
-    s__('OpenedNDaysAgo|Opened')
-    ```
+  ```js
+  s__('OpenedNDaysAgo|Opened')
+  ```
 
 Note: The namespace should be removed from the translation. See the [translation
 guidelines for more details](translation.md#namespaced-strings).
@@ -232,12 +236,12 @@ This makes use of [`Intl.DateTimeFormat`].
 - In Ruby/HAML, we have two ways of adding format to dates and times:
 
   1. **Through the `l` helper**, i.e. `l(active_session.created_at, format: :short)`. We have some predefined formats for
-  [dates](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L54) and [times](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L261).
-  If you need to add a new format, because other parts of the code could benefit from it,
-  you'll need to add it to [en.yml](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/locales/en.yml) file.
+     [dates](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L54) and [times](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L261).
+     If you need to add a new format, because other parts of the code could benefit from it,
+     you'll need to add it to [en.yml](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/locales/en.yml) file.
   1. **Through `strftime`**, i.e. `milestone.start_date.strftime('%b %-d')`. We use `strftime` in case none of the formats
-  defined on [en.yml](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/locales/en.yml) matches the date/time
-  specifications we need, and if there is no need to add it as a new format because is very particular (i.e. it's only used in a single view).
+     defined on [en.yml](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/locales/en.yml) matches the date/time
+     specifications we need, and if there is no need to add it as a new format because is very particular (i.e. it's only used in a single view).
 
 ## Best practices
 
@@ -264,20 +268,41 @@ should be externalized as follows:
 
 This also applies when using links in between translated sentences, otherwise these texts are not translatable in certain languages.
 
-Instead of:
+- In Ruby/HAML, instead of:
 
-```haml
-- zones_link = link_to(s_('ClusterIntegration|zones'), 'https://cloud.google.com/compute/docs/regions-zones/regions-zones', target: '_blank', rel: 'noopener noreferrer')
-= s_('ClusterIntegration|Learn more about %{zones_link}').html_safe % { zones_link: zones_link }
-```
+  ```haml
+  - zones_link = link_to(s_('ClusterIntegration|zones'), 'https://cloud.google.com/compute/docs/regions-zones/regions-zones', target: '_blank', rel: 'noopener noreferrer')
+  = s_('ClusterIntegration|Learn more about %{zones_link}').html_safe % { zones_link: zones_link }
+  ```
 
-Set the link starting and ending HTML fragments as variables like so:
+  Set the link starting and ending HTML fragments as variables like so:
 
-```haml
-- zones_link_url = 'https://cloud.google.com/compute/docs/regions-zones/regions-zones'
-- zones_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: zones_link_url }
-= s_('ClusterIntegration|Learn more about %{zones_link_start}zones%{zones_link_end}').html_safe % { zones_link_start: zones_link_start, zones_link_end: '</a>'.html_safe }
-```
+  ```haml
+  - zones_link_url = 'https://cloud.google.com/compute/docs/regions-zones/regions-zones'
+  - zones_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: zones_link_url }
+  = s_('ClusterIntegration|Learn more about %{zones_link_start}zones%{zones_link_end}').html_safe % { zones_link_start: zones_link_start, zones_link_end: '</a>'.html_safe }
+  ```
+
+- In JavaScript, instead of:
+
+  ```js
+  {{
+      sprintf(s__("ClusterIntegration|Learn more about %{link}"), {
+          link: '<a href="https://cloud.google.com/compute/docs/regions-zones/regions-zones" target="_blank" rel="noopener noreferrer">zones</a>'
+      })
+  }}
+  ```
+
+  Set the link starting and ending HTML fragments as variables like so:
+
+  ```js
+  {{
+      sprintf(s__("ClusterIntegration|Learn more about %{linkStart}zones%{linkEnd}"), {
+          linkStart: '<a href="https://cloud.google.com/compute/docs/regions-zones/regions-zones" target="_blank" rel="noopener noreferrer">'
+          linkEnd: '</a>',
+      })
+  }}
+  ```
 
 The reasoning behind this is that in some languages words change depending on context. For example in Japanese は is added to the subject of a sentence and を to the object. This is impossible to translate correctly if we extract individual words from the sentence.
 
@@ -350,29 +375,29 @@ Let's suppose you want to add translations for a new language, let's say French.
 
 1. The first step is to register the new language in `lib/gitlab/i18n.rb`:
 
-    ```ruby
-    ...
-    AVAILABLE_LANGUAGES = {
-      ...,
-      'fr' => 'Français'
-    }.freeze
-    ...
-    ```
+   ```ruby
+   ...
+   AVAILABLE_LANGUAGES = {
+     ...,
+     'fr' => 'Français'
+   }.freeze
+   ...
+   ```
 
 1. Next, you need to add the language:
 
-    ```sh
-    bin/rake gettext:add_language[fr]
-    ```
+   ```sh
+   bin/rake gettext:add_language[fr]
+   ```
 
-    If you want to add a new language for a specific region, the command is similar,
-    you just need to separate the region with an underscore (`_`). For example:
+   If you want to add a new language for a specific region, the command is similar,
+   you just need to separate the region with an underscore (`_`). For example:
 
-    ```sh
-    bin/rake gettext:add_language[en_GB]
-    ```
+   ```sh
+   bin/rake gettext:add_language[en_GB]
+   ```
 
-    Please note that you need to specify the region part in capitals.
+   Please note that you need to specify the region part in capitals.
 
 1. Now that the language is added, a new directory has been created under the
    path: `locale/fr/`. You can now start using your PO editor to edit the PO file
@@ -382,9 +407,9 @@ Let's suppose you want to add translations for a new language, let's say French.
    in order to generate the binary MO files and finally update the JSON files
    containing the translations:
 
-    ```sh
-    bin/rake gettext:compile
-    ```
+   ```sh
+   bin/rake gettext:compile
+   ```
 
 1. In order to see the translated content we need to change our preferred language
    which can be found under the user's **Settings** (`/profile`).
@@ -392,7 +417,7 @@ Let's suppose you want to add translations for a new language, let's say French.
 1. After checking that the changes are ok, you can proceed to commit the new files.
    For example:
 
-    ```sh
-    git add locale/fr/ app/assets/javascripts/locale/fr/
-    git commit -m "Add French translations for Cycle Analytics page"
-    ```
+   ```sh
+   git add locale/fr/ app/assets/javascripts/locale/fr/
+   git commit -m "Add French translations for Cycle Analytics page"
+   ```
diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md
index 35c5b155594..492e3d48164 100644
--- a/doc/development/i18n/proofreader.md
+++ b/doc/development/i18n/proofreader.md
@@ -80,6 +80,7 @@ are very appreciative of the work done by translators and proofreaders!
 - Russian
   - Nikita Grylov - [GitLab](https://gitlab.com/nixel2007), [Crowdin](https://crowdin.com/profile/nixel2007)
   - Alexy Lustin - [GitLab](https://gitlab.com/allustin), [Crowdin](https://crowdin.com/profile/lustin)
+  - Mark Minakou - [GitLab](https://gitlab.com/sandzhaj), [Crowdin](https://crowdin.com/profile/sandzhaj)
   - NickVolynkin - [Crowdin](https://crowdin.com/profile/NickVolynkin)
 - Serbian (Cyrillic)
   - Proofreaders needed.
@@ -106,32 +107,31 @@ are very appreciative of the work done by translators and proofreaders!
 1. Contribute translations to GitLab. See instructions for
    [translating GitLab](translation.md).
 
-    Translating GitLab is a community effort that requires team work and
-    attention to detail. Proofreaders play an important role helping new
-    contributors, and ensuring the consistency and quality of translations.
-    Your conduct and contributions as a translator should reflect this before
-    requesting to be a proofreader.
+   Translating GitLab is a community effort that requires team work and
+   attention to detail. Proofreaders play an important role helping new
+   contributors, and ensuring the consistency and quality of translations.
+   Your conduct and contributions as a translator should reflect this before
+   requesting to be a proofreader.
 
 1. Request proofreader permissions by opening a merge request to add yourself
    to the list of proofreaders.
 
-    Open the [proofreader.md source file][proofreader-src] and click **Edit**.
+   Open the [proofreader.md source file][proofreader-src] and click **Edit**.
 
-    Add your language in alphabetical order, and add yourself to the list
-    including:
-    - name
-    - link to your GitLab profile
-    - link to your CrowdIn profile
+   Add your language in alphabetical order, and add yourself to the list
+   including:
+   - name
+   - link to your GitLab profile
+   - link to your CrowdIn profile
 
-    In the merge request description, please include links to any projects you
-    have previously translated.
+   In the merge request description, please include links to any projects you
+   have previously translated.
 
 1. Your request to become a proofreader will be considered on the merits of
    your previous translations by [GitLab team members](https://about.gitlab.com/team/)
    or [Core team members](https://about.gitlab.com/core-team/) who are fluent in
    the language or current proofreaders.
    - When a request is made for the first proofreader for a language and there are no [GitLab team members](https://about.gitlab.com/team/)
-   or [Core team members](https://about.gitlab.com/core-team/) who speak the language, we will request links to previous translation work in other communities or projects.  
-
+   or [Core team members](https://about.gitlab.com/core-team/) who speak the language, we will request links to previous translation work in other communities or projects.
 
 [proofreader-src]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/development/i18n/proofreader.md
diff --git a/doc/development/img/architecture_simplified.png b/doc/development/img/architecture_simplified.png
index 1698c167c5e..1ad57b65468 100644
--- a/doc/development/img/architecture_simplified.png
+++ b/doc/development/img/architecture_simplified.png
diff --git a/doc/development/img/distributed_tracing_jaeger_ui.png b/doc/development/img/distributed_tracing_jaeger_ui.png
index 57517dacced..dcd18b1ec9f 100644
--- a/doc/development/img/distributed_tracing_jaeger_ui.png
+++ b/doc/development/img/distributed_tracing_jaeger_ui.png
diff --git a/doc/development/img/distributed_tracing_performance_bar.png b/doc/development/img/distributed_tracing_performance_bar.png
index c9998cedd2d..8c819045104 100644
--- a/doc/development/img/distributed_tracing_performance_bar.png
+++ b/doc/development/img/distributed_tracing_performance_bar.png
diff --git a/doc/development/import_export.md b/doc/development/import_export.md
index fd067b80c16..0c343bc22e4 100644
--- a/doc/development/import_export.md
+++ b/doc/development/import_export.md
@@ -19,6 +19,7 @@ Project.find_by_full_path('group/project').import_state.slice(:jid, :status, :la
 grep JID /var/log/gitlab/sidekiq/current
 grep "Import/Export error" /var/log/gitlab/sidekiq/current
 grep "Import/Export backtrace" /var/log/gitlab/sidekiq/current
+tail /var/log/gitlab/gitlab-rails/importer.log
 ```
 
 ## Troubleshooting performance issues
@@ -147,7 +148,6 @@ The `ModelConfigurationSpec` checks and confirms the addition of new models:
   If you think this model should be included in the export, please add it to `#{Gitlab::ImportExport.config_file}`.
 
   Definitely add it to `#{File.expand_path(ce_models_yml)}`
-  #{"or `#{File.expand_path(ee_models_yml)}` if the model/associations are EE-specific\n" if ee_models_hash.any?}
   to signal that you've handled this error and to prevent it from showing up in the future.
 MSG
 ```
@@ -230,8 +230,8 @@ meaning that we want to bump the version up in the next version (or patch releas
 For example:
 
 1. Add rename to `RelationRenameService` in X.Y
-2. Remove it from `RelationRenameService` in X.Y + 1
-3. Bump Import/Export version in X.Y + 1
+1. Remove it from `RelationRenameService` in X.Y + 1
+1. Bump Import/Export version in X.Y + 1
 
 ```ruby
 module Gitlab
@@ -253,7 +253,7 @@ Model relationships to be included in the project import/export:
 ```yaml
 project_tree:
   - labels:
-      :priorities
+    - :priorities
   - milestones:
     - events:
       - :push_event_payload
diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md
index 5f95cf3707c..777d372ec60 100644
--- a/doc/development/instrumentation.md
+++ b/doc/development/instrumentation.md
@@ -1,6 +1,6 @@
 # Instrumenting Ruby Code
 
-GitLab Performance Monitoring allows instrumenting of both methods and custom
+[GitLab Performance Monitoring](../administration/monitoring/performance/index.md) allows instrumenting of both methods and custom
 blocks of Ruby code. Method instrumentation is the primary form of
 instrumentation with block-based instrumentation only being used when we want to
 drill down to specific regions of code within a method.
diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md
index 5bf43d320c6..e1350b02262 100644
--- a/doc/development/integrations/jira_connect.md
+++ b/doc/development/integrations/jira_connect.md
@@ -4,7 +4,7 @@ The following are required to install and test the app:
 
 1. A Jira Cloud instance
 
-   Atlassian provides free instances for development and testing. [Click here to sign up](http://go.atlassian.com/cloud-dev).
+   Atlassian provides free instances for development and testing. [Click here to sign up](https://developer.atlassian.com/platform/marketplace/getting-started/#free-developer-instances-to-build-and-test-your-app).
 
 1. A GitLab instance available over the internet
 
@@ -15,7 +15,7 @@ The following are required to install and test the app:
 
 > This feature is currently behind the `:jira_connect_app` feature flag
 
-# Installing the app in Jira
+## Installing the app in Jira
 
 1. Enable Jira development mode to install apps that are not from the Atlassian Marketplace
 
@@ -30,9 +30,11 @@ The following are required to install and test the app:
    1. In the **From this URL** field, provide a link to the app descriptor. The host and port must point to your GitLab instance.
 
       For example:
+
       ```
       https://xxxx.serveo.net/-/jira_connect/app_descriptor.json
       ```
+
    1. Click **Upload**.
 
    If the install was successful, you should see the **GitLab for Jira** app under **Manage apps**.
diff --git a/doc/development/interacting_components.md b/doc/development/interacting_components.md
new file mode 100644
index 00000000000..5e6dc8d460a
--- /dev/null
+++ b/doc/development/interacting_components.md
@@ -0,0 +1,29 @@
+# Developing against interacting components or features
+
+It's not uncommon that a single code change can reflect and interact with multiple parts of GitLab
+codebase. Furthermore, an existing feature might have an underlying integration or behavior that
+might go unnoticed even by reviewers and maintainers.
+
+The goal of this section is to briefly list interacting pieces to think about
+when making _backend_ changes that might involve multiple features or [components](architecture.md#components).
+
+## Uploads
+
+GitLab supports uploads to [object storage]. That means every feature and
+change that affects uploads should also be tested against [object storage],
+which is _not_ enabled by default in [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit).
+
+When working on a related feature, make sure to enable and test it
+against [Minio](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/object_storage.md).
+
+See also [File Storage in GitLab](file_storage.md).
+
+## Merge requests
+
+### Forks
+
+GitLab supports a great amount of features for [merge requests](../user/project/merge_requests/index.md). One
+of them is the ability to create merge requests from and to [forks](../gitlab-basics/fork-project.md),
+which should also be highly considered and tested upon development phase.
+
+[object storage]: https://docs.gitlab.com/charts/advanced/external-object-storage/
diff --git a/doc/development/lfs.md b/doc/development/lfs.md
new file mode 100644
index 00000000000..8c3408eb6e2
--- /dev/null
+++ b/doc/development/lfs.md
@@ -0,0 +1,11 @@
+# Git LFS
+
+## Deep Dive
+
+In April 2019, Francisco Javier López hosted a [Deep Dive] on GitLab's [Git LFS] implementation to share his domain specific knowledge with anyone who may work in this part of the code base in the future. You can find the [recording on YouTube], and the slides on [Google Slides] and in [PDF]. Everything covered in this deep dive was accurate as of GitLab 11.10, and while specific details may have changed since then, it should still serve as a good introduction.
+
+[Deep Dive]: https://gitlab.com/gitlab-org/create-stage/issues/1
+[Git LFS]: ../workflow/lfs/manage_large_binaries_with_git_lfs.html
+[recording on YouTube]: https://www.youtube.com/watch?v=Yyxwcksr0Qc
+[Google Slides]: https://docs.google.com/presentation/d/1E-aw6-z0rYd0346YhIWE7E9A65zISL9iIMAOq2zaw9E/edit
+[PDF]: https://gitlab.com/gitlab-org/create-stage/uploads/07a89257a140db067bdfb484aecd35e1/Git_LFS_Deep_Dive__Create_.pdf
\ No newline at end of file
diff --git a/doc/development/licensed_feature_availability.md b/doc/development/licensed_feature_availability.md
index 6f3dd59b2c3..29e4ace157b 100644
--- a/doc/development/licensed_feature_availability.md
+++ b/doc/development/licensed_feature_availability.md
@@ -1,20 +1,20 @@
-# Licensed feature availability **[STARTER]**
+# Licensed feature availability **(STARTER)**
 
-As of GitLab 9.4, we've been supporting a simplified version of licensed 
-feature availability checks via `ee/app/models/license.rb`, both for 
+As of GitLab 9.4, we've been supporting a simplified version of licensed
+feature availability checks via `ee/app/models/license.rb`, both for
 on-premise or GitLab.com plans and features.
 
 ## Restricting features scoped by namespaces or projects
 
 GitLab.com plans are persisted on user groups and namespaces, therefore, if you're adding a
-feature such as [Related issues](../user/project/issues/related_issues.md) or 
-[Service desk](../user/project/service_desk.md), 
+feature such as [Related issues](../user/project/issues/related_issues.md) or
+[Service desk](../user/project/service_desk.md),
 it should be restricted on namespace scope.
 
-1. Add the feature symbol on `EES_FEATURES`, `EEP_FEATURES` or `EEU_FEATURES` constants in 
-  `ee/app/models/license.rb`. Note on `ee/app/models/ee/namespace.rb` that _Bronze_ GitLab.com 
+1. Add the feature symbol on `EES_FEATURES`, `EEP_FEATURES` or `EEU_FEATURES` constants in
+  `ee/app/models/license.rb`. Note on `ee/app/models/ee/namespace.rb` that _Bronze_ GitLab.com
   features maps to on-premise _EES_, _Silver_ to _EEP_ and _Gold_ to _EEU_.
-2. Check using:
+1. Check using:
 
 ```ruby
 project.feature_available?(:feature_symbol)
@@ -22,15 +22,15 @@ project.feature_available?(:feature_symbol)
 
 ## Restricting global features (instance)
 
-However, for features such as [Geo](../administration/geo/replication/index.md) and 
-[Load balancing](../administration/database_load_balancing.md), which cannot be restricted 
-to only a subset of projects or namespaces, the check will be made directly in 
+However, for features such as [Geo](../administration/geo/replication/index.md) and
+[Load balancing](../administration/database_load_balancing.md), which cannot be restricted
+to only a subset of projects or namespaces, the check will be made directly in
 the instance license.
 
-1. Add the feature symbol on `EES_FEATURES`, `EEP_FEATURES` or `EEU_FEATURES` constants in 
+1. Add the feature symbol on `EES_FEATURES`, `EEP_FEATURES` or `EEU_FEATURES` constants in
   `ee/app/models/license.rb`.
-2. Add the same feature symbol to `GLOBAL_FEATURES`
-3. Check using:
+1. Add the same feature symbol to `GLOBAL_FEATURES`
+1. Check using:
 
 ```ruby
 License.feature_available?(:feature_symbol)
diff --git a/doc/development/logging.md b/doc/development/logging.md
index d61441813b2..4f63c84fc0e 100644
--- a/doc/development/logging.md
+++ b/doc/development/logging.md
@@ -30,8 +30,8 @@ Completed 200 OK in 166ms (Views: 117.4ms | ActiveRecord: 27.2ms)
 These logs suffer from a number of problems:
 
 1. They often lack timestamps or other contextual information (e.g. project ID, user)
-2. They may span multiple lines, which make them hard to find via Elasticsearch.
-3. They lack a common structure, which make them hard to parse by log
+1. They may span multiple lines, which make them hard to find via Elasticsearch.
+1. They lack a common structure, which make them hard to parse by log
    forwarders, such as Logstash or Fluentd. This also makes them hard to
    search.
 
@@ -67,46 +67,46 @@ importer progresses. Here's what to do:
    make it easy for people to search pertinent logs in one place. For
    example, `geo.log` contains all logs pertaining to GitLab Geo.
    To create a new file:
-    1. Choose a filename (e.g. `importer_json.log`).
-    1. Create a new subclass of `Gitlab::JsonLogger`:
-
-        ```ruby
-        module Gitlab
-          module Import
-            class Logger < ::Gitlab::JsonLogger
-              def self.file_name_noext
-                'importer'
-              end
+   1. Choose a filename (e.g. `importer_json.log`).
+   1. Create a new subclass of `Gitlab::JsonLogger`:
+
+      ```ruby
+      module Gitlab
+        module Import
+          class Logger < ::Gitlab::JsonLogger
+            def self.file_name_noext
+              'importer'
             end
-           end
-        end
-        ```
+          end
+         end
+      end
+      ```
 
-    1. In your class where you want to log, you might initialize the logger as an instance variable:
+   1. In your class where you want to log, you might initialize the logger as an instance variable:
 
-        ```ruby
-        attr_accessor :logger
+      ```ruby
+      attr_accessor :logger
 
-        def initialize
-          @logger = Gitlab::Import::Logger.build
-        end
-        ```
+      def initialize
+        @logger = Gitlab::Import::Logger.build
+      end
+      ```
 
-        Note that it's useful to memoize this because creating a new logger
-        each time you log will open a file, adding unnecessary overhead.
+      Note that it's useful to memoize this because creating a new logger
+      each time you log will open a file, adding unnecessary overhead.
 
 1. Now insert log messages into your code. When adding logs,
    make sure to include all the context as key-value pairs:
 
-    ```ruby
-    # BAD
-    logger.info("Unable to create project #{project.id}")
-    ```
+   ```ruby
+   # BAD
+   logger.info("Unable to create project #{project.id}")
+   ```
 
-    ```ruby
-    # GOOD
-    logger.info(message: "Unable to create project", project_id: project.id)
-    ```
+   ```ruby
+   # GOOD
+   logger.info(message: "Unable to create project", project_id: project.id)
+   ```
 
 1. Be sure to create a common base structure of your log messages. For example,
    all messages might have `current_user_id` and `project_id` to make it easier
@@ -116,16 +116,16 @@ importer progresses. Here's what to do:
    logs properly if you [mix integer and string
    types](https://www.elastic.co/guide/en/elasticsearch/guide/current/mapping.html#_avoiding_type_gotchas):
 
-    ```ruby
-    # BAD
-    logger.info(message: "Import error", error: 1)
-    logger.info(message: "Import error", error: "I/O failure")
-    ```
+   ```ruby
+   # BAD
+   logger.info(message: "Import error", error: 1)
+   logger.info(message: "Import error", error: "I/O failure")
+   ```
 
-    ```ruby
-    # GOOD
-    logger.info(message: "Import error", error_code: 1, error: "I/O failure")
-    ```
+   ```ruby
+   # GOOD
+   logger.info(message: "Import error", error_code: 1, error: "I/O failure")
+   ```
 
 ## Additional steps with new log files
 
diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md
index 9b26f691b55..3181b3a88cc 100644
--- a/doc/development/migration_style_guide.md
+++ b/doc/development/migration_style_guide.md
@@ -10,9 +10,7 @@ migrations are written carefully, can be applied online and adhere to the style
 guide below.
 
 Migrations are **not** allowed to require GitLab installations to be taken
-offline unless _absolutely necessary_. Downtime assumptions should be based on
-the behaviour of a migration when performed using PostgreSQL, as various
-operations in MySQL may require downtime without there being alternatives.
+offline unless _absolutely necessary_.
 
 When downtime is necessary the migration has to be approved by:
 
@@ -21,7 +19,7 @@ When downtime is necessary the migration has to be approved by:
 1. A Database Specialist
 
 An up-to-date list of people holding these titles can be found at
-<https://about.gitlab.com/team/>.
+<https://about.gitlab.com/company/team/>.
 
 When writing your migrations, also consider that databases might have stale data
 or inconsistencies and guard for that. Try to make as few assumptions as
@@ -343,10 +341,7 @@ class AddOptionsToBuildMetadata < ActiveRecord::Migration[5.0]
 end
 ```
 
-On MySQL the `JSON` and `JSONB` is translated to `TEXT 1MB`, as `JSONB` is PostgreSQL only feature.
-
-For above reason you have to use a serializer to provide a translation layer
-in order to support PostgreSQL and MySQL seamlessly:
+You have to use a serializer to provide a translation layer:
 
 ```ruby
 class BuildMetadata
@@ -356,7 +351,7 @@ end
 
 ## Testing
 
-Make sure that your migration works with MySQL and PostgreSQL with data. An
+Make sure that your migration works for databases with data. An
 empty database does not guarantee that your migration is correct.
 
 Make sure your migration can be reversed.
diff --git a/doc/development/module_with_instance_variables.md b/doc/development/module_with_instance_variables.md
index 7bdfa04fc57..443eee0b62c 100644
--- a/doc/development/module_with_instance_variables.md
+++ b/doc/development/module_with_instance_variables.md
@@ -1,6 +1,6 @@
-## Modules with instance variables could be considered harmful
+# Modules with instance variables could be considered harmful
 
-### Background
+## Background
 
 Rails somehow encourages people using modules and instance variables
 everywhere. For example, using instance variables in the controllers,
@@ -9,7 +9,7 @@ helpers, and views. They're also encouraging the use of
 saving everything in a giant, single object, and people could access
 everything in that one giant object.
 
-### The problems
+## The problems
 
 Of course this is convenient to develop, because we just have everything
 within reach. However this has a number of downsides when that chosen object
@@ -24,7 +24,7 @@ manipulated from 3 different modules. It's hard to track when those variables
 start giving us troubles. We don't know which module would suddenly change
 one of the variables. Everything could touch anything.
 
-### Similar concerns
+## Similar concerns
 
 People are saying multiple inheritance is bad. Mixing multiple modules with
 multiple instance variables scattering everywhere suffer from the same issue.
@@ -40,7 +40,7 @@ Note that `included` doesn't solve the whole issue. They define the
 dependencies, but they still allow each modules to talk implicitly via the
 instance variables in the final giant object, and that's where the problem is.
 
-### Solutions
+## Solutions
 
 We should split the giant object into multiple objects, and they communicate
 with each other with the API, i.e. public methods. In short, composition over
@@ -53,7 +53,7 @@ With clearly defined API, this would make things less coupled and much easier
 to debug and track, and much more extensible for other objects to use, because
 they communicate in a clear way, rather than implicit dependencies.
 
-### Acceptable use
+## Acceptable use
 
 However, it's not always bad to use instance variables in a module,
 as long as it's contained in the same module; that is, no other modules or
@@ -74,7 +74,7 @@ Unfortunately it's not easy to code more complex rules into the cop, so
 we rely on people's best judgement. If we could find another good pattern
 we could easily add to the cop, we should do it.
 
-### How to rewrite and avoid disabling this cop
+## How to rewrite and avoid disabling this cop
 
 Even if we could just disable the cop, we should avoid doing so. Some code
 could be easily rewritten in simple form. Consider this acceptable method:
@@ -181,7 +181,7 @@ rather than whatever includes the module, and those modules which were also
 included, making it much easier to track down any issues,
 and reducing the chance of having name conflicts.
 
-### How to disable this cop
+## How to disable this cop
 
 Put the disabling comment right after your code in the same line:
 
@@ -210,14 +210,14 @@ end
 Note that you need to enable it at some point, otherwise everything below
 won't be checked.
 
-### Things we might need to ignore right now
+## Things we might need to ignore right now
 
 Because of the way Rails helpers and mailers work, we might not be able to
 avoid the use of instance variables there. For those cases, we could ignore
 them at the moment. At least we're not going to share those modules with
 other random objects, so they're still somewhat isolated.
 
-### Instance variables in views
+## Instance variables in views
 
 They're bad because we can't easily tell who's using the instance variables
 (from controller's point of view) and where we set them up (from partials'
diff --git a/doc/development/new_fe_guide/dependencies.md b/doc/development/new_fe_guide/dependencies.md
index 12a4f089d41..8a6930acd37 100644
--- a/doc/development/new_fe_guide/dependencies.md
+++ b/doc/development/new_fe_guide/dependencies.md
@@ -15,6 +15,18 @@ Exceptions are made for some tools that we require in the
 `gitlab:assets:compile` CI job such as `webpack-bundle-analyzer` to analyze our
 production assets post-compile.
 
+To add or upgrade a dependency, run:
+
+```sh
+yarn add <your dependency here>
+```
+
+This may introduce duplicate dependencies. To de-duplicate `yarn.lock`, run:
+
+```sh
+node_modules/.bin/yarn-deduplicate --list --strategy fewer yarn.lock && yarn install
+```
+
 ---
 
 > TODO: Add Dependencies
diff --git a/doc/development/new_fe_guide/development/accessibility.md b/doc/development/new_fe_guide/development/accessibility.md
index 81a29170129..ae5c4c6a6cc 100644
--- a/doc/development/new_fe_guide/development/accessibility.md
+++ b/doc/development/new_fe_guide/development/accessibility.md
@@ -1,17 +1,21 @@
 # Accessiblity
+
 Using semantic HTML plays a key role when it comes to accessibility.
 
 ## Accessible Rich Internet Applications - ARIA
+
 WAI-ARIA, the Accessible Rich Internet Applications specification, defines a way to make Web content and Web applications more accessible to people with disabilities.
 
 > Note: It is [recommended][using-aria] to use semantic elements as the primary method to achieve accessibility rather than adding aria attributes. Adding aria attributes should be seen as a secondary method for creating accessible elements.
 
 ### Role
+
 The `role` attribute describes the role the element plays in the context of the document.
 
 Check the list of WAI-ARIA roles [here][roles]
 
 ## Icons
+
 When using icons or images that aren't absolutely needed to understand the context, we should use `aria-hidden="true"`.
 
 On the other hand, if an icon is crucial to understand the context we should do one of the following:
@@ -20,6 +24,7 @@ On the other hand, if an icon is crucial to understand the context we should do
 1. Use `aria-labelledby` to point to an element that contains the explanation for that icon
 
 ## Form inputs
+
 In forms we should use the `for` attribute in the label statement:
 
 ```
diff --git a/doc/development/new_fe_guide/development/components.md b/doc/development/new_fe_guide/development/components.md
index 963ce53423b..cebdc87eab9 100644
--- a/doc/development/new_fe_guide/development/components.md
+++ b/doc/development/new_fe_guide/development/components.md
@@ -13,7 +13,7 @@ D3 is very popular across many projects outside of GitLab:
 
 - [The New York Times](https://archive.nytimes.com/www.nytimes.com/interactive/2012/02/13/us/politics/2013-budget-proposal-graphic.html)
 - [plot.ly](https://plot.ly/)
-- [Droptask](https://www.droptask.com/)
+- [Droptask](https://www.ayoa.com/previously-droptask/)
 
 Within GitLab, D3 has been used for the following notable features
 
diff --git a/doc/development/new_fe_guide/development/performance.md b/doc/development/new_fe_guide/development/performance.md
index 640a8d64176..d41239693bf 100644
--- a/doc/development/new_fe_guide/development/performance.md
+++ b/doc/development/new_fe_guide/development/performance.md
@@ -2,10 +2,10 @@
 
 ## Monitoring
 
-We have a performance dashboard available in one of our [grafana instances](https://dashboards.gitlab.net/d/1EBTz3Dmz/sitespeed-page-summary?orgId=1). This dashboard automatically aggregates metric data from [sitespeed.io](https://sitespeed.io) every 6 hours. These changes are displayed after a set number of pages are aggregated.
+We have a performance dashboard available in one of our [grafana instances](https://dashboards.gitlab.net/d/1EBTz3Dmz/sitespeed-page-summary?orgId=1). This dashboard automatically aggregates metric data from [sitespeed.io](https://www.sitespeed.io/) every 6 hours. These changes are displayed after a set number of pages are aggregated.
 
 These pages can be found inside a text file in the gitlab-build-images [repository](https://gitlab.com/gitlab-org/gitlab-build-images) called [gitlab.txt](https://gitlab.com/gitlab-org/gitlab-build-images/blob/master/scripts/gitlab.txt)
-Any frontend engineer can contribute to this dashboard. They can contribute by adding or removing urls of pages from this text file. Please have a [frontend monitoring expert](https://about.gitlab.com/team) review your changes before assigning to a maintainer of the `gitlab-build-images` project. The changes will go live on the next scheduled run after the changes are merged into `master`.
+Any frontend engineer can contribute to this dashboard. They can contribute by adding or removing urls of pages from this text file. Please have a [frontend monitoring expert](https://about.gitlab.com/company/team/) review your changes before assigning to a maintainer of the `gitlab-build-images` project. The changes will go live on the next scheduled run after the changes are merged into `master`.
 
 There are 3 recommended high impact metrics to review on each page:
 
diff --git a/doc/development/new_fe_guide/development/testing.md b/doc/development/new_fe_guide/development/testing.md
index 8441089418e..e0d413b748b 100644
--- a/doc/development/new_fe_guide/development/testing.md
+++ b/doc/development/new_fe_guide/development/testing.md
@@ -1,361 +1,6 @@
-# Overview of Frontend Testing
+---
+redirect_to: '../../testing_guide/frontend_testing.md'
+---
 
-Tests relevant for frontend development can be found at the following places:
+This document was moved to [another location](../../testing_guide/frontend_testing.md).
 
-- `spec/javascripts/` which are run by Karma (command: `yarn karma`) and contain
-  - [frontend unit tests](#frontend-unit-tests)
-  - [frontend component tests](#frontend-component-tests)
-  - [frontend integration tests](#frontend-integration-tests)
-- `spec/frontend/` which are run by Jest (command: `yarn jest`) and contain
-  - [frontend unit tests](#frontend-unit-tests)
-  - [frontend component tests](#frontend-component-tests)
-  - [frontend integration tests](#frontend-integration-tests)
-- `spec/features/` which are run by RSpec and contain
-  - [feature tests](#feature-tests)
-
-All tests in `spec/javascripts/` will eventually be migrated to `spec/frontend/` (see also [#52483](https://gitlab.com/gitlab-org/gitlab-ce/issues/52483)).
-
-In addition there were feature tests in `features/` run by Spinach in the past.
-These have been removed from our codebase in May 2018 ([#23036](https://gitlab.com/gitlab-org/gitlab-ce/issues/23036)).
-
-See also:
-
-- [Old testing guide](../../testing_guide/frontend_testing.html).
-- [Notes on testing Vue components](../../fe_guide/vue.html#testing-vue-components).
-
-## Frontend unit tests
-
-Unit tests are on the lowest abstraction level and typically test functionality that is not directly perceivable by a user.
-
-### When to use unit tests
-
-<details>
-  <summary>exported functions and classes</summary>
-  Anything that is exported can be reused at various places in a way you have no control over.
-  Therefore it is necessary to document the expected behavior of the public interface with tests.
-</details>
-
-<details>
-  <summary>Vuex actions</summary>
-  Any Vuex action needs to work in a consistent way independent of the component it is triggered from.
-</details>
-
-<details>
-  <summary>Vuex mutations</summary>
-  For complex Vuex mutations it helps to identify the source of a problem by separating the tests from other parts of the Vuex store.
-</details>
-
-### When *not* to use unit tests
-
-<details>
-  <summary>non-exported functions or classes</summary>
-  Anything that is not exported from a module can be considered private or an implementation detail and doesn't need to be tested.
-</details>
-
-<details>
-  <summary>constants</summary>
-  Testing the value of a constant would mean to copy it.
-  This results in extra effort without additional confidence that the value is correct.
-</details>
-
-<details>
-  <summary>Vue components</summary>
-  Computed properties, methods, and lifecycle hooks can be considered an implementation detail of components and don't need to be tested.
-  They are implicitly covered by component tests.
-  The <a href="https://vue-test-utils.vuejs.org/guides/#getting-started">official Vue guidelines</a> suggest the same.
-</details>
-
-### What to mock in unit tests
-
-<details>
-  <summary>state of the class under test</summary>
-  Modifying the state of the class under test directly rather than using methods of the class avoids side-effects in test setup.
-</details>
-
-<details>
-  <summary>other exported classes</summary>
-  Every class needs to be tested in isolation to prevent test scenarios from growing exponentially.
-</details>
-
-<details>
-  <summary>single DOM elements if passed as parameters</summary>
-  For tests that only operate on single DOM elements rather than a whole page, creating these elements is cheaper than loading a whole HTML fixture.
-</details>
-
-<details>
-  <summary>all server requests</summary>
-  When running frontend unit tests, the backend may not be reachable.
-  Therefore all outgoing requests need to be mocked.
-</details>
-
-<details>
-  <summary>asynchronous background operations</summary>
-  Background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects.
-</details>
-
-### What *not* to mock in unit tests
-
-<details>
-  <summary>non-exported functions or classes</summary>
-  Everything that is not exported can be considered private to the module and will be implicitly tested via the exported classes / functions.
-</details>
-
-<details>
-  <summary>methods of the class under test</summary>
-  By mocking methods of the class under test, the mocks will be tested and not the real methods.
-</details>
-
-<details>
-  <summary>utility functions (pure functions, or those that only modify parameters)</summary>
-  If a function has no side effects because it has no state, it is safe to not mock it in tests.
-</details>
-
-<details>
-  <summary>full HTML pages</summary>
-  Loading the HTML of a full page slows down tests, so it should be avoided in unit tests.
-</details>
-
-## Frontend component tests
-
-Component tests cover the state of a single component that is perceivable by a user depending on external signals such as user input, events fired from other components, or application state.
-
-### When to use component tests
-
-- Vue components
-
-### When *not* to use component tests
-
-<details>
-  <summary>Vue applications</summary>
-  Vue applications may contain many components.
-  Testing them on a component level requires too much effort.
-  Therefore they are tested on frontend integration level.
-</details>
-
-<details>
-  <summary>HAML templates</summary>
-  HAML templates contain only Markup and no frontend-side logic.
-  Therefore they are not complete components.
-</details>
-
-### What to mock in component tests
-
-<details>
-  <summary>DOM</summary>
-  Operating on the real DOM is significantly slower than on the virtual DOM.
-</details>
-
-<details>
-  <summary>properties and state of the component under test</summary>
-  Similarly to testing classes, modifying the properties directly (rather than relying on methods of the component) avoids side-effects.
-</details>
-
-<details>
-  <summary>Vuex store</summary>
-  To avoid side effects and keep component tests simple, Vuex stores are replaced with mocks.
-</details>
-
-<details>
-  <summary>all server requests</summary>
-  Similar to unit tests, when running component tests, the backend may not be reachable.
-  Therefore all outgoing requests need to be mocked.
-</details>
-
-<details>
-  <summary>asynchronous background operations</summary>
-  Similar to unit tests, background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects.
-</details>
-
-<details>
-  <summary>child components</summary>
-  Every component is tested individually, so child components are mocked.
-  See also <a href="https://vue-test-utils.vuejs.org/api/#shallowmount">shallowMount()</a>
-</details>
-
-### What *not* to mock in component tests
-
-<details>
-  <summary>methods or computed properties of the component under test</summary>
-  By mocking part of the component under test, the mocks will be tested and not the real component.
-</details>
-
-<details>
-  <summary>functions and classes independent from Vue</summary>
-  All plain JavaScript code is already covered by unit tests and needs not to be mocked in component tests.
-</details>
-
-## Frontend integration tests
-
-Integration tests cover the interaction between all components on a single page.
-Their abstraction level is comparable to how a user would interact with the UI.
-
-### When to use integration tests
-
-<details>
-  <summary>page bundles (<code>index.js</code> files in <code>app/assets/javascripts/pages/</code>)</summary>
-  Testing the page bundles ensures the corresponding frontend components integrate well.
-</details>
-
-<details>
-  <summary>Vue applications outside of page bundles</summary>
-  Testing Vue applications as a whole ensures the corresponding frontend components integrate well.
-</details>
-
-### What to mock in integration tests
-
-<details>
-  <summary>HAML views (use fixtures instead)</summary>
-  Rendering HAML views requires a Rails environment including a running database which we cannot rely on in frontend tests.
-</details>
-
-<details>
-  <summary>all server requests</summary>
-  Similar to unit and component tests, when running component tests, the backend may not be reachable.
-  Therefore all outgoing requests need to be mocked.
-</details>
-
-<details>
-  <summary>asynchronous background operations that are not perceivable on the page</summary>
-  Background operations that affect the page need to be tested on this level.
-  All other background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects.
-</details>
-
-### What *not* to mock in integration tests
-
-<details>
-  <summary>DOM</summary>
-  Testing on the real DOM ensures our components work in the environment they are meant for.
-  Part of this will be delegated to <a href="https://gitlab.com/gitlab-org/quality/team-tasks/issues/45">cross-browser testing</a>.
-</details>
-
-<details>
-  <summary>properties or state of components</summary>
-  On this level, all tests can only perform actions a user would do.
-  For example to change the state of a component, a click event would be fired.
-</details>
-
-<details>
-  <summary>Vuex stores</summary>
-  When testing the frontend code of a page as a whole, the interaction between Vue components and Vuex stores is covered as well.
-</details>
-
-## Feature tests
-
-In contrast to [frontend integration tests](#frontend-integration-tests), feature tests make requests against the real backend instead of using fixtures.
-This also implies that database queries are executed which makes this category significantly slower.
-
-See also the [RSpec testing guidelines](../../testing_guide/best_practices.md#rspec).
-
-### When to use feature tests
-
-- use cases that require a backend and cannot be tested using fixtures
-- behavior that is not part of a page bundle but defined globally
-
-### Relevant notes
-
-A `:js` flag is added to the test to make sure the full environment is loaded.
-
-```
-scenario 'successfully', :js do
-  sign_in(create(:admin))
-end
-```
-
-The steps of each test are written using capybara methods ([documentation](http://www.rubydoc.info/gems/capybara/2.15.1)).
-
-Bear in mind <abbr title="XMLHttpRequest">XHR</abbr> calls might require you to use `wait_for_requests` in between steps, like so:
-
-```rspec
-find('.form-control').native.send_keys(:enter)
-
-wait_for_requests
-
-expect(page).not_to have_selector('.card')
-```
-
-## Test helpers
-
-### Vuex Helper: `testAction`
-
-We have a helper available to make testing actions easier, as per [official documentation](https://vuex.vuejs.org/en/testing.html):
-
-```
-testAction(
-  actions.actionName, // action
-  { }, // params to be passed to action
-  state, // state
-  [
-    { type: types.MUTATION},
-    { type: types.MUTATION_1, payload: {}},
-  ], // mutations committed
-  [
-    { type: 'actionName', payload: {}},
-    { type: 'actionName1', payload: {}},
-  ] // actions dispatched
-  done,
-);
-```
-
-Check an example in [spec/javascripts/ide/stores/actions_spec.jsspec/javascripts/ide/stores/actions_spec.js](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/javascripts/ide/stores/actions_spec.js).
-
-### Vue Helper: `mountComponent`
-
-To make mounting a Vue component easier and more readable, we have a few helpers available in `spec/helpers/vue_mount_component_helper`.
-
-- `createComponentWithStore`
-- `mountComponentWithStore`
-
-Examples of usage:
-
-```
-beforeEach(() => {
-  vm = createComponentWithStore(Component, store);
-
-  vm.$store.state.currentBranchId = 'master';
-
-  vm.$mount();
-},
-```
-
-```
-beforeEach(() => {
-  vm = mountComponentWithStore(Component, {
-    el: '#dummy-element',
-    store,
-    props: { badge },
-  });
-},
-```
-
-Don't forget to clean up:
-
-```
-afterEach(() => {
-  vm.$destroy();
-});
-```
-
-## Testing with older browsers
-
-Some regressions only affect a specific browser version. We can install and test in particular browsers with either Firefox or Browserstack using the following steps:
-
-### Browserstack
-
-[Browserstack](https://www.browserstack.com/) allows you to test more than 1200 mobile devices and browsers.
-You can use it directly through the [live app](https://www.browserstack.com/live) or you can install the [chrome extension](https://chrome.google.com/webstore/detail/browserstack/nkihdmlheodkdfojglpcjjmioefjahjb) for easy access.
-You can find the credentials on 1Password, under `frontendteam@gitlab.com`.
-
-### Firefox
-
-#### macOS
-
-You can download any older version of Firefox from the releases FTP server, <https://ftp.mozilla.org/pub/firefox/releases/>
-
-1. From the website, select a version, in this case `50.0.1`.
-1. Go to the mac folder.
-1. Select your preferred language, you will find the dmg package inside, download it.
-1. Drag and drop the application to any other folder but the `Applications` folder.
-1. Rename the application to something like `Firefox_Old`.
-1. Move the application to the `Applications` folder.
-1. Open up a terminal and run `/Applications/Firefox_Old.app/Contents/MacOS/firefox-bin -profilemanager` to create a new profile specific to that Firefox version.
-1. Once the profile has been created, quit the app, and run it again like normal. You now have a working older Firefox version.
diff --git a/doc/development/new_fe_guide/index.md b/doc/development/new_fe_guide/index.md
index 0e8f5486861..227d03bd86f 100644
--- a/doc/development/new_fe_guide/index.md
+++ b/doc/development/new_fe_guide/index.md
@@ -19,7 +19,6 @@ Learn about all the internal JavaScript modules that make up our frontend.
 
 Style guides to keep our code consistent.
 
-
 ## [Tips](tips.md)
 
 Tips from our frontend team to develop more efficiently and effectively.
diff --git a/doc/development/new_fe_guide/modules/dirty_submit.md b/doc/development/new_fe_guide/modules/dirty_submit.md
index 6c03958b463..217743ea395 100644
--- a/doc/development/new_fe_guide/modules/dirty_submit.md
+++ b/doc/development/new_fe_guide/modules/dirty_submit.md
@@ -1,7 +1,6 @@
 # Dirty Submit
 
-> [Introduced][ce-21115] in GitLab 11.3.  
-> [dirty_submit][dirty-submit]
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21115) in GitLab 11.3.
 
 ## Summary
 
@@ -9,6 +8,9 @@ Prevent submitting forms with no changes.
 
 Currently handles `input`, `textarea` and `select` elements.
 
+Also, see [the code](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/dirty_submit/)
+within the GitLab project.
+
 ## Usage
 
 ```js
@@ -18,6 +20,3 @@ new DirtySubmitForm(document.querySelector('form'));
 // or
 new DirtySubmitForm(document.querySelectorAll('form'));
 ```
-
-[ce-21115]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21115
-[dirty-submit]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/dirty_submit/
\ No newline at end of file
diff --git a/doc/development/new_fe_guide/style/html.md b/doc/development/new_fe_guide/style/html.md
index e8c9c2ccebf..1445da3f0e1 100644
--- a/doc/development/new_fe_guide/style/html.md
+++ b/doc/development/new_fe_guide/style/html.md
@@ -16,7 +16,7 @@ Button tags requires a `type` attribute according to the [W3C HTML specification
 
 ### Button role
 
-If an HTML element has an `onClick` handler but is not a button, it should have `role="button"`. This is [more accessible](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role).
+If an HTML element has an `onClick` handler but is not a button, it should have `role="button"`. This is [more accessible](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role).
 
 ```html
 // bad
diff --git a/doc/development/new_fe_guide/style/index.md b/doc/development/new_fe_guide/style/index.md
index 335d9e66240..f073dc56f1f 100644
--- a/doc/development/new_fe_guide/style/index.md
+++ b/doc/development/new_fe_guide/style/index.md
@@ -8,7 +8,7 @@
 
 ## [Vue style guide](vue.md)
 
-# Tooling
+## Tooling
 
 ## [Prettier](prettier.md)
 
diff --git a/doc/development/new_fe_guide/style/javascript.md b/doc/development/new_fe_guide/style/javascript.md
index 3019eaa089c..b742d567f41 100644
--- a/doc/development/new_fe_guide/style/javascript.md
+++ b/doc/development/new_fe_guide/style/javascript.md
@@ -71,7 +71,6 @@ class myClass {
 }
 const instance = new myClass();
 instance.makeRequest();
-
 ```
 
 ## Avoid classes to handle DOM events
@@ -189,8 +188,8 @@ disabled due to legacy compatibility reasons but they are in the process of bein
 Do not disable specific ESLint rules. Due to technical debt, you may disable the following
 rules only if you are invoking/instantiating existing code modules.
 
-  - [no-new](http://eslint.org/docs/rules/no-new)
-  - [class-method-use-this](http://eslint.org/docs/rules/class-methods-use-this)
+- [no-new](http://eslint.org/docs/rules/no-new)
+- [class-method-use-this](http://eslint.org/docs/rules/class-methods-use-this)
 
 > Note: Disable these rules on a per line basis. This makes it easier to refactor
-  in the future. E.g. use `eslint-disable-next-line` or `eslint-disable-line`.
+> in the future. E.g. use `eslint-disable-next-line` or `eslint-disable-line`.
diff --git a/doc/development/new_fe_guide/style/prettier.md b/doc/development/new_fe_guide/style/prettier.md
index 4495f38f262..5f44c640d76 100644
--- a/doc/development/new_fe_guide/style/prettier.md
+++ b/doc/development/new_fe_guide/style/prettier.md
@@ -4,7 +4,7 @@ Our code is automatically formatted with [Prettier](https://prettier.io) to foll
 
 ## Editor
 
-The easiest way to include prettier in your workflow is by setting up your preferred editor (all major editors are supported) accordingly. We suggest setting up prettier to run automatically when each file is saved. Find [here](https://prettier.io/docs/en/editors.html) the best way to set it up in your preferred editor. 
+The easiest way to include prettier in your workflow is by setting up your preferred editor (all major editors are supported) accordingly. We suggest setting up prettier to run automatically when each file is saved. Find [here](https://prettier.io/docs/en/editors.html) the best way to set it up in your preferred editor.
 
 Please take care that you only let Prettier format the same file types as the global Yarn script does (.js, .vue, and .scss). In VSCode by example you can easily exclude file formats in your settings file:
 
@@ -28,6 +28,7 @@ Updates all currently staged files (based on `git diff`) with Prettier and saves
 ```
 yarn prettier-staged
 ```
+
 Checks all currently staged files (based on `git diff`) with Prettier and log which files would need manual updating to the console.
 
 ```
diff --git a/doc/development/new_fe_guide/tips.md b/doc/development/new_fe_guide/tips.md
index 4564f678ec0..879b54bd93c 100644
--- a/doc/development/new_fe_guide/tips.md
+++ b/doc/development/new_fe_guide/tips.md
@@ -10,16 +10,16 @@ yarn clean
 
 ## Creating feature flags in development
 
-The process for creating a feature flag is the same as [enabling a feature flag in development](../feature_flags.md#enabling-a-feature-flag-in-development).
+The process for creating a feature flag is the same as [enabling a feature flag in development](../feature_flags/development.md#enabling-a-feature-flag-in-development).
 
 Your feature flag can now be:
 
-- [made available to the frontend](../feature_flags.md#frontend) via the `gon`
-- queried in [tests](../feature_flags.md#specs)
-- queried in HAML templates and ruby files via the `Feature.enabled?(:my_shiny_new_feature_flag)` method
+- [Made available to the frontend](../feature_flags/development.md#frontend) via the `gon`
+- Queried in [tests](../feature_flags/development.md#specs)
+- Queried in HAML templates and ruby files via the `Feature.enabled?(:my_shiny_new_feature_flag)` method
 
 ### More on feature flags
 
 - [Deleting a feature flag](../../api/features.md#delete-a-feature)
-- [Manage feature flags](../feature_flags.md)
+- [Manage feature flags](../feature_flags/process.md)
 - [Feature flags API](../../api/features.md)
diff --git a/doc/development/newlines_styleguide.md b/doc/development/newlines_styleguide.md
index 5f7210020b6..a13adc2f13e 100644
--- a/doc/development/newlines_styleguide.md
+++ b/doc/development/newlines_styleguide.md
@@ -11,7 +11,7 @@ def method
 
   issue.save
 
-  render json: issue 
+  render json: issue
 end
 ```
 
@@ -21,7 +21,7 @@ def method
   issue = Issue.new
   issue.save
 
-  render json: issue 
+  render json: issue
 end
 ```
 
diff --git a/doc/development/packages.md b/doc/development/packages.md
index ab0c5f9904d..08aa0b08525 100644
--- a/doc/development/packages.md
+++ b/doc/development/packages.md
@@ -1,15 +1,15 @@
-# Packages **[PREMIUM]**
+# Packages **(PREMIUM)**
 
 This document will guide you through adding another [package management system](../administration/packages.md) support to GitLab.
 
 See already supported package types in [Packages documentation](../administration/packages.md)
 
 Since GitLab packages' UI is pretty generic, it is possible to add new
-package system support by solely backend changes. This guide is superficial and does 
-not cover the way the code should be written. However, you can find a good example 
-by looking at existing merge requests with Maven and NPM support: 
+package system support by solely backend changes. This guide is superficial and does
+not cover the way the code should be written. However, you can find a good example
+by looking at existing merge requests with Maven and NPM support:
 
-- [NPM registry support](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8673). 
+- [NPM registry support](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8673).
 - [Maven repository](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6607).
 - [Instance level endpoint for Maven repository](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8757)
 
@@ -17,44 +17,44 @@ by looking at existing merge requests with Maven and NPM support:
 
 The existing database model requires the following:
 
-- Every package belongs to a project. 
+- Every package belongs to a project.
 - Every package file belongs to a package.
 - A package can have one or more package files.
 - The package model is based on storing information about the package and its version.
 
 ## API endpoints
 
-Package systems work with GitLab via API. For example `ee/lib/api/npm_packages.rb` 
-implements API endpoints to work with NPM clients. So, the first thing to do is to 
-add a new `ee/lib/api/your_name_packages.rb` file with API endpoints that are 
-necessary to make the package system client to work. Usually that means having 
-endpoints like: 
+Package systems work with GitLab via API. For example `ee/lib/api/npm_packages.rb`
+implements API endpoints to work with NPM clients. So, the first thing to do is to
+add a new `ee/lib/api/your_name_packages.rb` file with API endpoints that are
+necessary to make the package system client to work. Usually that means having
+endpoints like:
 
 - GET package information.
 - GET package file content.
 - PUT upload package.
 
 Since the packages belong to a project, it's expected to have project-level endpoint
-for uploading and downloading them. For example: 
+for uploading and downloading them. For example:
 
 ```
 GET https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/
 PUT https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/
 ```
 
-Group-level and instance-level endpoints are good to have but are optional. 
+Group-level and instance-level endpoints are good to have but are optional.
 
 NOTE: **Note:**
-To avoid name conflict for instance-level endpoints we use 
+To avoid name conflict for instance-level endpoints we use
 [the package naming convention](../user/project/packages/npm_registry.md#package-naming-convention)
 
 ## Configuration
 
-GitLab has a `packages` section in its configuration file (`gitlab.rb`). 
-It applies to all package systems supported by GitLab. Usually you don't need 
-to add anything there. 
+GitLab has a `packages` section in its configuration file (`gitlab.rb`).
+It applies to all package systems supported by GitLab. Usually you don't need
+to add anything there.
 
-Packages can be configured to use object storage, therefore your code must support it. 
+Packages can be configured to use object storage, therefore your code must support it.
 
 ## Database
 
@@ -63,6 +63,6 @@ Every time you upload a new package, you can either create a new record of `Pack
 or add files to existing record. `PackageFile` should be able to store all file-related
 information like the file `name`, `side`, `sha1`, etc.
 
-If there is specific data necessary to be stored for only one package system support, 
-consider creating a separate metadata model. See `packages_maven_metadata` table 
+If there is specific data necessary to be stored for only one package system support,
+consider creating a separate metadata model. See `packages_maven_metadata` table
 and `Packages::MavenMetadatum` model as example for package specific data.
diff --git a/doc/development/performance.md b/doc/development/performance.md
index 0e21d45f57c..14b3f8204d2 100644
--- a/doc/development/performance.md
+++ b/doc/development/performance.md
@@ -246,6 +246,7 @@ irb(main):002:0> results.last.attributes.keys
 irb(main):003:0> results.where(status: "passed").average(:time).to_s
 => "0.211340155844156"
 ```
+
 These results can also be placed into a PostgreSQL database by setting the
 `RSPEC_PROFILING_POSTGRES_URL` variable. This is used to profile the test suite
 when running in the CI environment.
@@ -266,7 +267,7 @@ piece of code is worth optimizing. The only two things you can do are:
 1. Think about what the code does, how it's used, how many times it's called and
    how much time is spent in it relative to the total execution time (e.g., the
    total time spent in a web request).
-2. Ask others (preferably in the form of an issue).
+1. Ask others (preferably in the form of an issue).
 
 Some examples of changes that aren't really important/worth the effort:
 
@@ -284,10 +285,10 @@ directly in a web request as much as possible. This has numerous benefits such
 as:
 
 1. An error won't prevent the request from completing.
-2. The process being slow won't affect the loading time of a page.
-3. In case of a failure it's easy to re-try the process (Sidekiq takes care of
+1. The process being slow won't affect the loading time of a page.
+1. In case of a failure it's easy to re-try the process (Sidekiq takes care of
    this automatically).
-4. By isolating the code from a web request it will hopefully be easier to test
+1. By isolating the code from a web request it will hopefully be easier to test
    and maintain.
 
 It's especially important to use Sidekiq as much as possible when dealing with
@@ -424,7 +425,7 @@ might find using these gems more convenient:
 ### Examples
 
 You may find some useful examples in this snippet:
-https://gitlab.com/gitlab-org/gitlab-ce/snippets/33946
+<https://gitlab.com/gitlab-org/gitlab-ce/snippets/33946>
 
 [#15607]: https://gitlab.com/gitlab-org/gitlab-ce/issues/15607
 [yorickpeterse]: https://gitlab.com/yorickpeterse
diff --git a/doc/development/policies.md b/doc/development/policies.md
index c4ac42bb40a..833b0acb13e 100644
--- a/doc/development/policies.md
+++ b/doc/development/policies.md
@@ -89,8 +89,8 @@ Each line represents a rule that was evaluated. There are a few things to note:
 
 1. The `-` or `+` symbol indicates whether the rule block was evaluated to be
    `false` or `true`, respectively.
-2. The number inside the brackets indicates the score.
-3. The last part of the line (e.g. `@john : Issue/1`) shows the username
+1. The number inside the brackets indicates the score.
+1. The last part of the line (e.g. `@john : Issue/1`) shows the username
    and subject for that rule.
 
 Here you can see that the first four rules were evaluated `false` for
diff --git a/doc/development/profiling.md b/doc/development/profiling.md
index b2f3a105b23..e1d1d2e33fa 100644
--- a/doc/development/profiling.md
+++ b/doc/development/profiling.md
@@ -38,10 +38,6 @@ For routes that require authorization you will need to provide a user to
 Gitlab::Profiler.profile('/gitlab-org/gitlab-test', user: User.first)
 ```
 
-The user you provide will need to have a [personal access
-token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html) in
-the GitLab instance.
-
 Passing a `logger:` keyword argument to `Gitlab::Profiler.profile` will send
 ActiveRecord and ActionController log output to that logger. Further options are
 documented with the method source.
@@ -99,7 +95,9 @@ Sherlock is a custom profiling tool built into GitLab. Sherlock is _only_
 available when running GitLab in development mode _and_ when setting the
 environment variable `ENABLE_SHERLOCK` to a non empty value. For example:
 
-    ENABLE_SHERLOCK=1 bundle exec rails s
+```sh
+ENABLE_SHERLOCK=1 bundle exec rails s
+```
 
 Recorded transactions can be found by navigating to `/sherlock/transactions`.
 
@@ -110,7 +108,9 @@ Bullet adds quite a bit of logging noise it's disabled by default. To enable
 Bullet, set the environment variable `ENABLE_BULLET` to a non-empty value before
 starting GitLab. For example:
 
-    ENABLE_BULLET=true bundle exec rails s
+```sh
+ENABLE_BULLET=true bundle exec rails s
+```
 
 Bullet will log query problems to both the Rails log as well as the Chrome
 console.
diff --git a/doc/development/prometheus_metrics.md b/doc/development/prometheus_metrics.md
index 0511e735843..576601372a3 100644
--- a/doc/development/prometheus_metrics.md
+++ b/doc/development/prometheus_metrics.md
@@ -33,12 +33,10 @@ For example: you might be interested in migrating all dependent data to a differ
 class ImportCommonMetrics < ActiveRecord::Migration[4.2]
   include Gitlab::Database::MigrationHelpers
 
-  require Rails.root.join('db/importers/common_metrics_importer.rb')
-
   DOWNTIME = false
 
   def up
-    Importers::CommonMetricsImporter.new.execute
+    ::Gitlab::DatabaseImporters::CommonMetrics::Importer.new.execute
   end
 
   def down
diff --git a/doc/development/pry_debugging.md b/doc/development/pry_debugging.md
index de5e1323e6a..17d8428b0c0 100644
--- a/doc/development/pry_debugging.md
+++ b/doc/development/pry_debugging.md
@@ -73,7 +73,7 @@ Similar to source browsing, is [Documentation browsing](https://github.com/pry/p
 
 ### Command history
 
-With <kdb>Ctrl+R</kbd> you can search your [command history](https://github.com/pry/pry/wiki/History).
+With **Ctrl+R** you can search your [command history](https://github.com/pry/pry/wiki/History).
 
 ## Stepping
 
diff --git a/doc/development/python_guide/index.md b/doc/development/python_guide/index.md
index 6025dc9ebf2..a80bee27d4a 100644
--- a/doc/development/python_guide/index.md
+++ b/doc/development/python_guide/index.md
@@ -36,7 +36,7 @@ You can read more about it in: <https://github.com/pyenv/pyenv-installer#prerequ
 Pyenv installation will add required changes to Bash. If you use a different shell,
 check for any additional steps required for it.
 
-For Fish, you can install a plugin for [Fisherman](https://github.com/fisherman/fisherman):
+For Fish, you can install a plugin for [Fisher](https://github.com/jorgebucaran/fisher):
 
 ```bash
 fisher add fisherman/pyenv
@@ -76,4 +76,3 @@ pipenv shell
 
 After running that command, you can run GitLab on the same shell and it will be using the Python and dependencies
 installed from the `pipenv install` command.
-
diff --git a/doc/development/query_recorder.md b/doc/development/query_recorder.md
index 2167ed57428..3787e2ef187 100644
--- a/doc/development/query_recorder.md
+++ b/doc/development/query_recorder.md
@@ -1,6 +1,6 @@
 # QueryRecorder
 
-QueryRecorder is a tool for detecting the [N+1 queries problem](http://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations) from tests.
+QueryRecorder is a tool for detecting the [N+1 queries problem](https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations) from tests.
 
 > Implemented in [spec/support/query_recorder.rb](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/support/helpers/query_recorder.rb) via [9c623e3e](https://gitlab.com/gitlab-org/gitlab-ce/commit/9c623e3e5d7434f2e30f7c389d13e5af4ede770a)
 
@@ -36,6 +36,13 @@ it "avoids N+1 database queries" do
 end
 ```
 
+## Use request specs instead of controller specs
+
+Use a [request spec](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/spec/requests) when writing a N+1 test on the controller level.
+
+Controller specs should not be used to write N+1 tests as the controller is only initialized once per example.
+This could lead to false successes where subsequent "requests" could have queries reduced (e.g. because of memoization).
+
 ## Finding the source of the query
 
 It may be useful to identify the source of the queries by looking at the call backtrace.
@@ -86,4 +93,4 @@ QueryRecorder SQL: SELECT COUNT(*) FROM "issues" WHERE "issues"."deleted_at" IS
 
 - [Bullet](profiling.md#Bullet) For finding `N+1` query problems
 - [Performance guidelines](performance.md)
-- [Merge request performance guidelines](merge_request_performance_guidelines.md#query-counts)
\ No newline at end of file
+- [Merge request performance guidelines](merge_request_performance_guidelines.md#query-counts)
diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md
index 28a12572961..fc96820c555 100644
--- a/doc/development/rake_tasks.md
+++ b/doc/development/rake_tasks.md
@@ -9,7 +9,7 @@ bundle exec rake setup
 ```
 
 The `setup` task is an alias for `gitlab:setup`.
-This tasks calls `db:reset` to create the database, calls `add_limits_mysql` that adds limits to the database schema in case of a MySQL database and finally it calls `db:seed_fu` to seed the database.
+This tasks calls `db:reset` to create the database, and calls `db:seed_fu` to seed the database.
 Note: `db:setup` calls `db:seed` but this does nothing.
 
 ### Seeding issues for all or a given project
@@ -28,7 +28,7 @@ bin/rake "gitlab:seed:issues[group-path/project-path]"
 By default, this seeds an average of 2 issues per week for the last 5 weeks per
 project.
 
-#### Seeding issues for Insights charts **[ULTIMATE]**
+#### Seeding issues for Insights charts **(ULTIMATE)**
 
 You can seed issues specifically for working with the
 [Insights charts](../user/group/insights/index.md) with the
@@ -80,30 +80,6 @@ There are a few environment flags you can pass to change how projects are seeded
 - `LARGE_PROJECTS`: defaults to false. If set will clone 6 large projects to help with testing.
 - `FORK`: defaults to false. If set to `true` will fork `torvalds/linux` five times. Can also be set to an existing project full_path and it will fork that instead.
 
-### Notes for MySQL
-
-Since the seeds would contain various UTF-8 characters, such as emojis or so,
-we'll need to make sure that we're using `utf8mb4` for all the encoding
-settings and `utf8mb4_unicode_ci` for collation. Please check
-[MySQL utf8mb4 support](../install/database_mysql.md#mysql-utf8mb4-support)
-
-Make sure that `config/database.yml` has `encoding: utf8mb4`, too.
-
-Next, we'll need to update the schema to make the indices fit:
-
-``` shell
-sed -i 's/limit: 255/limit: 191/g' db/schema.rb
-```
-
-Then run the setup script:
-
-``` shell
-bundle exec rake setup
-```
-
-To make sure that indices still fit. You could find great details in:
-[How to support full Unicode in MySQL databases](https://mathiasbynens.be/notes/mysql-utf8mb4)
-
 ## Run tests
 
 In order to run the test you can use the following commands:
@@ -240,3 +216,4 @@ bundle exec rake routes
 
 Since these take some time to create, it's often helpful to save the output to
 a file for quick reference.
+
diff --git a/doc/development/repository_mirroring.md b/doc/development/repository_mirroring.md
new file mode 100644
index 00000000000..f8c33ff2b85
--- /dev/null
+++ b/doc/development/repository_mirroring.md
@@ -0,0 +1,11 @@
+# Repository mirroring
+
+## Deep Dive
+
+In December 2018, Tiago Botelho hosted a [Deep Dive] on GitLab's [Pull Repository Mirroring functionality] to share his domain specific knowledge with anyone who may work in this part of the code base in the future. You can find the [recording on YouTube], and the slides on [Google Slides] and in [PDF]. Everything covered in this deep dive was accurate as of GitLab 11.6, and while specific details may have changed since then, it should still serve as a good introduction.
+
+[Deep Dive]: https://gitlab.com/gitlab-org/create-stage/issues/1
+[Pull Repository Mirroring functionality]: ../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter
+[recording on YouTube]: https://www.youtube.com/watch?v=sSZq0fpdY-Y
+[Google Slides]: https://docs.google.com/presentation/d/17BTT6M6RyNRckV4wTt-dr07nIfBvD325_xVBoLtSoPM/edit?usp=sharing
+[PDF]: https://gitlab.com/gitlab-org/create-stage/uploads/8693404888a941fd851f8a8ecdec9675/Gitlab_Create_-_Pull_Mirroring_Deep_Dive.pdf
\ No newline at end of file
diff --git a/doc/development/reusing_abstractions.md b/doc/development/reusing_abstractions.md
index 01cedf734fb..fce144f8dc2 100644
--- a/doc/development/reusing_abstractions.md
+++ b/doc/development/reusing_abstractions.md
@@ -14,13 +14,13 @@ on maintainability, the ability to easily debug problems, or even performance.
 An example would be to use `ProjectsFinder` in `IssuesFinder` to limit issues to
 those belonging to a set of projects. While initially this may seem like a good
 idea, both classes provide a very high level interface with very little control.
-This means that `IssuesFinder` may not be able to produce a better optimised
+This means that `IssuesFinder` may not be able to produce a better optimized
 database query, as a large portion of the query is controlled by the internals
 of `ProjectsFinder`.
 
 To work around this problem, you would use the same code used by
 `ProjectsFinder`, instead of using `ProjectsFinder` itself directly. This allows
-you to compose your behaviour better, giving you more control over the behaviour
+you to compose your behavior better, giving you more control over the behavior
 of the code.
 
 To illustrate, consider the following code from `IssuableFinder#projects`:
@@ -52,7 +52,7 @@ functionality is added to this (high level) interface. Instead of _only_
 affecting the cases where this is necessary, it may also start affecting
 `IssuableFinder` in a negative way. For example, the query produced by
 `GroupProjectsFinder` may include unnecessary conditions. Since we're using a
-finder here, we can't easily opt-out of that behaviour. We could add options to
+finder here, we can't easily opt-out of that behavior. We could add options to
 do so, but then we'd need as many options as we have features. Every option adds
 two code paths, which means that for four features we have to cover 8 different
 code paths.
@@ -127,6 +127,42 @@ Everything in `lib/api`.
 
 Everything that resides in `app/services`.
 
+#### ServiceResponse
+
+Service classes usually have an `execute` method, which can return a
+`ServiceResponse`. You can use `ServiceResponse.success` and
+`ServiceResponse.error` to return a response in `execute` method.
+
+In a successful case:
+
+``` ruby
+response = ServiceResponse.success(message: 'Branch was deleted')
+
+response.success? # => true
+response.error? # => false
+response.status # => :success
+response.message # => 'Branch was deleted'
+```
+
+In a failed case:
+
+``` ruby
+response = ServiceResponse.error(message: 'Unsupported operation')
+
+response.success? # => false
+response.error? # => true
+response.status # => :error
+response.message # => 'Unsupported operation'
+```
+
+An additional payload can also be attached:
+
+``` ruby
+response = ServiceResponse.success(payload: { issue: issue })
+
+response.payload[:issue] # => issue
+```
+
 ### Finders
 
 Everything in `app/finders`, typically used for retrieving data from a database.
@@ -177,6 +213,5 @@ The API provided by Active Record itself, such as the `where` method, `save`,
 
 Everything in `app/workers`.
 
-The scheduling of Sidekiq jobs using `SomeWorker.perform_async`, `perform_in`,
-etc. Directly invoking a worker using `SomeWorker.new.perform` should be avoided
-at all times in application code, though this is fine to use in tests.
+Use `SomeWorker.perform_async` or `SomeWorker.perform_in` to schedule Sidekiq
+jobs. Never directly invoke a worker using `SomeWorker.new.perform`.
diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md
index 84028b1b342..6bad91d6287 100644
--- a/doc/development/rolling_out_changes_using_feature_flags.md
+++ b/doc/development/rolling_out_changes_using_feature_flags.md
@@ -1,225 +1 @@
-# Rolling out changes using feature flags
-
-[Feature flags](feature_flags.md) can be used to gradually roll out changes, be
-it a new feature, or a performance improvement. By using feature flags, we can
-comfortably measure the impact of our changes, while still being able to easily
-disable those changes, without having to revert an entire release.
-
-## When to use feature flags
-
-Starting with GitLab 11.4, developers are required to use feature flags for
-non-trivial changes. Such changes include:
-
-- New features (e.g. a new merge request widget, epics, etc).
-- Complex performance improvements that may require additional testing in
-  production, such as rewriting complex queries.
-- Invasive changes to the user interface, such as a new navigation bar or the
-  removal of a sidebar.
-- Adding support for importing projects from a third-party service.
-
-In all cases, those working on the changes can best decide if a feature flag is
-necessary. For example, changing the color of a button doesn't need a feature
-flag, while changing the navigation bar definitely needs one. In case you are
-uncertain if a feature flag is necessary, simply ask about this in the merge
-request, and those reviewing the changes will likely provide you with an answer.
-
-When using a feature flag for UI elements, make sure to _also_ use a feature
-flag for the underlying backend code, if there is any. This ensures there is
-absolutely no way to use the feature until it is enabled.
-
-## The cost of feature flags
-
-When reading the above, one might be tempted to think this procedure is going to
-add a lot of work. Fortunately, this is not the case, and we'll show why. For
-this example we'll specify the cost of the work to do as a number, ranging from
-0 to infinity. The greater the number, the more expensive the work is. The cost
-does _not_ translate to time, it's just a way of measuring complexity of one
-change relative to another.
-
-Let's say we are building a new feature, and we have determined that the cost of
-this is 10. We have also determined that the cost of adding a feature flag check
-in a variety of places is 1. If we do not use feature flags, and our feature
-works as intended, our total cost is 10. This however is the best case scenario.
-Optimising for the best case scenario is guaranteed to lead to trouble, whereas
-optimising for the worst case scenario is almost always better.
-
-To illustrate this, let's say our feature causes an outage, and there's no
-immediate way to resolve it. This means we'd have to take the following steps to
-resolve the outage:
-
-1. Revert the release.
-1. Perform any cleanups that might be necessary, depending on the changes that
-   were made.
-1. Revert the commit, ensuring the "master" branch remains stable. This is
-   especially necessary if solving the problem can take days or even weeks.
-1. Pick the revert commit into the appropriate stable branches, ensuring we
-   don't block any future releases until the problem is resolved.
-
-As history has shown, these steps are time consuming, complex, often involve
-many developers, and worst of all: our users will have a bad experience using
-GitLab.com until the problem is resolved.
-
-Now let's say that all of this has an associated cost of 10. This means that in
-the worst case scenario, which we should optimise for, our total cost is now 20.
-
-If we had used a feature flag, things would have been very different. We don't
-need to revert a release, and because feature flags are disabled by default we
-don't need to revert and pick any Git commits. In fact, all we have to do is
-disable the feature, and in the worst case, perform cleanup. Let's say that 
-the cost of this is 2. In this case, our best case cost is 11: 10 to build the 
-feature, and 1 to add the feature flag. The worst case cost is now 13: 10 to 
-build the feature, 1 to add the feature flag, and 2 to disable and clean up.
-
-Here we can see that in the best case scenario the work necessary is only a tiny
-bit more compared to not using a feature flag. Meanwhile, the process of
-reverting our changes has been made significantly and reliably cheaper.
-
-In other words, feature flags do not slow down the development process. Instead,
-they speed up the process as managing incidents now becomes _much_ easier. Once
-continuous deployments are easier to perform, the time to iterate on a feature
-is reduced even further, as you no longer need to wait weeks before your changes
-are available on GitLab.com.
-
-## Rolling out changes
-
-The procedure of using feature flags is straightforward, and similar to not
-using them. You add the necessary tests (make sure to test both the on and off
-states of your feature flag(s)), make sure they all pass, have the code
-reviewed, etc. You then submit your merge request, and add the ~"feature flag"
-label. This label is used to signal to release managers that your changes are
-hidden behind a feature flag and that it is safe to pick the MR into a stable
-branch, without the need for an exception request.
-
-When the changes are deployed it is time to start rolling out the feature to our
-users. The exact procedure of rolling out a change is unspecified, as this can
-vary from change to change. However, in general we recommend rolling out changes
-incrementally, instead of enabling them for everybody right away. We also
-recommend you to _not_ enable a feature _before_ the code is being deployed.
-This allows you to separate rolling out a feature from a deploy, making it
-easier to measure the impact of both separately.
-
-GitLab's feature library (using
-[Flipper](https://github.com/jnunemaker/flipper), and covered in the [Feature
-Flags](feature_flags.md) guide) supports rolling out changes to a percentage of
-users. This in turn can be controlled using [GitLab
-chatops](../ci/chatops/README.md).
-
-For an up to date list of feature flag commands please see [the source
-code](https://gitlab.com/gitlab-com/chatops/blob/master/lib/chatops/commands/feature.rb).
-Note that all the examples in that file must be preceded by
-`/chatops run`.
-
-If you get an error "Whoops! This action is not allowed. This incident
-will be reported." that means your Slack account is not allowed to
-change feature flags. To test if you are allowed to do anything at all,
-run:
-
-```
-/chatops run feature --help
-```
-
-For example, to enable a feature for 25% of all users, run the following in
-Slack:
-
-```
-/chatops run feature set new_navigation_bar 25
-```
-
-This will enable the feature for GitLab.com, with `new_navigation_bar` being the
-name of the feature. We can also enable the feature for <https://dev.gitlab.org>
-or <https://staging.gitlab.com>:
-
-```
-/chatops run feature set new_navigation_bar 25 --dev
-/chatops run feature set new_navigation_bar 25 --staging
-```
-
-If you are not certain what percentages to use, simply use the following steps:
-
-1. 25%
-1. 50%
-1. 75%
-1. 100%
-
-Between every step you'll want to wait a little while and monitor the
-appropriate graphs on <https://dashboards.gitlab.net>. The exact time to wait
-may differ. For some features a few minutes is enough, while for others you may
-want to wait several hours or even days. This is entirely up to you, just make
-sure it is clearly communicated to your team, and the Production team if you
-anticipate any potential problems.
-
-Feature gates can also be actor based, for example a feature could first be
-enabled for only the `gitlab-ce` project. The project is passed by supplying a
-`--project` flag:
-
-```
-/chatops run feature set --project=gitlab-org/gitlab-ce some_feature true
-```
-
-For groups the `--group` flag is available:
-
-```
-/chatops run feature set --group=gitlab-org some_feature true
-```
-
-Once a change is deemed stable, submit a new merge request to remove the
-feature flag. This ensures the change is available to all users and self-hosted
-instances. Make sure to add the ~"feature flag" label to this merge request so
-release managers are aware the changes are hidden behind a feature flag. If the
-merge request has to be picked into a stable branch (e.g. after the 7th), make
-sure to also add the appropriate "Pick into X" label (e.g. "Pick into 11.4").
-
-One might be tempted to think this will delay the release of a feature by at
-least one month (= one release). This is not the case. A feature flag does not
-have to stick around for a specific amount of time (e.g. at least one release),
-instead they should stick around until the feature is deemed stable. Stable
-means it works on GitLab.com without causing any problems, such as outages. In
-most cases this will translate to a feature (with a feature flag) being shipped
-in RC1, followed by the feature flag being removed in RC2. This in turn means
-the feature will be stable by the time we publish a stable package around the
-22nd of the month.
-
-## Implicit feature flags
-
-The [`Project#feature_available?`][project-fa],
-[`Namespace#feature_available?`][namespace-fa] (EE), and
-[`License.feature_available?`][license-fa] (EE) methods all implicitly check for
-a feature flag by the same name as the provided argument.
-
-For example if a feature is license-gated, there's no need to add an additional
-explicit feature flag check since the flag will be checked as part of the
-`License.feature_available?` call. Similarly, there's no need to "clean up" a
-feature flag once the feature has reached general availability.
-
-You'd still want to use an explicit `Feature.enabled?` check if your new feature
-isn't gated by a License or Plan.
-
-[project-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/app/models/project_feature.rb#L63-68
-[namespace-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/ee/namespace.rb#L71-85
-[license-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/license.rb#L293-300
-
-### Undefined feature flags default to "on"
-
-An important side-effect of the [implicit feature flags](#implicit-feature-flags) 
-mentioned above is that unless the feature is explicitly disabled or limited to a 
-percentage of users, the feature flag check will default to `true`.
-
-As an example, if you were to ship the backend half of a feature behind a flag,
-you'd want to explicitly disable that flag until the frontend half is also ready
-to be shipped. You can do this via ChatOps:
-
-```
-/chatops run feature set some_feature 0
-```
-
-Note that you can do this at any time, even before the merge request using the
-flag has been merged!
-
-### Cleaning up
-
-When a feature gate has been removed from the code base, the value still exists
-in the database. This can be removed through ChatOps:
-
-```
-/chatops run feature delete some_feature
-```
+This document was moved to [another location](feature_flags/index.md).
diff --git a/doc/development/routing.md b/doc/development/routing.md
index e9c0ad8d4e8..a25eb48b73c 100644
--- a/doc/development/routing.md
+++ b/doc/development/routing.md
@@ -7,11 +7,15 @@ support subgroups, GitLab project and group routes use the wildcard
 character to match project and group routes. For example, we might have
 a path such as:
 
-    /gitlab-com/customer-success/north-america/west/customerA
+```
+/gitlab-com/customer-success/north-america/west/customerA
+```
 
 However, paths can be ambiguous. Consider the following example:
 
-    /gitlab-com/edit
+```
+/gitlab-com/edit
+```
 
 It's ambiguous whether there is a subgroup named `edit` or whether
 this is a special endpoint to edit the `gitlab-com` group.
@@ -25,8 +29,10 @@ number of [reserved names](../user/reserved_names.md).
 
 We have a number of global routes. For example:
 
-    /-/health
-    /-/metrics
+```
+/-/health
+/-/metrics
+```
 
 ## Group routes
 
@@ -34,10 +40,12 @@ Every group route must be under the `/-/` scope.
 
 Examples:
 
-    gitlab-org/-/edit
-    gitlab-org/-/activity
-    gitlab-org/-/security/dashboard
-    gitlab-org/serverless/-/activity
+```
+gitlab-org/-/edit
+gitlab-org/-/activity
+gitlab-org/-/security/dashboard
+gitlab-org/serverless/-/activity
+```
 
 To achieve that, use the `scope '-'` method.
 
@@ -48,10 +56,12 @@ client or other software requires something different.
 
 Examples:
 
-    gitlab-org/gitlab-ce/-/activity
-    gitlab-org/gitlab-ce/-/jobs/123
-    gitlab-org/gitlab-ce/-/settings/repository
-    gitlab-org/serverless/runtimes/-/settings/repository
+```
+gitlab-org/gitlab-ce/-/activity
+gitlab-org/gitlab-ce/-/jobs/123
+gitlab-org/gitlab-ce/-/settings/repository
+gitlab-org/serverless/runtimes/-/settings/repository
+```
 
 Currently, only some project routes are placed under the `/-/` scope. However,
 you can help us migrate more of them! To migrate project routes:
diff --git a/doc/development/sha1_as_binary.md b/doc/development/sha1_as_binary.md
index 3151cc29bbc..6c4252ec634 100644
--- a/doc/development/sha1_as_binary.md
+++ b/doc/development/sha1_as_binary.md
@@ -2,7 +2,7 @@
 
 Storing SHA1 hashes as strings is not very space efficient. A SHA1 as a string
 requires at least 40 bytes, an additional byte to store the encoding, and
-perhaps more space depending on the internals of PostgreSQL and MySQL.
+perhaps more space depending on the internals of PostgreSQL.
 
 On the other hand, if one were to store a SHA1 as binary one would only need 20
 bytes for the actual SHA1, and 1 or 4 bytes of additional space (again depending
diff --git a/doc/development/shell_scripting_guide/index.md b/doc/development/shell_scripting_guide/index.md
new file mode 100644
index 00000000000..0809f8b1a0a
--- /dev/null
+++ b/doc/development/shell_scripting_guide/index.md
@@ -0,0 +1,118 @@
+# Shell scripting standards and style guidelines
+
+## Overview
+
+GitLab consists of many various services and sub-projects. The majority of
+their backend code is written in [Ruby](https://www.ruby-lang.org) and
+[Go](https://golang.org). However, some of them use shell scripts for
+automation of routine system administration tasks like deployment,
+installation, etc. It's being done either for historical reasons or as an effort
+to minimize the dependencies, for instance, for Docker images.
+
+This page aims to define and organize our shell scripting guidelines,
+based on our various experiences. All shell scripts across GitLab project
+should be eventually harmonized with this guide. If there are any per-project
+deviations from this guide, they should be described in the
+`README.md` or `PROCESS.md` file for such a project.
+
+### Avoid using shell scripts
+
+CAUTION: **Caution:**
+This is a must-read section.
+
+Having said all of the above, we recommend staying away from shell scripts
+as much as possible. A language like Ruby or Python (if required for
+consistency with codebases that we leverage) is almost always a better choice.
+The high-level interpreted languages have more readable syntax, offer much more
+mature capabilities for unit-testing, linting, and error reporting.
+
+Use shell scripts only if there's a strong restriction on project's
+dependencies size or any other requirements that are more important
+in a particular case.
+
+## Scope of this guide
+
+According to the [GitLab installation requirements](../../install/requirements.md),
+this guide covers only those shells that are used by
+[supported Linux distributions](../../install/requirements.md#supported-linux-distributions),
+that is:
+
+- [POSIX Shell](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html)
+- [Bash](https://www.gnu.org/software/bash/)
+
+## Shell language choice
+
+- When you need to reduce the dependencies list, use what's provided by the environment. For example, for Docker images it's `sh` from `alpine` which is the base image for most of our tool images.
+- Everywhere else, use `bash` if possible. It's more powerful than `sh` but still a widespread shell.
+
+## Code style and format
+
+This section describes the tools that should be made a mandatory part of
+a project's CI pipeline if it contains shell scripts. These tools
+automate shell code formatting, checking for errors or vulnerabilities, etc.
+
+### Linting
+
+We're using the [ShellCheck](https://www.shellcheck.net/) utility in its default configuration to lint our
+shell scripts.
+
+All projects with shell scripts should use this GitLab CI/CD job:
+
+```yaml
+shell check:
+  image: koalaman/shellcheck-alpine
+  stage: test
+  before_script:
+    - shellcheck --version
+  script:
+    - shellcheck scripts/**/*.sh # path to your shell scripts
+```
+
+TIP: **Tip:**
+By default, ShellCheck will use the [shell detection](https://github.com/koalaman/shellcheck/wiki/SC2148#rationale)
+to determine the shell dialect in use. If the shell file is out of your control and ShellCheck cannot
+detect the dialect, use `-s` flag to specify it: `-s sh` or `-s bash`.
+
+### Formatting
+
+It's recommended to use the [shfmt](https://github.com/mvdan/sh#shfmt) tool to maintain consistent formatting.
+We format shell scripts according to the [Google Shell Style Guide](https://google.github.io/styleguide/shell.xml),
+so the following `shfmt` invocation should be applied to the project's script files:
+
+```bash
+shfmt -i 2 -ci scripts/**/*.sh
+```
+
+TIP: **Tip:**
+By default, shfmt will use the [shell detection](https://github.com/mvdan/sh#shfmt) similar to one of ShellCheck
+and ignore files starting with a period. To override this, use `-ln` flag to specify the shell dialect:
+`-ln posix` or `-ln bash`.
+
+NOTE: **Note:**
+Currently, the `shfmt` tool [is not shipped](https://github.com/mvdan/sh/issues/68) as a Docker image containing
+a Linux shell. This makes it impossible to use the [official Docker image](https://hub.docker.com/r/mvdan/shfmt)
+in GitLab Runner. This [may change](https://github.com/mvdan/sh/issues/68#issuecomment-507721371) in future.
+
+## Testing
+
+NOTE: **Note:**
+This is a work in progress.
+
+It is an [ongoing effort](https://gitlab.com/gitlab-org/gitlab-ce/issues/64016) to evaluate different tools for the
+automated testing of shell scripts (like [BATS](https://github.com/sstephenson/bats)).
+
+## Code Review
+
+The code review should be performed according to:
+
+- [ShellCheck Checks list](https://github.com/koalaman/shellcheck/wiki/Checks)
+- [Google Shell Style Guide](https://google.github.io/styleguide/shell.xml)
+- [Shfmt formatting caveats](https://github.com/mvdan/sh#caveats)
+
+However, the recommended course of action is to use the aforementioned
+tools and address reported offenses. This should eliminate the need
+for code review.
+
+---
+
+[Return to Development documentation](../README.md).
diff --git a/doc/development/sql.md b/doc/development/sql.md
index edeca7fb298..2584dcfb4ca 100644
--- a/doc/development/sql.md
+++ b/doc/development/sql.md
@@ -15,14 +15,11 @@ FROM issues
 WHERE title LIKE 'WIP:%';
 ```
 
-On PostgreSQL the `LIKE` statement is case-sensitive. On MySQL this depends on
-the case-sensitivity of the collation, which is usually case-insensitive. To
-perform a case-insensitive `LIKE` on PostgreSQL you have to use `ILIKE` instead.
-This statement in turn isn't supported on MySQL.
+On PostgreSQL the `LIKE` statement is case-sensitive. To perform a case-insensitive
+`LIKE` you have to use `ILIKE` instead.
 
-To work around this problem you should write `LIKE` queries using Arel instead
-of raw SQL fragments as Arel automatically uses `ILIKE` on PostgreSQL and `LIKE`
-on MySQL. This means that instead of this:
+To handle this automatically you should use `LIKE` queries using Arel instead
+of raw SQL fragments, as Arel automatically uses `ILIKE` on PostgreSQL.
 
 ```ruby
 Issue.where('title LIKE ?', 'WIP:%')
@@ -45,7 +42,7 @@ table = Issue.arel_table
 Issue.where(table[:title].matches('WIP:%').or(table[:foo].matches('WIP:%')))
 ```
 
-For PostgreSQL this produces:
+On PostgreSQL, this produces:
 
 ```sql
 SELECT *
@@ -53,18 +50,10 @@ FROM issues
 WHERE (title ILIKE 'WIP:%' OR foo ILIKE 'WIP:%')
 ```
 
-In turn for MySQL this produces:
-
-```sql
-SELECT *
-FROM issues
-WHERE (title LIKE 'WIP:%' OR foo LIKE 'WIP:%')
-```
-
 ## LIKE & Indexes
 
-Neither PostgreSQL nor MySQL use any indexes when using `LIKE` / `ILIKE` with a
-wildcard at the start. For example, this will not use any indexes:
+PostgreSQL won't use any indexes when using `LIKE` / `ILIKE` with a wildcard at
+the start. For example, this will not use any indexes:
 
 ```sql
 SELECT *
@@ -75,9 +64,8 @@ WHERE title ILIKE '%WIP:%';
 Because the value for `ILIKE` starts with a wildcard the database is not able to
 use an index as it doesn't know where to start scanning the indexes.
 
-MySQL provides no known solution to this problem. Luckily PostgreSQL _does_
-provide a solution: trigram GIN indexes. These indexes can be created as
-follows:
+Luckily, PostgreSQL _does_ provide a solution: trigram GIN indexes. These
+indexes can be created as follows:
 
 ```sql
 CREATE INDEX [CONCURRENTLY] index_name_here
@@ -94,7 +82,9 @@ on the amount of data indexed).
 To keep naming of these indexes consistent please use the following naming
 pattern:
 
-    index_TABLE_on_COLUMN_trigram
+```
+index_TABLE_on_COLUMN_trigram
+```
 
 For example, a GIN/trigram index for `issues.title` would be called
 `index_issues_on_title_trigram`.
diff --git a/doc/development/swapping_tables.md b/doc/development/swapping_tables.md
index 29cd6a43aff..5c62900dbff 100644
--- a/doc/development/swapping_tables.md
+++ b/doc/development/swapping_tables.md
@@ -39,14 +39,6 @@ PostgreSQL you can use the `reset_pk_sequence!` method like so:
 reset_pk_sequence!('events')
 ```
 
-For MySQL however you need to do run the following:
-
-```ruby
-amount = Event.pluck('COALESCE(MAX(id), 1)').first
-
-execute "ALTER TABLE events AUTO_INCREMENT = #{amount}"
-```
-
 Failure to reset the primary keys will result in newly created rows starting
 with an ID value of 1. Depending on the existing data this can then lead to
 duplicate key constraints from popping up, preventing users from creating new
diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md
index 71e3b7740cb..f30a83a4c71 100644
--- a/doc/development/testing_guide/best_practices.md
+++ b/doc/development/testing_guide/best_practices.md
@@ -15,16 +15,6 @@ manifest themselves within our code. When designing our tests, take time to revi
 our test design. We can find some helpful heuristics documented in the Handbook in the
 [Test Design](https://about.gitlab.com/handbook/engineering/quality/guidelines/test-engineering/test-design/) section.
 
-## Run tests against MySQL
-
-By default, tests are only run against PostgreSQL, but you can run them on
-demand against MySQL by following one of the following conventions:
-
-| Convention           | Valid example                |
-|:----------------------|:-----------------------------|
-| Include `mysql` in your branch name | `enhance-mysql-support` |
-| Include `[run mysql]` in your commit message   | `Fix MySQL support<br><br>[run mysql]` |
-
 ## Test speed
 
 GitLab has a massive test suite that, without [parallelization], can take hours
@@ -70,6 +60,7 @@ bundle exec rspec spec/[path]/[to]/[spec].rb
 - On `before` and `after` hooks, prefer it scoped to `:context` over `:all`
 - When using `evaluate_script("$('.js-foo').testSomething()")` (or `execute_script`) which acts on a given element,
   use a Capyabara matcher beforehand (e.g. `find('.js-foo')`) to ensure the element actually exists.
+- Use `focus: true` to isolate parts of the specs you want to run.
 
 [four-phase-test]: https://robots.thoughtbot.com/four-phase-test
 
@@ -327,7 +318,7 @@ However, if a spec makes direct Redis calls, it should mark itself with the
 `:clean_gitlab_redis_queues` traits as appropriate.
 
 Sidekiq jobs are typically not run in specs, but this behaviour can be altered
-in each spec through the use of `Sidekiq::Testing.inline!` blocks. Any spec that
+in each spec through the use of `perform_enqueued_jobs` blocks. Any spec that
 causes Sidekiq jobs to be pushed to Redis should use the `:sidekiq` trait, to
 ensure that they are removed once the spec completes.
 
@@ -454,6 +445,19 @@ complexity of RSpec expectations.They should be placed under
 a certain type of specs only (e.g. features, requests etc.) but shouldn't be if
 they apply to multiple type of specs.
 
+#### `be_like_time`
+
+Time returned from a database can differ in precision from time objects
+in Ruby, so we need flexible tolerances when comparing in specs. We can
+use `be_like_time` to compare that times are within one second of each
+other.
+
+Example:
+
+```ruby
+expect(metrics.merged_at).to be_like_time(time)
+```
+
 #### `have_gitlab_http_status`
 
 Prefer `have_gitlab_http_status` over `have_http_status` because the former
diff --git a/doc/development/testing_guide/ci.md b/doc/development/testing_guide/ci.md
index 7a7fca46534..d9f66a827de 100644
--- a/doc/development/testing_guide/ci.md
+++ b/doc/development/testing_guide/ci.md
@@ -1,6 +1,6 @@
 # GitLab tests in the Continuous Integration (CI) context
 
-### Test suite parallelization on the CI
+## Test suite parallelization on the CI
 
 Our current CI parallelization setup is as follows:
 
@@ -26,7 +26,7 @@ Our current CI parallelization setup is as follows:
 After that, the next pipeline will use the up-to-date
 `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file.
 
-### Monitoring
+## Monitoring
 
 The GitLab test suite is [monitored] for the `master` branch, and any branch
 that includes `rspec-profile` in their name.
@@ -39,7 +39,6 @@ slowest test files and try to improve them.
 
 ## CI setup
 
-- On CE and EE, the test suite runs both PostgreSQL and MySQL.
 - Rails logging to `log/test.log` is disabled by default in CI [for
   performance reasons][logging]. To override this setting, provide the
   `RAILS_ENABLE_TEST_LOG` environment variable.
diff --git a/doc/development/testing_guide/end_to_end/dynamic_element_validation.md b/doc/development/testing_guide/end_to_end/dynamic_element_validation.md
index f7b3ca8bc89..aec0a3ede5a 100644
--- a/doc/development/testing_guide/end_to_end/dynamic_element_validation.md
+++ b/doc/development/testing_guide/end_to_end/dynamic_element_validation.md
@@ -5,8 +5,8 @@ We devised a solution to solve common test automation problems such as the dread
 Other problems that dynamic element validations solve are...
 
 - When we perform an action with the mouse, we expect something to occur.
-- When our test is navigating to (or from) a page, we ensure that we are on the page we expect before 
-test continuation.
+- When our test is navigating to (or from) a page, we ensure that we are on the page we expect before
+  test continuation.
 
 ## How it works
 
@@ -19,7 +19,7 @@ We interpret user actions on the page to have some sort of effect. These actions
 
 When a page is navigated to, there are elements that will always appear on the page unconditionally.
 
-Dynamic element validation is instituted when using 
+Dynamic element validation is instituted when using
 
 ```ruby
 Runtime::Browser.visit(:gitlab, Some::Page)
@@ -27,7 +27,7 @@ Runtime::Browser.visit(:gitlab, Some::Page)
 
 ### Clicks
 
-When we perform a click within our tests, we expect something to occur.  That something could be a component to now 
+When we perform a click within our tests, we expect something to occur.  That something could be a component to now
 appear on the webpage, or the test to navigate away from the page entirely.
 
 Dynamic element validation is instituted when using
@@ -71,7 +71,7 @@ class MyPage < Page::Base
     element :another_element, required: true
     element :conditional_element
   end
-  
+
   def open_layer
     click_element :my_element, Layer::MyLayer
   end
@@ -95,7 +95,7 @@ execute_stuff
 ```
 
 will invoke GitLab QA to scan `MyPage` for `my_element` and `another_element` to be on the page before continuing to
-`execute_stuff` 
+`execute_stuff`
 
 ### Clicking
 
diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md
index afd81ff00b2..d6b944a3e74 100644
--- a/doc/development/testing_guide/end_to_end/index.md
+++ b/doc/development/testing_guide/end_to_end/index.md
@@ -65,28 +65,23 @@ Below you can read more about how to use it and how does it work.
 Currently, we are using _multi-project pipeline_-like approach to run QA
 pipelines.
 
-![QA on merge requests CI/CD architecture](../img/qa_on_merge_requests_cicd_architecture.png)
-
-<details>
-<summary>Show mermaid source</summary>
-<pre>
+```mermaid
 graph LR
     A1 -.->|1. Triggers an omnibus-gitlab pipeline and wait for it to be done| A2
-    B2[<b>`Trigger-qa` stage</b><br />`Trigger:qa-test` job] -.->|2. Triggers a gitlab-qa pipeline and wait for it to be done| A3
+    B2[`Trigger-qa` stage<br>`Trigger:qa-test` job] -.->|2. Triggers a gitlab-qa pipeline and wait for it to be done| A3
 
-subgraph gitlab-ce/ee pipeline
-    A1[<b>`test` stage</b><br />`package-and-qa` job]
+subgraph "gitlab-ce/ee pipeline"
+    A1[`test` stage<br>`package-and-qa` job]
     end
 
-subgraph omnibus-gitlab pipeline
-    A2[<b>`Trigger-docker` stage</b></b><br />`Trigger:gitlab-docker` job] -->|once done| B2
+subgraph "omnibus-gitlab pipeline"
+    A2[`Trigger-docker` stage<br>`Trigger:gitlab-docker` job] -->|once done| B2
     end
 
-subgraph gitlab-qa pipeline
-    A3>QA jobs run] -.->|3. Reports back the pipeline result to the `package-and-qa` job<br />and post the result  on the original commit tested| A1
+subgraph "gitlab-qa pipeline"
+    A3>QA jobs run] -.->|3. Reports back the pipeline result to the `package-and-qa` job<br>and post the result  on the original commit tested| A1
     end
-</pre>
-</details>
+```
 
 1. Developer triggers a manual action, that can be found in CE / EE merge
    requests. This starts a chain of pipelines in multiple projects.
@@ -126,6 +121,18 @@ See [Review Apps][review-apps] for more details about Review Apps.
 [helm-chart]: https://gitlab.com/charts/gitlab/
 [cng]: https://gitlab.com/gitlab-org/build/CNG
 
+## How do I run the tests?
+
+There are two main options for running the tests. If you simply want to run the
+existing tests against a live GitLab instance or against a pre-built docker image
+you can use the [GitLab QA orchestrator][gitlab-qa-readme]. See also [examples
+of the test scenarios you can run via the orchestrator](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/what_tests_can_be_run.md#examples).
+
+On the other hand, if you would like to run against a local development GitLab
+environment, you can use the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/).
+Please refer to the instructions in the [QA README](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/README.md#how-can-i-use-it)
+and the section below.
+
 ## How do I write tests?
 
 In order to write new tests, you first need to learn more about GitLab QA
@@ -136,7 +143,7 @@ Once you decided where to put [test environment orchestration scenarios] and
 the [GitLab QA orchestrator README][gitlab-qa-readme], and [the already existing
 instance-level scenarios][instance-level scenarios].
 
-Continued reading:  
+Continued reading:
 
 - [Quick Start Guide](quick_start_guide.md)
 - [Style Guide](style_guide.md)
diff --git a/doc/development/testing_guide/end_to_end/page_objects.md b/doc/development/testing_guide/end_to_end/page_objects.md
index 73e1fd862c1..47e58a425fd 100644
--- a/doc/development/testing_guide/end_to_end/page_objects.md
+++ b/doc/development/testing_guide/end_to_end/page_objects.md
@@ -27,7 +27,7 @@ When someone later changes `t.text_field :login` in the view associated with
 this page to `t.text_field :username` it will generate a different field
 identifier, what would effectively break all tests.
 
-Because we are using `Page::Main::Login.act { sign_in_using_credentials }`
+Because we are using `Page::Main::Login.perform(&:sign_in_using_credentials)`
 everywhere, when we want to sign into GitLab, the page object is the single
 source of truth, and we will need to update `fill_in :user_login`
 to `fill_in :user_username` only in a one place.
@@ -82,7 +82,7 @@ module Page
       end
 
       # ...
-    end 
+    end
   end
 end
 ```
@@ -92,20 +92,25 @@ end
 The `view` DSL method will correspond to the rails View, partial, or vue component that renders the elements.
 
 The `element` DSL method in turn declares an element for which a corresponding
-`qa-element-name-dasherized` CSS class will need to be added to the view file.
+`data-qa-selector=element_name_snaked` data attribute will need to be added to the view file.
 
 You can also define a value (String or Regexp) to match to the actual view
 code but **this is deprecated** in favor of the above method for two reasons:
 
 - Consistency: there is only one way to define an element
-- Separation of concerns: QA uses dedicated CSS classes instead of reusing code
+- Separation of concerns: QA uses dedicated `data-qa-*` attributes instead of reusing code
   or classes used by other components (e.g. `js-*` classes etc.)
 
 ```ruby
 view 'app/views/my/view.html.haml' do
-  # Implicitly require `.qa-logout-button` CSS class to be present in the view
+
+  ### Good ###
+
+  # Implicitly require the CSS selector `[data-qa-selector="logout_button"]` to be present in the view
   element :logout_button
 
+  ### Bad ###
+
   ## This is deprecated and forbidden by the `QA/ElementWithPattern` RuboCop cop.
   # Require `f.submit "Sign in"` to be present in `my/view.html.haml
   element :my_button, 'f.submit "Sign in"' # rubocop:disable QA/ElementWithPattern
@@ -129,24 +134,38 @@ view 'app/views/my/view.html.haml' do
 end
 ```
 
-To add these elements to the view, you must change the rails View, partial, or vue component by adding a `qa-element-descriptor` class
+To add these elements to the view, you must change the rails View, partial, or vue component by adding a `data-qa-selector` attribute
 for each element defined.
 
-In our case, `qa-login-field`, `qa-password-field` and `qa-sign-in-button`
+In our case, `data-qa-selector="login_field"`, `data-qa-selector="password_field"` and `data-qa-selector="sign_in_button"`
 
-**app/views/my/view.html.haml**  
+**app/views/my/view.html.haml**
 
 ```haml
-= f.text_field :login, class: "form-control top qa-login-field", autofocus: "autofocus", autocapitalize: "off", autocorrect: "off", required: true, title: "This field is required."
-= f.password_field :password, class: "form-control bottom qa-password-field", required: true, title: "This field is required."
-= f.submit "Sign in", class: "btn btn-success qa-sign-in-button"
+= f.text_field :login, class: "form-control top", autofocus: "autofocus", autocapitalize: "off", autocorrect: "off", required: true, title: "This field is required.", data: { qa_selector: 'login_field' }
+= f.password_field :password, class: "form-control bottom", required: true, title: "This field is required.", data: { qa_selector: 'password_field' }
+= f.submit "Sign in", class: "btn btn-success", data: { qa_selector: 'sign_in_button' }
 ```
 
 Things to note:
 
-- The CSS class must be `kebab-cased` (separated with hyphens "`-`")
+- The name of the element and the qa_selector must match and be snake_cased
 - If the element appears on the page unconditionally, add `required: true` to the element. See
-[Dynamic element validation](dynamic_element_validation.md)
+  [Dynamic element validation](dynamic_element_validation.md)
+- You may see `.qa-selector` classes in existing Page Objects.  We should prefer the [`data-qa-selector`](#data-qa-selector-vs-qa-selector)
+  method of definition over the `.qa-selector` CSS class
+
+### `data-qa-selector` vs `.qa-selector`
+
+> Introduced in GitLab 12.1
+
+There are two supported methods of defining elements within a view.
+
+1. `data-qa-selector` attribute
+1. `.qa-selector` class
+
+Any existing `.qa-selector` class should be considered deprecated
+and we should prefer the `data-qa-selector` method of definition.
 
 ## Running the test locally
 
diff --git a/doc/development/testing_guide/end_to_end/quick_start_guide.md b/doc/development/testing_guide/end_to_end/quick_start_guide.md
index 521e3e56e7a..e1df8be8b6f 100644
--- a/doc/development/testing_guide/end_to_end/quick_start_guide.md
+++ b/doc/development/testing_guide/end_to_end/quick_start_guide.md
@@ -101,7 +101,7 @@ it 'replaces an existing label if it has the same key' do
   page.find('#content-body').click
   page.refresh
 
-  labels_block = page.find('.qa-labels-block')
+  labels_block = page.find(%q([data-qa-selector="labels_block"]))
 
   expect(labels_block).to have_content('animal::dolphin')
   expect(labels_block).not_to have_content('animal::fox')
@@ -110,15 +110,15 @@ end
 ```
 
 > Notice that the test itself is simple. The most challenging part is the creation of the application state, which will be covered later.
-
+>
 > The exemplified test case's MVC is not enough for the change to be merged, but it helps to build up the test logic. The reason is that we do not want to use locators directly in the tests, and tests **must** use [Page Objects] before they can be merged. This way we better separate the responsibilities, where the Page Objects encapsulate elements and methods that allow us to interact with pages, while the spec files describe the test cases in more business-related language.
 
 Below are the steps that the test covers:
 
 1. The test finds the 'Edit' link for the labels and clicks on it.
-2. Then it fills in the 'Assign labels' input field with the value 'animal::dolphin' and press enters.
-3. Then it clicks in the content body to apply the label and refreshes the page.
-4. Finally, the expectations check that the previous scoped label was removed and that the new one was added.
+1. Then it fills in the 'Assign labels' input field with the value 'animal::dolphin' and press enters.
+1. Then it clicks in the content body to apply the label and refreshes the page.
+1. Finally, the expectations check that the previous scoped label was removed and that the new one was added.
 
 Let's now see how the second test case would look.
 
@@ -130,7 +130,7 @@ it 'keeps both scoped labels when adding a label with a different key' do
   page.find('#content-body').click
   page.refresh
 
-  labels_block = page.find('.qa-labels-block')
+  labels_block = page.find(%q([data-qa-selector="labels_block"]))
 
   expect(labels_block).to have_content('animal::fox')
   expect(labels_block).to have_content('plant::orchid')
@@ -139,14 +139,14 @@ it 'keeps both scoped labels when adding a label with a different key' do
 end
 ```
 
-> Note that elements are always located using CSS selectors, and a good practice is to add test-specific selectors (this is called adding testability to the application and we will talk more about it later.) For example, the `labels_block` element uses the selector `.qa-labels-block`, which was added specifically for testing purposes.
+> Note that elements are always located using CSS selectors, and a good practice is to add test-specific selectors (this is called "testability"). For example, the `labels_block` element uses the CSS selector [`data-qa-selector="labels_block"`](page_objects.md#data-qa-selector-vs-qa-selector), which was added specifically for testing purposes.
 
 Below are the steps that the test covers:
 
 1. The test finds the 'Edit' link for the labels and clicks on it.
-2. Then it fills in the 'Assign labels' input field with the value 'plant::orchid' and press enters.
-3. Then it clicks in the content body to apply the label and refreshes the page.
-4. Finally, the expectations check that both scoped labels are present.
+1. Then it fills in the 'Assign labels' input field with the value 'plant::orchid' and press enters.
+1. Then it clicks in the content body to apply the label and refreshes the page.
+1. Finally, the expectations check that both scoped labels are present.
 
 > Similar to the previous test, this one is also very straightforward, but there is some code duplication. Let's address it.
 
@@ -168,7 +168,7 @@ end
 it 'replaces an existing label if it has the same key' do
   select_label_and_refresh @new_label_same_scope
 
-  labels_block = page.find('.qa-labels-block')
+  labels_block = page.find(%q([data-qa-selector="labels_block"]))
 
   expect(labels_block).to have_content(@new_label_same_scope)
   expect(labels_block).not_to have_content(@initial_label)
@@ -179,7 +179,7 @@ end
 it 'keeps both scoped label when adding a label with a different key' do
   select_label_and_refresh @new_label_different_scope
 
-  labels_block = page.find('.qa-labels-block')
+  labels_block = page.find(%q([data-qa-selector="labels_block"]))
 
   expect(labels_blocks).to have_content(@new_label_different_scope)
   expect(labels_blocks).to have_content(@initial_label)
@@ -211,7 +211,7 @@ A pre-condition for the entire test suite is defined in the `before :context` bl
 
 > For our test suite, due to the need of the tests being completely independent of each other, we won't use the `before :context` block. The `before :context` block would make the tests dependent on each other because the first test changes the label of the issue, and the second one depends on the `'animal::fox'` label being set.
 
-> **Tip:** In case of a test suite with only one `it` block it's ok to use only the `before` block (see below) with all the test's pre-conditions.
+TIP: **Tip:** In case of a test suite with only one `it` block it's ok to use only the `before` block (see below) with all the test's pre-conditions.
 
 #### `before`
 
@@ -222,7 +222,7 @@ As the pre-conditions for our test suite, the things that needs to happen before
 - A project being created with an issue and labels already set;
 - The issue page being opened with only one scoped label applied to it.
 
-> When running end-to-end tests as part of the GitLab's continuous integration process [a license is already set as an environment variable](https://gitlab.com/gitlab-org/gitlab-ee/blob/1a60d926740db10e3b5724713285780a4f470531/qa/qa/ee/strategy.rb#L20). For running tests locally you can set up such license by following the document [what tests can be run?](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/what_tests_can_be_run.md#supported-remote-grid-environment-variables), based on the [supported GitLab environment variables](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/what_tests_can_be_run.md#supported-gitlab-environment-variables).
+> When running end-to-end tests as part of the GitLab's continuous integration process [a license is already set as an environment variable](https://gitlab.com/gitlab-org/gitlab-ee/blob/1a60d926740db10e3b5724713285780a4f470531/qa/qa/ee/strategy.rb#L20). For running tests locally you can set up such license by following the document [what tests can be run?](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/what_tests_can_be_run.md), based on the [supported GitLab environment variables](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/what_tests_can_be_run.md#supported-gitlab-environment-variables).
 
 #### Implementation
 
@@ -242,12 +242,12 @@ module QA
 
         issue = Resource::Issue.fabricate_via_api! do |issue|
           issue.title = 'Issue to test the scoped labels'
-          issue.labels = @initial_label
+          issue.labels = [@initial_label]
         end
 
         [@new_label_same_scope, @new_label_different_scope].each do |label|
           Resource::Label.fabricate_via_api! do |l|
-            l.project = issue.project.id
+            l.project = issue.project
             l.title = label
           end
         end
@@ -274,11 +274,11 @@ end
 In the `before` block we create all the application state needed for the tests to run. We do that by using the `Runtime::Browser.visit` method to go to the login page, by performing a `sign_in_using_credentials` from the `Login` Page Object, by fabricating resources via APIs (`issue`, and `Resource::Label`), and by using the `issue.visit!` to visit the issue page.
 
 > A project is created in the background by creating the `issue` resource.
-
+>
 > When creating the [Resources], notice that when calling the `fabricate_via_api` method, we pass some attribute:values, like `title`, and `labels` for the `issue` resource; and `project` and `title` for the `label` resource.
-
+>
 > What's important to understand here is that by creating the application state mostly using the public APIs we save a lot of time in the test suite setup stage.
-
+>
 > Soon we will cover the use of the already existing resources' methods and the creation of your own `fabricate_via_api` methods for resources where this is still not available, but first, let's optimize our implementation.
 
 ### 6. Optimization
@@ -290,7 +290,7 @@ As already mentioned in the [best practices](best_practices.md) document, end-to
 Some improvements that we could make in our test suite to optimize its time to run are:
 
 1. Having a single test case (an `it` block) that exercises both scenarios to avoid "wasting" time in the tests' pre-conditions, instead of having two different test cases.
-2. Making the selection of labels more performant by allowing for the selection of more than one label in the same reusable method.
+1. Making the selection of labels more performant by allowing for the selection of more than one label in the same reusable method.
 
 Let's look at a suggestion that addresses the above points, one by one:
 
@@ -305,7 +305,7 @@ module QA
         it 'correctly applies scoped labels depending on if they are from the same or a different scope' do
           select_labels_and_refresh [@new_label_same_scope, @new_label_different_scope]
 
-          labels_block = page.all('.qa-labels-block')
+          labels_block = page.all(%q([data-qa-selector="labels_block"]))
 
           expect(labels_block).to have_content(@new_label_same_scope)
           expect(labels_block).to have_content(@new_label_different_scope)
@@ -332,8 +332,8 @@ To address point 1, we changed the test implementation from two `it` blocks into
 > Notice that the implementation of the new and unique `it` block had to change a little bit. Below we describe in details what it does.
 
 1. It selects two scoped labels simultaneously, one from the same scope of the one already applied in the issue during the setup phase (in the `before` block), and another one from a different scope.
-2. It asserts that the correct labels are visible in the `labels_block`, and that the labels were correctly added and removed;
-3. Finally, the `select_label_and_refresh` method is changed to `select_labels_and_refresh`, which accepts an array of labels instead of a single label, and it iterates on them for faster label selection (this is what is used in step 1 explained above.)
+1. It asserts that the correct labels are visible in the `labels_block`, and that the labels were correctly added and removed;
+1. Finally, the `select_label_and_refresh` method is changed to `select_labels_and_refresh`, which accepts an array of labels instead of a single label, and it iterates on them for faster label selection (this is what is used in step 1 explained above.)
 
 ### 7. Resources
 
@@ -357,13 +357,21 @@ In the following we describe the changes needed in each of the resource files me
 
 Now, let's make it possible to create an issue resource through the API.
 
-First, in the [issue resource](https://gitlab.com/gitlab-org/gitlab-ee/blob/d3584e80b4236acdf393d815d604801573af72cc/qa/qa/resource/issue.rb), let's expose its labels attribute.
+First, in the [issue resource](https://gitlab.com/gitlab-org/gitlab-ee/blob/d3584e80b4236acdf393d815d604801573af72cc/qa/qa/resource/issue.rb), let's expose its id and labels attributes.
 
-Add the following `attribute :labels` right above the [`attribute :title`](https://gitlab.com/gitlab-org/gitlab-ee/blob/d3584e80b4236acdf393d815d604801573af72cc/qa/qa/resource/issue.rb#L15).
+Add the following `attribute :id` and `attribute :labels` right above the [`attribute :title`](https://gitlab.com/gitlab-org/gitlab-ee/blob/d3584e80b4236acdf393d815d604801573af72cc/qa/qa/resource/issue.rb#L15).
 
-> This line is needed to allow for labels to be automatically added to an issue when fabricating it via API.
+> This line is needed to allow for the issue fabrication, and for labels to be automatically added to the issue when fabricating it via API.
+>
+> We add the attributes above the existing attribute to keep them alphabetically organized.
 
-> We add the new line above the existing attribute to keep them alphabetically organized.
+Then, let's initialize an instance variable for labels to allow an empty array as default value when such information is not passed during the resource fabrication, since this optional. [Between the attributes and the `fabricate!` method](https://gitlab.com/gitlab-org/gitlab-ee/blob/1a1f1408728f19b2aa15887cd20bddab7e70c8bd/qa/qa/resource/issue.rb#L18), add the following:
+
+```ruby
+def initialize
+  @labels = []
+end
+```
 
 Next, add the following code right below the [`fabricate!`](https://gitlab.com/gitlab-org/gitlab-ee/blob/d3584e80b4236acdf393d815d604801573af72cc/qa/qa/resource/issue.rb#L27) method.
 
@@ -378,7 +386,7 @@ end
 
 def api_post_body
   {
-    labels: [labels],
+    labels: labels,
     title: title
   }
 end
@@ -386,15 +394,15 @@ end
 
 By defining the `api_get_path` method, we allow the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to get a single issue.
 
-> This `GET` path can be found in the [public API documentation](https://docs.gitlab.com/ee/api/issues.html#single-issue).
+> This `GET` path can be found in the [public API documentation](../../../api/issues.md#single-issue).
 
 By defining the `api_post_path` method, we allow the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to create a new issue in a specific project.
 
-> This `POST` path can be found in the [public API documentation](https://docs.gitlab.com/ee/api/issues.html#new-issue).
+> This `POST` path can be found in the [public API documentation](../../../api/issues.md#new-issue).
 
 By defining the `api_post_body` method, we allow the [`ApiFabricator.api_post`](https://gitlab.com/gitlab-org/gitlab-ee/blob/a9177ca1812bac57e2b2fa4560e1d5dd8ffac38b/qa/qa/resource/api_fabricator.rb#L68) method to know which data to send when making the `POST` request.
 
-> Notice that we pass both `labels` and `title` attributes in the `api_post_body`, where `labels` receives an array of labels, and [`title` is required](https://docs.gitlab.com/ee/api/issues.html#new-issue). Also, notice that we keep them alphabetically organized.
+> Notice that we pass both `labels` and `title` attributes in the `api_post_body`, where `labels` receives an array of labels, and [`title` is required](../../../api/issues.md#new-issue). Also, notice that we keep them alphabetically organized.
 
 **Label resource**
 
@@ -414,7 +422,7 @@ def api_get_path
 end
 
 def api_post_path
-  "/projects/#{project}/labels"
+  "/projects/#{project.id}/labels"
 end
 
 def api_post_body
@@ -429,11 +437,11 @@ By defining the `resource_web_url(resource)` method, we override the one from th
 
 By defining the `api_get_path` method, we **would** allow for the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to get a single label, but since there's no path available for that in the publich API, we raise a `NotImplementedError` instead.
 
-By defining the `api_post_path` method, we allow for the [`ApiFabricator `](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to create a new label in a specific project.
+By defining the `api_post_path` method, we allow for the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to create a new label in a specific project.
 
 By defining the `api_post_body` method, we we allow for the [`ApiFabricator.api_post`](https://gitlab.com/gitlab-org/gitlab-ee/blob/a9177ca1812bac57e2b2fa4560e1d5dd8ffac38b/qa/qa/resource/api_fabricator.rb#L68) method to know which data to send when making the `POST` request.
 
-> Notice that we pass both `color` and `name` attributes in the `api_post_body` since [those are required](https://docs.gitlab.com/ee/api/labels.html#create-a-new-label). Also, notice that we keep them alphabetically organized.
+> Notice that we pass both `color` and `name` attributes in the `api_post_body` since [those are required](../../../api/labels.md#create-a-new-label). Also, notice that we keep them alphabetically organized.
 
 ### 8. Page Objects
 
@@ -532,10 +540,11 @@ end
 ##### Details of `select_labels_and_refresh`
 
 Notice that we have not only moved the `select_labels_and_refresh` method, but we have also changed its implementation to:
+
 1. Click the `:edit_link_labels` element previously defined, instead of using `find('.block.labels .edit-link').click`
-2. Use `within_element(:dropdown_menu_labels, text: label)`, and inside of it, we call `send_keys_to_element(:dropdown_input_field, [label, :enter])`, which is a method that we will implement in the `QA::Page::Base` class to replace `find('.dropdown-menu-labels .dropdown-input-field').send_keys [label, :enter]`
-3. Use `click_body` after iterating on each label, instead of using `find('#content-body').click`
-4. Iterate on every label again, and then we use `has_element?(:labels_block, text: label)` after clicking the page body (which applies the labels), and before refreshing the page, to avoid test flakiness due to refreshing too fast.
+1. Use `within_element(:dropdown_menu_labels, text: label)`, and inside of it, we call `send_keys_to_element(:dropdown_input_field, [label, :enter])`, which is a method that we will implement in the `QA::Page::Base` class to replace `find('.dropdown-menu-labels .dropdown-input-field').send_keys [label, :enter]`
+1. Use `click_body` after iterating on each label, instead of using `find('#content-body').click`
+1. Iterate on every label again, and then we use `has_element?(:labels_block, text: label)` after clicking the page body (which applies the labels), and before refreshing the page, to avoid test flakiness due to refreshing too fast.
 
 ##### Details of `text_of_labels_block`
 
@@ -543,25 +552,36 @@ The `text_of_labels_block` method is a simple method that returns the `:labels_b
 
 #### Updates in the view (*.html.haml) and `dropdowns_helper.rb` files
 
-Now let's change the view and the `dropdowns_helper` files to add the selectors that relate to the Page Object.
+Now let's change the view and the `dropdowns_helper` files to add the selectors that relate to the [Page Objects].
 
-In the [app/views/shared/issuable/_sidebar.html.haml](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/app/views/shared/issuable/_sidebar.html.haml) file, on [line 105 ](https://gitlab.com/gitlab-org/gitlab-ee/blob/84043fa72ca7f83ae9cde48ad670e6d5d16501a3/app/views/shared/issuable/_sidebar.html.haml#L105), add an extra class `qa-edit-link-labels`.
+In  [`app/views/shared/issuable/_sidebar.html.haml:105`](https://gitlab.com/gitlab-org/gitlab-ee/blob/7ca12defc7a965987b162a6ebef302f95dc8867f/app/views/shared/issuable/_sidebar.html.haml#L105), add a `data: { qa_selector: 'edit_link_labels' }` data attribute.
 
-The code should look like this: `= link_to _('Edit'), '#', class: 'js-sidebar-dropdown-toggle edit-link float-right qa-edit-link-labels'`.
+The code should look like this:
 
-In the same file, on [line 121](https://gitlab.com/gitlab-org/gitlab-ee/blob/84043fa72ca7f83ae9cde48ad670e6d5d16501a3/app/views/shared/issuable/_sidebar.html.haml#L121), add an extra class `.qa-dropdown-menu-labels`.
+```haml
+= link_to _('Edit'), '#', class: 'js-sidebar-dropdown-toggle edit-link float-right', data: { qa_selector: 'edit_link_labels' }
+```
 
-The code should look like this: `.dropdown-menu.dropdown-select.dropdown-menu-paging.dropdown-menu-labels.dropdown-menu-selectable.qa-dropdown-menu-labels`.
+In the same file, on [line 121](https://gitlab.com/gitlab-org/gitlab-ee/blob/7ca12defc7a965987b162a6ebef302f95dc8867f/app/views/shared/issuable/_sidebar.html.haml#L121), add a `data: { qa_selector: 'dropdown_menu_labels' }` data attribute.
 
-In the [`dropdowns_helper.rb`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/app/helpers/dropdowns_helper.rb) file, on [line 94](https://gitlab.com/gitlab-org/gitlab-ee/blob/99e51a374f2c20bee0989cac802e4b5621f72714/app/helpers/dropdowns_helper.rb#L94), add an extra class `qa-dropdown-input-field`.
+The code should look like this:
 
-The code should look like this: `filter_output = search_field_tag search_id, nil, class: "dropdown-input-field qa-dropdown-input-field", placeholder: placeholder, autocomplete: 'off'`.
+```haml
+.dropdown-menu.dropdown-select.dropdown-menu-paging.dropdown-menu-labels.dropdown-menu-selectable.dropdown-extended-height{ data: { qa_selector: 'dropdown_menu_labels' } }
+```
 
-> Classes starting with `qa-` are used for testing purposes only, and by defining such classes in the elements we add **testability** in the application.
+In [`app/helpers/dropdowns_helper.rb:94`](https://gitlab.com/gitlab-org/gitlab-ee/blob/7ca12defc7a965987b162a6ebef302f95dc8867f/app/helpers/dropdowns_helper.rb#L94), add a `data: { qa_selector: 'dropdown_input_field' }` data attribute.
 
-> When defining a class like `qa-labels-block`, it is transformed into `:labels_block` for usage in the Page Objects. So, `qa-edit-link-labels` is transformed into `:edit_link_labels`, `qa-dropdown-menu-labels` is transformed into `:dropdown_menu_labels`, and `qa-dropdown-input-field` is transformed into `:dropdown_input_field`. Also, we use a [sanity test](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/qa/page#how-did-we-solve-fragile-tests-problem) to check that defined elements have their respective `qa-` selectors in the specified views.
+The code should look like this:
 
-> We did not define the `qa-labels-block` class in the `app/views/shared/issuable/_sidebar.html.haml` file because it was already there to be used.
+```ruby
+filter_output = search_field_tag search_id, nil, class: "dropdown-input-field", placeholder: placeholder, autocomplete: 'off', data: { qa_selector: 'dropdown_input_field' }
+```
+
+> `data-qa-*` data attributes and CSS classes starting with `qa-` are used solely for the purpose of QA and testing.
+> By defining these, we add **testability** to the application.
+>
+> When defining a data attribute like: `qa_selector: 'labels_block'`, it should match the element definition: `element :labels_block`. We use a [sanity test](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/qa/page#how-did-we-solve-fragile-tests-problem) to check that defined elements have their respective selectors in the specified views.
 
 #### Updates in the `QA::Page::Base` class
 
@@ -579,8 +599,6 @@ This method receives an element (`name`) and the `keys` that it will send to tha
 
 As you might remember, in the Issue Page Object we call this method like this: `send_keys_to_element(:dropdown_input_field, [label, :enter])`.
 
-___
-
 With that, you should be able to start writing end-to-end tests yourself. *Congratulations!*
 
 [Page Objects]: page_objects.md
diff --git a/doc/development/testing_guide/end_to_end/style_guide.md b/doc/development/testing_guide/end_to_end/style_guide.md
index 0272e1810f2..97560e616a1 100644
--- a/doc/development/testing_guide/end_to_end/style_guide.md
+++ b/doc/development/testing_guide/end_to_end/style_guide.md
@@ -45,7 +45,7 @@ Notice that in the above example, before clicking the `:operations_environments_
 
 > We can create these methods as helpers to abstract multi-step navigation.
 
-### Element naming convention
+## Element naming convention
 
 When adding new elements to a page, it's important that we have a uniform element naming convention.
 
@@ -63,17 +63,17 @@ We follow a simple formula roughly based on hungarian notation.
   - `_checkbox`
   - `_radio`
   - `_content`
-  
+
 *Note: This list is a work in progress. This list will eventually be the end-all enumeration of all available types.
         I.e., any element that does not end with something in this list is bad form.*
-  
-#### Examples
+
+### Examples
 
 **Good**
 
 ```ruby
 view '...' do
-  element :edit_button 
+  element :edit_button
   element :notes_tab
   element :squash_checkbox
   element :username_field
@@ -84,16 +84,61 @@ end
 **Bad**
 
 ```ruby
-view '...' do  
+view '...' do
   # `_confirmation` should be `_field`. what sort of confirmation? a checkbox confirmation? no real way to disambiguate.
   # an appropriate replacement would be `element :password_confirmation_field`
   element :password_confirmation
 
-  # `clone_options` is too vague. If it's a dropdown menu, it should be `clone_dropdown`. 
+  # `clone_options` is too vague. If it's a dropdown menu, it should be `clone_dropdown`.
   # If it's a checkbox, it should be `clone_checkbox`
   element :clone_options
-  
+
   # how is this url being displayed? is it a textbox? a simple span?
+  # If it is content on the page, it should be `ssh_clone_url_content`
   element :ssh_clone_url
 end
 ```
+
+## Block argument naming
+
+To have a standard on how we call pages when using the `.perform` method, we use the name of page object being called, all lowercased, and separated by underscore, if needed (see good and bad examples below.) This also applies to resources. We chose not to simply use `page` because that would shadow the Capybara DSL, potentially leading to confusion and bugs.
+
+### Examples
+
+**Good**
+
+```ruby
+# qa/specs/features/browser_ui/1_manage/project/add_project_member_spec.rb
+
+Page::Project::Settings::Members.perform do |members|
+  members.do_something
+end
+```
+
+```ruby
+# qa/specs/features/ee/browser_ui/3_create/merge_request/add_batch_comments_in_merge_request_spec.rb
+
+Resource::MergeRequest.fabricate! do |merge_request|
+  merge_request.do_something_else
+end
+```
+
+**Bad**
+
+```ruby
+# qa/specs/features/browser_ui/1_manage/project/add_project_member_spec.rb
+
+Page::Project::Settings::Members.perform do |project_settings_members_page|
+  project_settings_members_page.do_something
+end
+```
+
+```ruby
+# qa/specs/features/ee/browser_ui/3_create/merge_request/add_batch_comments_in_merge_request_spec.rb
+
+Resource::MergeRequest.fabricate! do |merge_request_page|
+  merge_request_page.do_something_else
+end
+```
+
+> Besides the advantage of having a standard in place, by following this standard we also write shorter lines of code.
\ No newline at end of file
diff --git a/doc/development/testing_guide/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md
index 931cbc51cae..eb0bf6fc563 100644
--- a/doc/development/testing_guide/flaky_tests.md
+++ b/doc/development/testing_guide/flaky_tests.md
@@ -35,8 +35,8 @@ Once a test is in quarantine, there are 3 choices:
 
 Quarantined tests are run on the CI in dedicated jobs that are allowed to fail:
 
-- `rspec-pg-quarantine` and `rspec-mysql-quarantine` (CE & EE)
-- `rspec-pg-quarantine-ee` and `rspec-mysql-quarantine-ee` (EE only)
+- `rspec-pg-quarantine` (CE & EE)
+- `rspec-pg-quarantine-ee` (EE only)
 
 ## Automatic retries and flaky tests detection
 
diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md
index 4c9d1684c00..52ac746716c 100644
--- a/doc/development/testing_guide/frontend_testing.md
+++ b/doc/development/testing_guide/frontend_testing.md
@@ -27,14 +27,30 @@ we need to solve before being able to use Jest for all our needs.
 ### Differences to Karma
 
 - Jest runs in a Node.js environment, not in a browser. Support for running Jest tests in a browser [is planned](https://gitlab.com/gitlab-org/gitlab-ce/issues/58205).
-- Because Jest runs in a Node.js environment, it uses [jsdom](https://github.com/jsdom/jsdom) by default.
+- Because Jest runs in a Node.js environment, it uses [jsdom](https://github.com/jsdom/jsdom) by default. See also its [limitations](#limitations-of-jsdom) below.
+- Jest does not have access to Webpack loaders or aliases.
+  The aliases used by Jest are defined in its [own config](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/jest.config.js).
 - All calls to `setTimeout` and `setInterval` are mocked away. See also [Jest Timer Mocks](https://jestjs.io/docs/en/timer-mocks).
 - `rewire` is not required because Jest supports mocking modules. See also [Manual Mocks](https://jestjs.io/docs/en/manual-mocks).
+- No [context object](https://jasmine.github.io/tutorials/your_first_suite#section-The_%3Ccode%3Ethis%3C/code%3E_keyword) is passed to tests in Jest.
+  This means sharing `this.something` between `beforeEach()` and `it()` for example does not work.
+  Instead you should declare shared variables in the context that they are needed (via `const` / `let`).
 - The following will cause tests to fail in Jest:
   - Unmocked requests.
   - Unhandled Promise rejections.
   - Calls to `console.warn`, including warnings from libraries like Vue.
 
+### Limitations of jsdom
+
+As mentioned [above](#differences-to-karma), Jest uses jsdom instead of a browser for running tests.
+This comes with a number of limitations, namely:
+
+- [No scrolling support](https://github.com/jsdom/jsdom/blob/15.1.1/lib/jsdom/browser/Window.js#L623-L625)
+- [No element sizes or positions](https://github.com/jsdom/jsdom/blob/15.1.1/lib/jsdom/living/nodes/Element-impl.js#L334-L371)
+- [No layout engine](https://github.com/jsdom/jsdom/issues/1322) in general
+
+See also the issue for [support running Jest tests in browsers](https://gitlab.com/gitlab-org/gitlab-ce/issues/58205).
+
 ### Debugging Jest tests
 
 Running `yarn jest-debug` will run Jest in debug mode, allowing you to debug/inspect as described in the [Jest docs](https://jestjs.io/docs/en/troubleshooting#tests-are-failing-and-you-don-t-know-why).
@@ -63,6 +79,37 @@ describe('Component', () => {
 
 Remember that the performance of each test depends on the environment.
 
+### Manual module mocks
+
+Jest supports [manual module mocks](https://jestjs.io/docs/en/manual-mocks) by placing a mock in a `__mocks__/` directory next to the source module. **Don't do this.** We want to keep all of our test-related code in one place (the `spec/` folder), and the logic that Jest uses to apply mocks from `__mocks__/` is rather inconsistent.
+
+Instead, our test runner detects manual mocks from `spec/frontend/mocks/`. Any mock placed here is automatically picked up and injected whenever you import its source module.
+
+- Files in `spec/frontend/mocks/ce` will mock the corresponding CE module from `app/assets/javascripts`, mirroring the source module's path.
+  - Example: `spec/frontend/mocks/ce/lib/utils/axios_utils` will mock the module `~/lib/utils/axios_utils`.
+- Files in `spec/frontend/mocks/node` will mock NPM packages of the same name or path.
+- We don't support mocking EE modules yet.
+
+If a mock is found for which a source module doesn't exist, the test suite will fail. 'Virtual' mocks, or mocks that don't have a 1-to-1 association with a source module, are not supported yet.
+
+#### Writing a mock
+
+Create a JS module in the appropriate place in `spec/frontend/mocks/`. That's it. It will automatically mock its source package in all tests.
+
+Make sure that your mock's export has the same format as the mocked module. So, if you're mocking a CommonJS module, you'll need to use `module.exports` instead of the ES6 `export`.
+
+It might be useful for a mock to expose a property that indicates if the mock was loaded. This way, tests can assert the presence of a mock without calling any logic and causing side-effects. The `~/lib/utils/axios_utils` module mock has such a property, `isMock`, that is `true` in the mock and undefined in the original class. Jest's mock functions also have a `mock` property that you can test.
+
+#### Bypassing mocks
+
+If you ever need to import the original module in your tests, use [`jest.requireActual()`](https://jestjs.io/docs/en/jest-object#jestrequireactualmodulename) (or `jest.requireActual().default` for the default export). The `jest.mock()` and `jest.unmock()` won't have an effect on modules that have a manual mock, because mocks are imported and cached before any tests are run.
+
+#### Keep mocks light
+
+Global mocks introduce magic and can affect how modules are imported in your tests. Try to keep them as light as possible and dependency-free. A global mock should be useful for any unit test. For example, the `axios_utils` and `jquery` module mocks throw an error when an HTTP request is attempted, since this is useful behaviour in &gt;99% of tests.
+
+When in doubt, construct mocks in your test file using [`jest.mock()`](https://jestjs.io/docs/en/jest-object#jestmockmodulename-factory-options), [`jest.spyOn()`](https://jestjs.io/docs/en/jest-object#jestspyonobject-methodname), etc.
+
 ## Karma test suite
 
 GitLab uses the [Karma][karma] test runner with [Jasmine] as its test
@@ -418,7 +465,7 @@ See this [section][vue-test].
 
 For running the frontend tests, you need the following commands:
 
-- `rake karma:fixtures` (re-)generates [fixtures](#frontend-test-fixtures).
+- `rake frontend:fixtures` (re-)generates [fixtures](#frontend-test-fixtures).
 - `yarn test` executes the tests.
 
 As long as the fixtures don't change, `yarn test` is sufficient (and saves you some time).
@@ -471,8 +518,8 @@ Information on setting up and running RSpec integration tests with
 Code that is added to HAML templates (in `app/views/`) or makes Ajax requests to the backend has tests that require HTML or JSON from the backend.
 Fixtures for these tests are located at:
 
-- `spec/javascripts/fixtures/`, for running tests in CE.
-- `ee/spec/javascripts/fixtures/`, for running tests in EE.
+- `spec/frontend/fixtures/`, for running tests in CE.
+- `ee/spec/frontend/fixtures/`, for running tests in EE.
 
 Fixture files in:
 
@@ -483,29 +530,29 @@ The following are examples of tests that work for both Karma and Jest:
 
 ```javascript
 it('makes a request', () => {
-  const responseBody = getJSONFixture('some/fixture.json'); // loads spec/javascripts/fixtures/some/fixture.json
+  const responseBody = getJSONFixture('some/fixture.json'); // loads spec/frontend/fixtures/some/fixture.json
   axiosMock.onGet(endpoint).reply(200, responseBody);
-  
+
   myButton.click();
-  
+
   // ...
 });
 
 it('uses some HTML element', () => {
-  loadFixtures('some/page.html'); // loads spec/javascripts/fixtures/some/page.html and adds it to the DOM
-  
+  loadFixtures('some/page.html'); // loads spec/frontend/fixtures/some/page.html and adds it to the DOM
+
   const element = document.getElementById('#my-id');
-  
+
   // ...
 });
 ```
 
-HTML and JSON fixtures are generated from backend views and controllers using RSpec (see `spec/javascripts/fixtures/*.rb`).
+HTML and JSON fixtures are generated from backend views and controllers using RSpec (see `spec/frontend/fixtures/*.rb`).
 
 For each fixture, the content of the `response` variable is stored in the output file.
 This variable gets automagically set if the test is marked as `type: :request` or `type: :controller`.
-Fixtures are regenerated using the `bin/rake karma:fixtures` command but you can also generate them individually,
-for example `bin/rspec spec/javascripts/fixtures/merge_requests.rb`.
+Fixtures are regenerated using the `bin/rake frontend:fixtures` command but you can also generate them individually,
+for example `bin/rspec spec/frontend/fixtures/merge_requests.rb`.
 When creating a new fixture, it often makes sense to take a look at the corresponding tests for the endpoint in `(ee/)spec/controllers/` or `(ee/)spec/requests/`.
 
 ## Gotchas
@@ -541,12 +588,370 @@ end
 
 [jasmine-focus]: https://jasmine.github.io/2.5/focused_specs.html
 [karma]: http://karma-runner.github.io/
-[vue-test]: https://docs.gitlab.com/ce/development/fe_guide/vue.html#testing-vue-components
+[vue-test]: ../fe_guide/vue.md#testing-vue-components
 [rspec]: https://github.com/rspec/rspec-rails#feature-specs
 [capybara]: https://github.com/teamcapybara/capybara
-[karma]: http://karma-runner.github.io/
 [jasmine]: https://jasmine.github.io/
 
+## Overview of Frontend Testing Levels
+
+Tests relevant for frontend development can be found at the following places:
+
+- `spec/javascripts/` which are run by Karma (command: `yarn karma`) and contain
+  - [frontend unit tests](#frontend-unit-tests)
+  - [frontend component tests](#frontend-component-tests)
+  - [frontend integration tests](#frontend-integration-tests)
+- `spec/frontend/` which are run by Jest (command: `yarn jest`) and contain
+  - [frontend unit tests](#frontend-unit-tests)
+  - [frontend component tests](#frontend-component-tests)
+  - [frontend integration tests](#frontend-integration-tests)
+- `spec/features/` which are run by RSpec and contain
+  - [feature tests](#feature-tests)
+
+All tests in `spec/javascripts/` will eventually be migrated to `spec/frontend/` (see also [#52483](https://gitlab.com/gitlab-org/gitlab-ce/issues/52483)).
+
+In addition, there used to be feature tests in `features/`, run by Spinach.
+These were removed from the codebase in May 2018 ([#23036](https://gitlab.com/gitlab-org/gitlab-ce/issues/23036)).
+
+See also [Notes on testing Vue components](../fe_guide/vue.html#testing-vue-components).
+
+### Frontend unit tests
+
+Unit tests are on the lowest abstraction level and typically test functionality that is not directly perceivable by a user.
+
+#### When to use unit tests
+
+<details>
+  <summary>exported functions and classes</summary>
+  Anything that is exported can be reused at various places in a way you have no control over.
+  Therefore it is necessary to document the expected behavior of the public interface with tests.
+</details>
+
+<details>
+  <summary>Vuex actions</summary>
+  Any Vuex action needs to work in a consistent way independent of the component it is triggered from.
+</details>
+
+<details>
+  <summary>Vuex mutations</summary>
+  For complex Vuex mutations it helps to identify the source of a problem by separating the tests from other parts of the Vuex store.
+</details>
+
+#### When *not* to use unit tests
+
+<details>
+  <summary>non-exported functions or classes</summary>
+  Anything that is not exported from a module can be considered private or an implementation detail and doesn't need to be tested.
+</details>
+
+<details>
+  <summary>constants</summary>
+  Testing the value of a constant would mean to copy it.
+  This results in extra effort without additional confidence that the value is correct.
+</details>
+
+<details>
+  <summary>Vue components</summary>
+  Computed properties, methods, and lifecycle hooks can be considered an implementation detail of components and don't need to be tested.
+  They are implicitly covered by component tests.
+  The <a href="https://vue-test-utils.vuejs.org/guides/#getting-started">official Vue guidelines</a> suggest the same.
+</details>
+
+#### What to mock in unit tests
+
+<details>
+  <summary>state of the class under test</summary>
+  Modifying the state of the class under test directly rather than using methods of the class avoids side-effects in test setup.
+</details>
+
+<details>
+  <summary>other exported classes</summary>
+  Every class needs to be tested in isolation to prevent test scenarios from growing exponentially.
+</details>
+
+<details>
+  <summary>single DOM elements if passed as parameters</summary>
+  For tests that only operate on single DOM elements rather than a whole page, creating these elements is cheaper than loading a whole HTML fixture.
+</details>
+
+<details>
+  <summary>all server requests</summary>
+  When running frontend unit tests, the backend may not be reachable.
+  Therefore all outgoing requests need to be mocked.
+</details>
+
+<details>
+  <summary>asynchronous background operations</summary>
+  Background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects.
+</details>
+
+#### What *not* to mock in unit tests
+
+<details>
+  <summary>non-exported functions or classes</summary>
+  Everything that is not exported can be considered private to the module and will be implicitly tested via the exported classes / functions.
+</details>
+
+<details>
+  <summary>methods of the class under test</summary>
+  By mocking methods of the class under test, the mocks will be tested and not the real methods.
+</details>
+
+<details>
+  <summary>utility functions (pure functions, or those that only modify parameters)</summary>
+  If a function has no side effects because it has no state, it is safe to not mock it in tests.
+</details>
+
+<details>
+  <summary>full HTML pages</summary>
+  Loading the HTML of a full page slows down tests, so it should be avoided in unit tests.
+</details>
+
+### Frontend component tests
+
+Component tests cover the state of a single component that is perceivable by a user depending on external signals such as user input, events fired from other components, or application state.
+
+#### When to use component tests
+
+- Vue components
+
+#### When *not* to use component tests
+
+<details>
+  <summary>Vue applications</summary>
+  Vue applications may contain many components.
+  Testing them on a component level requires too much effort.
+  Therefore they are tested on frontend integration level.
+</details>
+
+<details>
+  <summary>HAML templates</summary>
+  HAML templates contain only Markup and no frontend-side logic.
+  Therefore they are not complete components.
+</details>
+
+#### What to mock in component tests
+
+<details>
+  <summary>DOM</summary>
+  Operating on the real DOM is significantly slower than on the virtual DOM.
+</details>
+
+<details>
+  <summary>properties and state of the component under test</summary>
+  Similarly to testing classes, modifying the properties directly (rather than relying on methods of the component) avoids side-effects.
+</details>
+
+<details>
+  <summary>Vuex store</summary>
+  To avoid side effects and keep component tests simple, Vuex stores are replaced with mocks.
+</details>
+
+<details>
+  <summary>all server requests</summary>
+  Similar to unit tests, when running component tests, the backend may not be reachable.
+  Therefore all outgoing requests need to be mocked.
+</details>
+
+<details>
+  <summary>asynchronous background operations</summary>
+  Similar to unit tests, background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects.
+</details>
+
+<details>
+  <summary>child components</summary>
+  Every component is tested individually, so child components are mocked.
+  See also <a href="https://vue-test-utils.vuejs.org/api/#shallowmount">shallowMount()</a>
+</details>
+
+#### What *not* to mock in component tests
+
+<details>
+  <summary>methods or computed properties of the component under test</summary>
+  By mocking part of the component under test, the mocks will be tested and not the real component.
+</details>
+
+<details>
+  <summary>functions and classes independent from Vue</summary>
+  All plain JavaScript code is already covered by unit tests and needs not to be mocked in component tests.
+</details>
+
+### Frontend integration tests
+
+Integration tests cover the interaction between all components on a single page.
+Their abstraction level is comparable to how a user would interact with the UI.
+
+#### When to use integration tests
+
+<details>
+  <summary>page bundles (<code>index.js</code> files in <code>app/assets/javascripts/pages/</code>)</summary>
+  Testing the page bundles ensures the corresponding frontend components integrate well.
+</details>
+
+<details>
+  <summary>Vue applications outside of page bundles</summary>
+  Testing Vue applications as a whole ensures the corresponding frontend components integrate well.
+</details>
+
+#### What to mock in integration tests
+
+<details>
+  <summary>HAML views (use fixtures instead)</summary>
+  Rendering HAML views requires a Rails environment including a running database which we cannot rely on in frontend tests.
+</details>
+
+<details>
+  <summary>all server requests</summary>
+  Similar to unit and component tests, when running component tests, the backend may not be reachable.
+  Therefore all outgoing requests need to be mocked.
+</details>
+
+<details>
+  <summary>asynchronous background operations that are not perceivable on the page</summary>
+  Background operations that affect the page need to be tested on this level.
+  All other background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects.
+</details>
+
+#### What *not* to mock in integration tests
+
+<details>
+  <summary>DOM</summary>
+  Testing on the real DOM ensures our components work in the environment they are meant for.
+  Part of this will be delegated to <a href="https://gitlab.com/gitlab-org/quality/team-tasks/issues/45">cross-browser testing</a>.
+</details>
+
+<details>
+  <summary>properties or state of components</summary>
+  On this level, all tests can only perform actions a user would do.
+  For example to change the state of a component, a click event would be fired.
+</details>
+
+<details>
+  <summary>Vuex stores</summary>
+  When testing the frontend code of a page as a whole, the interaction between Vue components and Vuex stores is covered as well.
+</details>
+
+### Feature tests
+
+In contrast to [frontend integration tests](#frontend-integration-tests), feature tests make requests against the real backend instead of using fixtures.
+This also implies that database queries are executed which makes this category significantly slower.
+
+See also the [RSpec testing guidelines](../testing_guide/best_practices.md#rspec).
+
+#### When to use feature tests
+
+- Use cases that require a backend and cannot be tested using fixtures.
+- Behavior that is not part of a page bundle but defined globally.
+
+#### Relevant notes
+
+A `:js` flag is added to the test to make sure the full environment is loaded.
+
+```js
+scenario 'successfully', :js do
+  sign_in(create(:admin))
+end
+```
+
+The steps of each test are written using capybara methods ([documentation](https://www.rubydoc.info/gems/capybara)).
+
+Bear in mind <abbr title="XMLHttpRequest">XHR</abbr> calls might require you to use `wait_for_requests` in between steps, like so:
+
+```rspec
+find('.form-control').native.send_keys(:enter)
+
+wait_for_requests
+
+expect(page).not_to have_selector('.card')
+```
+
+## Test helpers
+
+### Vuex Helper: `testAction`
+
+We have a helper available to make testing actions easier, as per [official documentation](https://vuex.vuejs.org/guide/testing.html):
+
+```js
+testAction(
+  actions.actionName, // action
+  { }, // params to be passed to action
+  state, // state
+  [
+    { type: types.MUTATION},
+    { type: types.MUTATION_1, payload: {}},
+  ], // mutations committed
+  [
+    { type: 'actionName', payload: {}},
+    { type: 'actionName1', payload: {}},
+  ] // actions dispatched
+  done,
+);
+```
+
+Check an example in [spec/javascripts/ide/stores/actions_spec.jsspec/javascripts/ide/stores/actions_spec.js](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/javascripts/ide/stores/actions_spec.js).
+
+### Vue Helper: `mountComponent`
+
+To make mounting a Vue component easier and more readable, we have a few helpers available in `spec/helpers/vue_mount_component_helper`:
+
+- `createComponentWithStore`
+- `mountComponentWithStore`
+
+Examples of usage:
+
+```js
+beforeEach(() => {
+  vm = createComponentWithStore(Component, store);
+
+  vm.$store.state.currentBranchId = 'master';
+
+  vm.$mount();
+});
+```
+
+```js
+beforeEach(() => {
+  vm = mountComponentWithStore(Component, {
+    el: '#dummy-element',
+    store,
+    props: { badge },
+  });
+});
+```
+
+Don't forget to clean up:
+
+```js
+afterEach(() => {
+  vm.$destroy();
+});
+```
+
+## Testing with older browsers
+
+Some regressions only affect a specific browser version. We can install and test in particular browsers with either Firefox or Browserstack using the following steps:
+
+### Browserstack
+
+[Browserstack](https://www.browserstack.com/) allows you to test more than 1200 mobile devices and browsers.
+You can use it directly through the [live app](https://www.browserstack.com/live) or you can install the [chrome extension](https://chrome.google.com/webstore/detail/browserstack/nkihdmlheodkdfojglpcjjmioefjahjb) for easy access.
+You can find the credentials on 1Password, under `frontendteam@gitlab.com`.
+
+### Firefox
+
+#### macOS
+
+You can download any older version of Firefox from the releases FTP server, <https://ftp.mozilla.org/pub/firefox/releases/>:
+
+1. From the website, select a version, in this case `50.0.1`.
+1. Go to the mac folder.
+1. Select your preferred language, you will find the dmg package inside, download it.
+1. Drag and drop the application to any other folder but the `Applications` folder.
+1. Rename the application to something like `Firefox_Old`.
+1. Move the application to the `Applications` folder.
+1. Open up a terminal and run `/Applications/Firefox_Old.app/Contents/MacOS/firefox-bin -profilemanager` to create a new profile specific to that Firefox version.
+1. Once the profile has been created, quit the app, and run it again like normal. You now have a working older Firefox version.
+
 ---
 
 [Return to Testing documentation](index.md)
diff --git a/doc/development/testing_guide/img/qa_on_merge_requests_cicd_architecture.png b/doc/development/testing_guide/img/qa_on_merge_requests_cicd_architecture.png
deleted file mode 100644
index 5b93a05db96..00000000000
--- a/doc/development/testing_guide/img/qa_on_merge_requests_cicd_architecture.png
+++ /dev/null
diff --git a/doc/development/testing_guide/img/review_apps_cicd_architecture.png b/doc/development/testing_guide/img/review_apps_cicd_architecture.png
deleted file mode 100644
index 1ee28d3db91..00000000000
--- a/doc/development/testing_guide/img/review_apps_cicd_architecture.png
+++ /dev/null
diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md
index 93ee2a6371a..96e8c30a679 100644
--- a/doc/development/testing_guide/index.md
+++ b/doc/development/testing_guide/index.md
@@ -11,7 +11,7 @@ importance.
 
 ## Overview
 
-GitLab is built on top of [Ruby on Rails][rails], and we're using [RSpec] for all
+GitLab is built on top of [Ruby on Rails](https://rubyonrails.org/), and we're using [RSpec] for all
 the backend tests, with [Capybara] for end-to-end integration testing.
 On the frontend side, we're using [Karma] and [Jasmine] for JavaScript unit and
 integration testing.
@@ -22,67 +22,46 @@ automated testing means, and what are its principles:
 - [Five Factor Testing](https://www.devmynd.com/blog/five-factor-testing): Why do we need tests?
 - [Principles of Automated Testing](http://www.lihaoyi.com/post/PrinciplesofAutomatedTesting.html): Levels of testing. Prioritize tests. Cost of tests.
 
----
-
 ## [Testing levels](testing_levels.md)
 
 Learn about the different testing levels, and how to decide at what level your
 changes should be tested.
 
----
-
 ## [Testing best practices](best_practices.md)
 
 Everything you should know about how to write good tests: Test Design, RSpec, FactoryBot,
 system tests, parameterized tests etc.
 
----
-
 ## [Frontend testing standards and style guidelines](frontend_testing.md)
 
 Everything you should know about how to write good Frontend tests: Karma,
 testing promises, stubbing etc.
 
----
-
 ## [Flaky tests](flaky_tests.md)
 
 What are flaky tests, the different kind of flaky tests we encountered, and what
 we do about them.
 
----
-
 ## [GitLab tests in the Continuous Integration (CI) context](ci.md)
 
 How GitLab test suite is run in the CI context: setup, caches, artifacts,
 parallelization, monitoring.
 
----
-
 ## [Review apps](review_apps.md)
 
 How review apps are set up for GitLab CE/EE and how to use them.
 
----
-
 ## [Testing Rake tasks](testing_rake_tasks.md)
 
 Everything you should know about how to test Rake tasks.
 
----
-
 ## [End-to-end tests](end_to_end/index.md)
 
 Everything you should know about how to run end-to-end tests using
 [GitLab QA][gitlab-qa] testing framework.
 
----
-
 [Return to Development documentation](../README.md)
 
-[^1]: /ci/yaml/README.html#dependencies
-
-[rails]: http://rubyonrails.org/
 [RSpec]: https://github.com/rspec/rspec-rails#feature-specs
 [Capybara]: https://github.com/teamcapybara/capybara
 [Karma]: http://karma-runner.github.io/
diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md
index 63b7b97c32f..11449712a04 100644
--- a/doc/development/testing_guide/review_apps.md
+++ b/doc/development/testing_guide/review_apps.md
@@ -8,38 +8,33 @@ Review Apps are automatically deployed by each pipeline, both in
 
 ### CI/CD architecture diagram
 
-![Review Apps CI/CD architecture](img/review_apps_cicd_architecture.png)
-
-<details>
-<summary>Show mermaid source</summary>
-<pre>
+```mermaid
 graph TD
     build-qa-image -.->|once the `prepare` stage is done| gitlab:assets:compile
     review-build-cng -->|triggers a CNG-mirror pipeline and wait for it to be done| CNG-mirror
     review-build-cng -.->|once the `test` stage is done| review-deploy
     review-deploy -.->|once the `review` stage is done| review-qa-smoke
 
-subgraph 1. gitlab-ce/ee `prepare` stage
+subgraph "1. gitlab-ce/ee `prepare` stage"
     build-qa-image
     end
 
-subgraph 2. gitlab-ce/ee `test` stage
+subgraph "2. gitlab-ce/ee `test` stage"
     gitlab:assets:compile -->|plays dependent job once done| review-build-cng
     end
 
-subgraph 3. gitlab-ce/ee `review` stage
-    review-deploy["review-deploy<br /><br />Helm deploys the Review App using the Cloud<br/>Native images built by the CNG-mirror pipeline.<br /><br />Cloud Native images are deployed to the `review-apps-ce` or `review-apps-ee`<br />Kubernetes (GKE) cluster, in the GCP `gitlab-review-apps` project."]
+subgraph "3. gitlab-ce/ee `review` stage"
+    review-deploy["review-deploy<br><br>Helm deploys the Review App using the Cloud<br/>Native images built by the CNG-mirror pipeline.<br><br>Cloud Native images are deployed to the `review-apps-ce` or `review-apps-ee`<br>Kubernetes (GKE) cluster, in the GCP `gitlab-review-apps` project."]
     end
 
-subgraph 4. gitlab-ce/ee `qa` stage
-    review-qa-smoke[review-qa-smoke<br /><br />gitlab-qa runs the smoke suite against the Review App.]
+subgraph "4. gitlab-ce/ee `qa` stage"
+    review-qa-smoke[review-qa-smoke<br><br>gitlab-qa runs the smoke suite against the Review App.]
     end
 
-subgraph CNG-mirror pipeline
+subgraph "CNG-mirror pipeline"
     CNG-mirror>Cloud Native images are built];
     end
-</pre>
-</details>
+```
 
 ### Detailed explanation
 
@@ -115,6 +110,28 @@ On every [pipeline][gitlab-pipeline] in the `qa` stage, the
 browser performance testing using a
 [Sitespeed.io Container](../../user/project/merge_requests/browser_performance_testing.md).
 
+## Cluster configuration
+
+### Node pools
+
+Both `review-apps-ce` and `review-apps-ee` clusters are currently set up with
+two node pools:
+
+- a node pool of non-preemptible `n1-standard-2` (2 vCPU, 7.5 GB memory) nodes
+  dedicated to the `tiller` deployment (see below) with a single node.
+- a node pool of preemptible `n1-standard-2` (2 vCPU, 7.5 GB memory) nodes,
+  with a minimum of 1 node and a maximum of 250 nodes.
+
+### Helm/Tiller
+
+The `tiller` deployment (the Helm server) is deployed to a dedicated node pool
+that has the `app=helm` label and a specific
+[taint](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)
+to prevent other pods from being scheduled on this node pool.
+
+This is to ensure Tiller isn't affected by "noisy" neighbors that could put
+their node under pressure.
+
 ## How to:
 
 ### Log into my Review App
@@ -137,8 +154,8 @@ secure note named **gitlab-{ce,ee} Review App's root password**.
 
 ### Run a Rails console
 
-1. [Filter Workloads by your Review App slug](https://console.cloud.google.com/kubernetes/workload?project=gitlab-review-apps)
-  , e.g. `review-qa-raise-e-12chm0`.
+1. [Filter Workloads by your Review App slug](https://console.cloud.google.com/kubernetes/workload?project=gitlab-review-apps),
+   e.g. `review-qa-raise-e-12chm0`.
 1. Find and open the `task-runner` Deployment, e.g. `review-qa-raise-e-12chm0-task-runner`.
 1. Click on the Pod in the "Managed pods" section, e.g. `review-qa-raise-e-12chm0-task-runner-d5455cc8-2lsvz`.
 1. Click on the `KUBECTL` dropdown, then `Exec` -> `task-runner`.
@@ -196,7 +213,7 @@ For the record, the debugging steps to find out this issue were:
 1. `kubectl describe pod <pod name>` & confirm exact error message
 1. Web search for exact error message, following rabbit hole to [a relevant kubernetes bug report](https://github.com/kubernetes/kubernetes/issues/57345)
 1. Access the node over SSH via the GCP console (**Computer Engine > VM
-  instances** then click the "SSH" button for the node where the `dns-gitlab-review-app-external-dns` pod runs)
+   instances** then click the "SSH" button for the node where the `dns-gitlab-review-app-external-dns` pod runs)
 1. In the node: `systemctl --version` => systemd 232
 1. Gather some more information:
    - `mount | grep kube | wc -l` => e.g. 290
@@ -211,7 +228,7 @@ For the record, the debugging steps to find out this issue were:
 To resolve the problem, we needed to (forcibly) drain some nodes:
 
 1. Try a normal drain on the node where the `dns-gitlab-review-app-external-dns`
-  pod runs so that Kubernetes automatically move it to another node: `kubectl drain NODE_NAME`
+   pod runs so that Kubernetes automatically move it to another node: `kubectl drain NODE_NAME`
 1. If that doesn't work, you can also perform a forcible "drain" the node by removing all pods: `kubectl delete pods --field-selector=spec.nodeName=NODE_NAME`
 1. In the node:
    - Perform `systemctl daemon-reload` to remove the dead/inactive units
@@ -238,17 +255,8 @@ that a machine will hit the "too many mount points" problem in the future.
 thousands of unused Docker images.**
 
   > We have to start somewhere and improve later. Also, we're using the
-  CNG-mirror project to store these Docker images so that we can just wipe out
-  the registry at some point, and use a new fresh, empty one.
-
-**How big are the Kubernetes clusters (`review-apps-ce` and `review-apps-ee`)?**
-
-  > The clusters are currently set up with a single pool of preemptible nodes,
-  with a minimum of 1 node and a maximum of 500 nodes.
-
-**What are the machine running on the cluster?**
-
-  > We're currently using `n1-standard-1` (1 vCPU, 3.75 GB memory) machines.
+  > CNG-mirror project to store these Docker images so that we can just wipe out
+  > the registry at some point, and use a new fresh, empty one.
 
 **How do we secure this from abuse? Apps are open to the world so we need to
 find a way to limit it to only us.**
@@ -257,7 +265,7 @@ find a way to limit it to only us.**
 
 ## Other resources
 
-* [Review Apps integration for CE/EE (presentation)](https://docs.google.com/presentation/d/1QPLr6FO4LduROU8pQIPkX1yfGvD13GEJIBOenqoKxR8/edit?usp=sharing)
+- [Review Apps integration for CE/EE (presentation)](https://docs.google.com/presentation/d/1QPLr6FO4LduROU8pQIPkX1yfGvD13GEJIBOenqoKxR8/edit?usp=sharing)
 
 [charts-1068]: https://gitlab.com/charts/gitlab/issues/1068
 [gitlab-pipeline]: https://gitlab.com/gitlab-org/gitlab-ce/pipelines/44362587
diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md
index e1ce4d3b7d1..0090c84cbf0 100644
--- a/doc/development/testing_guide/testing_levels.md
+++ b/doc/development/testing_guide/testing_levels.md
@@ -63,10 +63,9 @@ They're useful to test permissions, redirections, what view is rendered etc.
 
 | Code path | Tests path | Testing engine | Notes |
 | --------- | ---------- | -------------- | ----- |
-| `app/controllers/` | `spec/controllers/` | RSpec | |
+| `app/controllers/` | `spec/controllers/` | RSpec | For N+1 tests, use [request specs](../query_recorder.md#use-request-specs-instead-of-controller-specs) |
 | `app/mailers/` | `spec/mailers/` | RSpec | |
 | `lib/api/` | `spec/requests/api/` | RSpec | |
-| `lib/ci/api/` | `spec/requests/ci/api/` | RSpec | |
 | `app/assets/javascripts/` | `spec/javascripts/`, `spec/frontend/` | Karma & Jest | More details in the [Frontend Testing guide](frontend_testing.md) section. |
 
 ### About controller tests
diff --git a/doc/development/understanding_explain_plans.md b/doc/development/understanding_explain_plans.md
index bfbb7be70e3..7c926c83a36 100644
--- a/doc/development/understanding_explain_plans.md
+++ b/doc/development/understanding_explain_plans.md
@@ -199,7 +199,7 @@ more common ones here.
 
 A full list of all the available nodes and their descriptions can be found in
 the [PostgreSQL source file
-"plannodes.h"](https://github.com/postgres/postgres/blob/master/src/include/nodes/plannodes.h)
+"plannodes.h"](https://gitlab.com/postgres/postgres/blob/master/src/include/nodes/plannodes.h)
 
 ### Seq Scan
 
@@ -224,7 +224,7 @@ used when we would read too much data from an index scan, but too little to
 perform a sequential scan. A bitmap scan uses what is known as a [bitmap
 index](https://en.wikipedia.org/wiki/Bitmap_index) to perform its work.
 
-The [source code of PostgreSQL](https://github.com/postgres/postgres/blob/1c2cb2744bf3d8ad751cd5cf3b347f10f48492b3/src/include/nodes/plannodes.h#L446-L457)
+The [source code of PostgreSQL](https://gitlab.com/postgres/postgres/blob/REL_11_STABLE/src/include/nodes/plannodes.h#L441)
 states the following on bitmap scans:
 
 > Bitmap Index Scan delivers a bitmap of potential tuple locations; it does not
@@ -654,7 +654,6 @@ and related tools such as:
 - <https://explain.depesz.com/>
 - <http://tatiyants.com/postgres-query-plan-visualization/>
 
-
 ## Producing query plans
 
 There are a few ways to get the output of a query plan. Of course you
diff --git a/doc/development/utilities.md b/doc/development/utilities.md
index 0e396baccff..4021756343c 100644
--- a/doc/development/utilities.md
+++ b/doc/development/utilities.md
@@ -6,44 +6,44 @@ We developed a number of utilities to ease development.
 
 - Deep merges an array of hashes:
 
-    ``` ruby
-    Gitlab::Utils::MergeHash.merge(
-      [{ hello: ["world"] },
-       { hello: "Everyone" },
-       { hello: { greetings: ['Bonjour', 'Hello', 'Hallo', 'Dzien dobry'] } },
-        "Goodbye", "Hallo"]
-    )
-    ```
-
-    Gives:
-
-    ``` ruby
-    [
-      {
-        hello:
-          [
-            "world",
-            "Everyone",
-            { greetings: ['Bonjour', 'Hello', 'Hallo', 'Dzien dobry'] }
-          ]
-      },
-      "Goodbye"
-    ]
-    ```
+  ``` ruby
+  Gitlab::Utils::MergeHash.merge(
+    [{ hello: ["world"] },
+     { hello: "Everyone" },
+     { hello: { greetings: ['Bonjour', 'Hello', 'Hallo', 'Dzien dobry'] } },
+      "Goodbye", "Hallo"]
+  )
+  ```
+
+  Gives:
+
+  ``` ruby
+  [
+    {
+      hello:
+        [
+          "world",
+          "Everyone",
+          { greetings: ['Bonjour', 'Hello', 'Hallo', 'Dzien dobry'] }
+        ]
+    },
+    "Goodbye"
+  ]
+  ```
 
 - Extracts all keys and values from a hash into an array:
 
-    ``` ruby
-    Gitlab::Utils::MergeHash.crush(
-      { hello: "world", this: { crushes: ["an entire", "hash"] } }
-    )
-    ```
+  ``` ruby
+  Gitlab::Utils::MergeHash.crush(
+    { hello: "world", this: { crushes: ["an entire", "hash"] } }
+  )
+  ```
 
-    Gives:
+  Gives:
 
-    ``` ruby
-    [:hello, "world", :this, :crushes, "an entire", "hash"]
-    ```
+  ``` ruby
+  [:hello, "world", :this, :crushes, "an entire", "hash"]
+  ```
 
 ## [`Override`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/override.rb)
 
@@ -53,9 +53,9 @@ We developed a number of utilities to ease development.
   `ENV['STATIC_VERIFICATION']` is set to avoid production runtime overhead.
   This is useful to check:
 
-    - If we have typos in overriding methods.
-    - If we renamed the overridden methods, making original overriding methods
-      overrides nothing.
+  - If we have typos in overriding methods.
+  - If we renamed the overridden methods, making original overriding methods
+    overrides nothing.
 
     Here's a simple example:
 
@@ -94,47 +94,47 @@ We developed a number of utilities to ease development.
 
 - Memoize the value even if it is `nil` or `false`.
 
-    We often do `@value ||= compute`, however this doesn't work well if
-    `compute` might eventually give `nil` and we don't want to compute again.
-    Instead we could use `defined?` to check if the value is set or not.
-    However it's tedious to write such pattern, and `StrongMemoize` would
-    help us use such pattern.
+  We often do `@value ||= compute`, however this doesn't work well if
+  `compute` might eventually give `nil` and we don't want to compute again.
+  Instead we could use `defined?` to check if the value is set or not.
+  However it's tedious to write such pattern, and `StrongMemoize` would
+  help us use such pattern.
 
-    Instead of writing patterns like this:
+  Instead of writing patterns like this:
 
-    ``` ruby
-    class Find
-      def result
-        return @result if defined?(@result)
+  ``` ruby
+  class Find
+    def result
+      return @result if defined?(@result)
 
-        @result = search
-      end
+      @result = search
     end
-    ```
+  end
+  ```
 
-    We could write it like:
+  We could write it like:
 
-    ``` ruby
-    class Find
-      include Gitlab::Utils::StrongMemoize
+  ``` ruby
+  class Find
+    include Gitlab::Utils::StrongMemoize
 
-      def result
-        strong_memoize(:result) do
-          search
-        end
+    def result
+      strong_memoize(:result) do
+        search
       end
     end
-    ```
+  end
+  ```
 
 - Clear memoization
 
-    ``` ruby
-    class Find
-      include Gitlab::Utils::StrongMemoize
-    end
+  ``` ruby
+  class Find
+    include Gitlab::Utils::StrongMemoize
+  end
 
-    Find.new.clear_memoization(:result)
-    ```
+  Find.new.clear_memoization(:result)
+  ```
 
 ## [`RequestCache`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/cache/request_cache.rb)
 
diff --git a/doc/development/ux_guide/animation.md b/doc/development/ux_guide/animation.md
index 583ff19bc69..a998ab74a96 100644
--- a/doc/development/ux_guide/animation.md
+++ b/doc/development/ux_guide/animation.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: 'https://design.gitlab.com/foundations/motion'
+redirect_to: 'https://design.gitlab.com/product-foundations/motion'
 ---
 
-The content of this document was moved into the [GitLab Design System](https://design.gitlab.com).
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/product-foundations/motion).
diff --git a/doc/development/ux_guide/illustrations.md b/doc/development/ux_guide/illustrations.md
index ed072b6515f..3592d25c95d 100644
--- a/doc/development/ux_guide/illustrations.md
+++ b/doc/development/ux_guide/illustrations.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: 'https://design.gitlab.com/foundations/illustration/'
+redirect_to: 'https://design.gitlab.com/product-foundations/illustration'
 ---
 
-The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/product-foundations/illustration).
diff --git a/doc/development/ux_guide/resources.md b/doc/development/ux_guide/resources.md
index baec235a8dd..ae092246d05 100644
--- a/doc/development/ux_guide/resources.md
+++ b/doc/development/ux_guide/resources.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: 'https://design.gitlab.com/resources/design-resources'
+redirect_to: 'https://design.gitlab.com/resources/design-resources/'
 ---
 
-The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/resources/design-resources/).
diff --git a/doc/development/verifying_database_capabilities.md b/doc/development/verifying_database_capabilities.md
index 661ab9cef1a..6b4995aebe2 100644
--- a/doc/development/verifying_database_capabilities.md
+++ b/doc/development/verifying_database_capabilities.md
@@ -1,15 +1,15 @@
 # Verifying Database Capabilities
 
-Sometimes certain bits of code may only work on a certain database and/or
+Sometimes certain bits of code may only work on a certain database
 version. While we try to avoid such code as much as possible sometimes it is
 necessary to add database (version) specific behaviour.
 
 To facilitate this we have the following methods that you can use:
 
-- `Gitlab::Database.postgresql?`: returns `true` if PostgreSQL is being used
-- `Gitlab::Database.mysql?`: returns `true` if MySQL is being used
+- `Gitlab::Database.postgresql?`: returns `true` if PostgreSQL is being used.
+  You can normally just assume this is the case.
 - `Gitlab::Database.version`: returns the PostgreSQL version number as a string
-  in the format `X.Y.Z`. This method does not work for MySQL
+  in the format `X.Y.Z`.
 
 This allows you to write code such as:
 
@@ -25,7 +25,7 @@ else
 end
 ```
 
-# Read-only database
+## Read-only database
 
 The database can be used in read-only mode. In this case we have to
 make sure all GET requests don't attempt any write operations to the
diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md
index 24edd05da2f..944bf5900c5 100644
--- a/doc/development/what_requires_downtime.md
+++ b/doc/development/what_requires_downtime.md
@@ -7,9 +7,8 @@ downtime.
 
 ## Adding Columns
 
-On PostgreSQL you can safely add a new column to an existing table as long as it
-does **not** have a default value. For example, this query would not require
-downtime:
+You can safely add a new column to an existing table as long as it does **not**
+have a default value. For example, this query would not require downtime:
 
 ```sql
 ALTER TABLE projects ADD COLUMN random_value int;
@@ -27,11 +26,6 @@ This requires updating every single row in the `projects` table so that
 indexes in a table. This in turn acquires enough locks on the table for it to
 effectively block any other queries.
 
-As of MySQL 5.6 adding a column to a table is still quite an expensive
-operation, even when using `ALGORITHM=INPLACE` and `LOCK=NONE`. This means
-downtime _may_ be required when modifying large tables as otherwise the
-operation could potentially take hours to complete.
-
 Adding a column with a default value _can_ be done without requiring downtime
 when using the migration helper method
 `Gitlab::Database::MigrationHelpers#add_column_with_default`. This method works
@@ -140,7 +134,7 @@ done without requiring downtime. However, this does require that any application
 changes are deployed _first_. Thus, changing the constraints of a column should
 happen in a post-deployment migration.
 NOTE: Avoid using `change_column` as it produces inefficient query because it re-defines
-the whole column type. For example, to add a NOT NULL constraint, prefer `change_column_null `
+the whole column type. For example, to add a NOT NULL constraint, prefer `change_column_null`
 
 ## Changing Column Types
 
@@ -311,8 +305,7 @@ migrations](background_migrations.md#cleaning-up).
 ## Adding Indexes
 
 Adding indexes is an expensive process that blocks INSERT and UPDATE queries for
-the duration. When using PostgreSQL one can work around this by using the
-`CONCURRENTLY` option:
+the duration. You can work around this by using the `CONCURRENTLY` option:
 
 ```sql
 CREATE INDEX CONCURRENTLY index_name ON projects (column_name);
@@ -336,17 +329,9 @@ end
 Note that `add_concurrent_index` can not be reversed automatically, thus you
 need to manually define `up` and `down`.
 
-When running this on PostgreSQL the `CONCURRENTLY` option mentioned above is
-used. On MySQL this method produces a regular `CREATE INDEX` query.
-
-MySQL doesn't really have a workaround for this. Supposedly it _can_ create
-indexes without the need for downtime but only for variable width columns. The
-details on this are a bit sketchy. Since it's better to be safe than sorry one
-should assume that adding indexes requires downtime on MySQL.
-
 ## Dropping Indexes
 
-Dropping an index does not require downtime on both PostgreSQL and MySQL.
+Dropping an index does not require downtime.
 
 ## Adding Tables
 
@@ -370,7 +355,7 @@ transaction this means this approach would require downtime.
 
 GitLab allows you to work around this by using
 `Gitlab::Database::MigrationHelpers#add_concurrent_foreign_key`. This method
-ensures that when PostgreSQL is used no downtime is needed.
+ensures that no downtime is needed.
 
 ## Removing Foreign Keys
 
diff --git a/doc/downgrade_ee_to_ce/README.md b/doc/downgrade_ee_to_ce/README.md
index a187b3cbb07..a3f6f2b327c 100644
--- a/doc/downgrade_ee_to_ce/README.md
+++ b/doc/downgrade_ee_to_ce/README.md
@@ -81,7 +81,7 @@ To downgrade an Omnibus installation, it is sufficient to install the Community
 Edition package on top of the currently installed one. You can do this manually,
 by directly [downloading the package](https://packages.gitlab.com/gitlab/gitlab-ce)
 you need, or by adding our CE package repository and following the
-[CE installation instructions](https://about.gitlab.com/installation/?version=ce).
+[CE installation instructions](https://about.gitlab.com/install/?version=ce).
 
 **Source Installation**
 
diff --git a/doc/gitlab-basics/README.md b/doc/gitlab-basics/README.md
index 0c268eff9f1..fc3d36910f2 100644
--- a/doc/gitlab-basics/README.md
+++ b/doc/gitlab-basics/README.md
@@ -1,15 +1,18 @@
 ---
 comments: false
+type: index
 ---
 
 # GitLab basics guides
 
-This section provides resources to help you start with GitLab by focusing on basic functionality.
+This section provides resources to help you start working with GitLab and Git by focusing
+on the basic features that you will need to use.
 
 This documentation is split into the following groups:
 
 - [GitLab-specific functionality](#gitlab-basics), for basic GitLab features.
-- [General Git functionality](#git-basics), for working with Git in conjunction with GitLab.
+- [General Git functionality](#working-with-git-from-the-command-line), for working
+  with Git in conjunction with GitLab.
 
 ## GitLab basics
 
@@ -17,22 +20,26 @@ The following are guides to basic GitLab functionality:
 
 - [Create and add your SSH public key](create-your-ssh-keys.md), for enabling Git over SSH.
 - [Create a project](create-project.md), to start using GitLab.
-- [Create a group](../user/group/index.md#create-a-new-group), to combine and administer projects together.
+- [Create a group](../user/group/index.md#create-a-new-group), to combine and administer
+  projects together.
 - [Create a branch](create-branch.md), to make changes to files stored in a project's repository.
 - [Fork a project](fork-project.md), to duplicate projects so they can be worked on in parallel.
 - [Add a file](add-file.md), to add new files to a project's repository.
-- [Add an image](add-image.md), to add new images to a project's repository.
-- [Create an issue](../user/project/issues/create_new_issue.md), to start collaborating within a project.
-- [Create a merge request](add-merge-request.md), to request changes made in a branch be merged into a project's repository.
-- See how these features come together in the [GitLab Flow introduction video](https://youtu.be/InKNIvky2KE) and [GitLab Flow page](../workflow/gitlab_flow.md).
+- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue),
+  to start collaborating within a project.
+- [Create a merge request](add-merge-request.md), to request changes made in a branch
+  be merged into a project's repository.
+- See how these features come together in the [GitLab Flow introduction video](https://youtu.be/InKNIvky2KE)
+  and [GitLab Flow page](../workflow/gitlab_flow.md).
 
-## Git basics
+## Working with Git from the command line
 
-If you're familiar with Git on the command line, you can interact with your GitLab projects just as you would with any other Git repository.
+If you're familiar with Git on the command line, you can interact with your GitLab
+projects just as you would with any other Git repository.
 
 These resources will help get further acclimated to working on the command line.
 
 - [Start using Git on the command line](start-using-git.md), for some simple Git commands.
 - [Command line basics](command-line-commands.md), to create and edit files using the command line.
 
-More Git resources are available at GitLab's [Git documentation](../topics/git/index.md).
+More Git resources are available in GitLab's [Git documentation](../topics/git/index.md).
diff --git a/doc/gitlab-basics/add-file.md b/doc/gitlab-basics/add-file.md
index e9fbcbc23a9..41cc8bc4aeb 100644
--- a/doc/gitlab-basics/add-file.md
+++ b/doc/gitlab-basics/add-file.md
@@ -1,5 +1,91 @@
-# How to add a file
+---
+type: howto
+---
 
-You can create a file in your [terminal](command-line-commands.md) and push
-to GitLab or you can use the
+# Add a file to a repository
+
+Adding files to a repository is a small, but key task. Bringing files in to a repository,
+such as code, images, or documents, allows them to be tracked by Git, even though they
+may have been created elsewhere.
+
+You can add a file to a repository in your [terminal](#add-a-file-using-the-command-line), and
+then push to GitLab. You can also use the [web interface](../user/project/repository/web_editor.md#upload-a-file),
+which may be a simpler solution.
+
+If you need to create a file first, for example a `README.md` text file, that can
+also be done from the [terminal](command-line-commands.md#create-a-text-file-in-the-current-directory) or
 [web interface](../user/project/repository/web_editor.md#create-a-file).
+
+## Add a file using the command line
+
+Open a [terminal/shell](command-line-commands.md), and change into the folder of your
+GitLab project. This usually means running the following command until you get
+to the desired destination:
+
+```sh
+cd <destination folder>
+```
+
+[Create a branch](create-branch.md) to add your file to, before it is added to the master
+(main) branch of the project. It is not strictly necessary, but working directly in
+the `master` branch is not recommended unless your project is very small, and you are
+the only person working on it. You can [switch to an existing branch](start-using-git.md#work-on-an-existing-branch),
+if you have one already.
+
+Using your standard tool for copying files (for example, Finder in macOS, or File Explorer
+in Windows), put the file into a directory within the GitLab project.
+
+Check if your file is actually present in the directory (if you are in Windows,
+use `dir` instead):
+
+```sh
+ls
+```
+
+You should see the name of the file in the list shown.
+
+Check the status:
+
+```sh
+git status
+```
+
+Your file's name should appear in red, so `git` took notice of it! Now add it
+to the repository:
+
+```sh
+git add <name of file>
+```
+
+Check the status again, your file's name should have turned green:
+
+```sh
+git status
+```
+
+Commit (save) your file to the repository:
+
+```sh
+git commit -m "DESCRIBE COMMIT IN A FEW WORDS"
+```
+
+Now you can push (send) your changes (in the branch `<branch-name>`) to GitLab
+(the git remote named 'origin'):
+
+```sh
+git push origin <branch-name>
+```
+
+Your image will be added to your branch in your repository in GitLab.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/gitlab-basics/add-image.md b/doc/gitlab-basics/add-image.md
index 17c210c43e0..11a4a6bbd97 100644
--- a/doc/gitlab-basics/add-image.md
+++ b/doc/gitlab-basics/add-image.md
@@ -1,56 +1,5 @@
-# How to add an image
+---
+redirect_to: 'add-file.md'
+---
 
-Using your standard tool for copying files (e.g. Finder in Mac OS, or Explorer
-in Windows, or...), put the image file into the GitLab project. You can find the
-project as a regular folder in your files.
-
-Go to your [shell](command-line-commands.md), and move into the folder of your
-GitLab project. This usually means running the following command until you get
-to the desired destination:
-
-```
-cd NAME-OF-FOLDER-YOU'D-LIKE-TO-OPEN
-```
-
-Check if your image is actually present in the directory (if you are in Windows,
-use `dir` instead):
-
-```
-ls
-```
-
-You should see the name of the image in the list shown.
-
-Check the status:
-
-```
-git status
-```
-
-Your image's name should appear in red, so `git` took notice of it! Now add it
-to the repository:
-
-```
-git add NAME-OF-YOUR-IMAGE
-```
-
-Check the status again, your image's name should have turned green:
-
-```
-git status
-```
-
-Commit:
-
-```
-git commit -m "DESCRIBE COMMIT IN A FEW WORDS"
-```
-
-Now you can push (send) your changes (in the branch NAME-OF-BRANCH) to GitLab
-(the git remote named 'origin'):
-
-```
-git push origin NAME-OF-BRANCH
-```
-
-Your image will be added to your branch in your repository in GitLab.
+This document was moved to [another location](add-file.md).
diff --git a/doc/gitlab-basics/add-merge-request.md b/doc/gitlab-basics/add-merge-request.md
index 7bb2e014738..1a6a26152fa 100644
--- a/doc/gitlab-basics/add-merge-request.md
+++ b/doc/gitlab-basics/add-merge-request.md
@@ -1,9 +1,16 @@
+---
+type: howto
+---
+
 # How to create a merge request
 
-Merge requests are useful to integrate separate changes that you've made to a
-project, on different branches. This is a brief guide on how to create a merge
-request. For more information, check the
-[merge requests documentation](../user/project/merge_requests/index.md).
+Merge requests are how you integrate separate changes that you've made in a
+[branch](create-branch.md) to a [project](create-project.md).
+
+This is a brief guide on how to create a merge request. For more detailed information,
+check the [merge requests documentation](../user/project/merge_requests/index.md), or
+you can watch our [GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE) for
+a quick overview of working with merge requests.
 
 ---
 
@@ -12,19 +19,31 @@ request. For more information, check the
 1. Go to the project where you'd like to merge your changes and click on the
    **Merge requests** tab.
 1. Click on **New merge request** on the right side of the screen.
-1. From there on, you have the option to select the source branch and the target
+1. From there, you have the option to select the source branch and the target
    branch you'd like to compare to. The default target project is the upstream
    repository, but you can choose to compare across any of its forks.
 
-    ![Select a branch](img/merge_request_select_branch.png)
+   ![Select a branch](img/merge_request_select_branch.png)
 
 1. When ready, click on the **Compare branches and continue** button.
 1. At a minimum, add a title and a description to your merge request. Optionally,
-   select a user to review your merge request and to accept or close it. You may
-   also select a milestone and labels.
+   select a user to review your merge request. You may also select a milestone and
+   labels.
 
-    ![New merge request page](img/merge_request_page.png)
+   ![New merge request page](img/merge_request_page.png)
 
 1. When ready, click on the **Submit merge request** button.
 
-Your merge request will be ready to be approved and merged.
+Your merge request will be ready to be reviewed, approved, and merged.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/gitlab-basics/basic-git-commands.md b/doc/gitlab-basics/basic-git-commands.md
index c2a3415cbc4..4e0cc2de2bc 100644
--- a/doc/gitlab-basics/basic-git-commands.md
+++ b/doc/gitlab-basics/basic-git-commands.md
@@ -1,3 +1,5 @@
-# Basic Git commands
+---
+redirect_to: 'start-using-git.md'
+---
 
-This section is now merged into [Start using Git](start-using-git.md).
+This document was moved to [another location](start-using-git.md).
diff --git a/doc/gitlab-basics/command-line-commands.md b/doc/gitlab-basics/command-line-commands.md
index 1cf883679d7..ed70d3ce598 100644
--- a/doc/gitlab-basics/command-line-commands.md
+++ b/doc/gitlab-basics/command-line-commands.md
@@ -1,73 +1,47 @@
-# Command Line basic commands
-
-## Start working on your project
-
-In Git, when you copy a project you say you "clone" it. To work on a git project locally (from your own computer), you will need to clone it. To do this, sign in to GitLab.
-
-When you are on your Dashboard, click on the project that you'd like to clone.
-To work in the project, you can copy a link to the Git repository through a SSH
-or a HTTPS protocol. SSH is easier to use after it's been
-[set up](create-your-ssh-keys.md). While you are at the **Project** tab, select
-HTTPS or SSH from the dropdown menu and copy the link using the _Copy URL to clipboard_
-button (you'll have to paste it on your shell in the next step).
-
-![Copy the HTTPS or SSH](img/project_clone_url.png)
-
-## Working with project files on the command line
-
-This section has examples of some basic shell commands that you might find useful. For more information, search the web for _bash commands_.
-
-Alternatively, you can edit files using your choice of editor (IDE) or the GitLab user interface.
-
-### Clone your project
+---
+type: howto, reference
+---
 
-Go to your computer's shell and type the following command with your SSH or HTTPS URL:
-
-```
-git clone PASTE HTTPS OR SSH HERE
-```
-
-A clone of the project will be created in your computer.
-
->**Note:** If you clone your project via a URL that contains special characters, make sure that characters are URL-encoded.
-
-### Go into a project directory to work in it
-
-```
-cd NAME-OF-PROJECT
-```
+# Command Line basic commands
 
-### Go back one directory
+When [working with Git from the command line](start-using-git.md), you will need to
+use more than just the Git commands. There are several basic commands that you should
+learn, in order to make full use of the command line.
 
-```
-cd ..
-```
+## Start working on your project
 
-### List what’s in the current directory
+To work on a git project locally (from your own computer), with the command line,
+first you will need to [clone (copy) it](start-using-git.md#clone-a-repository) to
+your computer.
 
-```
-ls
-```
+## Working with files on the command line
 
-### List what’s in the current directory that starts with `a`
+This section has examples of some basic shell commands that you might find useful.
+For more information, search the web for _bash commands_.
 
-```
-ls a*
-```
+Alternatively, you can edit files using your choice of editor (IDE), or the GitLab user
+interface (not locally).
 
-### List what’s in the current directory that ends with `.md`
+### Common commands
 
-```
-ls *.md
-```
+The list below is not exhaustive, but contains many of the most commonly used commands.
 
-### Create a new directory
+| Command                        | Description                                 |
+|--------------------------------|---------------------------------------------|
+| `cd NAME-OF-DIRECTORY`         | Go into a directory to work in it           |
+| `cd ..`                        | Go back one directory                       |
+| `ls`                           | List what’s in the current directory        |
+| `ls a*`                        | List what’s in the current directory that starts with `a` |
+| `ls *.md`                      | List what’s in the current directory that ends with `.md` |
+| `mkdir NAME-OF-YOUR-DIRECTORY` | Create a new directory                      |
+| `cat README.md`                | Display the contents of a [text file you created previously](#create-a-text-file-in-the-current-directory) |
+| `pwd`                          | Show the current directory                  |
+| `clear`                        | Clear the shell window                      |
 
-```
-mkdir NAME-OF-YOUR-DIRECTORY
-```
+### Create a text file in the current directory
 
-### Create a README.md file in the current directory
+To create a text file from the command line, for example `README.md`, follow these
+steps:
 
 ```
 touch README.md
@@ -78,31 +52,37 @@ nano README.md
 #### Press: enter
 ```
 
-### Show the contents of the README.md file
+### Remove a file or directory
 
-```
-cat README.md
-```
+It is easy to delete (remove) a file or directory, but be careful:
 
-### Remove a file
+DANGER: **Danger:**
+This will **permanently** delete a file.
 
 ```
 rm NAME-OF-FILE
 ```
 
-### Remove a directory and all of its contents
+DANGER: **Danger:**
+This will **permanently** delete a directory and **all** of its contents.
 
 ```
 rm -r NAME-OF-DIRECTORY
 ```
 
-### View command history
+### View and Execute commands from history
+
+You can view the history of all the commands you executed from the command line,
+and then execute any of them again, if needed.
+
+First, list the commands you executed previously:
 
 ```
 history
 ```
 
-### Execute command 123 from history
+Then, choose a command from the list and check the number next to the command (`123`,
+for example) . Execute the same full command with:
 
 ```
 !123
@@ -110,23 +90,32 @@ history
 
 ### Carry out commands for which the account you are using lacks authority
 
-You will be asked for an administrator’s password.
+Not all commands can be executed from a basic user account on a computer, you may
+need administrator's rights to execute commands that affect the system, or try to access
+protected data, for example. You can use `sudo` to execute these commands, but you
+will likely be asked for an administrator password.
 
 ```
-sudo
+sudo RESTRICTED-COMMAND
 ```
 
-### Show which directory I am in
+CAUTION: **Caution:**
+Be careful of the commands you run with `sudo`. Certain commands may cause
+damage to your data or system.
 
-```
-pwd
-```
+## Sample Git taskflow
 
-### Clear the shell window
+If you are completely new to Git, looking through some [sample taskflows](https://rogerdudler.github.io/git-guide/)
+will help you understand the best practices for using these commands as you work.
 
-```
-clear
-```
-### Sample Git taskflow
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
 
-If you are completely new to Git, looking through some [sample taskflows](https://rogerdudler.github.io/git-guide/) will help you understand best practices for using these commands as you work.
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/gitlab-basics/create-branch.md b/doc/gitlab-basics/create-branch.md
index ad94f0dad29..e2a2fb52af8 100644
--- a/doc/gitlab-basics/create-branch.md
+++ b/doc/gitlab-basics/create-branch.md
@@ -1,12 +1,16 @@
+---
+type: howto
+---
+
 # How to create a branch
 
-A branch is an independent line of development.
+A branch is an independent line of development in a [project](../user/project/index.md).
 
-New commits are recorded in the history for the current branch, which results
-in taking the source from someone’s repository (the place where the history of
-your work is stored) at certain point in time, and apply your own changes to it
-in the history of the project.
+When you create a new branch (in your [terminal](basic-git-commands.md) or with
+[the web interface](../user/project/repository/web_editor.md#create-a-new-branch)),
+you are creating a snapshot of a certain branch, usually the main `master` branch,
+at it's current state. From there, you can start to make your own changes without
+affecting the main codebase. The history of your changes will be tracked in your branch.
 
-To add changes to your GitLab project, you should create a branch. You can do
-it in your [terminal](basic-git-commands.md) or by
-[using the web interface](../user/project/repository/web_editor.md#create-a-new-branch).
+When your changes are ready, you then merge them into the rest of the codebase with a
+[merge request](add-merge-request.md).
diff --git a/doc/gitlab-basics/create-issue.md b/doc/gitlab-basics/create-issue.md
index 6e2a09fc030..5fa5f1bf2e2 100644
--- a/doc/gitlab-basics/create-issue.md
+++ b/doc/gitlab-basics/create-issue.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: '../user/project/issues/index.md#issue-actions'
+redirect_to: '../user/project/issues/index.md#viewing-and-managing-issues'
 ---
 
-This document was moved to [another location](../user/project/issues/index.md#issue-actions).
+This document was moved to [another location](../user/project/issues/index.md#viewing-and-managing-issues).
diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md
index a9ae4fb23f9..8bbaf5d1927 100644
--- a/doc/gitlab-basics/create-project.md
+++ b/doc/gitlab-basics/create-project.md
@@ -1,10 +1,13 @@
-# Create a project
+---
+type: howto
+---
 
-[Projects](../user/project/index.md) combine many features of GitLab together.
+# Creating projects
 
-NOTE: **Note:**
-For a list of words that cannot be used as project names see
-[Reserved project and group names](../user/reserved_names.md).
+Most work in GitLab is done within a [Project](../user/project/index.md). Files and
+code are saved in projects, and most features are used within the scope of projects.
+
+## Create a project in GitLab
 
 To create a project in GitLab:
 
@@ -14,94 +17,98 @@ To create a project in GitLab:
    - Create a [blank project](#blank-projects).
    - Create a project using with one of the available [project templates](#project-templates).
    - [Import a project](../user/project/import/index.md) from a different repository,
-     if enabled on your GitLab instance. Contact your GitLab admin if this
-     is unavailable.
-   - Run [CI/CD pipelines for external repositories](../ci/ci_cd_for_external_repos/index.md). **[PREMIUM]**
+     if enabled on your GitLab instance. Contact your GitLab admin if this is unavailable.
+   - Run [CI/CD pipelines for external repositories](../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)**
 
-## Blank projects
+NOTE: **Note:**
+For a list of words that cannot be used as project names see
+[Reserved project and group names](../user/reserved_names.md).
+
+### Blank projects
 
 To create a new blank project on the **New project** page:
 
 1. On the **Blank project** tab, provide the following information:
-    - The name of your project in the **Project name** field. You can't use
-      special characters, but you can use spaces, hyphens, underscores or even
-      emoji.
-    - The **Project description (optional)** field enables you to enter a
-      description for your project's dashboard, which will help others
-      understand what your project is about. Though it's not required, it's a good
-      idea to fill this in.
-    - Changing the **Visibility Level** modifies the project's
-      [viewing and access rights](../public_access/public_access.md) for users.
-    - Selecting the **Initialize repository with a README** option creates a
-      README file so that the Git repository is initialized, has a default branch, and
-      can be cloned.
+   - The name of your project in the **Project name** field. You can't use
+     special characters, but you can use spaces, hyphens, underscores or even
+     emoji.
+   - The **Project description (optional)** field enables you to enter a
+     description for your project's dashboard, which will help others
+     understand what your project is about. Though it's not required, it's a good
+     idea to fill this in.
+   - Changing the **Visibility Level** modifies the project's
+     [viewing and access rights](../public_access/public_access.md) for users.
+   - Selecting the **Initialize repository with a README** option creates a
+     README file so that the Git repository is initialized, has a default branch, and
+     can be cloned.
 1. Click **Create project**.
 
-## Project templates
+### Project templates
 
-Project templates can pre-populate your project with necessary files to get you started quickly.
+Project templates can pre-populate a new project with the necessary files to get you
+started quickly.
 
 There are two types of project templates:
 
 - [Built-in templates](#built-in-templates), sourced from the following groups:
   - [`project-templates`](https://gitlab.com/gitlab-org/project-templates)
   - [`pages`](https://gitlab.com/pages)
-- [Custom project templates](#custom-project-templates-premium-only), for custom templates configured by GitLab administrators and users.
+- [Custom project templates](#custom-project-templates-premium), for custom templates
+  configured by GitLab administrators and users.
 
-### Built-in templates
+#### Built-in templates
 
 Built-in templates are project templates that are:
 
-- Developed and maintained in the
-  [`project-templates`](https://gitlab.com/gitlab-org/project-templates) and [`pages`](https://gitlab.com/pages) groups.
+- Developed and maintained in the [`project-templates`](https://gitlab.com/gitlab-org/project-templates)
+  and [`pages`](https://gitlab.com/pages) groups.
 - Released with GitLab.
 
 To use a built-in template on the **New project** page:
 
 1. On the **Create from template** tab, select the **Built-in** tab.
 1. From the list of available built-in templates, click the:
-    - **Preview** button to look at the template source itself.
-    - **Use template** button to start creating the project.
-1. Finish creating the project by filling out the project's details. The process is the same as for
-   using a [blank project](#blank-projects).
+   - **Preview** button to look at the template source itself.
+   - **Use template** button to start creating the project.
+1. Finish creating the project by filling out the project's details. The process is
+   the same as creating a [blank project](#blank-projects).
 
 TIP: **Tip:**
-You can improve the existing built-in templates or contribute new ones on the
-[`project-templates`](https://gitlab.com/gitlab-org/project-templates) and [`pages`](https://gitlab.com/pages) groups.
+You can improve the existing built-in templates or contribute new ones in the
+[`project-templates`](https://gitlab.com/gitlab-org/project-templates) and
+[`pages`](https://gitlab.com/pages) groups.
 
-### Custom project templates **[PREMIUM ONLY]**
+#### Custom project templates **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in
 [GitLab Premium](https://about.gitlab.com/pricing) 11.2.
 
-Creating new projects based on custom project templates is a convenient option to bootstrap a project.
+Creating new projects based on custom project templates is a convenient option to
+bootstrap a project.
 
-Custom projects are available from the **Instance** or **Group** tabs under the **Create from template** tab,
-depending on the type of template.
+Custom projects are available at the [instance-level](../user/admin_area/custom_project_templates.md)
+from the **Instance** tab, or at the [group-level](../user/group/custom_project_templates.md)
+from the **Group** tab, under the **Create from template** tab.
 
 To use a custom project template on the **New project** page:
 
 1. On the **Create from template** tab, select the **Instance** tab or the **Group** tab.
 1. From the list of available custom templates, click the:
-    - **Preview** button to look at the template source itself.
-    - **Use template** button to start creating the project.
-1. Finish creating the project by filling out the project's details. The process is the same as for
-   using a [blank project](#blank-projects).
-
-For information on configuring custom project templates, see:
-
-- [Custom instance-level project templates](../user/admin_area/custom_project_templates.md), for instance-level templates.
-- [Custom group-level project templates](../user/group/custom_project_templates.md), for group-level templates.
+   - **Preview** button to look at the template source itself.
+   - **Use template** button to start creating the project.
+1. Finish creating the project by filling out the project's details. The process is
+   the same as creating a [blank project](#blank-projects).
 
 ## Push to create a new project
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/26388) in GitLab 10.5.
 
-When you create a new repo locally, instead of going to GitLab to manually
-create a new project and then push the repo, you can directly push it to
-GitLab to create the new project, all without leaving your terminal. If you have access to that
-namespace, we will automatically create a new project under that GitLab namespace with its
-visibility set to Private by default (you can later change it in the [project's settings](../public_access/public_access.md#how-to-change-project-visibility)).
+When you create a new repository locally, instead of going to GitLab to manually
+create a new project and then [clone the repo](start-using-git.md#clone-a-repository)
+locally, you can directly push it to GitLab to create the new project, all without leaving
+your terminal. If you have access rights to the associated namespace, GitLab will
+automatically create a new project under that GitLab namespace with its visibility
+set to Private by default (you can later change it in the [project's settings](../public_access/public_access.md#how-to-change-project-visibility)).
 
 This can be done by using either SSH or HTTPS:
 
@@ -127,3 +134,15 @@ remote: To view the project, visit:
 remote:   https://gitlab.example.com/namespace/nonexistent-project
 remote:
 ```
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/gitlab-basics/create-your-ssh-keys.md b/doc/gitlab-basics/create-your-ssh-keys.md
index aac73d4c9c5..338b96374aa 100644
--- a/doc/gitlab-basics/create-your-ssh-keys.md
+++ b/doc/gitlab-basics/create-your-ssh-keys.md
@@ -1,22 +1,27 @@
-# Create and add your SSH public key
+---
+type: howto
+---
 
-This topic describes how to:
+# Create and add your SSH public key
 
-- Create an SSH key pair to use with GitLab.
-- Add the SSH public key to your GitLab account.
+It is best practice to use [Git over SSH instead of Git over HTTP](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols).
+In order to use SSH, you will need to
 
-You do this to use [Git over SSH instead of Git over HTTP](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols).
+1. [Create an SSH key pair](#creating-your-ssh-key-pair) on your local computer.
+1. [Add the key to GitLab](#adding-your-ssh-public-key-to-gitlab).
 
 ## Creating your SSH key pair
 
-1. Go to your [command line](start-using-git.md).
-1. Follow the [instructions](../ssh/README.md#generating-a-new-ssh-key-pair) to generate your SSH key pair.
+1. Go to your [command line](start-using-git.md#open-a-shell).
+1. Follow the [instructions](../ssh/README.md#generating-a-new-ssh-key-pair) to generate
+   your SSH key pair.
 
 ## Adding your SSH public key to GitLab
 
-To add the SSH public key to GitLab,
-see [Adding an SSH key to your GitLab account](../ssh/README.md#adding-an-ssh-key-to-your-gitlab-account).
+To add the SSH public key to GitLab, see
+[Adding an SSH key to your GitLab account](../ssh/README.md#adding-an-ssh-key-to-your-gitlab-account).
 
 NOTE: **Note:**
-Once you add a key, you cannot edit it. If the paste
-[didn't work](../ssh/README.md#testing-that-everything-is-set-up-correctly), you need to remove the key and re-add it.
+Once you add a key, you cannot edit it. If it didn't paste properly, it
+[will not work](../ssh/README.md#testing-that-everything-is-set-up-correctly), and
+you will need to remove the key from GitLab and try adding it again.
diff --git a/doc/gitlab-basics/fork-project.md b/doc/gitlab-basics/fork-project.md
index a128a7c7dd3..5c19985121d 100644
--- a/doc/gitlab-basics/fork-project.md
+++ b/doc/gitlab-basics/fork-project.md
@@ -1,20 +1,11 @@
+---
+type: howto
+---
+
 # How to fork a project
 
 A fork is a copy of an original repository that you put in another namespace
 where you can experiment and apply changes that you can later decide whether or
 not to share, without affecting the original project.
 
-It takes just a few steps to fork a project in GitLab.
-
-1. Go to a project's dashboard under the **Project** tab and click on the
-   **Fork** button.
-
-    ![Click on Fork button](img/fork_new.png)
-
-1. You will be asked where to fork the repository. Click on the user or group
-   to where you'd like to add the forked project.
-
-    ![Choose namespace](img/fork_choose_namespace.png)
-
-1. After a few moments, depending on the repository's size, the forking will
-   complete.
+It takes just a few steps to [fork a project in GitLab](../workflow/forking_workflow.md#creating-a-fork).
diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md
index b3c5d32f2f5..3e3f96fb31f 100644
--- a/doc/gitlab-basics/start-using-git.md
+++ b/doc/gitlab-basics/start-using-git.md
@@ -1,38 +1,43 @@
+---
+type: howto, tutorial
+---
+
 # Start using Git on the command line
 
-If you want to start using Git and GitLab, make sure that you have created and/or signed into an account on GitLab.
+While GitLab has a powerful user interface, if you want to use Git itself, you will
+have to do so from the command line. If you want to start using Git and GitLab together,
+make sure that you have created and/or signed into an account on GitLab.
 
 ## Open a shell
 
-Depending on your operating system, you will need to use a shell of your preference. Here are some suggestions:
-
-- [Terminal](http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) on  Mac OSX
+Depending on your operating system, you will need to use a shell of your preference.
+Here are some suggestions:
 
+- [Terminal](http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) on macOS
 - [GitBash](https://msysgit.github.io) on Windows
-
 - [Linux Terminal](http://www.howtogeek.com/140679/beginner-geek-how-to-start-using-the-linux-terminal/) on Linux
 
 ## Check if Git has already been installed
 
-Git is usually preinstalled on Mac and Linux.
-
-Type the following command and then press enter:
+Git is usually preinstalled on Mac and Linux, so run the following command:
 
 ```bash
 git --version
 ```
 
-You should receive a message that tells you which Git version you have on your computer. If you don’t receive a "Git version" message, it means that you need to [download Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+You should receive a message that tells you which Git version you have on your computer.
+If you don’t receive a "Git version" message, it means that you need to
+[download Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
 
-If Git doesn't automatically download, there's an option on the website to [download manually](https://git-scm.com/downloads). Then follow the steps on the installation window.
-
-After you are finished installing Git, open a new shell and type `git --version` again to verify that it was correctly installed.
+After you are finished installing Git, open a new shell and type `git --version` again
+to verify that it was correctly installed.
 
 ## Add your Git username and set your email
 
-It is important to configure your Git username and email address, since every Git commit will use this information to identify you as the author.
+It is important to configure your Git username and email address, since every Git
+commit will use this information to identify you as the author.
 
-On your shell, type the following command to add your username:
+In your shell, type the following command to add your username:
 
 ```bash
 git config --global user.name "YOUR_USERNAME"
@@ -56,7 +61,10 @@ To verify that you entered your email correctly, type:
 git config --global user.email
 ```
 
-You'll need to do this only once, since you are using the `--global` option. It tells Git to always use this information for anything you do on that system. If you want to override this with a different username or email address for specific projects, you can run the command without the `--global` option when you’re in that project.
+You'll need to do this only once, since you are using the `--global` option. It tells
+Git to always use this information for anything you do on that system. If you want
+to override this with a different username or email address for specific projects,
+you can run the command without the `--global` option when you’re in that project.
 
 ## Check your information
 
@@ -68,12 +76,12 @@ git config --global --list
 
 ## Basic Git commands
 
-Start using Git via the command line with the most basic
-commands as described below.
+Start using Git via the command line with the most basic commands as described below.
 
-## Initialize a local directory for Git version control
+### Initialize a local directory for Git version control
 
-If you have an existing local directory that you want to *initialize* for version control, use the `init` command to instruct Git to begin tracking the directory:
+If you have an existing local directory that you want to *initialize* for version
+control, use the `init` command to instruct Git to begin tracking the directory:
 
 ```bash
 git init
@@ -81,34 +89,33 @@ git init
 
 This creates a `.git` directory that contains the Git configuration files.
 
-Once the directory has been initialized, you can [add a remote repository](#add-a-remote-repository) and [send changes to GitLab.com](#send-changes-to-gitlabcom). View the instructions on [Create a project](../gitlab-basics/create-project.html#push-to-create-a-new-project) to create a new project on GitLab with your changes.
+Once the directory has been initialized, you can [add a remote repository](#add-a-remote-repository)
+and [send changes to GitLab.com](#send-changes-to-gitlabcom). You will also need to
+[create a new project in GitLab](../gitlab-basics/create-project.html#push-to-create-a-new-project)
+for your Git repository.
 
 ### Clone a repository
 
-To start working locally on an existing remote repository,
-clone it with the command `git clone <repository path>`.
-By cloning a repository, you'll download a copy of its
-files into your local computer, preserving the Git
-connection with the remote repository.
+To start working locally on an existing remote repository, clone it with the command
+`git clone <repository path>`. By cloning a repository, you'll download a copy of its
+files to your local computer, automatically preserving the Git connection with the
+remote repository.
 
-You can either clone it via HTTPS or [SSH](../ssh/README.md).
-If you chose to clone it via HTTPS, you'll have to enter your
-credentials every time you pull and push. With SSH, you enter
-your credentials once and can pull and push straightaway.
+You can either clone it via HTTPS or [SSH](../ssh/README.md). If you chose to clone
+it via HTTPS, you'll have to enter your credentials every time you pull and push.
+With SSH, you enter your credentials only once.
 
-You can find both paths (HTTPS and SSH) by navigating to
-your project's landing page and clicking **Clone**. GitLab
-will prompt you with both paths, from which you can copy
+You can find both paths (HTTPS and SSH) by navigating to your project's landing page
+and clicking **Clone**. GitLab will prompt you with both paths, from which you can copy
 and paste in your command line.
 
-As an example, consider a repository path:
+As an example, consider this repository path:
 
 - HTTPS: `https://gitlab.com/gitlab-org/gitlab-ce.git`
-- SSH: `` git@gitlab.com:gitlab-org/gitlab-ce.git ``
+- SSH: `git@gitlab.com:gitlab-org/gitlab-ce.git`
 
-To get started, open a terminal window in the directory
-you wish to clone the repository files into, and run one
-of the following commands.
+To get started, open a terminal window in the directory you wish to clone the repository
+files into, and run one of the following commands.
 
 Clone via HTTPS:
 
@@ -122,13 +129,15 @@ Clone via SSH:
 git clone git@gitlab.com:gitlab-org/gitlab-ce.git
 ```
 
-Both commands will download a copy of the files in a
-folder named after the project's name.
-
-You can then navigate to the directory and start working
+Both commands will download a copy of the files in a folder named after the project's
+name. You can then navigate to the directory and start working
 on it locally.
 
-### Go to the master branch to pull the latest changes from there
+### Switch to the master branch
+
+You are always in a branch when working with Git. The main branch is the master branch,
+but you can use the same command to switch to a different branch by changing `master`
+to the branch name.
 
 ```bash
 git checkout master
@@ -136,13 +145,20 @@ git checkout master
 
 ### Download the latest changes in the project
 
-This is for you to work on an up-to-date copy (it is important to do this every time you start working on a project), while you set up tracking branches. You pull from remote repositories to get all the changes made by users since the last time you cloned or pulled the project. Later, you can push your local commits to the remote repositories.
+To work on an up-to-date copy of the project (it is important to do this every time
+you start working on a project), you `pull` to get all the changes made by users since
+the last time you cloned or pulled the project. Use `master` for the `<name-of-branch>`
+to get the main branch code, or the branch name of the branch you are currently working
+in.
 
 ```bash
-git pull REMOTE NAME-OF-BRANCH
+git pull REMOTE <name-of-branch>
 ```
 
-When you first clone a repository, REMOTE is typically "origin". This is where the repository came from, and it indicates the SSH or HTTPS URL of the repository on the remote server. NAME-OF-BRANCH is usually "master", but it may be any existing branch.
+When you first clone a repository, REMOTE is typically `origin`. This is where the
+repository was cloned from, and it indicates the SSH or HTTPS URL of the repository
+on the remote server. `<name-of-branch>` is usually `master`, but it may be any existing
+branch.
 
 ### View your remote repositories
 
@@ -157,17 +173,20 @@ git remote -v
 To add a link to a remote repository:
 
 ```bash
-git remote add SOURCE-NAME REPOSITORY-PATH
+git remote add <source-name> <repository-path>
 ```
 
-You'll use this source name every time you [push changes to GitLab.com](#send-changes-to-gitlabcom), so use something easy to remember and type.
+You'll use this source name every time you [push changes to GitLab.com](#send-changes-to-gitlabcom),
+so use something easy to remember and type.
 
 ### Create a branch
 
-To create a branch, type the following (spaces won't be recognized in the branch name, so you will need to use a hyphen or underscore):
+To create a new branch, to work from without affecting the `master` branch, type the
+following (spaces won't be recognized in the branch name, so you will need to use a
+hyphen or underscore):
 
 ```bash
-git checkout -b NAME-OF-BRANCH
+git checkout -b <name-of-branch>>
 ```
 
 ### Work on an existing branch
@@ -175,12 +194,14 @@ git checkout -b NAME-OF-BRANCH
 To switch to an existing branch, so you can work on it:
 
 ```bash
-git checkout NAME-OF-BRANCH
+git checkout <name-of-branch>
 ```
 
 ### View the changes you've made
 
-It's important to be aware of what's happening and the status of your changes. When you add, change, or delete files/folders, Git knows about it. To check the status of your changes:
+It's important to be aware of what's happening and the status of your changes. When
+you add, change, or delete files/folders, Git knows about it. To check the status of
+your changes:
 
 ```bash
 git status
@@ -188,7 +209,8 @@ git status
 
 ### View differences
 
-To view the differences between your local, unstaged changes and the repository versions that you cloned or pulled, type:
+To view the differences between your local, unstaged changes and the repository versions
+that you cloned or pulled, type:
 
 ```bash
 git diff
@@ -196,16 +218,19 @@ git diff
 
 ### Add and commit local changes
 
-You'll see your local changes in red when you type `git status`. These changes may be new, modified, or deleted files/folders. Use `git add` to stage a local file/folder for committing. Then use `git commit` to commit the staged files:
+You'll see any local changes in red when you type `git status`. These changes may
+be new, modified, or deleted files/folders. Use `git add` to first stage (prepare)
+a local file/folder for committing. Then use `git commit` to commit (save) the staged
+files:
 
 ```bash
-git add FILE OR FOLDER
+git add <file-name OR folder-name>
 git commit -m "COMMENT TO DESCRIBE THE INTENTION OF THE COMMIT"
 ```
 
 ### Add all changes to commit
 
-To add and commit all local changes in one command:
+To add and commit (save) all local changes quickly:
 
 ```bash
 git add .
@@ -217,35 +242,32 @@ The `.` character typically means _all_ in Git.
 
 ### Send changes to GitLab.com
 
-To push all local commits to the remote repository:
+To push all local commits (saved changes) to the remote repository:
 
 ```bash
-git push REMOTE NAME-OF-BRANCH
+git push <remote> <name-of-branch>
 ```
 
-For example, to push your local commits to the _master_ branch of the _origin_ remote:
+For example, to push your local commits to the _`master`_ branch of the _`origin`_ remote:
 
 ```bash
 git push origin master
 ```
 
-### Delete all changes in the Git repository
+### Delete all changes in the branch
 
-To delete all local changes in the repository that have not been added to the staging area, and leave unstaged files/folders, type:
+To delete all local changes in the branch that have not been added to the staging
+area, and leave unstaged files/folders, type:
 
 ```bash
 git checkout .
 ```
 
-### Delete all untracked changes in the Git repository
-
-```bash
-git clean -f
-```
+Note that this removes *changes* to files, not the files themselves.
 
 ### Unstage all changes that have been added to the staging area
 
-To undo the most recent add, but not committed, files/folders:
+To undo the most recently added, but not committed, changes to files/folders:
 
 ```bash
 git reset .
@@ -259,25 +281,31 @@ To undo the most recent commit, type:
 git reset HEAD~1
 ```
 
-This leaves the files and folders unstaged in your local repository.
+This leaves the changed files and folders unstaged in your local repository.
 
 CAUTION: **Warning:**
-A Git commit is mostly irreversible, particularly if you already pushed it to the remote repository. Although you can undo a commit, the best option is to avoid the situation altogether.
+A Git commit should not usually be reverse, particularly if you already pushed it
+to the remote repository. Although you can undo a commit, the best option is to avoid
+the situation altogether by working carefully.
 
-### Merge created branch with master branch
+### Merge a branch with master branch
 
-You need to be in the created branch.
+When you are ready to make all the changes in a branch a permanent addition to
+the master branch, you `merge` the two together:
 
 ```bash
-git checkout NAME-OF-BRANCH
+git checkout <name-of-branch>
 git merge master
 ```
 
-### Merge master branch with created branch
+<!-- ## Troubleshooting
 
-You need to be in the master branch.
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
 
-```bash
-git checkout master
-git merge NAME-OF-BRANCH
-```
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/install/README.md b/doc/install/README.md
index 9cc21412898..af98791c8e9 100644
--- a/doc/install/README.md
+++ b/doc/install/README.md
@@ -4,7 +4,7 @@ description: Read through the GitLab installation methods.
 type: index
 ---
 
-# Installation **[CORE ONLY]**
+# Installation **(CORE ONLY)**
 
 GitLab can be installed in most GNU/Linux distributions and in a number
 of cloud providers. To get the best experience from GitLab you need to balance
diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md
index 73eaf758923..358ba971049 100644
--- a/doc/install/aws/index.md
+++ b/doc/install/aws/index.md
@@ -59,10 +59,11 @@ Here's a list of the AWS services we will use, with links to pricing information
 - **ElastiCache**: An in-memory cache environment will be used to provide a
   High Availability Redis configuration. See the
   [Amazon ElastiCache pricing](https://aws.amazon.com/elasticache/pricing/).
-  
+
 NOTE: **Note:** Please note that while we will be using EBS for storage, we do not recommend using EFS as it may negatively impact GitLab's performance. You can review the [relevant documentation](../../administration/high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs) for more details.
 
 ## Creating an IAM EC2 instance role and profile
+
 To minimize the permissions of the user, we'll create a new [IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html)
 role with limited access:
 
@@ -90,7 +91,7 @@ We'll now create a VPC, a virtual networking environment that you'll control:
    `10.0.0.0/16`. If you don't require dedicated hardware, you can leave
    "Tenancy" as default. Click **Yes, Create** when ready.
 
-    ![Create VPC](img/create_vpc.png)
+   ![Create VPC](img/create_vpc.png)
 
 ### Subnets
 
@@ -107,16 +108,16 @@ RDS instances as well:
    for example `gitlab-public-10.0.0.0`, select the VPC we created previously,
    and at the IPv4 CIDR block let's give it a 24 subnet `10.0.0.0/24`:
 
-    ![Create subnet](img/create_subnet.png)
+   ![Create subnet](img/create_subnet.png)
 
 1. Follow the same steps to create all subnets:
 
-    | Name tag | Type |Availability Zone | CIDR block |
-    | -------- | ---- | ---------------- | ---------- |
-    | gitlab-public-10.0.0.0  | public  | us-west-2a | 10.0.0.0 |
-    | gitlab-private-10.0.1.0 | private | us-west-2a | 10.0.1.0 |
-    | gitlab-public-10.0.2.0  | public  | us-west-2b | 10.0.2.0 |
-    | gitlab-private-10.0.3.0 | private | us-west-2b | 10.0.3.0 |
+   | Name tag | Type |Availability Zone | CIDR block |
+   | -------- | ---- | ---------------- | ---------- |
+   | gitlab-public-10.0.0.0  | public  | us-west-2a | 10.0.0.0 |
+   | gitlab-private-10.0.1.0 | private | us-west-2a | 10.0.1.0 |
+   | gitlab-public-10.0.2.0  | public  | us-west-2b | 10.0.2.0 |
+   | gitlab-private-10.0.3.0 | private | us-west-2b | 10.0.3.0 |
 
 ### Route Table
 
@@ -139,7 +140,7 @@ create a new one:
 1. Select it from the table, and then under the **Actions** dropdown choose
    "Attach to VPC".
 
-    ![Create gateway](img/create_gateway.png)
+   ![Create gateway](img/create_gateway.png)
 
 1. Choose `gitlab-vpc` from the list and hit **Attach**.
 
@@ -154,14 +155,14 @@ it receive traffic from any destination.
    as destination. In the target, select the `gitlab-gateway` we created previously.
    Hit **Save** once done.
 
-    ![Associate subnet with gateway](img/associate_subnet_gateway.png)
+   ![Associate subnet with gateway](img/associate_subnet_gateway.png)
 
 Next, we must associate the **public** subnets to the route table:
 
 1. Select the **Subnet Associations** tab and hit **Edit**.
 1. Check only the public subnet and hit **Save**.
 
-    ![Associate subnet with gateway](img/associate_subnet_gateway_2.png)
+   ![Associate subnet with gateway](img/associate_subnet_gateway_2.png)
 
 ---
 
@@ -178,12 +179,12 @@ The security group is basically the firewall:
    Inbound Rules tab. You will need to open the SSH, HTTP, and HTTPS ports. Set
    the source to `0.0.0.0/0`.
 
-     ![Create security group](img/create_security_group.png)
+   ![Create security group](img/create_security_group.png)
 
-     TIP: **Tip:**
-     Based on best practices, you should allow SSH traffic from only a known
-     host or CIDR block. In that case, change the SSH source to be custom and give
-     it the IP you want to SSH from.
+   TIP: **Tip:**
+   Based on best practices, you should allow SSH traffic from only a known
+   host or CIDR block. In that case, change the SSH source to be custom and give
+   it the IP you want to SSH from.
 
 1. When done, click **Save**.
 
@@ -204,7 +205,7 @@ create the actual RDS instance.
    we defined them in the [subnets section](#subnets)).
    Click **Create** when ready.
 
-    ![RDS Subnet Group](img/rds_subnet_group.png)
+   ![RDS Subnet Group](img/rds_subnet_group.png)
 
 ### Creating the database
 
@@ -214,27 +215,27 @@ Now, it's time to create the database:
 1. Select PostgreSQL and click **Next**.
 1. Since this is a production server, let's choose "Production". Click **Next**.
 1. Let's see the instance specifications:
-    1. Leave the license model as is (`postgresql-license`).
-    1. For the version, select the latest of the 9.6 series (check the
-       [database requirements](../../install/requirements.md#postgresql-requirements))
-       if there are any updates on this).
-    1. For the size, let's select a `t2.medium` instance.
-    1. Multi-AZ-deployment is recommended as redundancy, so choose "Create
-       replica in different zone". Read more at
-       [High Availability (Multi-AZ)](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html).
-    1. A Provisioned IOPS (SSD) storage type is best suited for HA (though you can
-       choose a General Purpose (SSD) to reduce the costs). Read more about it at
-       [Storage for Amazon RDS](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Storage.html).
-
-1. The rest of the settings on this page request a DB isntance identifier, username
+   1. Leave the license model as is (`postgresql-license`).
+   1. For the version, select the latest of the 9.6 series (check the
+      [database requirements](../../install/requirements.md#postgresql-requirements))
+      if there are any updates on this).
+   1. For the size, let's select a `t2.medium` instance.
+   1. Multi-AZ-deployment is recommended as redundancy, so choose "Create
+      replica in different zone". Read more at
+      [High Availability (Multi-AZ)](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html).
+   1. A Provisioned IOPS (SSD) storage type is best suited for HA (though you can
+      choose a General Purpose (SSD) to reduce the costs). Read more about it at
+      [Storage for Amazon RDS](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Storage.html).
+
+1. The rest of the settings on this page request a DB instance identifier, username
    and a master password. We've chosen to use `gitlab-db-ha`, `gitlab` and a
    very secure password respectively. Keep these in hand for later.
 1. Click **Next** to proceed to the advanced settings.
 1. Make sure to choose our gitlab VPC, our subnet group, set public accessibility to
    **No**, and to leave it to create a new security group. The only additional
-    change which will be helpful is the database name for which we can use
-    `gitlabhq_production`. At the very bottom, there's an option to enable
-    auto updates to minor versions. You may want to turn it off.
+   change which will be helpful is the database name for which we can use
+   `gitlabhq_production`. At the very bottom, there's an option to enable
+   auto updates to minor versions. You may want to turn it off.
 1. When done, click **Create database**.
 
 ### Installing the `pg_trgm` extension for PostgreSQL
@@ -276,7 +277,7 @@ To set up Redis:
    Make sure to select our VPC and its [private subnets](#subnets). Click
    **Create** when ready.
 
-    ![ElastiCache subnet](img/ec_subnet.png)
+   ![ElastiCache subnet](img/ec_subnet.png)
 
 1. Select **Redis** on the left menu and click **Create** to create a new
    Redis cluster. Depending on your load, you can choose whether to enable
@@ -284,16 +285,16 @@ To set up Redis:
    chance to deploy Redis in multi availability zones. In this guide, we chose
    not to enable it.
 1. In the settings section:
-    1. Give the cluster a name (`gitlab-redis`) and a description.
-    1. For the version, select the latest of `3.2` series (e.g., `3.2.10`).
-    1. Select the node type and the number of replicas.
+   1. Give the cluster a name (`gitlab-redis`) and a description.
+   1. For the version, select the latest of `3.2` series (e.g., `3.2.10`).
+   1. Select the node type and the number of replicas.
 1. In the advanced settings section:
    1. Select the multi-AZ auto-failover option.
    1. Select the subnet group we created previously.
    1. Manually select the preferred availability zones, and under "Replica 2"
       choose a different zone than the other two.
 
-        ![Redis availability zones](img/ec_az.png)
+      ![Redis availability zones](img/ec_az.png)
 
 1. In the security settings, edit the security groups and choose the
    `gitlab-security-group` we had previously created.
@@ -316,11 +317,11 @@ and add a custom TCP rule for port `6379` accessible within itself.
 On the EC2 dashboard, look for Load Balancer on the left column:
 
 1. Click the **Create Load Balancer** button.
-  1. Choose the Application Load Balancer.
-  1. Give it a name (`gitlab-loadbalancer`) and set the scheme to "internet-facing".
-  1. In the "Listeners" section, make sure it has HTTP and HTTPS.
-  1. In the "Availability Zones" section, select the `gitlab-vpc` we have created
-     and associate the **public subnets**.
+   1. Choose the Application Load Balancer.
+   1. Give it a name (`gitlab-loadbalancer`) and set the scheme to "internet-facing".
+   1. In the "Listeners" section, make sure it has HTTP and HTTPS.
+   1. In the "Availability Zones" section, select the `gitlab-vpc` we have created
+      and associate the **public subnets**.
 1. Click **Configure Security Settings** to go to the next section to
    select the TLS certificate. When done, go to the next step.
 1. In the "Security Groups" section, create a new one by giving it a name
@@ -355,7 +356,7 @@ Choose the AMI:
    where `<version>` the latest version as seen on the
    [releases page](https://about.gitlab.com/releases/).
 
-    ![Choose AMI](img/choose_ami.png)
+   ![Choose AMI](img/choose_ami.png)
 
 ### Choose an instance type
 
@@ -504,19 +505,19 @@ The EBS volume will host the Git repositories data:
 1. Tell GitLab to store its data in the new directory by editing
    `/etc/gitlab/gitlab.rb` with your editor:
 
-    ```ruby
-    git_data_dirs({
-      "default" => { "path" => "/mnt/gitlab-data" }
-    })
-    ```
+   ```ruby
+   git_data_dirs({
+     "default" => { "path" => "/mnt/gitlab-data" }
+   })
+   ```
 
-    where `/mnt/gitlab-data` the location where you will store the Git data.
+   where `/mnt/gitlab-data` the location where you will store the Git data.
 
 1. Save the file and reconfigure GitLab:
 
-    ```sh
-    sudo gitlab-ctl reconfigure
-    ```
+   ```sh
+   sudo gitlab-ctl reconfigure
+   ```
 
 TIP: **Tip:**
 If you wish to add more than one data volumes to store the Git repositories,
@@ -549,15 +550,15 @@ After you SSH into the instance, configure the domain name:
 1. Open `/etc/gitlab/gitlab.rb` with your preferred editor.
 1. Edit the `external_url` value:
 
-    ```ruby
-    external_url 'http://example.com'
-    ```
+   ```ruby
+   external_url 'http://example.com'
+   ```
 
 1. Reconfigure GitLab:
 
-    ```sh
-    sudo gitlab-ctl reconfigure
-    ```
+   ```sh
+   sudo gitlab-ctl reconfigure
+   ```
 
 You should now be able to reach GitLab at the URL you defined. To use HTTPS
 (recommended), see the [HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https).
@@ -608,9 +609,9 @@ To back up GitLab:
 1. SSH into your instance.
 1. Take a backup:
 
-    ```sh
-    sudo gitlab-rake gitlab:backup:create
-    ```
+   ```sh
+   sudo gitlab-backup create
+   ```
 
 ### Restoring GitLab from a backup
 
@@ -626,16 +627,16 @@ released, you can update your GitLab instance:
 1. SSH into your instance
 1. Take a backup:
 
-    ```sh
-    sudo gitlab-rake gitlab:backup:create
-    ```
+   ```sh
+   sudo gitlab-backup create
+   ```
 
 1. Update the repositories and install GitLab:
 
-    ```sh
-    sudo apt update
-    sudo apt install gitlab-ee
-    ```
+   ```sh
+   sudo apt update
+   sudo apt install gitlab-ee
+   ```
 
 After a few minutes, the new version should be up and running.
 
diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md
index b1f79893baf..543a222bd25 100644
--- a/doc/install/azure/index.md
+++ b/doc/install/azure/index.md
@@ -67,18 +67,19 @@ The first items we need to configure are the basic settings of the underlying vi
 1. Enter a `User name` - e.g. **"gitlab-admin"**
 1. Select an `Authentication type`, either **SSH public key** or **Password**:
 
-    > **Note:** if you're unsure which authentication type to use, select **Password**
+   > **Note:** if you're unsure which authentication type to use, select **Password**
+
+   1. If you chose **SSH public key** - enter your `SSH public key` into the field provided
+   _(read the [SSH documentation](../../ssh/README.md) to learn more about how to set up SSH
+   public keys)_
+   1. If you chose **Password** - enter the password you wish to use _(this is the password that you
+   will use later in this tutorial to [SSH] into the VM, so make sure it's a strong password/passphrase)_
 
-    1. If you chose **SSH public key** - enter your `SSH public key` into the field provided
-    _(read the [SSH documentation][GitLab-Docs-SSH] to learn more about how to set up SSH
-    public keys)_
-    1. If you chose **Password** - enter the password you wish to use _(this is the password that you
-    will use later in this tutorial to [SSH] into the VM, so make sure it's a strong password/passphrase)_
 1. Choose the appropriate `Subscription` tier for your Azure account
 1. Choose an existing `Resource Group` or create a new one - e.g. **"GitLab-CE-Azure"**
 
-    > **Note:** a "Resource group" is a way to group related resources together for easier administration.
-    > We chose "GitLab-CE-Azure", but your resource group can have the same name as your VM.
+   > **Note:** a "Resource group" is a way to group related resources together for easier administration.
+   > We chose "GitLab-CE-Azure", but your resource group can have the same name as your VM.
 
 1. Choose a `Location` - if you're unsure, select the default location
 
@@ -248,6 +249,7 @@ rules in the list:
 ![Azure - Inbound security rules - List](img/azure-inbound-sec-rules-list.png)
 
 ## Connecting to GitLab
+
 Use the domain name you set up earlier (or the public IP address) to visit your new GitLab instance
 in your browser. If everything has gone according to plan you should be presented with the
 following page, asking you to set a _new_ password for the administrator account automatically
@@ -348,6 +350,7 @@ your VM, you can use the IP address in its place in the following command:
 ```bash
 ssh username@your-azure-domain-name.com
 ```
+
 Provide your password at the prompt to authenticate.
 
 #### SSH from Windows (PuTTY)
@@ -404,25 +407,22 @@ on any cloud service you choose.
 
 ## Where to next?
 
-Check out our other [Technical Articles][GitLab-Technical-Articles] or browse the [GitLab Documentation][GitLab-Docs] to learn more about GitLab.
+Check out our other [Technical Articles](../../articles/index.md) or browse the [GitLab Documentation][GitLab-Docs](../../README.md) to learn more about GitLab.
 
 ### Useful links
 
 - [GitLab Community Edition][CE]
 - [GitLab Enterprise Edition][EE]
 - [Microsoft Azure][Azure]
-    - [Azure - Free Account FAQ][Azure-Free-Account-FAQ]
-    - [Azure - Marketplace][Azure-Marketplace]
-    - [Azure Portal][Azure-Portal]
-    - [Azure - Pricing Calculator][Azure-Pricing-Calculator]
-    - [Azure - Troubleshoot SSH Connections to an Azure Linux VM][Azure-Troubleshoot-SSH-Connection]
-    - [Azure - Properly Shutdown an Azure VM][Azure-Properly-Shutdown-VM]
+  - [Azure - Free Account FAQ][Azure-Free-Account-FAQ]
+  - [Azure - Marketplace][Azure-Marketplace]
+  - [Azure Portal][Azure-Portal]
+  - [Azure - Pricing Calculator][Azure-Pricing-Calculator]
+  - [Azure - Troubleshoot SSH Connections to an Azure Linux VM][Azure-Troubleshoot-SSH-Connection]
+  - [Azure - Properly Shutdown an Azure VM][Azure-Properly-Shutdown-VM]
 - [SSH], [PuTTY] and [Using SSH in PuTTY][Using-SSH-In-Putty]
 
 [Original-Blog-Post]: https://about.gitlab.com/2016/07/13/how-to-setup-a-gitlab-instance-on-microsoft-azure/ "How to Set up a GitLab Instance on Microsoft Azure"
-[GitLab-Docs]: https://docs.gitlab.com/ce/README.html "GitLab Documentation"
-[GitLab-Technical-Articles]: https://docs.gitlab.com/ce/articles/index.html "GitLab Technical Articles"
-[GitLab-Docs-SSH]: https://docs.gitlab.com/ce/ssh/README.html "GitLab Documentation: SSH"
 [CE]: https://about.gitlab.com/features/
 [EE]: https://about.gitlab.com/features/#ee-starter
 
diff --git a/doc/install/database_mysql.md b/doc/install/database_mysql.md
deleted file mode 100644
index cbb3b766b4e..00000000000
--- a/doc/install/database_mysql.md
+++ /dev/null
@@ -1,319 +0,0 @@
----
-type: reference
----
-
-# Database MySQL
-
-NOTE: **Note:**
-We do not recommend using MySQL due to various issues.
-For example, there have been bugs with case
-[(in)sensitivity](https://dev.mysql.com/doc/refman/5.7/en/case-sensitivity.html).
-
-Bugs relating to case sensitivity:
-
-- <https://bugs.mysql.com/bug.php?id=65830>
-- <https://bugs.mysql.com/bug.php?id=50909>
-- <https://bugs.mysql.com/bug.php?id=65830>
-- <https://bugs.mysql.com/bug.php?id=63164>
-
-## Initial database setup
-
-```sh
-# Install the database packages
-sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev
-
-# Ensure you have MySQL version 5.6 or later
-mysql --version
-
-# Pick a MySQL root password (can be anything), type it and press enter
-# Retype the MySQL root password and press enter
-
-# Secure your installation
-sudo mysql_secure_installation
-
-# Login to MySQL
-mysql -u root -p
-
-# Type the MySQL root password
-
-# Create a user for GitLab
-# do not type the 'mysql>', this is part of the prompt
-# change $password in the command below to a real password you pick
-mysql> CREATE USER 'git'@'localhost' IDENTIFIED BY '$password';
-
-# Ensure you can use the InnoDB engine which is necessary to support long indexes
-# If this fails, check your MySQL config files (e.g. `/etc/mysql/*.cnf`, `/etc/mysql/conf.d/*`) for the setting "innodb = off"
-mysql> SET storage_engine=INNODB;
-
-# If you have MySQL < 5.7.7 and want to enable utf8mb4 character set support with your GitLab install, you must set the following NOW:
-mysql> SET GLOBAL innodb_file_per_table=1, innodb_file_format=Barracuda, innodb_large_prefix=1;
-
-# If you use MySQL with replication, or just have MySQL configured with binary logging, you need to run the following to allow the use of `TRIGGER`:
-mysql> SET GLOBAL log_bin_trust_function_creators = 1;
-
-# Create the GitLab production database
-mysql> CREATE DATABASE IF NOT EXISTS `gitlabhq_production` DEFAULT CHARACTER SET `utf8` COLLATE `utf8_general_ci`;
-
-# Grant the GitLab user necessary permissions on the database
-mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, CREATE TEMPORARY TABLES, DROP, INDEX, ALTER, LOCK TABLES, REFERENCES, TRIGGER ON `gitlabhq_production`.* TO 'git'@'localhost';
-
-# Quit the database session
-mysql> \q
-
-# Try connecting to the new database with the new user
-sudo -u git -H mysql -u git -p -D gitlabhq_production
-
-# Type the password you replaced $password with earlier
-
-# You should now see a 'mysql>' prompt
-
-# Quit the database session
-mysql> \q
-```
-
-You are done installing the database for now and can go back to the rest of the installation.
-Please proceed to the rest of the installation **before** running through the steps below.
-
-### `log_bin_trust_function_creators`
-
-If you use MySQL with replication, or just have MySQL configured with binary logging, all of your MySQL servers will need to have `log_bin_trust_function_creators` enabled to allow the use of `TRIGGER` in migrations. You have already set this global variable in the steps above, but to make it persistent, add the following to your `my.cnf` file:
-
-```
-log_bin_trust_function_creators=1
-```
-
-### MySQL utf8mb4 support
-
-After installation or upgrade, remember to [convert any new tables](#tables-and-data-conversion-to-utf8mb4) to `utf8mb4`/`utf8mb4_general_ci`.
-
----
-
-GitLab 8.14 has introduced [a feature](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7420) requiring `utf8mb4` encoding to be supported in your GitLab MySQL Database, which is not the case if you have set up your database before GitLab 8.16.
-
-Follow the below instructions to ensure you use the most up to date requirements for your GitLab MySQL Database.
-
-**We are about to do the following:**
-
-- Ensure you can enable `utf8mb4` encoding and `utf8mb4_general_ci` collation for your GitLab DB, tables and data.
-- Convert your GitLab tables and data from `utf8`/`utf8_general_ci` to `utf8mb4`/`utf8mb4_general_ci`.
-
-### Check for utf8mb4 support
-
-#### Check for InnoDB File-Per-Table Tablespaces
-
-We need to check, enable and maybe convert your existing GitLab DB tables to the [InnoDB File-Per-Table Tablespaces](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) as a prerequisite for supporting **utfb8mb4 with long indexes** required by recent GitLab databases.
-
-    # Login to MySQL
-    mysql -u root -p
-
-    # Type the MySQL root password
-    mysql > use gitlabhq_production;
-
-    # Check your MySQL version is >= 5.5.3 (GitLab requires 5.5.14+)
-    mysql > SHOW VARIABLES LIKE 'version';
-    +---------------+-----------------+
-    | Variable_name | Value           |
-    +---------------+-----------------+
-    | version       | 5.5.53-0+deb8u1 |
-    +---------------+-----------------+
-
-    # Note where is your MySQL data dir for later:
-    mysql > select @@datadir;
-    +----------------+
-    | @@datadir      |
-    +----------------+
-    | /var/lib/mysql |
-    +----------------+
-
-    # Note whether your MySQL server runs with innodb_file_per_table ON or OFF:
-    mysql> SELECT @@innodb_file_per_table;
-    +-------------------------+
-    | @@innodb_file_per_table |
-    +-------------------------+
-    |                       1 |
-    +-------------------------+
-
-    # You can now quit the database session
-    mysql> \q
-
-> You need **MySQL 5.5.3 or later** to perform this update.
-
-Whatever the results of your checks above, we now need to check if your GitLab database has been created using [InnoDB File-Per-Table Tablespaces](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) (i.e. `innodb_file_per_table` was set to **1** at initial setup time).
-
-NOTE: **Note:**
-This setting is [enabled by default](http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_file_per_table) since MySQL 5.6.6.
-
-    # Run this command with root privileges, replace the data dir if different:
-    sudo ls -lh /var/lib/mysql/gitlabhq_production/*.ibd | wc -l
-
-    # Run this command with root privileges, replace the data dir if different:
-    sudo ls -lh /var/lib/mysql/gitlabhq_production/*.frm | wc -l
-
-- **Case 1: a result > 0 for both commands**
-
-Congratulations, your GitLab database uses the right InnoDB tablespace format.
-
-However, you must still ensure that any **future tables** created by GitLab will still use the right format:
-
-- If `SELECT @@innodb_file_per_table` returned **1** previously, your server is running correctly.
-
-    > It's however a requirement to check *now* that this setting is indeed persisted in your [`my.cnf`](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) file!
-
-- If `SELECT @@innodb_file_per_table` returned **0** previously, your server is not running correctly.
-
-    > [Enable innodb_file_per_table](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) by running in a MySQL session as root the command `SET GLOBAL innodb_file_per_table=1, innodb_file_format=Barracuda;` and persist the two settings in your [`my.cnf`](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) file.
-
-Now, if you have a **different result** returned by the 2 commands above, it means you have a **mix of tables format** uses in your GitLab database. This can happen if your MySQL server had different values for `innodb_file_per_table` in its life and you updated GitLab at different moments with those inconsistent values. So keep reading.
-
-- **Case 2: a result equals to "0" OR not the same result for both commands**
-
-Unfortunately, none or only some of your GitLab database tables use the GitLab requirement of [InnoDB File-Per-Table Tablespaces](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html).
-
-Let's enable what we need on the running server:
-
-    # Login to MySQL
-    mysql -u root -p
-
-    # Type the MySQL root password
-
-    # Enable innodb_file_per_table and set innodb_file_format on the running server:
-    mysql > SET GLOBAL innodb_file_per_table=1, innodb_file_format=Barracuda;
-
-    # You can now quit the database session
-    mysql> \q
-
-> Now, **persist** [innodb_file_per_table](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) and [innodb_file_format](https://dev.mysql.com/doc/refman/5.7/en/innodb-file-format-enabling.html) in your `my.cnf` file.
-
-Ensure at this stage that your GitLab instance is indeed **stopped**.
-
-Now, let's convert all the GitLab database tables to the new tablespace format:
-
-    # Login to MySQL
-    mysql -u root -p
-
-    # Type the MySQL root password
-    mysql > use gitlabhq_production;
-
-    # Safety check: you should still have those values set as follows:
-    mysql> SELECT @@innodb_file_per_table, @@innodb_file_format;
-    +-------------------------+----------------------+
-    | @@innodb_file_per_table | @@innodb_file_format |
-    +-------------------------+----------------------+
-    |                       1 | Barracuda            |
-    +-------------------------+----------------------+
-
-    mysql > SELECT CONCAT('ALTER TABLE `', TABLE_NAME,'` ENGINE=InnoDB;') AS 'Copy & run these SQL statements:' FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA="gitlabhq_production" AND TABLE_TYPE="BASE TABLE";
-
-    # If previous query returned results, copy & run all shown SQL statements
-
-    # You can now quit the database session
-    mysql> \q
-
----
-
-#### Check for proper InnoDB File Format, Row Format, Large Prefix and tables conversion
-
-We need to check, enable and probably convert your existing GitLab DB tables to use the [Barracuda InnoDB file format](https://dev.mysql.com/doc/refman/5.7/en/innodb-file-format.html), the [DYNAMIC row format](https://dev.mysql.com/doc/refman/5.7/en/glossary.html#glos_dynamic_row_format) and [innodb_large_prefix](http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_large_prefix) as a second prerequisite for supporting **utfb8mb4 with long indexes** used by recent GitLab databases.
-
-    # Login to MySQL
-    mysql -u root -p
-
-    # Type the MySQL root password
-    mysql > use gitlabhq_production;
-
-    # Set innodb_file_format and innodb_large_prefix on the running server:
-    # Note: These are the default settings only for MySQL 5.7.7 and later.
-
-    mysql > SET GLOBAL innodb_file_format=Barracuda, innodb_large_prefix=1;
-
-    # Your DB must be (still) using utf8/utf8_general_ci as default encoding and collation.
-    # We will NOT change the default encoding and collation on the DB in order to support future GitLab migrations creating tables
-    # that require "long indexes support" on installations using MySQL <= 5.7.9.
-    # However, when such migrations occur, you will have to follow this guide again to convert the newly created tables to the proper encoding/collation.
-
-    # This should return the following:
-    mysql> SELECT @@character_set_database, @@collation_database;
-    +--------------------------+----------------------+
-    | @@character_set_database | @@collation_database |
-    +--------------------------+----------------------+
-    | utf8                     | utf8_general_ci      |
-    +--------------------------+----------------------+
-
-> Now, ensure that [innodb_file_format](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) and [innodb_large_prefix](http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_large_prefix) are **persisted** in your `my.cnf` file.
-
-#### Tables and data conversion to utf8mb4
-
-Now that you have a persistent MySQL setup, you can safely upgrade tables after setup or upgrade time:
-
-    # Convert tables not using ROW_FORMAT DYNAMIC:
-
-    mysql> SELECT CONCAT('ALTER TABLE `', TABLE_NAME,'` ROW_FORMAT=DYNAMIC;') AS 'Copy & run these SQL statements:' FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA="gitlabhq_production" AND TABLE_TYPE="BASE TABLE" AND ROW_FORMAT!="Dynamic";
-
-    # !! If previous query returned results, copy & run all shown SQL statements
-
-    # Convert tables/columns not using utf8mb4/utf8mb4_general_ci as encoding/collation:
-
-    mysql > SET foreign_key_checks = 0;
-
-    mysql > SELECT CONCAT('ALTER TABLE `', TABLE_NAME,'` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;') AS 'Copy & run these SQL statements:' FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA="gitlabhq_production" AND TABLE_COLLATION != "utf8mb4_general_ci" AND TABLE_TYPE="BASE TABLE";
-
-    # !! If previous query returned results, copy & run all shown SQL statements
-
-    # Turn foreign key checks back on
-    mysql > SET foreign_key_checks = 1;
-
-    # You can now quit the database session
-    mysql> \q
-
-Ensure your GitLab database configuration file uses a proper connection encoding and collation:
-
-`sudo -u git -H editor config/database.yml`
-
-    production:
-      adapter: mysql2
-      encoding: utf8mb4
-      collation: utf8mb4_general_ci
-
-[Restart your GitLab instance](../administration/restart_gitlab.md).
-
-## MySQL strings limits
-
-After installation or upgrade, remember to run the `add_limits_mysql` Rake task:
-
-**Omnibus GitLab installations**
-
-```sh
-sudo gitlab-rake add_limits_mysql
-```
-
-**Installations from source**
-
-```sh
-bundle exec rake add_limits_mysql RAILS_ENV=production
-```
-
-The `text` type in MySQL has a different size limit than the `text` type in
-PostgreSQL. In MySQL `text` columns are limited to ~65kB, whereas in PostgreSQL
-`text` columns are limited up to ~1GB!
-
-The `add_limits_mysql` Rake task converts some important `text` columns in the
-GitLab database to `longtext` columns, which can persist values of up to 4GB
-(sometimes less if the value contains multibyte characters).
-
-Details can be found in the [PostgreSQL][postgres-text-type] and
-[MySQL](https://dev.mysql.com/doc/refman/5.7/en/string-type-overview.html) manuals.
-
-[postgres-text-type]: http://www.postgresql.org/docs/9.2/static/datatype-character.html
-[ce-38152]: https://gitlab.com/gitlab-org/gitlab-ce/issues/38152
-
-<!-- ## Troubleshooting
-
-Include any troubleshooting steps that you can foresee. If you know beforehand what issues
-one might have when setting this up, or when something is changed, or on upgrading, it's
-important to describe those, too. Think of things that may go wrong and include them here.
-This is important to minimize requests for support and to avoid doc comments with
-questions that you know someone might ask.
-
-Each scenario can be a third-level heading, e.g. `### Getting error message X`.
-If you have none to add when creating a doc, leave this section in place
-but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/install/digitaloceandocker.md b/doc/install/digitaloceandocker.md
index 63bb941ad47..b6bf7c95527 100644
--- a/doc/install/digitaloceandocker.md
+++ b/doc/install/digitaloceandocker.md
@@ -36,30 +36,30 @@ The rest of the steps are identical for macOS and Linux.
 1. Login to Digital Ocean.
 1. Generate a new API token at <https://cloud.digitalocean.com/settings/api/tokens>.
 
-    This command will create a new DO droplet called `gitlab-test-env-do` that will act as a docker host.
+   This command will create a new DO droplet called `gitlab-test-env-do` that will act as a docker host.
 
-    NOTE: **Note:**
-    4GB is the minimum requirement for a Docker host that will run more than one GitLab instance.
+   NOTE: **Note:**
+   4GB is the minimum requirement for a Docker host that will run more than one GitLab instance.
 
-    - RAM: 4GB
-    - Name: `gitlab-test-env-do`
-    - Driver: `digitalocean`
+   - RAM: 4GB
+   - Name: `gitlab-test-env-do`
+   - Driver: `digitalocean`
 
 1. Set the DO token:
 
-    ```sh
-    export DOTOKEN=<your generated token>
-    ```
+   ```sh
+   export DOTOKEN=<your generated token>
+   ```
 
 1. Create the machine:
 
-    ```sh
-    docker-machine create \
-      --driver digitalocean \
-      --digitalocean-access-token=$DOTOKEN \
-      --digitalocean-size "4gb" \
-        gitlab-test-env-do
-    ```
+   ```sh
+   docker-machine create \
+     --driver digitalocean \
+     --digitalocean-access-token=$DOTOKEN \
+     --digitalocean-size "4gb" \
+       gitlab-test-env-do
+   ```
 
 Resource: <https://docs.docker.com/machine/drivers/digital-ocean/>.
 
diff --git a/doc/install/docker.md b/doc/install/docker.md
index 06da65189ba..e0cef71a4d8 100644
--- a/doc/install/docker.md
+++ b/doc/install/docker.md
@@ -10,7 +10,7 @@ GitLab provides official Docker images allowing you to easily take advantage of
 
 ## Omnibus GitLab based images
 
-GitLab maintains a set of [official Docker images](https://hub.docker.com/r/gitlab) based on our [Omnibus GitLab package](https://docs.gitlab.com/omnibus/README.html). These images include:
+GitLab maintains a set of [official Docker images](https://hub.docker.com/u/gitlab) based on our [Omnibus GitLab package](https://docs.gitlab.com/omnibus/README.html). These images include:
 
 - [GitLab Community Edition](https://hub.docker.com/r/gitlab/gitlab-ce/)
 - [GitLab Enterprise Edition](https://hub.docker.com/r/gitlab/gitlab-ee/)
diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md
index 77c61acbfd4..be29bcc7cd7 100644
--- a/doc/install/google_cloud_platform/index.md
+++ b/doc/install/google_cloud_platform/index.md
@@ -30,16 +30,16 @@ To deploy GitLab on GCP you first need to create a virtual machine:
 1. Go to <https://console.cloud.google.com/compute/instances> and log in with your Google credentials.
 1. Click on **Create**
 
-    ![Search for GitLab](img/launch_vm.png)
+   ![Search for GitLab](img/launch_vm.png)
 
-1.  On the next page, you can select the type of VM as well as the
+1. On the next page, you can select the type of VM as well as the
    estimated costs. Provide the name of the instance, desired datacenter, and machine type. Note that GitLab recommends at least 2 vCPU's and 4GB of RAM.
 
-    ![Launch on Compute Engine](img/vm_details.png)
+   ![Launch on Compute Engine](img/vm_details.png)
 
 1. Click **Change** under Boot disk to select the size, type, and desired operating system. GitLab supports a [variety of linux operating systems][req], including Ubuntu and Debian. Click **Select** when finished.
 
-    ![Deploy in progress](img/boot_disk.png)
+   ![Deploy in progress](img/boot_disk.png)
 
 1. As a last step allow HTTP and HTTPS traffic, then click **Create**. The process will finish in a few seconds.
 
@@ -53,13 +53,13 @@ After a few seconds, the instance will be created and available to log in. The n
 1. Click on the SSH button to connect to the instance.
 1. A new window will appear, with you logged into the instance.
 
-    ![GitLab first sign in](img/ssh_terminal.png)
+   ![GitLab first sign in](img/ssh_terminal.png)
 
-1. Next, follow the instructions for installing GitLab for the operating system you choose, at <https://about.gitlab.com/installation/>. You can use the IP address from the step above, as the hostname.
+1. Next, follow the instructions for installing GitLab for the operating system you choose, at <https://about.gitlab.com/install/>. You can use the IP address from the step above, as the hostname.
 
 1. Congratulations! GitLab is now installed and you can access it via your browser. To finish installation, open the URL in your browser and provide the initial administrator password. The username for this account is `root`.
 
-    ![GitLab first sign in](img/first_signin.png)
+   ![GitLab first sign in](img/first_signin.png)
 
 ## Next steps
 
@@ -83,31 +83,31 @@ here's how you configure GitLab to be aware of the change:
 1. SSH into the VM. You can easily use the **SSH** button in the Google console
    and a new window will pop up.
 
-    ![SSH button](img/vm_created.png)
+   ![SSH button](img/vm_created.png)
 
-     In the future you might want to set up [connecting with an SSH key][ssh]
-     instead.
+   In the future you might want to set up [connecting with an SSH key][ssh]
+   instead.
 
 1. Edit the config file of Omnibus GitLab using your favorite text editor:
 
-    ```
-    sudo vim /etc/gitlab/gitlab.rb
-    ```
+   ```
+   sudo vim /etc/gitlab/gitlab.rb
+   ```
 
 1. Set the `external_url` value to the domain name you wish GitLab to have
    **without** `https`:
 
-    ```
-    external_url 'http://gitlab.example.com'
-    ```
+   ```
+   external_url 'http://gitlab.example.com'
+   ```
 
-    We will set up HTTPS in the next step, no need to do this now.
+   We will set up HTTPS in the next step, no need to do this now.
 
 1. Reconfigure GitLab for the changes to take effect:
 
-    ```
-    sudo gitlab-ctl reconfigure
-    ```
+   ```
+   sudo gitlab-ctl reconfigure
+   ```
 
 1. You can now visit GitLab using the domain name.
 
@@ -128,9 +128,9 @@ GitLab can be configured to authenticate with other OAuth providers, LDAP, SAML,
 Kerberos, etc. Here are some documents you might be interested in reading:
 
 - [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/)
-- [Integration documentation](https://docs.gitlab.com/ce/integration/)
-- [GitLab Pages configuration](https://docs.gitlab.com/ce/administration/pages/index.html)
-- [GitLab Container Registry configuration](https://docs.gitlab.com/ce/administration/container_registry.html)
+- [Integration documentation](../../integration/README.md)
+- [GitLab Pages configuration](../../administration/pages/index.md)
+- [GitLab Container Registry configuration](../../administration/container_registry.md)
 
 [freetrial]: https://console.cloud.google.com/freetrial "GCP free trial"
 [ip]: https://cloud.google.com/compute/docs/configure-instance-ip-addresses#promote_ephemeral_ip "Configuring an Instance's IP Addresses"
diff --git a/doc/install/installation.md b/doc/install/installation.md
index eb484dde545..295d9804497 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -6,7 +6,7 @@ type: howto
 
 This is the official installation guide to set up a production GitLab server
 using the source files. To set up a **development installation** or for many
-other installation options, see the [main installation page](index.md).
+other installation options, see the [main installation page](README.md).
 It was created for and tested on **Debian/Ubuntu** operating systems.
 Read [requirements.md](requirements.md) for hardware and operating system requirements.
 If you want to install on RHEL/CentOS, we recommend using the
@@ -134,7 +134,7 @@ Make sure you have the right version of Git installed:
 # Install Git
 sudo apt-get install -y git-core
 
-# Make sure Git is version 2.21.0 or higher
+# Make sure Git is version 2.22.0 or higher
 git --version
 ```
 
@@ -167,13 +167,13 @@ cd pcre2-10.33
 chmod +x configure
 ./configure --prefix=/usr --enable-jit
 make
-make install
+sudo make install
 
 # Download and compile from source
 cd /tmp
-curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.21.0.tar.gz
-echo '85eca51c7404da75e353eba587f87fea9481ba41e162206a6f70ad8118147bee  git-2.21.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.21.0.tar.gz
-cd git-2.21.0/
+curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.22.0.tar.gz
+echo 'a4b7e4365bee43caa12a38d646d2c93743d755d1cea5eab448ffb40906c9da0b  git-2.22.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.22.0.tar.gz
+cd git-2.22.0/
 ./configure --with-libpcre
 make prefix=/usr/local all
 
@@ -202,8 +202,8 @@ Then select 'Internet Site' and press enter to confirm the hostname.
 
 The Ruby interpreter is required to run GitLab.
 
-**Note:** The current supported Ruby (MRI) version is 2.5.x. GitLab 11.6
-  dropped support for Ruby 2.4.x.
+**Note:** The current supported Ruby (MRI) version is 2.6.x. GitLab 12.2
+  dropped support for Ruby 2.5.x.
 
 The use of Ruby version managers such as [RVM], [rbenv] or [chruby] with GitLab
 in production, frequently leads to hard to diagnose problems. For example,
@@ -263,7 +263,7 @@ Since GitLab 8.17, GitLab requires the use of Node to compile JavaScript
 assets, and Yarn to manage JavaScript dependencies. The current minimum
 requirements for these are:
 
-- `node` >= v8.10.0.
+- `node` >= v8.10.0. (We recommend node 12.x as it is faster)
 - `yarn` >= v1.10.0.
 
 In many distros,
@@ -271,8 +271,8 @@ the versions provided by the official package repositories are out of date, so
 we'll need to install through the following commands:
 
 ```sh
-# install node v8.x
-curl --location https://deb.nodesource.com/setup_8.x | sudo bash -
+# install node v12.x
+curl --location https://deb.nodesource.com/setup_12.x | sudo bash -
 sudo apt-get install -y nodejs
 
 curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
@@ -293,64 +293,63 @@ sudo adduser --disabled-login --gecos 'GitLab' git
 
 ## 6. Database
 
-We recommend using a PostgreSQL database. For MySQL, see the [MySQL setup guide](database_mysql.md).
-
 NOTE: **Note:**
-Because we need to make use of extensions and concurrent index removal, you need at least PostgreSQL 9.2.
+Starting from GitLab 12.1, only PostgreSQL is supported. Because we need to make
+use of extensions and concurrent index removal, you need at least PostgreSQL 9.2.
 
 1. Install the database packages:
 
-    ```sh
-    sudo apt-get install -y postgresql postgresql-client libpq-dev postgresql-contrib
-    ```
+   ```sh
+   sudo apt-get install -y postgresql postgresql-client libpq-dev postgresql-contrib
+   ```
 
 1. Create a database user for GitLab:
 
-    ```sh
-    sudo -u postgres psql -d template1 -c "CREATE USER git CREATEDB;"
-    ```
+   ```sh
+   sudo -u postgres psql -d template1 -c "CREATE USER git CREATEDB;"
+   ```
 
 1. Create the `pg_trgm` extension (required for GitLab 8.6+):
 
-    ```sh
-    sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
-    ```
+   ```sh
+   sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
+   ```
 
 1. Create the GitLab production database and grant all privileges on database:
 
-    ```sh
-    sudo -u postgres psql -d template1 -c "CREATE DATABASE gitlabhq_production OWNER git;"
-    ```
+   ```sh
+   sudo -u postgres psql -d template1 -c "CREATE DATABASE gitlabhq_production OWNER git;"
+   ```
 
 1. Try connecting to the new database with the new user:
 
-    ```sh
-    sudo -u git -H psql -d gitlabhq_production
-    ```
+   ```sh
+   sudo -u git -H psql -d gitlabhq_production
+   ```
 
 1. Check if the `pg_trgm` extension is enabled:
 
-    ```sh
-    SELECT true AS enabled
-    FROM pg_available_extensions
-    WHERE name = 'pg_trgm'
-    AND installed_version IS NOT NULL;
-    ```
+   ```sh
+   SELECT true AS enabled
+   FROM pg_available_extensions
+   WHERE name = 'pg_trgm'
+   AND installed_version IS NOT NULL;
+   ```
 
-    If the extension is enabled this will produce the following output:
+   If the extension is enabled this will produce the following output:
 
-    ```
-    enabled
-    ---------
-     t
-    (1 row)
-    ```
+   ```
+   enabled
+   ---------
+    t
+   (1 row)
+   ```
 
 1. Quit the database session:
 
-    ```sh
-    gitlabhq_production> \q
-    ```
+   ```sh
+   gitlabhq_production> \q
+   ```
 
 ## 7. Redis
 
@@ -493,7 +492,7 @@ sudo -u git -H editor config/resque.yml
 ```
 
 CAUTION: **Caution:**
-Make sure to edit both `gitlab.yml` and `unicorn.rb` to match your setup. 
+Make sure to edit both `gitlab.yml` and `unicorn.rb` to match your setup.
 If you want to use Puma web server, see [Using Puma](#using-puma) for the additional steps.
 
 NOTE: **Note:**
@@ -502,13 +501,8 @@ If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional ste
 ### Configure GitLab DB Settings
 
 ```sh
-# PostgreSQL only:
 sudo -u git cp config/database.yml.postgresql config/database.yml
 
-# MySQL only:
-sudo -u git cp config/database.yml.mysql config/database.yml
-
-# PostgreSQL only:
 # Remove host, username, and password lines from config/database.yml.
 # Once modified, the `production` settings will be as follows:
 #
@@ -520,7 +514,7 @@ sudo -u git cp config/database.yml.mysql config/database.yml
 #
 sudo -u git -H editor config/database.yml
 
-# MySQL and remote PostgreSQL only:
+# Remote PostgreSQL only:
 # Update username/password in config/database.yml.
 # You only need to adapt the production settings (first part).
 # If you followed the database guide then please do as follows:
@@ -528,7 +522,6 @@ sudo -u git -H editor config/database.yml
 # You can keep the double quotes around the password
 sudo -u git -H editor config/database.yml
 
-# PostgreSQL and MySQL:
 # Make config/database.yml readable to git only
 sudo -u git -H chmod o-rwx config/database.yml
 ```
@@ -544,11 +537,7 @@ Make sure you have `bundle` (run `bundle -v`):
 - `< 2.x`.
 
 ```sh
-# For PostgreSQL (note, the option says "without ... mysql")
 sudo -u git -H bundle install --deployment --without development test mysql aws kerberos
-
-# Or if you use MySQL (note, the option says "without ... postgres")
-sudo -u git -H bundle install --deployment --without development test postgres aws kerberos
 ```
 
 NOTE: **Note:**
@@ -571,7 +560,7 @@ NOTE: **Note:**
 If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps.
 
 NOTE: **Note:**
-Make sure your hostname can be resolved on the machine itself by either a proper DNS record or an additional line in `/etc/hosts` ("127.0.0.1  hostname"). This might be necessary, for example, if you set up GitLab behind a reverse proxy. If the hostname cannot be resolved, the final installation check will fail with "Check GitLab API access: FAILED. code: 401" and pushing commits will be rejected with "[remote rejected] master -> master (hook declined)".
+Make sure your hostname can be resolved on the machine itself by either a proper DNS record or an additional line in `/etc/hosts` ("127.0.0.1  hostname"). This might be necessary, for example, if you set up GitLab behind a reverse proxy. If the hostname cannot be resolved, the final installation check will fail with `Check GitLab API access: FAILED. code: 401` and pushing commits will be rejected with `[remote rejected] master -> master (hook declined)`.
 
 NOTE: **Note:**
 GitLab Shell application startup time can be greatly reduced by disabling RubyGems. This can be done in several ways:
@@ -645,8 +634,8 @@ Gitaly must be running for the next section.
 gitlab_path=/home/git/gitlab
 gitaly_path=/home/git/gitaly
 
-sudo -u git -H $gitlab_path/bin/daemon_with_pidfile $gitlab_path/tmp/pids/gitaly.pid \
-  $gitaly_path/gitaly $gitaly_path/config.toml >> $gitlab_path/log/gitaly.log 2>&1 &
+sudo -u git -H sh -c "$gitlab_path/bin/daemon_with_pidfile $gitlab_path/tmp/pids/gitaly.pid \
+  $gitaly_path/gitaly $gitaly_path/config.toml >> $gitlab_path/log/gitaly.log 2>&1 &"
 ```
 
 ### Initialize Database and Activate Advanced Features
@@ -842,26 +831,27 @@ how to configure GitLab with a relative URL.
 To use GitLab with HTTPS:
 
 1. In `gitlab.yml`:
-    1. Set the `port` option in section 1 to `443`.
-    1. Set the `https` option in section 1 to `true`.
+   1. Set the `port` option in section 1 to `443`.
+   1. Set the `https` option in section 1 to `true`.
 1. In the `config.yml` of gitlab-shell:
-    1. Set `gitlab_url` option to the HTTPS endpoint of GitLab (e.g. `https://git.example.com`).
-    1. Set the certificates using either the `ca_file` or `ca_path` option.
+   1. Set `gitlab_url` option to the HTTPS endpoint of GitLab (e.g. `https://git.example.com`).
+   1. Set the certificates using either the `ca_file` or `ca_path` option.
 1. Use the `gitlab-ssl` Nginx example config instead of the `gitlab` config.
-    1. Update `YOUR_SERVER_FQDN`.
-    1. Update `ssl_certificate` and `ssl_certificate_key`.
-    1. Review the configuration file and consider applying other security and performance enhancing features.
+   1. Update `YOUR_SERVER_FQDN`.
+   1. Update `ssl_certificate` and `ssl_certificate_key`.
+   1. Review the configuration file and consider applying other security and performance enhancing features.
 
 Using a self-signed certificate is discouraged but if you must use it, follow the normal directions. Then:
 
 1. Generate a self-signed SSL certificate:
 
-    ```sh
-    mkdir -p /etc/nginx/ssl/
-    cd /etc/nginx/ssl/
-    sudo openssl req -newkey rsa:2048 -x509 -nodes -days 3560 -out gitlab.crt -keyout gitlab.key
-    sudo chmod o-r gitlab.key
-    ```
+   ```sh
+   mkdir -p /etc/nginx/ssl/
+   cd /etc/nginx/ssl/
+   sudo openssl req -newkey rsa:2048 -x509 -nodes -days 3560 -out gitlab.crt -keyout gitlab.key
+   sudo chmod o-r gitlab.key
+   ```
+
 1. In the `config.yml` of gitlab-shell set `self_signed_cert` to `true`.
 
 ### Enable Reply by email
@@ -948,7 +938,7 @@ To use GitLab with Puma:
    cd /home/git/gitlab
 
    # Copy config file for the web server
-   sudo -u git -H config/puma.rb.example config/puma.rb
+   sudo -u git -H cp config/puma.rb.example config/puma.rb
    ```
 
 1. Edit the system `init.d` script to use `EXPERIMENTAL_PUMA=1` flag. If you have `/etc/default/gitlab`, then you should edit it instead.
diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md
index 43655767002..d067c341be8 100644
--- a/doc/install/kubernetes/gitlab_chart.md
+++ b/doc/install/kubernetes/gitlab_chart.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: https://docs.gitlab.com/charts/
+redirect_to: 'https://docs.gitlab.com/charts/'
 ---
 
 This document was moved to [another location](https://docs.gitlab.com/charts/).
diff --git a/doc/install/kubernetes/gitlab_omnibus.md b/doc/install/kubernetes/gitlab_omnibus.md
index 43655767002..d067c341be8 100644
--- a/doc/install/kubernetes/gitlab_omnibus.md
+++ b/doc/install/kubernetes/gitlab_omnibus.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: https://docs.gitlab.com/charts/
+redirect_to: 'https://docs.gitlab.com/charts/'
 ---
 
 This document was moved to [another location](https://docs.gitlab.com/charts/).
diff --git a/doc/install/kubernetes/gitlab_runner_chart.md b/doc/install/kubernetes/gitlab_runner_chart.md
index 08ccf2cf9ad..be58c957166 100644
--- a/doc/install/kubernetes/gitlab_runner_chart.md
+++ b/doc/install/kubernetes/gitlab_runner_chart.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: https://docs.gitlab.com/runner/install/kubernetes.html
+redirect_to: 'https://docs.gitlab.com/runner/install/kubernetes.html'
 ---
 
 This document was moved to [another location](https://docs.gitlab.com/runner/install/kubernetes.html).
diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md
index 43655767002..d067c341be8 100644
--- a/doc/install/kubernetes/index.md
+++ b/doc/install/kubernetes/index.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: https://docs.gitlab.com/charts/
+redirect_to: 'https://docs.gitlab.com/charts/'
 ---
 
 This document was moved to [another location](https://docs.gitlab.com/charts/).
diff --git a/doc/install/kubernetes/preparation/connect.md b/doc/install/kubernetes/preparation/connect.md
index db55e03d3d4..839461c982c 100644
--- a/doc/install/kubernetes/preparation/connect.md
+++ b/doc/install/kubernetes/preparation/connect.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: https://docs.gitlab.com/charts/installation/cloud/
+redirect_to: 'https://docs.gitlab.com/charts/installation/cloud/'
 ---
 
 This document was moved to [another location](https://docs.gitlab.com/charts/installation/cloud/).
diff --git a/doc/install/kubernetes/preparation/eks.md b/doc/install/kubernetes/preparation/eks.md
index 975d35c11c6..c3f53c2f580 100644
--- a/doc/install/kubernetes/preparation/eks.md
+++ b/doc/install/kubernetes/preparation/eks.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: https://docs.gitlab.com/charts/installation/cloud/eks.html
+redirect_to: 'https://docs.gitlab.com/charts/installation/cloud/eks.html'
 ---
 
 This document was moved to [another location](https://docs.gitlab.com/charts/installation/cloud/eks.html).
diff --git a/doc/install/kubernetes/preparation/networking.md b/doc/install/kubernetes/preparation/networking.md
index 2af16a752dc..7e88bbd3cd1 100644
--- a/doc/install/kubernetes/preparation/networking.md
+++ b/doc/install/kubernetes/preparation/networking.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: https://docs.gitlab.com/charts/installation/deployment.html#networking-and-dns
+redirect_to: 'https://docs.gitlab.com/charts/installation/deployment.html#networking-and-dns'
 ---
 
 This document was moved to [another location](https://docs.gitlab.com/charts/installation/deployment.html#networking-and-dns).
diff --git a/doc/install/kubernetes/preparation/rbac.md b/doc/install/kubernetes/preparation/rbac.md
index f94e7c24cdc..fc18b91641c 100644
--- a/doc/install/kubernetes/preparation/rbac.md
+++ b/doc/install/kubernetes/preparation/rbac.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: https://docs.gitlab.com/charts/installation/deployment.html#rbac
+redirect_to: 'https://docs.gitlab.com/charts/installation/deployment.html#rbac'
 ---
 
 This document was moved to [another location](https://docs.gitlab.com/charts/installation/deployment.html#rbac).
diff --git a/doc/install/kubernetes/preparation/tiller.md b/doc/install/kubernetes/preparation/tiller.md
index 66d6c8faece..c1c7910703e 100644
--- a/doc/install/kubernetes/preparation/tiller.md
+++ b/doc/install/kubernetes/preparation/tiller.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: https://docs.gitlab.com/charts/installation/tools.html
+redirect_to: 'https://docs.gitlab.com/charts/installation/tools.html'
 ---
 
 This document was moved to [another location](https://docs.gitlab.com/charts/installation/tools.html).
diff --git a/doc/install/kubernetes/preparation/tools_installation.md b/doc/install/kubernetes/preparation/tools_installation.md
index 66d6c8faece..c1c7910703e 100644
--- a/doc/install/kubernetes/preparation/tools_installation.md
+++ b/doc/install/kubernetes/preparation/tools_installation.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: https://docs.gitlab.com/charts/installation/tools.html
+redirect_to: 'https://docs.gitlab.com/charts/installation/tools.html'
 ---
 
 This document was moved to [another location](https://docs.gitlab.com/charts/installation/tools.html).
diff --git a/doc/install/openshift_and_gitlab/index.md b/doc/install/openshift_and_gitlab/index.md
index 18981c43464..fbbe2a34952 100644
--- a/doc/install/openshift_and_gitlab/index.md
+++ b/doc/install/openshift_and_gitlab/index.md
@@ -13,8 +13,8 @@ for details.
 
 ## Introduction
 
-[OpenShift Origin][openshift] is an open source container application
-platform created by [RedHat], based on [kubernetes] and [Docker]. That means
+[OpenShift Origin](https://www.okd.io/) (**Note:** renamed to OKD in Aug 2018) is an open source container application
+platform created by [RedHat], based on [kubernetes](https://kubernetes.io/) and [Docker]. That means
 you can host your own PaaS for free and almost with no hassle.
 
 In this tutorial, we will see how to deploy GitLab in OpenShift using GitLab's
@@ -27,8 +27,11 @@ For a video demonstration on installing GitLab on OpenShift, check the article [
 
 ## Prerequisites
 
-OpenShift 3 is not yet deployed on RedHat's offered Online platform ([openshift.com]),
-so in order to test it, we will use an [all-in-one Virtualbox image][vm] that is
+CAUTION: **Caution:** This information is no longer up to date, as the current versions
+have changed and products have been renamed.
+
+OpenShift 3 is not yet deployed on RedHat's offered Online platform, [openshift.com](https://www.openshift.com/),
+so in order to test it, we will use an [all-in-one Virtualbox image](https://www.okd.io/minishift/) that is
 offered by the OpenShift developers and managed by Vagrant. If you haven't done
 already, go ahead and install the following components as they are essential to
 test OpenShift easily:
@@ -67,17 +70,17 @@ In short:
 
 1. Open a terminal and in a new directory run:
 
-    ```sh
-    vagrant init openshift/origin-all-in-one
-    ```
+   ```sh
+   vagrant init openshift/origin-all-in-one
+   ```
 
 1. This will generate a Vagrantfile based on the all-in-one VM image
 1. In the same directory where you generated the Vagrantfile
    enter:
 
-    ```sh
-    vagrant up
-    ```
+   ```sh
+   vagrant up
+   ```
 
 This will download the VirtualBox image and fire up the VM with some preconfigured
 values as you can see in the Vagrantfile. As you may have noticed, you need
@@ -145,12 +148,12 @@ Login successful.
 
 You have access to the following projects and can switch between them with 'oc project <projectname>':
 
-  * cockpit
-  * default (current)
-  * delete
-  * openshift
-  * openshift-infra
-  * sample
+- cockpit
+- default (current)
+- delete
+- openshift
+- openshift-infra
+- sample
 
 Using project "default".
 ```
@@ -192,22 +195,22 @@ In that case, the OpenShift service might not be running, so in order to fix it:
 1. SSH into the VM by going to the directory where the Vagrantfile is and then
    run:
 
-    ```sh
-    vagrant ssh
-    ```
+   ```sh
+   vagrant ssh
+   ```
 
 1. Run `systemctl` and verify by the output that the `openshift` service is not
    running (it will be in red color). If that's the case start the service with:
 
-    ```sh
-    sudo systemctl start openshift
-    ```
+   ```sh
+   sudo systemctl start openshift
+   ```
 
 1. Verify the service is up with:
 
-    ```sh
-    systemctl status openshift -l
-    ```
+   ```sh
+   systemctl status openshift -l
+   ```
 
 Now you will be able to login using `oc` (like we did before) and visit the web
 console.
@@ -390,55 +393,55 @@ Let's see how to do that using the following steps.
 
 1. Make sure you are in the `gitlab` project:
 
-    ```sh
-    oc project gitlab
-    ```
+   ```sh
+   oc project gitlab
+   ```
 
 1. See what services are used for this project:
 
-    ```sh
-    oc get svc
-    ```
+   ```sh
+   oc get svc
+   ```
 
-    The output will be similar to:
+   The output will be similar to:
 
-    ```
-    NAME                   CLUSTER-IP       EXTERNAL-IP   PORT(S)         AGE
-    gitlab-ce              172.30.243.177   <none>        22/TCP,80/TCP   5d
-    gitlab-ce-postgresql   172.30.116.75    <none>        5432/TCP        5d
-    gitlab-ce-redis        172.30.105.88    <none>        6379/TCP        5d
-    ```
+   ```
+   NAME                   CLUSTER-IP       EXTERNAL-IP   PORT(S)         AGE
+   gitlab-ce              172.30.243.177   <none>        22/TCP,80/TCP   5d
+   gitlab-ce-postgresql   172.30.116.75    <none>        5432/TCP        5d
+   gitlab-ce-redis        172.30.105.88    <none>        6379/TCP        5d
+   ```
 
 1. We need to see the replication controllers of the `gitlab-ce` service.
    Get a detailed view of the current ones:
 
-    ```sh
-    oc describe rc gitlab-ce
-    ```
+   ```sh
+   oc describe rc gitlab-ce
+   ```
 
-    This will return a large detailed list of the current replication controllers.
-    Search for the name of the GitLab controller, usually `gitlab-ce-1` or if
-    that failed at some point and you spawned another one, it will be named
-    `gitlab-ce-2`.
+   This will return a large detailed list of the current replication controllers.
+   Search for the name of the GitLab controller, usually `gitlab-ce-1` or if
+   that failed at some point and you spawned another one, it will be named
+   `gitlab-ce-2`.
 
 1. Scale GitLab using the previous information:
 
-    ```sh
-    oc scale --replicas=2 replicationcontrollers gitlab-ce-2
-    ```
+   ```sh
+   oc scale --replicas=2 replicationcontrollers gitlab-ce-2
+   ```
 
 1. Get the new replicas number to make sure scaling worked:
 
-    ```sh
-    oc get rc gitlab-ce-2
-    ```
+   ```sh
+   oc get rc gitlab-ce-2
+   ```
 
-    which will return something like:
+   which will return something like:
 
-    ```
-    NAME          DESIRED   CURRENT   AGE
-    gitlab-ce-2   2         2         5d
-    ```
+   ```
+   NAME          DESIRED   CURRENT   AGE
+   gitlab-ce-2   2         2         5d
+   ```
 
 And that's it! We successfully scaled the replicas to 2 using the CLI.
 
@@ -458,7 +461,7 @@ OpenShift's website about [autoscaling].
 
 ## Current limitations
 
-As stated in the [all-in-one VM][vm] page:
+As stated in the [all-in-one VM](https://www.okd.io/minishift/) page:
 
 > By default, OpenShift will not allow a container to run as root or even a
 non-random container assigned userid. Most Docker images in the Dockerhub do not
@@ -475,13 +478,13 @@ For OpenShift v3.0, you will need to do this manually:
 
 1. Edit the Security Context:
 
-    ```sh
-    oc edit scc anyuid
-    ```
+   ```sh
+   oc edit scc anyuid
+   ```
 
 1. Add `system:serviceaccount:<project>:gitlab-ce-user` to the `users` section.
    If you changed the Application Name from the default the user will
-     will be `<app-name>-user` instead of `gitlab-ce-user`
+   will be `<app-name>-user` instead of `gitlab-ce-user`
 
 1. Save and exit the editor
 
@@ -506,12 +509,8 @@ is capable of. As always, you can refer to the detailed
 PaaS and managing your applications with the ease of containers.
 
 [RedHat]: https://www.redhat.com/en "RedHat website"
-[openshift]: https://www.openshift.org "OpenShift Origin website"
-[vm]: https://www.openshift.org/vm/ "OpenShift All-in-one VM"
 [vm-new]: https://app.vagrantup.com/openshift/boxes/origin-all-in-one "Official OpenShift Vagrant box on Vagrant Cloud"
 [template]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/docker/openshift-template.json "OpenShift template for GitLab"
-[openshift.com]: https://openshift.com "OpenShift Online"
-[kubernetes]: http://kubernetes.io/ "Kubernetes website"
 [Docker]: https://www.docker.com "Docker website"
 [oc]: https://docs.openshift.org/latest/cli_reference/get_started_cli.html "Documentation - oc CLI documentation"
 [VirtualBox]: https://www.virtualbox.org/wiki/Downloads "VirtualBox downloads"
diff --git a/doc/install/pivotal/index.md b/doc/install/pivotal/index.md
index f068572f1e9..6a4b361c842 100644
--- a/doc/install/pivotal/index.md
+++ b/doc/install/pivotal/index.md
@@ -1,4 +1,4 @@
-# GitLab Pivotal Tile **[PREMIUM ONLY]**
+# GitLab Pivotal Tile **(PREMIUM ONLY)**
 
 CAUTION: **Discontinued:**
 As of September 13, 2017, the GitLab Enterprise Plus for Pivotal Cloud Foundry
diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md
index 96b7d0f3648..bc6364f57f7 100644
--- a/doc/install/relative_url.md
+++ b/doc/install/relative_url.md
@@ -58,59 +58,59 @@ assumptions are made:
 
 Make sure to follow all steps below:
 
-1.  (Optional) If you run short on resources, you can temporarily free up some
-    memory by shutting down the GitLab service with the following command:
+1. (Optional) If you run short on resources, you can temporarily free up some
+   memory by shutting down the GitLab service with the following command:
 
-    ```shell
-    sudo service gitlab stop
-    ```
+   ```shell
+   sudo service gitlab stop
+   ```
 
-1.  Create `/home/git/gitlab/config/initializers/relative_url.rb`
+1. Create `/home/git/gitlab/config/initializers/relative_url.rb`
 
-    ```shell
-    cp /home/git/gitlab/config/initializers/relative_url.rb.sample \
-       /home/git/gitlab/config/initializers/relative_url.rb
-    ```
+   ```shell
+   cp /home/git/gitlab/config/initializers/relative_url.rb.sample \
+      /home/git/gitlab/config/initializers/relative_url.rb
+   ```
 
-    and change the following line:
+   and change the following line:
 
-    ```ruby
-    config.relative_url_root = "/gitlab"
-    ```
+   ```ruby
+   config.relative_url_root = "/gitlab"
+   ```
 
-1.  Edit `/home/git/gitlab/config/gitlab.yml` and uncomment/change the
-    following line:
+1. Edit `/home/git/gitlab/config/gitlab.yml` and uncomment/change the
+   following line:
 
-    ```yaml
-    relative_url_root: /gitlab
-    ```
+   ```yaml
+   relative_url_root: /gitlab
+   ```
 
-1.  Edit `/home/git/gitlab/config/unicorn.rb` and uncomment/change the
-    following line:
+1. Edit `/home/git/gitlab/config/unicorn.rb` and uncomment/change the
+   following line:
 
-    ```ruby
-    ENV['RAILS_RELATIVE_URL_ROOT'] = "/gitlab"
-    ```
+   ```ruby
+   ENV['RAILS_RELATIVE_URL_ROOT'] = "/gitlab"
+   ```
 
-1.  Edit `/home/git/gitlab-shell/config.yml` and append the relative path to
-    the following line:
+1. Edit `/home/git/gitlab-shell/config.yml` and append the relative path to
+   the following line:
 
-    ```yaml
-    gitlab_url: http://127.0.0.1/gitlab
-    ```
+   ```yaml
+   gitlab_url: http://127.0.0.1/gitlab
+   ```
 
-1.  Make sure you have copied the supplied init script and the defaults file
-    as stated in the [installation guide](installation.md#install-init-script).
-    Then, edit `/etc/default/gitlab` and set in `gitlab_workhorse_options` the
-    `-authBackend` setting to read like:
+1. Make sure you have copied the supplied init script and the defaults file
+   as stated in the [installation guide](installation.md#install-init-script).
+   Then, edit `/etc/default/gitlab` and set in `gitlab_workhorse_options` the
+   `-authBackend` setting to read like:
 
-    ```shell
-    -authBackend http://127.0.0.1:8080/gitlab
-    ```
+   ```shell
+   -authBackend http://127.0.0.1:8080/gitlab
+   ```
 
-    **Note:**
-    If you are using a custom init script, make sure to edit the above
-    gitlab-workhorse setting as needed.
+   **Note:**
+   If you are using a custom init script, make sure to edit the above
+   gitlab-workhorse setting as needed.
 
 1. [Restart GitLab][] for the changes to take effect.
 
@@ -118,12 +118,12 @@ Make sure to follow all steps below:
 
 To disable the relative URL:
 
-1.  Remove `/home/git/gitlab/config/initializers/relative_url.rb`
+1. Remove `/home/git/gitlab/config/initializers/relative_url.rb`
 
-1.  Follow the same as above starting from 2. and set up the
+1. Follow the same as above starting from 2. and set up the
     GitLab URL to one that doesn't contain a relative path.
 
-[omnibus-rel]: http://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab "How to set up relative URL in Omnibus GitLab"
+[omnibus-rel]: https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab "How to set up relative URL in Omnibus GitLab"
 [restart gitlab]: ../administration/restart_gitlab.md#installations-from-source "How to restart GitLab"
 
 <!-- ## Troubleshooting
diff --git a/doc/install/requirements.md b/doc/install/requirements.md
index ee3d17704a2..234e5acb394 100644
--- a/doc/install/requirements.md
+++ b/doc/install/requirements.md
@@ -9,7 +9,7 @@ as the hardware requirements that are needed to install and use GitLab.
 
 ## Operating Systems
 
-### Supported Unix distributions
+### Supported Linux distributions
 
 - Ubuntu
 - Debian
@@ -21,7 +21,7 @@ as the hardware requirements that are needed to install and use GitLab.
 
 For the installations options, see [the main installation page](README.md).
 
-### Unsupported Unix distributions
+### Unsupported Linux distributions and Unix-like operating systems
 
 - Arch Linux
 - Fedora
@@ -29,18 +29,18 @@ For the installations options, see [the main installation page](README.md).
 - Gentoo
 - macOS
 
-On the above unsupported distributions is still possible to install GitLab yourself.
-Please see the [installation from source guide](installation.md) and the [installation guides](https://about.gitlab.com/installation/) for more information.
+Installation of GitLab on these operating systems is possible, but not supported.
+Please see the [installation from source guide](installation.md) and the [installation guides](https://about.gitlab.com/install/) for more information.
 
-### Non-Unix operating systems such as Windows
+### Microsoft Windows
 
-GitLab is developed for Unix operating systems.
-It does **not** run on Windows, and we have no plans to support it in the near future. For the latest development status view this [issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/46567).
+GitLab is developed for Linux-based operating systems.
+It does **not** run on Microsoft Windows, and we have no plans to support it in the near future. For the latest development status view this [issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/46567).
 Please consider using a virtual machine to run GitLab.
 
 ## Ruby versions
 
-GitLab requires Ruby (MRI) 2.5. Support for Ruby versions below 2.5 (2.3, 2.4) will stop with GitLab 11.6.
+GitLab requires Ruby (MRI) 2.6. Support for Ruby versions below 2.6 (2.4, 2.5) will stop with GitLab 12.2.
 
 You will have to use the standard MRI implementation of Ruby.
 We love [JRuby](https://www.jruby.org/) and [Rubinius](https://rubinius.com) but GitLab
@@ -62,17 +62,19 @@ NOTE: **Note:** Since file system performance may affect GitLab's overall perfor
 
 ### CPU
 
+This is the recommended minimum hardware for a handful of example GitLab user base sizes. Your exact needs may be more, depending on your workload. Your workload is influenced by factors such as - but not limited to - how active your users are, how much automation you use, mirroring, and repo/change size.
+
 - 1 core supports up to 100 users but the application can be a bit slower due to having all workers and background jobs running on the same core
-- **2 cores** is the **recommended** number of cores and supports up to 500 users
-- 4 cores supports up to 2,000 users
-- 8 cores supports up to 5,000 users
-- 16 cores supports up to 10,000 users
-- 32 cores supports up to 20,000 users
-- 64 cores supports up to 40,000 users
-- More users? Run it on [multiple application servers](https://about.gitlab.com/high-availability/)
+- **2 cores** is the **recommended** minimum number of cores and supports up to 100 users
+- 4 cores supports up to 500 users
+- 8 cores supports up to 1,000 users
+- 32 cores supports up to 5,000 users
+- More users? Run it high-availability on [multiple application servers](https://about.gitlab.com/high-availability/)
 
 ### Memory
 
+This is the recommended minimum hardware for a handful of example GitLab user base sizes. Your exact needs may be more, depending on your workload. Your workload is influenced by factors such as - but not limited to - how active your users are, how much automation you use, mirroring, and repo/change size.
+
 You need at least 8GB of addressable memory (RAM + swap) to install and use GitLab!
 The operating system and any other running applications will also be using memory
 so keep in mind that you need at least 4GB available before running GitLab. With
@@ -80,13 +82,11 @@ less memory GitLab will give strange errors during the reconfigure run and 500
 errors during usage.
 
 - 4GB RAM + 4GB swap supports up to 100 users but it will be very slow
-- **8GB RAM** is the **recommended** memory size for all installations and supports up to 100 users
-- 16GB RAM supports up to 2,000 users
-- 32GB RAM supports up to 4,000 users
-- 64GB RAM supports up to 8,000 users
-- 128GB RAM supports up to 16,000 users
-- 256GB RAM supports up to 32,000 users
-- More users? Run it on [multiple application servers](https://about.gitlab.com/high-availability/)
+- **8GB RAM** is the **recommended** minimum memory size for all installations and supports up to 100 users
+- 16GB RAM supports up to 500 users
+- 32GB RAM supports up to 1,000 users
+- 128GB RAM supports up to 5,000 users
+- More users? Run it high-availability on [multiple application servers](https://about.gitlab.com/high-availability/)
 
 We recommend having at least [2GB of swap on your server](https://askubuntu.com/a/505344/310789), even if you currently have
 enough available RAM. Having swap will help reduce the chance of errors occurring
@@ -94,6 +94,8 @@ if your available memory changes. We also recommend [configuring the kernel's sw
 to a low value like `10` to make the most of your RAM while still having the swap
 available when needed.
 
+Our [Memory Team](https://about.gitlab.com/handbook/engineering/development/enablement/memory/) is actively working to reduce the memory requirement.
+
 NOTE: **Note:** The 25 workers of Sidekiq will show up as separate processes in your process overview (such as `top` or `htop`) but they share the same RAM allocation since Sidekiq is a multithreaded application. Please see the section below about Unicorn workers for information about how many you need of those.
 
 ## Database
@@ -104,32 +106,10 @@ installation (e.g. the number of users, projects, etc).
 
 We currently support the following databases:
 
-- PostgreSQL (highly recommended)
-- MySQL/MariaDB (strongly discouraged, not all GitLab features are supported, no support for [MySQL/MariaDB GTID](https://mariadb.com/kb/en/mariadb/gtid/))
-
-We highly recommend the use of PostgreSQL instead of MySQL/MariaDB as not all
-features of GitLab work with MySQL/MariaDB:
-
-1. MySQL support for subgroups was [dropped with GitLab 9.3][post].
-   See [issue #30472][30472] for more information.
-1. Geo does [not support MySQL](../administration/geo/replication/database.md). This means no supported Disaster Recovery solution if using MySQL. **[PREMIUM ONLY]**
-1. [Zero downtime migrations](../update/README.md#upgrading-without-downtime) do not work with MySQL.
-1. [Database load balancing](../administration/database_load_balancing.md) is
-   supported only for PostgreSQL. **[PREMIUM ONLY]**
-1. GitLab [optimizes the loading of dashboard events](https://gitlab.com/gitlab-org/gitlab-ce/issues/31806) using [PostgreSQL LATERAL JOINs](https://blog.heapanalytics.com/postgresqls-powerful-new-join-type-lateral/).
-1. In general, SQL optimized for PostgreSQL may run much slower in MySQL due to
-   differences in query planners. For example, subqueries that work well in PostgreSQL
-   may not be [performant in MySQL](https://dev.mysql.com/doc/refman/5.7/en/optimizing-subqueries.html).
-1. Binary column index length is limited to 20 bytes. This is accomplished with [a hack](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/initializers/mysql_set_length_for_binary_indexes.rb).
-1. MySQL requires a variety of hacks to increase limits on various columns, [for example](https://gitlab.com/gitlab-org/gitlab-ce/issues/49583).
-1. [The milestone filter runs slower queries on MySQL](https://gitlab.com/gitlab-org/gitlab-ce/issues/51173#note_99391731).
-1. We expect this list to grow over time.
-
-Existing users using GitLab with MySQL/MariaDB are advised to
-[migrate to PostgreSQL](../update/mysql_to_postgresql.md) instead.
-
-[30472]: https://gitlab.com/gitlab-org/gitlab-ce/issues/30472
-[post]: https://about.gitlab.com/2017/06/22/gitlab-9-3-released/#dropping-support-for-subgroups-in-mysql
+- PostgreSQL
+
+Support for MySQL was removed in GitLab 12.1. Existing users using GitLab with
+MySQL/MariaDB are advised to [migrate to PostgreSQL](../update/mysql_to_postgresql.md) before upgrading.
 
 ### PostgreSQL Requirements
 
@@ -168,8 +148,8 @@ CREATE EXTENSION postgres_fdw;
 
 ## Unicorn Workers
 
-For most instances we recommend using: CPU cores + 1 = unicorn workers.
-So for a machine with 2 cores, 3 unicorn workers is ideal.
+For most instances we recommend using: (CPU cores * 1.5) + 1 = unicorn workers.
+For example a node with 4 cores would have 7 unicorn workers.
 
 For all machines that have 2GB and up we recommend a minimum of three unicorn workers.
 If you have a 1GB machine we recommend to configure only two Unicorn workers to prevent excessive swapping.
diff --git a/doc/integration/README.md b/doc/integration/README.md
index 1fea6a32c28..55f9666e3a3 100644
--- a/doc/integration/README.md
+++ b/doc/integration/README.md
@@ -13,10 +13,10 @@ See the documentation below for details on how to configure these services.
 - [Auth0 OmniAuth](auth0.md) Enable the Auth0 OmniAuth provider
 - [Bitbucket](bitbucket.md) Import projects from Bitbucket.org and login to your GitLab instance with your Bitbucket.org account
 - [CAS](cas.md) Configure GitLab to sign in using CAS
-- [External issue tracker](external-issue-tracker.md) Redmine, JIRA, etc.
+- [External issue tracker](external-issue-tracker.md) Redmine, Jira, etc.
 - [Gmail actions buttons](gmail_action_buttons_for_gitlab.md) Adds GitLab actions to messages
 - [Jenkins](jenkins.md) Integrate with the Jenkins CI
-- [JIRA](../user/project/integrations/jira.md) Integrate with the JIRA issue tracker
+- [Jira](../user/project/integrations/jira.md) Integrate with the Jira issue tracker
 - [Kerberos](kerberos.md) Integrate with Kerberos
 - [LDAP](ldap.md) Set up sign in via LDAP
 - [OAuth2 provider](oauth_provider.md) OAuth2 application creation
@@ -27,7 +27,7 @@ See the documentation below for details on how to configure these services.
 - [SAML](saml.md) Configure GitLab as a SAML 2.0 Service Provider
 - [Trello](trello_power_up.md) Integrate Trello with GitLab
 
-> GitLab Enterprise Edition contains [advanced Jenkins support][jenkins].
+> GitLab Enterprise Edition contains [advanced Jenkins support](jenkins.md).
 
 ## Project services
 
@@ -55,7 +55,7 @@ at Super User also has relevant information.
 
 **Omnibus Trusted Chain**
 
-[Install the self signed certificate or custom certificate authorities](http://docs.gitlab.com/omnibus/common_installation_problems/README.html#using-self-signed-certificate-or-custom-certificate-authorities)
+[Install the self signed certificate or custom certificate authorities](https://docs.gitlab.com/omnibus/common_installation_problems/README.html#using-self-signed-certificate-or-custom-certificate-authorities)
 in to GitLab Omnibus.
 
 It is enough to concatenate the certificate to the main trusted certificate
@@ -70,5 +70,3 @@ After that restart GitLab with:
 ```bash
 sudo gitlab-ctl restart
 ```
-
-[jenkins]: http://docs.gitlab.com/ee/integration/jenkins.html
diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md
index 4f7be70baf2..cb8f25d2895 100644
--- a/doc/integration/akismet.md
+++ b/doc/integration/akismet.md
@@ -3,7 +3,7 @@
 > *Note:* Before 8.11 only issues submitted via the API and for non-project
 members were submitted to Akismet.
 
-GitLab leverages [Akismet](http://akismet.com) to protect against spam. Currently
+GitLab leverages [Akismet](https://akismet.com/) to protect against spam. Currently
 GitLab uses Akismet to prevent the creation of spam issues on public projects. Issues
 created via the WebUI or the API can be submitted to Akismet for review.
 
diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md
index c67375ede50..5061b863e79 100644
--- a/doc/integration/auth0.md
+++ b/doc/integration/auth0.md
@@ -16,64 +16,64 @@ application.
 1. At the top of the Settings screen, you should see your Domain, Client ID and
    Client Secret. Take note of these as you'll need to put them in the
    configuration file. For example:
-    - Domain: `test1234.auth0.com`
-    - Client ID: `t6X8L2465bNePWLOvt9yi41i`
-    - Client Secret: `KbveM3nqfjwCbrhaUy_gDu2dss8TIlHIdzlyf33pB7dEK5u_NyQdp65O_o02hXs2`
+   - Domain: `test1234.auth0.com`
+   - Client ID: `t6X8L2465bNePWLOvt9yi41i`
+   - Client Secret: `KbveM3nqfjwCbrhaUy_gDu2dss8TIlHIdzlyf33pB7dEK5u_NyQdp65O_o02hXs2`
 
 1. Fill in the Allowed Callback URLs:
-    - `http://YOUR_GITLAB_URL/users/auth/auth0/callback` (or)
-    - `https://YOUR_GITLAB_URL/users/auth/auth0/callback`
+   - `http://YOUR_GITLAB_URL/users/auth/auth0/callback` (or)
+   - `https://YOUR_GITLAB_URL/users/auth/auth0/callback`
 
 1. Fill in the Allowed Origins (CORS):
-    - `http://YOUR_GITLAB_URL` (or)
-    - `https://YOUR_GITLAB_URL`
+   - `http://YOUR_GITLAB_URL` (or)
+   - `https://YOUR_GITLAB_URL`
 
 1. On your GitLab server, open the configuration file.
 
-    For omnibus package:
+   For omnibus package:
 
-    ```sh
-      sudo editor /etc/gitlab/gitlab.rb
-    ```
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```sh
-      cd /home/git/gitlab
-      sudo -u git -H editor config/gitlab.yml
-    ```
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H editor config/gitlab.yml
+   ```
 
 1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration)
    for initial settings.
 
 1. Add the provider configuration:
 
-    For omnibus package:
-
-    ```ruby
-      gitlab_rails['omniauth_providers'] = [
-        {
-          "name" => "auth0",
-          "args" => { client_id: 'YOUR_AUTH0_CLIENT_ID',
-                      client_secret: 'YOUR_AUTH0_CLIENT_SECRET',
-                      domain: 'YOUR_AUTH0_DOMAIN',
-                      scope: 'openid profile email'
-                    }
-        }
-      ]
-    ```
-
-    For installations from source:
-
-    ```yaml
-      - { name: 'auth0',
-          args: {
-            client_id: 'YOUR_AUTH0_CLIENT_ID',
-            client_secret: 'YOUR_AUTH0_CLIENT_SECRET',
-            domain: 'YOUR_AUTH0_DOMAIN',
-            scope: 'openid profile email' }
-        }
-    ```
+   For omnibus package:
+
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       "name" => "auth0",
+       "args" => { client_id: 'YOUR_AUTH0_CLIENT_ID',
+                   client_secret: 'YOUR_AUTH0_CLIENT_SECRET',
+                   domain: 'YOUR_AUTH0_DOMAIN',
+                   scope: 'openid profile email'
+                 }
+     }
+   ]
+   ```
+
+   For installations from source:
+
+   ```yaml
+   - { name: 'auth0',
+       args: {
+         client_id: 'YOUR_AUTH0_CLIENT_ID',
+         client_secret: 'YOUR_AUTH0_CLIENT_SECRET',
+         domain: 'YOUR_AUTH0_DOMAIN',
+         scope: 'openid profile email' }
+     }
+   ```
 
 1. Change `YOUR_AUTH0_CLIENT_ID` to the client ID from the Auth0 Console page
    from step 5.
@@ -81,8 +81,8 @@ application.
 1. Change `YOUR_AUTH0_CLIENT_SECRET` to the client secret from the Auth0 Console
    page from step 5.
 
-1.  [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
-    installed GitLab via Omnibus or from source respectively.
+1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
+   installed GitLab via Omnibus or from source respectively.
 
 On the sign in page there should now be an Auth0 icon below the regular sign in
 form. Click the icon to begin the authentication process. Auth0 will ask the
diff --git a/doc/integration/azure.md b/doc/integration/azure.md
index 7a6d4bb143f..a9468f201ef 100644
--- a/doc/integration/azure.md
+++ b/doc/integration/azure.md
@@ -2,21 +2,21 @@
 
 To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your application with Azure. Azure will generate a client ID and secret key for you to use.
 
-1.  Sign in to the [Azure Management Portal](https://manage.windowsazure.com).
+1. Sign in to the [Azure Management Portal](https://portal.azure.com).
 
-1.  Select "Active Directory" on the left and choose the directory you want to use to register GitLab.
+1. Select "Active Directory" on the left and choose the directory you want to use to register GitLab.
 
-1.  Select "Applications" at the top bar and click the "Add" button the bottom.
+1. Select "Applications" at the top bar and click the "Add" button the bottom.
 
-1.  Select "Add an application my organization is developing".
+1. Select "Add an application my organization is developing".
 
-1.  Provide the project information and click the "Next" button.
-    - Name: 'GitLab' works just fine here.
-    - Type: 'WEB APPLICATION AND/OR WEB API'
+1. Provide the project information and click the "Next" button.
+   - Name: 'GitLab' works just fine here.
+   - Type: 'WEB APPLICATION AND/OR WEB API'
 
-1.  On the "App properties" page enter the needed URI's and click the "Complete" button.
-    - SIGN-IN URL: Enter the URL of your GitLab installation (e.g `https://gitlab.mycompany.com/`)
-    - APP ID URI: Enter the endpoint URL for Microsoft to use, just has to be unique (e.g `https://mycompany.onmicrosoft.com/gitlab`)
+1. On the "App properties" page enter the needed URI's and click the "Complete" button.
+   - SIGN-IN URL: Enter the URL of your GitLab installation (e.g `https://gitlab.mycompany.com/`)
+   - APP ID URI: Enter the endpoint URL for Microsoft to use, just has to be unique (e.g `https://mycompany.onmicrosoft.com/gitlab`)
 
 1. Select "Configure" in the top menu.
 
@@ -30,59 +30,59 @@ To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your ap
 
 1. You will see lots of endpoint URLs in the form `https://login.microsoftonline.com/TENANT ID/...`, note down the TENANT ID part of one of those endpoints.
 
-1.  On your GitLab server, open the configuration file.
+1. On your GitLab server, open the configuration file.
 
-    For omnibus package:
+   For omnibus package:
 
-    ```sh
-      sudo editor /etc/gitlab/gitlab.rb
-    ```
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```sh
-      cd /home/git/gitlab
+   ```sh
+   cd /home/git/gitlab
 
-      sudo -u git -H editor config/gitlab.yml
-    ```
+   sudo -u git -H editor config/gitlab.yml
+   ```
 
-1.  See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
 
-1.  Add the provider configuration:
+1. Add the provider configuration:
 
-    For omnibus package:
+   For omnibus package:
 
-    ```ruby
-      gitlab_rails['omniauth_providers'] = [
-        {
-          "name" => "azure_oauth2",
-          "args" => {
-            "client_id" => "CLIENT ID",
-            "client_secret" => "CLIENT SECRET",
-            "tenant_id" => "TENANT ID",
-          }
-        }
-      ]
-    ```
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       "name" => "azure_oauth2",
+       "args" => {
+         "client_id" => "CLIENT ID",
+         "client_secret" => "CLIENT SECRET",
+         "tenant_id" => "TENANT ID",
+       }
+     }
+   ]
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```
-     - { name: 'azure_oauth2',
-       args: { client_id: "CLIENT ID",
-       client_secret: "CLIENT SECRET",
-       tenant_id: "TENANT ID" } }
-    ```
+   ```
+   - { name: 'azure_oauth2',
+     args: { client_id: "CLIENT ID",
+     client_secret: "CLIENT SECRET",
+     tenant_id: "TENANT ID" } }
+   ```
 
-    The `base_azure_url` is optional and can be added for different locales;
-    e.g. `base_azure_url: "https://login.microsoftonline.de"`.
+   The `base_azure_url` is optional and can be added for different locales;
+   e.g. `base_azure_url: "https://login.microsoftonline.de"`.
 
-1.  Replace 'CLIENT ID', 'CLIENT SECRET' and 'TENANT ID' with the values you got above.
+1. Replace 'CLIENT ID', 'CLIENT SECRET' and 'TENANT ID' with the values you got above.
 
-1.  Save the configuration file.
+1. Save the configuration file.
 
-1.  [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
-    installed GitLab via Omnibus or from source respectively.
+1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
+   installed GitLab via Omnibus or from source respectively.
 
 On the sign in page there should now be a Microsoft icon below the regular sign in form. Click the icon to begin the authentication process. Microsoft will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in.
 
diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md
index 68ec8c4b5c2..5d8f2ebcb8b 100644
--- a/doc/integration/bitbucket.md
+++ b/doc/integration/bitbucket.md
@@ -30,97 +30,97 @@ To enable the Bitbucket OmniAuth provider you must register your application
 with Bitbucket.org. Bitbucket will generate an application ID and secret key for
 you to use.
 
-1.  Sign in to [Bitbucket.org](https://bitbucket.org).
-1.  Navigate to your individual user settings (**Bitbucket settings**) or a team's
-    settings (**Manage team**), depending on how you want the application registered.
-    It does not matter if the application is registered as an individual or a
-    team, that is entirely up to you.
-1.  Select **OAuth** in the left menu under "Access Management".
-1.  Select **Add consumer**.
-1.  Provide the required details:
-
-    | Item | Description |
-    | :--- | :---------- |
-    | **Name** | This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. |
-    | **Application description** | Fill this in if you wish. |
-    | **Callback URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com/users/auth`. |
-    | **URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com`. |
-
-    NOTE: Be sure to append `/users/auth` to the end of the callback URL
-    to prevent a [OAuth2 convert
-    redirect](http://tetraph.com/covert_redirect/) vulnerability.
-
-    NOTE: Starting in GitLab 8.15, you MUST specify a callback URL, or you will
-    see an "Invalid redirect_uri" message. For more details, see [the
-    Bitbucket documentation](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html).
-
-    And grant at least the following permissions:
-
-    ```
-    Account: Email, Read
-    Projects: Read
-    Repositories: Read
-    Pull Requests: Read
-    Issues: Read
-    Wiki: Read and Write
-    ```
-
-    ![Bitbucket OAuth settings page](img/bitbucket_oauth_settings_page.png)
-
-1.  Select **Save**.
-1.  Select your newly created OAuth consumer and you should now see a Key and
-    Secret in the list of OAuth consumers. Keep this page open as you continue
-    the configuration.
-
-      ![Bitbucket OAuth key](img/bitbucket_oauth_keys.png)
-
-1.  On your GitLab server, open the configuration file:
-
-    ```
-    # For Omnibus packages
-    sudo editor /etc/gitlab/gitlab.rb
-
-    # For installations from source
-    sudo -u git -H editor /home/git/gitlab/config/gitlab.yml
-    ```
-
-1.  Add the Bitbucket provider configuration:
-
-    For Omnibus packages:
-
-    ```ruby
-    gitlab_rails['omniauth_enabled'] = true
-
-    gitlab_rails['omniauth_providers'] = [
-      {
-        "name" => "bitbucket",
-        "app_id" => "BITBUCKET_APP_KEY",
-        "app_secret" => "BITBUCKET_APP_SECRET",
-        "url" => "https://bitbucket.org/"
-      }
-    ]
-    ```
-
-    For installations from source:
-
-    ```yaml
-    omniauth:
-      enabled: true
-      providers:
-        - { name: 'bitbucket',
-            app_id: 'BITBUCKET_APP_KEY',
-            app_secret: 'BITBUCKET_APP_SECRET',
-            url: 'https://bitbucket.org/' }
-    ```
-
-    ---
-
-    Where `BITBUCKET_APP_KEY` is the Key and `BITBUCKET_APP_SECRET` the Secret
-    from the Bitbucket application page.
-
-1.  Save the configuration file.
-1.  For the changes to take effect, [reconfigure GitLab][] if you installed via
-    Omnibus, or [restart][] if installed from source.
+1. Sign in to [Bitbucket.org](https://bitbucket.org).
+1. Navigate to your individual user settings (**Bitbucket settings**) or a team's
+   settings (**Manage team**), depending on how you want the application registered.
+   It does not matter if the application is registered as an individual or a
+   team, that is entirely up to you.
+1. Select **OAuth** in the left menu under "Access Management".
+1. Select **Add consumer**.
+1. Provide the required details:
+
+   | Item | Description |
+   | :--- | :---------- |
+   | **Name** | This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. |
+   | **Application description** | Fill this in if you wish. |
+   | **Callback URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com/users/auth`. |
+   | **URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com`. |
+
+   NOTE: Be sure to append `/users/auth` to the end of the callback URL
+   to prevent a [OAuth2 convert
+   redirect](http://tetraph.com/covert_redirect/) vulnerability.
+
+   NOTE: Starting in GitLab 8.15, you MUST specify a callback URL, or you will
+   see an "Invalid redirect_uri" message. For more details, see [the
+   Bitbucket documentation](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html).
+
+   And grant at least the following permissions:
+
+   ```
+   Account: Email, Read
+   Projects: Read
+   Repositories: Read
+   Pull Requests: Read
+   Issues: Read
+   Wiki: Read and Write
+   ```
+
+   ![Bitbucket OAuth settings page](img/bitbucket_oauth_settings_page.png)
+
+1. Select **Save**.
+1. Select your newly created OAuth consumer and you should now see a Key and
+   Secret in the list of OAuth consumers. Keep this page open as you continue
+   the configuration.
+
+   ![Bitbucket OAuth key](img/bitbucket_oauth_keys.png)
+
+1. On your GitLab server, open the configuration file:
+
+   ```
+   # For Omnibus packages
+   sudo editor /etc/gitlab/gitlab.rb
+
+   # For installations from source
+   sudo -u git -H editor /home/git/gitlab/config/gitlab.yml
+   ```
+
+1. Add the Bitbucket provider configuration:
+
+   For Omnibus packages:
+
+   ```ruby
+   gitlab_rails['omniauth_enabled'] = true
+
+   gitlab_rails['omniauth_providers'] = [
+     {
+       "name" => "bitbucket",
+       "app_id" => "BITBUCKET_APP_KEY",
+       "app_secret" => "BITBUCKET_APP_SECRET",
+       "url" => "https://bitbucket.org/"
+     }
+   ]
+   ```
+
+   For installations from source:
+
+   ```yaml
+   omniauth:
+     enabled: true
+     providers:
+       - { name: 'bitbucket',
+           app_id: 'BITBUCKET_APP_KEY',
+           app_secret: 'BITBUCKET_APP_SECRET',
+           url: 'https://bitbucket.org/' }
+   ```
+
+   ---
+
+   Where `BITBUCKET_APP_KEY` is the Key and `BITBUCKET_APP_SECRET` the Secret
+   from the Bitbucket application page.
+
+1. Save the configuration file.
+1. For the changes to take effect, [reconfigure GitLab][] if you installed via
+   Omnibus, or [restart][] if installed from source.
 
 On the sign in page there should now be a Bitbucket icon below the regular sign
 in form. Click the icon to begin the authentication process. Bitbucket will ask
diff --git a/doc/integration/cas.md b/doc/integration/cas.md
index c6178fa44f0..f99337376a8 100644
--- a/doc/integration/cas.md
+++ b/doc/integration/cas.md
@@ -2,63 +2,63 @@
 
 To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab will supply to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for backchannel logout.
 
-1.  On your GitLab server, open the configuration file.
+1. On your GitLab server, open the configuration file.
 
-    For omnibus package:
+   For omnibus package:
 
-    ```sh
-      sudo editor /etc/gitlab/gitlab.rb
-    ```
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```sh
-      cd /home/git/gitlab
+   ```sh
+   cd /home/git/gitlab
 
-      sudo -u git -H editor config/gitlab.yml
-    ```
+   sudo -u git -H editor config/gitlab.yml
+   ```
 
-1.  See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
 
-1.  Add the provider configuration:
+1. Add the provider configuration:
 
-    For omnibus package:
+   For omnibus package:
 
-    ```ruby
-      gitlab_rails['omniauth_providers'] = [
-        {
-            "name"=> "cas3",
-            "label"=> "cas",
-            "args"=> {
-                "url"=> 'CAS_SERVER',
-                "login_url"=> '/CAS_PATH/login',
-                "service_validate_url"=> '/CAS_PATH/p3/serviceValidate',
-                "logout_url"=> '/CAS_PATH/logout'
-            }
-        }
-      ]
-    ```
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+         "name"=> "cas3",
+         "label"=> "cas",
+         "args"=> {
+             "url"=> 'CAS_SERVER',
+             "login_url"=> '/CAS_PATH/login',
+             "service_validate_url"=> '/CAS_PATH/p3/serviceValidate',
+             "logout_url"=> '/CAS_PATH/logout'
+         }
+     }
+   ]
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```
-      - { name: 'cas3',
-          label: 'cas',
-          args: {
-                  url: 'CAS_SERVER',
-                  login_url: '/CAS_PATH/login',
-                  service_validate_url: '/CAS_PATH/p3/serviceValidate',
-                  logout_url: '/CAS_PATH/logout'} }
-    ```
+   ```
+   - { name: 'cas3',
+       label: 'cas',
+       args: {
+               url: 'CAS_SERVER',
+               login_url: '/CAS_PATH/login',
+               service_validate_url: '/CAS_PATH/p3/serviceValidate',
+               logout_url: '/CAS_PATH/logout'} }
+   ```
 
-1.  Change 'CAS_PATH' to the root of your CAS instance (ie. `cas`).
+1. Change 'CAS_PATH' to the root of your CAS instance (ie. `cas`).
 
-1.  If your CAS instance does not use default TGC lifetimes, update the `cas3.session_duration` to at least the current TGC maximum lifetime. To explicitly disable SLO, regardless of CAS settings, set this to 0.
+1. If your CAS instance does not use default TGC lifetimes, update the `cas3.session_duration` to at least the current TGC maximum lifetime. To explicitly disable SLO, regardless of CAS settings, set this to 0.
 
-1.  Save the configuration file.
+1. Save the configuration file.
 
-1.  [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
-    installed GitLab via Omnibus or from source respectively.
+1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
+   installed GitLab via Omnibus or from source respectively.
 
 On the sign in page there should now be a CAS tab in the sign in form.
 
diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md
index 6064c417900..eee05eaef02 100644
--- a/doc/integration/elasticsearch.md
+++ b/doc/integration/elasticsearch.md
@@ -1,4 +1,4 @@
-# Elasticsearch integration **[STARTER ONLY]**
+# Elasticsearch integration **(STARTER ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/109 "Elasticsearch Merge Request") in GitLab [Starter](https://about.gitlab.com/pricing/) 8.4. Support
 > for [Amazon Elasticsearch](http://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-gsg.html) was [introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1305) in GitLab
@@ -12,6 +12,7 @@ special searches:
 - [Advanced Syntax Search](../user/search/advanced_search_syntax.md)
 
 ## Version Requirements
+
 <!-- Please remember to update ee/lib/system_check/app/elasticsearch_check.rb if this changes -->
 
 | GitLab version | Elasticsearch version |
@@ -23,25 +24,32 @@ special searches:
 ## Installing Elasticsearch
 
 Elasticsearch is _not_ included in the Omnibus packages. You will have to
-install it yourself whether you are using the Omnibus package or installed
-GitLab from source. Providing detailed information on installing Elasticsearch
-is out of the scope of this document.
+[install it yourself](https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html "Elasticsearch installation documentation")
+whether you are using the Omnibus package or installed GitLab from source.
+Providing detailed information on installing Elasticsearch is out of the scope
+of this document.
+
+NOTE: **Note:**
+Elasticsearch should be installed on a separate server, whether you install
+it yourself or by using the
+[Amazon Elasticsearch](http://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-gsg.html)
+service. Running Elasticsearch on the same server as GitLab is not recommended
+and it will likely cause performance degradation on the GitLab installation.
 
 Once the data is added to the database or repository and [Elasticsearch is
 enabled in the admin area](#enabling-elasticsearch) the search index will be
-updated automatically. Elasticsearch can be installed on the same machine as
-GitLab or on a separate server, or you can use the [Amazon Elasticsearch](http://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-gsg.html)
-service.
-
-You can follow the steps as described in the [official web site](https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html "Elasticsearch installation documentation") or
-use the packages that are available for your OS.
+updated automatically.
 
 ## Elasticsearch repository indexer (beta)
 
 In order to improve elasticsearch indexing performance, GitLab has made available a [new indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer).
 This will replace the included Ruby indexer in the future but should be considered beta software for now, so there may be some bugs.
 
-If you would like to use it, please follow the instructions below.
+The Elasticsearch Go indexer is included in Omnibus for GitLab 11.8 and newer.
+
+To use the new Elasticsearch indexer included in Omnibus, check the box "Use the new repository indexer (beta)"  when [enabling the Elasticsearch integration](#enabling-elasticsearch).
+
+If you would like to use the Elasticsearch Go indexer with a source installation or an older version of GitLab, please follow the instructions below.
 
 ### Installation
 
@@ -130,7 +138,7 @@ The following Elasticsearch settings are available:
 | `Elasticsearch indexing`            | Enables/disables Elasticsearch indexing. You may want to enable indexing but disable search in order to give the index time to be fully completed, for example. Also, keep in mind that this option doesn't have any impact on existing data, this only enables/disables background indexer which tracks data changes. So by enabling this you will not get your existing data indexed, use special rake task for that as explained in [Adding GitLab's data to the Elasticsearch index](#adding-gitlabs-data-to-the-elasticsearch-index). |
 | `Use the new repository indexer (beta)` | Perform repository indexing using [GitLab Elasticsearch Indexer](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). |
 | `Search with Elasticsearch enabled` | Enables/disables using Elasticsearch in search. |
-| `URL`                              | The URL to use for connecting to Elasticsearch. Use a comma-separated list to support clustering (e.g., "http://host1, https://host2:9200"). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). |
+| `URL`                              | The URL to use for connecting to Elasticsearch. Use a comma-separated list to support clustering (e.g., `http://host1, https://host2:9200`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). |
 | `Number of Elasticsearch shards` | Elasticsearch indexes are split into multiple shards for performance reasons. In general, larger indexes need to have more shards. Changes to this value do not take effect until the index is recreated. You can read more about tradeoffs in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html#create-index-settings) |
 | `Number of Elasticsearch replicas` | Each Elasticsearch shard can have a number of replicas. These are a complete copy of the shard, and can provide increased query performance or resilience against hardware failure. Increasing this value will greatly increase total disk space required by the index. |
 | `Limit namespaces and projects that can be indexed` | Enabling this will allow you to select namespaces and projects to index. All other namespaces and projects will use database search instead. Please note that if you enable this option but do not select any namespaces or projects, none will be indexed. [Read more below](#limiting-namespaces-and-projects).
@@ -156,7 +164,7 @@ If no namespaces or projects are selected, no Elasticsearch indexing will take p
 CAUTION: **Warning**:
 If you have already indexed your instance, you will have to regenerate the index in order to delete all existing data
 for filtering to work correctly. To do this run the rake tasks `gitlab:elastic:create_empty_index` and
-`gitlab:elastic:clear_index_status` Afterwards, removing a namespace or a projeect from the list will delete the data
+`gitlab:elastic:clear_index_status`. Afterwards, removing a namespace or a project from the list will delete the data
 from the Elasticsearch index as expected.
 
 ## Disabling Elasticsearch
@@ -167,7 +175,7 @@ To disable the Elasticsearch integration:
 1. Find the 'Elasticsearch' section and uncheck 'Search with Elasticsearch enabled'
    and 'Elasticsearch indexing'
 1. Click **Save** for the changes to take effect
-1. [Optional] Delete the existing index by running the command `sudo gitlab-rake gitlab:elastic:delete_index`
+1. (Optional) Delete the existing index by running the command `sudo gitlab-rake gitlab:elastic:delete_index`
 
 ## Adding GitLab's data to the Elasticsearch index
 
@@ -275,19 +283,18 @@ You can also use the `gitlab:elastic:clear_index_status` Rake task to force the
 indexer to "forget" all progress, so retrying the indexing process from the
 start.
 
-To index all wikis:
+The `index_projects` command enqueues jobs to index all project and wiki
+repositories, and most database content. However, snippets still need to be
+indexed separately. To do so, run one of these commands:
 
 ```sh
 # Omnibus installations
-sudo gitlab-rake gitlab:elastic:index_wikis
+sudo gitlab-rake gitlab:elastic:index_snippets
 
 # Installations from source
-bundle exec rake gitlab:elastic:index_wikis RAILS_ENV=production
+bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production
 ```
 
-The wiki indexer also supports the `ID_FROM` and `ID_TO` parameters if you want
-to limit a project set.
-
 Enable replication and refreshing again after indexing (only if you previously disabled it):
 
 ```bash
@@ -305,7 +312,7 @@ For Elasticsearch 6.x, before proceeding with the force merge, the index should
 ```bash
 curl --request PUT localhost:9200/gitlab-production/_settings --data '{
   "settings": {
-    "index.blocks.write": true 
+    "index.blocks.write": true
   } }'
 ```
 
@@ -320,12 +327,16 @@ After this, if your index is in read-only, switch back to read-write:
 ```bash
 curl --request PUT localhost:9200/gitlab-production/_settings --data '{
   "settings": {
-    "index.blocks.write": false 
+    "index.blocks.write": false
   } }'
 ```
 
 Enable Elasticsearch search in **Admin > Settings > Integrations**. That's it. Enjoy it!
 
+### Index limit
+
+Currently for repository and snippet files, GitLab would only index up to 1 MB of content, in order to avoid indexing timeout.
+
 ## GitLab Elasticsearch Rake Tasks
 
 There are several rake tasks available to you via the command line:
@@ -335,14 +346,11 @@ There are several rake tasks available to you via the command line:
     - `sudo gitlab-rake gitlab:elastic:create_empty_index`
     - `sudo gitlab-rake gitlab:elastic:clear_index_status`
     - `sudo gitlab-rake gitlab:elastic:index_projects`
-    - `sudo gitlab-rake gitlab:elastic:index_wikis`
     - `sudo gitlab-rake gitlab:elastic:index_snippets`
 - [sudo gitlab-rake gitlab:elastic:index_projects](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake)
   - This iterates over all projects and queues sidekiq jobs to index them in the background.
 - [sudo gitlab-rake gitlab:elastic:index_projects_status](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake)
   - This determines the overall status of the indexing. It is done by counting the total number of indexed projects, dividing by a count of the total number of projects, then multiplying by 100.
-- [sudo gitlab-rake gitlab:elastic:index_wikis](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake)
-  - Iterates over every project, determines if said project contains wiki data, and then indexes the blobs (content) of said wiki data.
 - [sudo gitlab-rake gitlab:elastic:create_empty_index](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake)
   - This generates an empty index on the Elasticsearch side.
 - [sudo gitlab-rake gitlab:elastic:clear_index_status](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake)
@@ -353,6 +361,8 @@ There are several rake tasks available to you via the command line:
   - Does the same thing as `sudo gitlab-rake gitlab:elastic:create_empty_index`
 - [sudo gitlab-rake gitlab:elastic:index_snippets](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake)
   - Performs an Elasticsearch import that indexes the snippets data.
+- [sudo gitlab-rake gitlab:elastic:projects_not_indexed](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake)
+  - Displays which projects are not indexed.
 
 ### Environment Variables
 
@@ -396,9 +406,9 @@ When performing a search, the GitLab index will use the following scopes:
 
 Whenever a change or deletion is made to an indexed GitLab object (a merge request description is changed, a file is deleted from the master branch in a repository, a project is deleted, etc), a document in the index is deleted.  However, since these are "soft" deletes, the overall number of "deleted documents", and therefore wasted space, increases.  Elasticsearch does intelligent merging of segments in order to remove these deleted documents.  However, depending on the amount and type of activity in your GitLab installation, it's possible to see as much as 50% wasted space in the index.
 
-In general, we recommend simply letting Elasticseach merge and reclaim space automatically, with the default settings.  From [Lucene's Handling of Deleted Documents](https://www.elastic.co/blog/lucenes-handling-of-deleted-documents "Lucene's Handling of Deleted Documents"), _"Overall, besides perhaps decreasing the maximum segment size, it is best to leave Lucene's defaults as-is and not fret too much about when deletes are reclaimed."_
+In general, we recommend simply letting Elasticsearch merge and reclaim space automatically, with the default settings. From [Lucene's Handling of Deleted Documents](https://www.elastic.co/blog/lucenes-handling-of-deleted-documents "Lucene's Handling of Deleted Documents"), _"Overall, besides perhaps decreasing the maximum segment size, it is best to leave Lucene's defaults as-is and not fret too much about when deletes are reclaimed."_
 
-However, some larger installations may wish to tune the merge policy settings: 
+However, some larger installations may wish to tune the merge policy settings:
 
 - Consider reducing the `index.merge.policy.max_merged_segment` size from the default 5 GB to maybe 2 GB or 3 GB.  Merging only happens when a segment has at least 50% deletions.  Smaller segment sizes will allow merging to happen more frequently.
 
@@ -428,91 +438,94 @@ Here are some common pitfalls and how to overcome them:
 
 - **How can I verify my GitLab instance is using Elasticsearch?**
 
-    The easiest method is via the rails console (`sudo gitlab-rails console`) by running the following:
-    
-    ```ruby
-    u = User.find_by_username('your-username')
-    s = SearchService.new(u, {:search => 'search_term'})
-    pp s.search_objects.class.name
-    ```
-    
-    If you see `Elasticsearch::Model::Response::Records`, you are using Elasticsearch. 
+  The easiest method is via the rails console (`sudo gitlab-rails console`) by running the following:
+
+  ```ruby
+  u = User.find_by_username('your-username')
+  s = SearchService.new(u, {:search => 'search_term'})
+  pp s.search_objects.class.name
+  ```
+
+  If you see `Elasticsearch::Model::Response::Records`, you are using Elasticsearch.
 
 - **I updated GitLab and now I can't find anything**
 
-    We continuously make updates to our indexing strategies and aim to support
-    newer versions of Elasticsearch. When indexing changes are made, it may
-    be necessary for you to [reindex](#adding-gitlabs-data-to-the-elasticsearch-index) after updating GitLab.
+  We continuously make updates to our indexing strategies and aim to support
+  newer versions of Elasticsearch. When indexing changes are made, it may
+  be necessary for you to [reindex](#adding-gitlabs-data-to-the-elasticsearch-index) after updating GitLab.
 
 - **I indexed all the repositories but I can't find anything**
 
-    Make sure you indexed all the database data [as stated above](#adding-gitlabs-data-to-the-elasticsearch-index).
-    
-    Beyond that, check via the [Elasticsearch Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html) to see if the data shows up on the Elasticsearch side.
-    
-    If it shows up via the [Elasticsearch Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html), check that it shows up via the rails console (`sudo gitlab-rails console`):
-    
-    ```ruby
-    u = User.find_by_username('your-username')
-    s = SearchService.new(u, {:search => 'search_term', :scope => ‘blobs’})
-    pp s.search_objects.to_a
-    ```
-    
-    See [Elasticsearch Index Scopes](elasticsearch.md#elasticsearch-index-scopes) for more information on searching for specific types of data.
-
-- **I indexed all the repositories but then switched elastic search servers and now I can't find anything**
-
-    You will need to re-run all the rake tasks to re-index the database, repositories, and wikis.
-    
+  Make sure you indexed all the database data [as stated above](#adding-gitlabs-data-to-the-elasticsearch-index).
+
+  Beyond that, check via the [Elasticsearch Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html) to see if the data shows up on the Elasticsearch side.
+
+  If it shows up via the [Elasticsearch Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html), check that it shows up via the rails console (`sudo gitlab-rails console`):
+
+  ```ruby
+  u = User.find_by_username('your-username')
+  s = SearchService.new(u, {:search => 'search_term', :scope => ‘blobs’})
+  pp s.search_objects.to_a
+  ```
+
+  See [Elasticsearch Index Scopes](elasticsearch.md#elasticsearch-index-scopes) for more information on searching for specific types of data.
+
+- **I indexed all the repositories but then switched Elasticsearch servers and now I can't find anything**
+
+  You will need to re-run all the rake tasks to re-index the database, repositories, and wikis.
+
 - **The indexing process is taking a very long time**
 
-    The more data present in your GitLab instance, the longer the indexing process takes.
+  The more data present in your GitLab instance, the longer the indexing process takes.
+
+- **There are some projects that weren't indexed, but we don't know which ones**
+
+  You can run `sudo gitlab-rake gitlab:elastic:projects_not_indexed` to display projects that aren't indexed.
 
 - **No new data is added to the Elasticsearch index when I push code**
 
-    When performing the initial indexing of blobs, we lock all projects until the project finishes indexing. It could
-    happen that an error during the process causes one or multiple projects to remain locked. In order to unlock them,
-    run the `gitlab:elastic:clear_locked_projects` rake task.
+  When performing the initial indexing of blobs, we lock all projects until the project finishes indexing. It could
+  happen that an error during the process causes one or multiple projects to remain locked. In order to unlock them,
+  run the `gitlab:elastic:clear_locked_projects` rake task.
 
 - **"Can't specify parent if no parent field has been configured"**
 
-    If you enabled Elasticsearch before GitLab 8.12 and have not rebuilt indexes you will get
-    exception in lots of different cases:
-
-    ```text
-    Elasticsearch::Transport::Transport::Errors::BadRequest([400] {
-        "error": {
-            "root_cause": [{
-                "type": "illegal_argument_exception",
-                "reason": "Can't specify parent if no parent field has been configured"
-            }],
-            "type": "illegal_argument_exception",
-            "reason": "Can't specify parent if no parent field has been configured"
-        },
-        "status": 400
-    }):
-    ```
-
-    This is because we changed the index mapping in GitLab 8.12 and the old indexes should be removed and built from scratch again,
-    see details in the [8-11-to-8-12 update guide](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/update/8.11-to-8.12.md#11-elasticsearch-index-update-if-you-currently-use-elasticsearch).
+  If you enabled Elasticsearch before GitLab 8.12 and have not rebuilt indexes you will get
+  exception in lots of different cases:
+
+  ```text
+  Elasticsearch::Transport::Transport::Errors::BadRequest([400] {
+      "error": {
+          "root_cause": [{
+              "type": "illegal_argument_exception",
+              "reason": "Can't specify parent if no parent field has been configured"
+          }],
+          "type": "illegal_argument_exception",
+          "reason": "Can't specify parent if no parent field has been configured"
+      },
+      "status": 400
+  }):
+  ```
+
+  This is because we changed the index mapping in GitLab 8.12 and the old indexes should be removed and built from scratch again,
+  see details in the [8-11-to-8-12 update guide](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/update/8.11-to-8.12.md#11-elasticsearch-index-update-if-you-currently-use-elasticsearch).
 
 - Exception `Elasticsearch::Transport::Transport::Errors::BadRequest`
 
-    If you have this exception (just like in the case above but the actual message is different) please check if you have the correct Elasticsearch version and you met the other [requirements](#system-requirements).
-    There is also an easy way to check it automatically with `sudo gitlab-rake gitlab:check` command.
+  If you have this exception (just like in the case above but the actual message is different) please check if you have the correct Elasticsearch version and you met the other [requirements](#system-requirements).
+  There is also an easy way to check it automatically with `sudo gitlab-rake gitlab:check` command.
 
 - Exception `Elasticsearch::Transport::Transport::Errors::RequestEntityTooLarge`
 
-    ```text
-    [413] {"Message":"Request size exceeded 10485760 bytes"}
-    ```
-
-    This exception is seen when your Elasticsearch cluster is configured to reject
-    requests above a certain size (10MiB in this case). This corresponds to the
-    `http.max_content_length` setting in `elasticsearch.yml`. Increase it to a
-    larger size and restart your Elasticsearch cluster.
+  ```text
+  [413] {"Message":"Request size exceeded 10485760 bytes"}
+  ```
 
-    AWS has [fixed limits](http://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/aes-limits.html)
-    for this setting ("Maximum Size of HTTP Request Payloads"), based on the size of
-    the underlying instance.
+  This exception is seen when your Elasticsearch cluster is configured to reject
+  requests above a certain size (10MiB in this case). This corresponds to the
+  `http.max_content_length` setting in `elasticsearch.yml`. Increase it to a
+  larger size and restart your Elasticsearch cluster.
 
+  AWS has [fixed limits](http://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/aes-limits.html)
+  for this setting ("Maximum Size of HTTP Request Payloads"), based on the size of
+  the underlying instance.
diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md
index fe789a80eed..49b3d194a01 100644
--- a/doc/integration/facebook.md
+++ b/doc/integration/facebook.md
@@ -2,7 +2,7 @@
 
 To enable the Facebook OmniAuth provider you must register your application with Facebook. Facebook will generate an app ID and secret key for you to use.
 
-1.  Sign in to the [Facebook Developer Platform](https://developers.facebook.com/).
+1. Sign in to the [Facebook Developer Platform](https://developers.facebook.com/).
 
 1. Choose "My Apps" &gt; "Add a New App"
 
@@ -19,7 +19,7 @@ To enable the Facebook OmniAuth provider you must register your application with
 
 1. Enter the address of your GitLab installation at the bottom of the package
 
-    ![Facebook Website URL](img/facebook_website_url.png)
+   ![Facebook Website URL](img/facebook_website_url.png)
 
 1. Choose "Next"
 
@@ -29,7 +29,7 @@ To enable the Facebook OmniAuth provider you must register your application with
 
 1. Fill in a contact email for your app
 
-    ![Facebook App Settings](img/facebook_app_settings.png)
+   ![Facebook App Settings](img/facebook_app_settings.png)
 
 1. Choose "Save Changes"
 
@@ -45,55 +45,55 @@ To enable the Facebook OmniAuth provider you must register your application with
 
 1. You should now see an app key and app secret (see screenshot). Keep this page open as you continue configuration.
 
-    ![Facebook API Keys](img/facebook_api_keys.png)
+   ![Facebook API Keys](img/facebook_api_keys.png)
 
-1.  On your GitLab server, open the configuration file.
+1. On your GitLab server, open the configuration file.
 
-    For omnibus package:
+   For omnibus package:
 
-    ```sh
-    sudo editor /etc/gitlab/gitlab.rb
-    ```
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```sh
-    cd /home/git/gitlab
+   ```sh
+   cd /home/git/gitlab
 
-    sudo -u git -H editor config/gitlab.yml
-    ```
+   sudo -u git -H editor config/gitlab.yml
+   ```
 
-1.  See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
 
-1.  Add the provider configuration:
+1. Add the provider configuration:
 
-    For omnibus package:
+   For omnibus package:
 
-    ```ruby
-    gitlab_rails['omniauth_providers'] = [
-      {
-        "name" => "facebook",
-        "app_id" => "YOUR_APP_ID",
-        "app_secret" => "YOUR_APP_SECRET"
-      }
-    ]
-    ```
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       "name" => "facebook",
+       "app_id" => "YOUR_APP_ID",
+       "app_secret" => "YOUR_APP_SECRET"
+     }
+   ]
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```
-    - { name: 'facebook', app_id: 'YOUR_APP_ID',
-      app_secret: 'YOUR_APP_SECRET' }
-    ```
+   ```
+   - { name: 'facebook', app_id: 'YOUR_APP_ID',
+     app_secret: 'YOUR_APP_SECRET' }
+   ```
 
-1.  Change 'YOUR_APP_ID' to the API key from Facebook page in step 10.
+1. Change 'YOUR_APP_ID' to the API key from Facebook page in step 10.
 
-1.  Change 'YOUR_APP_SECRET' to the API secret from the Facebook page in step 10.
+1. Change 'YOUR_APP_SECRET' to the API secret from the Facebook page in step 10.
 
-1.  Save the configuration file.
+1. Save the configuration file.
 
-1.  [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
-    installed GitLab via Omnibus or from source respectively.
+1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
+   installed GitLab via Omnibus or from source respectively.
 
 On the sign in page there should now be a Facebook icon below the regular sign in form. Click the icon to begin the authentication process. Facebook will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in.
 
diff --git a/doc/integration/github.md b/doc/integration/github.md
index 5b01dd9feb7..c8dbae65465 100644
--- a/doc/integration/github.md
+++ b/doc/integration/github.md
@@ -7,111 +7,111 @@ You can integrate your GitLab instance with GitHub.com as well as GitHub Enterpr
 To enable GitHub OmniAuth provider, you must use GitHub's credentials for your GitLab instance.
 To get the credentials (a pair of Client ID and Client Secret), you must register an application as an OAuth App on GitHub.
 
-1.  Sign in to GitHub.
+1. Sign in to GitHub.
 
-1.  Navigate to your individual user or organization settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or an organization - that is entirely up to you.
+1. Navigate to your individual user or organization settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or an organization - that is entirely up to you.
 
-    - For individual accounts, select **Developer settings** from the left menu, then select **OAuth Apps**.
-    - For organization accounts, directly select **OAuth Apps** from the left menu.
+   - For individual accounts, select **Developer settings** from the left menu, then select **OAuth Apps**.
+   - For organization accounts, directly select **OAuth Apps** from the left menu.
 
-1.  Select **Register an application** (if you don't have any OAuth App) or **New OAuth App** (if you already have OAuth Apps).
-    ![Register OAuth App](img/github_app_entry.png)
+1. Select **Register an application** (if you don't have any OAuth App) or **New OAuth App** (if you already have OAuth Apps).
+   ![Register OAuth App](img/github_app_entry.png)
 
-1.  Provide the required details.
-    - Application name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive.
-    - Homepage URL: The URL of your GitLab installation. For example, `https://gitlab.example.com`.
-    - Application description: Fill this in if you wish.
-    - Authorization callback URL: `http(s)://${YOUR_DOMAIN}/users/auth`. Please make sure the port is included if your GitLab instance is not configured on default port.
-    ![Register OAuth App](img/github_register_app.png)
+1. Provide the required details.
+   - Application name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive.
+   - Homepage URL: The URL of your GitLab installation. For example, `https://gitlab.example.com`.
+   - Application description: Fill this in if you wish.
+   - Authorization callback URL: `http(s)://${YOUR_DOMAIN}/users/auth`. Please make sure the port is included if your GitLab instance is not configured on default port.
+   ![Register OAuth App](img/github_register_app.png)
 
-    NOTE: Be sure to append `/users/auth` to the end of the callback URL
-    to prevent a [OAuth2 convert
-    redirect](http://tetraph.com/covert_redirect/) vulnerability.
+   NOTE: Be sure to append `/users/auth` to the end of the callback URL
+   to prevent a [OAuth2 convert
+   redirect](http://tetraph.com/covert_redirect/) vulnerability.
 
-1.  Select **Register application**.
+1. Select **Register application**.
 
-1.  You should now see a pair of **Client ID** and **Client Secret** near the top right of the page (see screenshot).
-    Keep this page open as you continue configuration.
-    ![GitHub app](img/github_app.png)
+1. You should now see a pair of **Client ID** and **Client Secret** near the top right of the page (see screenshot).
+   Keep this page open as you continue configuration.
+   ![GitHub app](img/github_app.png)
 
-1.  On your GitLab server, open the configuration file.
+1. On your GitLab server, open the configuration file.
 
-    For omnibus package:
+   For omnibus package:
 
-    ```sh
-      sudo editor /etc/gitlab/gitlab.rb
-    ```
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```sh
-      cd /home/git/gitlab
+   ```sh
+   cd /home/git/gitlab
 
-      sudo -u git -H editor config/gitlab.yml
-    ```
+   sudo -u git -H editor config/gitlab.yml
+   ```
 
-1.  See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
 
-1.  Add the provider configuration:
+1. Add the provider configuration:
 
-    For omnibus package:
+   For omnibus package:
 
-    For GitHub.com:
+   For GitHub.com:
 
-    ```ruby
-      gitlab_rails['omniauth_providers'] = [
-        {
-          "name" => "github",
-          "app_id" => "YOUR_APP_ID",
-          "app_secret" => "YOUR_APP_SECRET",
-          "args" => { "scope" => "user:email" }
-        }
-      ]
-    ```
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       "name" => "github",
+       "app_id" => "YOUR_APP_ID",
+       "app_secret" => "YOUR_APP_SECRET",
+       "args" => { "scope" => "user:email" }
+     }
+   ]
+   ```
 
-    For GitHub Enterprise:
+   For GitHub Enterprise:
 
-    ```ruby
-      gitlab_rails['omniauth_providers'] = [
-        {
-          "name" => "github",
-          "app_id" => "YOUR_APP_ID",
-          "app_secret" => "YOUR_APP_SECRET",
-          "url" => "https://github.example.com/",
-          "args" => { "scope" => "user:email" }
-        }
-      ]
-    ```
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       "name" => "github",
+       "app_id" => "YOUR_APP_ID",
+       "app_secret" => "YOUR_APP_SECRET",
+       "url" => "https://github.example.com/",
+       "args" => { "scope" => "user:email" }
+     }
+   ]
+   ```
 
-    For installation from source:
+   For installation from source:
 
-    For GitHub.com:
+   For GitHub.com:
 
-    ```
-      - { name: 'github', app_id: 'YOUR_APP_ID',
-        app_secret: 'YOUR_APP_SECRET',
-        args: { scope: 'user:email' } }
-    ```
+   ```
+   - { name: 'github', app_id: 'YOUR_APP_ID',
+     app_secret: 'YOUR_APP_SECRET',
+     args: { scope: 'user:email' } }
+   ```
 
-    For GitHub Enterprise:
+   For GitHub Enterprise:
 
-    ```
-      - { name: 'github', app_id: 'YOUR_APP_ID',
-        app_secret: 'YOUR_APP_SECRET',
-        url: "https://github.example.com/",
-        args: { scope: 'user:email' } }
-    ```
+   ```
+   - { name: 'github', app_id: 'YOUR_APP_ID',
+     app_secret: 'YOUR_APP_SECRET',
+     url: "https://github.example.com/",
+     args: { scope: 'user:email' } }
+   ```
 
-    __Replace `https://github.example.com/` with your GitHub URL.__
+   __Replace `https://github.example.com/` with your GitHub URL.__
 
-1.  Change `YOUR_APP_ID` to the Client ID from the GitHub application page from step 6.
+1. Change `YOUR_APP_ID` to the Client ID from the GitHub application page from step 6.
 
-1.  Change `YOUR_APP_SECRET` to the Client Secret from the GitHub application page from step 6.
+1. Change `YOUR_APP_SECRET` to the Client Secret from the GitHub application page from step 6.
 
-1.  Save the configuration file.
+1. Save the configuration file.
 
-1.  [Reconfigure GitLab][] or [restart GitLab][] for the changes to take effect if you
-    installed GitLab via Omnibus or from source respectively.
+1. [Reconfigure GitLab][] or [restart GitLab][] for the changes to take effect if you
+   installed GitLab via Omnibus or from source respectively.
 
 On the sign in page there should now be a GitHub icon below the regular sign in form.
 Click the icon to begin the authentication process. GitHub will ask the user to sign in and authorize the GitLab application.
@@ -127,16 +127,16 @@ and changing the global Git `sslVerify` option to `false` in the GitLab server.
 For omnibus package:
 
 ```ruby
-  gitlab_rails['omniauth_providers'] = [
-    {
-      "name" => "github",
-      "app_id" => "YOUR_APP_ID",
-      "app_secret" => "YOUR_APP_SECRET",
-      "url" => "https://github.example.com/",
-      "verify_ssl" => false,
-      "args" => { "scope" => "user:email" }
-    }
-  ]
+gitlab_rails['omniauth_providers'] = [
+  {
+    "name" => "github",
+    "app_id" => "YOUR_APP_ID",
+    "app_secret" => "YOUR_APP_SECRET",
+    "url" => "https://github.example.com/",
+    "verify_ssl" => false,
+    "args" => { "scope" => "user:email" }
+  }
+]
 ```
 
 You will also need to disable Git SSL verification on the server hosting GitLab.
@@ -148,11 +148,11 @@ omnibus_gitconfig['system'] = { "http" => ["sslVerify = false"] }
 For installation from source:
 
 ```
-  - { name: 'github', app_id: 'YOUR_APP_ID',
-    app_secret: 'YOUR_APP_SECRET',
-    url: "https://github.example.com/",
-    verify_ssl: false,
-    args: { scope: 'user:email' } }
+- { name: 'github', app_id: 'YOUR_APP_ID',
+  app_secret: 'YOUR_APP_SECRET',
+  url: "https://github.example.com/",
+  verify_ssl: false,
+  args: { scope: 'user:email' } }
 ```
 
 You will also need to disable Git SSL verification on the server hosting GitLab.
diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md
index 70087576678..46da3d88d90 100644
--- a/doc/integration/gitlab.md
+++ b/doc/integration/gitlab.md
@@ -5,78 +5,78 @@ Import projects from GitLab.com and login to your GitLab instance with your GitL
 To enable the GitLab.com OmniAuth provider you must register your application with GitLab.com.
 GitLab.com will generate an application ID and secret key for you to use.
 
-1.  Sign in to GitLab.com
+1. Sign in to GitLab.com
 
 1. On the upper right corner, click on your avatar and go to your **Settings**.
 
-1.  Select **Applications** in the left menu.
+1. Select **Applications** in the left menu.
 
-1.  Provide the required details for **Add new application**.
-    - Name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive.
-    - Redirect URI:
+1. Provide the required details for **Add new application**.
+   - Name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive.
+   - Redirect URI:
 
-    ```
-    http://your-gitlab.example.com/import/gitlab/callback
-    http://your-gitlab.example.com/users/auth/gitlab/callback
-    ```
+   ```
+   http://your-gitlab.example.com/import/gitlab/callback
+   http://your-gitlab.example.com/users/auth/gitlab/callback
+   ```
 
-    The first link is required for the importer and second for the authorization.
+   The first link is required for the importer and second for the authorization.
 
-1.  Select **Save application**.
+1. Select **Save application**.
 
-1.  You should now see a **Application Id** and **Secret** near the top right of the page (see screenshot).
-    Keep this page open as you continue configuration.
-    ![GitLab app](img/gitlab_app.png)
+1. You should now see a **Application Id** and **Secret** near the top right of the page (see screenshot).
+   Keep this page open as you continue configuration.
+   ![GitLab app](img/gitlab_app.png)
 
-1.  On your GitLab server, open the configuration file.
+1. On your GitLab server, open the configuration file.
 
-    For omnibus package:
+   For omnibus package:
 
-    ```sh
-      sudo editor /etc/gitlab/gitlab.rb
-    ```
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```sh
-      cd /home/git/gitlab
+   ```sh
+   cd /home/git/gitlab
 
-      sudo -u git -H editor config/gitlab.yml
-    ```
+   sudo -u git -H editor config/gitlab.yml
+   ```
 
-1.  See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
 
-1.  Add the provider configuration:
+1. Add the provider configuration:
 
-    For omnibus package:
+   For omnibus package:
 
-    ```ruby
-      gitlab_rails['omniauth_providers'] = [
-        {
-          "name" => "gitlab",
-          "app_id" => "YOUR_APP_ID",
-          "app_secret" => "YOUR_APP_SECRET",
-          "args" => { "scope" => "api" }
-        }
-      ]
-    ```
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       "name" => "gitlab",
+       "app_id" => "YOUR_APP_ID",
+       "app_secret" => "YOUR_APP_SECRET",
+       "args" => { "scope" => "api" }
+     }
+   ]
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```
-      - { name: 'gitlab', app_id: 'YOUR_APP_ID',
-        app_secret: 'YOUR_APP_SECRET',
-        args: { scope: 'api' } }
-    ```
+   ```
+   - { name: 'gitlab', app_id: 'YOUR_APP_ID',
+     app_secret: 'YOUR_APP_SECRET',
+     args: { scope: 'api' } }
+   ```
 
-1.  Change 'YOUR_APP_ID' to the Application ID from the GitLab.com application page.
+1. Change 'YOUR_APP_ID' to the Application ID from the GitLab.com application page.
 
-1.  Change 'YOUR_APP_SECRET' to the secret from the GitLab.com application page.
+1. Change 'YOUR_APP_SECRET' to the secret from the GitLab.com application page.
 
-1.  Save the configuration file.
+1. Save the configuration file.
 
-1.  [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
-    installed GitLab via Omnibus or from source respectively.
+1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
+   installed GitLab via Omnibus or from source respectively.
 
 On the sign in page there should now be a GitLab.com icon below the regular sign in form.
 Click the icon to begin the authentication process. GitLab.com will ask the user to sign in and authorize the GitLab application.
diff --git a/doc/integration/google.md b/doc/integration/google.md
index d2b4e119978..4f6999571b6 100644
--- a/doc/integration/google.md
+++ b/doc/integration/google.md
@@ -10,10 +10,10 @@ In Google's side:
 1. Navigate to the [cloud resource manager](https://console.cloud.google.com/cloud-resource-manager) page
 1. Select **Create Project**
 1. Provide the project information:
-    - **Project name** - "GitLab" works just fine here.
-    - **Project ID** - Must be unique to all Google Developer registered applications.
-      Google provides a randomly generated Project ID by default. You can use
-      the randomly generated ID or choose a new one.
+   - **Project name** - "GitLab" works just fine here.
+   - **Project ID** - Must be unique to all Google Developer registered applications.
+     Google provides a randomly generated Project ID by default. You can use
+     the randomly generated ID or choose a new one.
 1. Refresh the page and you should see your new project in the list
 1. Go to the [Google API Console](https://console.developers.google.com/apis/dashboard)
 1. Select the previously created project form the upper left corner
@@ -21,17 +21,17 @@ In Google's side:
 1. Select **OAuth consent screen** and fill the form with the required information
 1. In the **Credentials** tab, select **Create credentials > OAuth client ID**
 1. Fill in the required information
-    - **Application type** - Choose "Web Application"
-    - **Name** - Use the default one or provide your own
-    - **Authorized JavaScript origins** -This isn't really used by GitLab but go
-      ahead and put `https://gitlab.example.com`
-    - **Authorized redirect URIs** - Enter your domain name followed by the
-      callback URIs one at a time:
-
-        ```
-        https://gitlab.example.com/users/auth/google_oauth2/callback
-        https://gitlab.example.com/-/google_api/auth/callback
-        ```
+   - **Application type** - Choose "Web Application"
+   - **Name** - Use the default one or provide your own
+   - **Authorized JavaScript origins** -This isn't really used by GitLab but go
+     ahead and put `https://gitlab.example.com`
+   - **Authorized redirect URIs** - Enter your domain name followed by the
+     callback URIs one at a time:
+
+     ```
+     https://gitlab.example.com/users/auth/google_oauth2/callback
+     https://gitlab.example.com/-/google_api/auth/callback
+     ```
 
 1. You should now be able to see a Client ID and Client secret. Note them down
    or keep this page open as you will need them later.
@@ -45,64 +45,64 @@ On your GitLab server:
 
 1. Open the configuration file.
 
-    For Omnibus GitLab:
+   For Omnibus GitLab:
 
-    ```sh
-    sudo editor /etc/gitlab/gitlab.rb
-    ```
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```sh
-    cd /home/git/gitlab
-    sudo -u git -H editor config/gitlab.yml
-    ```
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H editor config/gitlab.yml
+   ```
 
 1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
 1. Add the provider configuration:
 
-    For Omnibus GitLab:
+   For Omnibus GitLab:
 
-    ```ruby
-    gitlab_rails['omniauth_providers'] = [
-      {
-        "name" => "google_oauth2",
-        "app_id" => "YOUR_APP_ID",
-        "app_secret" => "YOUR_APP_SECRET",
-        "args" => { "access_type" => "offline", "approval_prompt" => '' }
-      }
-    ]
-    ```
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       "name" => "google_oauth2",
+       "app_id" => "YOUR_APP_ID",
+       "app_secret" => "YOUR_APP_SECRET",
+       "args" => { "access_type" => "offline", "approval_prompt" => '' }
+     }
+   ]
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```yaml
-    - { name: 'google_oauth2', app_id: 'YOUR_APP_ID',
-      app_secret: 'YOUR_APP_SECRET',
-      args: { access_type: 'offline', approval_prompt: '' } }
-    ```
+   ```yaml
+   - { name: 'google_oauth2', app_id: 'YOUR_APP_ID',
+     app_secret: 'YOUR_APP_SECRET',
+     args: { access_type: 'offline', approval_prompt: '' } }
+   ```
 
 1. Change `YOUR_APP_ID` to the client ID from the Google Developer page
 1. Similarly, change `YOUR_APP_SECRET` to the client secret
 1. Make sure that you configure GitLab to use an FQDN as Google will not accept
    raw IP addresses.
 
-    For Omnibus packages:
+   For Omnibus packages:
 
-    ```ruby
-    external_url 'https://gitlab.example.com'
-    ```
+   ```ruby
+   external_url 'https://gitlab.example.com'
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```yaml
-    gitlab:
-      host: https://gitlab.example.com
-    ```
+   ```yaml
+   gitlab:
+     host: https://gitlab.example.com
+   ```
 
-1.  Save the configuration file.
-1.  [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
-    installed GitLab via Omnibus or from source respectively.
+1. Save the configuration file.
+1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
+   installed GitLab via Omnibus or from source respectively.
 
 On the sign in page there should now be a Google icon below the regular sign in
 form. Click the icon to begin the authentication process. Google will ask the
diff --git a/doc/integration/img/limit_namespace_filter.png b/doc/integration/img/limit_namespace_filter.png
index 88f5caa41db..437aecad467 100644
--- a/doc/integration/img/limit_namespace_filter.png
+++ b/doc/integration/img/limit_namespace_filter.png
diff --git a/doc/integration/img/limit_namespaces_projects_options.png b/doc/integration/img/limit_namespaces_projects_options.png
index 488341f7e92..fa666c7491e 100644
--- a/doc/integration/img/limit_namespaces_projects_options.png
+++ b/doc/integration/img/limit_namespaces_projects_options.png
diff --git a/doc/integration/img/salesforce_app_details.png b/doc/integration/img/salesforce_app_details.png
index 00e66f07282..c7a4084102e 100644
--- a/doc/integration/img/salesforce_app_details.png
+++ b/doc/integration/img/salesforce_app_details.png
diff --git a/doc/integration/img/salesforce_app_secret_details.png b/doc/integration/img/salesforce_app_secret_details.png
index fad2a4a1f97..8734a7a5cbb 100644
--- a/doc/integration/img/salesforce_app_secret_details.png
+++ b/doc/integration/img/salesforce_app_secret_details.png
diff --git a/doc/integration/img/salesforce_oauth_app_details.png b/doc/integration/img/salesforce_oauth_app_details.png
index a5fb680cca6..e29c55df656 100644
--- a/doc/integration/img/salesforce_oauth_app_details.png
+++ b/doc/integration/img/salesforce_oauth_app_details.png
diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md
index 5950737b964..6755640d39c 100644
--- a/doc/integration/jenkins.md
+++ b/doc/integration/jenkins.md
@@ -1,4 +1,4 @@
-# Jenkins CI service **[STARTER]**
+# Jenkins CI service **(STARTER)**
 
 >**Note:**
 In GitLab 8.3, Jenkins integration using the
@@ -25,22 +25,25 @@ and [Migrating from Jenkins to GitLab](https://www.youtube.com/watch?v=RlEVGOpYF
 ## Use cases
 
 - Suppose you are new to GitLab, and want to keep using Jenkins until you prepare
-your projects to build with [GitLab CI/CD](../ci/README.md). You set up the
-integration between GitLab and Jenkins, then you migrate to GitLab CI later. While
-you organize yourself and your team to onboard GitLab, you keep your pipelines
-running with Jenkins, but view the results in your project's repository in GitLab.
+  your projects to build with [GitLab CI/CD](../ci/README.md). You set up the
+  integration between GitLab and Jenkins, then you migrate to GitLab CI later. While
+  you organize yourself and your team to onboard GitLab, you keep your pipelines
+  running with Jenkins, but view the results in your project's repository in GitLab.
 - Your team uses [Jenkins Plugins](https://plugins.jenkins.io/) for other proceedings,
-therefore, you opt for keep using Jenkins to build your apps. Show the results of your
-pipelines directly in GitLab.
+  therefore, you opt for keep using Jenkins to build your apps. Show the results of your
+  pipelines directly in GitLab.
 
 For a real use case, read the blog post [Continuous integration: From Jenkins to GitLab using Docker](https://about.gitlab.com/2017/07/27/docker-my-precious/).
 
+NOTE: **Moving from a traditional CI plug-in to a single application for the entire software development lifecycle can decrease hours spent on maintaining toolchains by 10% or more.** 
+Visit the ['GitLab vs. Jenkins' comparison page](https://about.gitlab.com/devops-tools/jenkins-vs-gitlab.html) to learn how our built-in CI compares to Jenkins.
+
 ## Requirements
 
-* [Jenkins GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin)
-* [Jenkins Git Plugin](https://wiki.jenkins.io/display/JENKINS/Git+Plugin)
-* Git clone access for Jenkins from the GitLab repository
-* GitLab API access to report build status
+- [Jenkins GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin)
+- [Jenkins Git Plugin](https://wiki.jenkins.io/display/JENKINS/Git+Plugin)
+- Git clone access for Jenkins from the GitLab repository
+- GitLab API access to report build status
 
 ## Configure GitLab users
 
@@ -65,7 +68,7 @@ Go to Manage Jenkins -> Configure System and scroll down to the 'GitLab' section
 Enter the GitLab server URL in the 'GitLab host URL' field and paste the API token
 copied earlier in the 'API Token' field.
 
-For more information, see GitLab Plugin documentation about 
+For more information, see GitLab Plugin documentation about
 [Jenkins-to-GitLab authentication](https://github.com/jenkinsci/gitlab-plugin#jenkins-to-gitlab-authentication)
 
 ![Jenkins GitLab plugin configuration](img/jenkins_gitlab_plugin_config.png)
@@ -76,8 +79,8 @@ Follow the GitLab Plugin documentation about [Jenkins Job Configuration](https:/
 
 NOTE: **Note:**
 Be sure to include the steps about [Build status configuration](https://github.com/jenkinsci/gitlab-plugin#build-status-configuration).
-The 'Publish build status to GitLab' post-build step is required to view 
-Jenkins build status in GitLab Merge Requests. 
+The 'Publish build status to GitLab' post-build step is required to view
+Jenkins build status in GitLab Merge Requests.
 
 ## Configure a GitLab project
 
@@ -114,21 +117,21 @@ and storing build status for Commits and Merge Requests.
 All steps are implemented using AJAX requests on the merge request page.
 
 1. In order to display the build status in a merge request you must create a project service in GitLab.
-2. Your project service will do a (JSON) query to a URL of the CI tool with the SHA1 of the commit.
-3. The project service builds this URL and payload based on project service settings and knowledge of the CI tool.
-4. The response is parsed to give a response in GitLab (success/failed/pending).
+1. Your project service will do a (JSON) query to a URL of the CI tool with the SHA1 of the commit.
+1. The project service builds this URL and payload based on project service settings and knowledge of the CI tool.
+1. The response is parsed to give a response in GitLab (success/failed/pending).
 
 ## Troubleshooting
 
 ### Error in merge requests - "Could not connect to the CI server"
 
 This integration relies on Jenkins reporting the build status back to GitLab via
-the [Commit Status API](../api/commits.md#commit-status). 
+the [Commit Status API](../api/commits.md#commit-status).
 
 The error 'Could not connect to the CI server' usually means that GitLab did not
 receive a build status update via the API. Either Jenkins was not properly
-configured or there was an error reporting the status via the API. 
+configured or there was an error reporting the status via the API.
 
 1. [Configure the Jenkins server](#configure-the-jenkins-server) for GitLab API access
-2. [Configure a Jenkins project](#configure-a-jenkins-project), including the 
-   'Publish build status to GitLab' post-build action. 
+1. [Configure a Jenkins project](#configure-a-jenkins-project), including the
+   'Publish build status to GitLab' post-build action.
diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md
index 8001c5dbd83..bac89ae2dc6 100644
--- a/doc/integration/jenkins_deprecated.md
+++ b/doc/integration/jenkins_deprecated.md
@@ -8,18 +8,18 @@ Please use documentation for the new [Jenkins CI service](jenkins.md).
 
 Integration includes:
 
-* Trigger Jenkins build after push to repo
-* Show build status on Merge Request page
+- Trigger Jenkins build after push to repo
+- Show build status on Merge Request page
 
 Requirements:
 
-* [Jenkins GitLab Hook plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin)
-* git clone access for Jenkins from GitLab repo (via ssh key)
+- [Jenkins GitLab Hook plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin)
+- git clone access for Jenkins from GitLab repo (via ssh key)
 
 ## Jenkins
 
 1. Install [GitLab Hook plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin)
-2. Set up jenkins project
+1. Set up jenkins project
 
 ![screen](img/jenkins_project.png)
 
diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md
index 703736eeb3c..3e894371df9 100644
--- a/doc/integration/jira_development_panel.md
+++ b/doc/integration/jira_development_panel.md
@@ -1,4 +1,4 @@
-# GitLab Jira development panel integration **[PREMIUM]**
+# GitLab Jira development panel integration **(PREMIUM)**
 
 > [Introduced][ee-2381] in [GitLab Premium][eep] 10.0.
 
@@ -43,67 +43,68 @@ There are no special requirements if you are using GitLab.com.
 
 1. In GitLab, create a new application in order to allow Jira to connect with your GitLab account
 
-    While logged-in, go to `Settings -> Applications`. (Click your profile avatar at
-    the top right, choose `Settings`, and then navigate to `Applications` from the left
-    navigation menu.) Use the form to create a new application.
+   While logged-in, go to `Settings -> Applications`. (Click your profile avatar at
+   the top right, choose `Settings`, and then navigate to `Applications` from the left
+   navigation menu.) Use the form to create a new application.
 
-    Enter a useful name for the `Name` field.
+   Enter a useful name for the `Name` field.
 
-    For the `Redirect URI` field, enter `https://<your-gitlab-instance-domain>/login/oauth/callback`,
-    replacing `<your-gitlab-instance-domain>` appropriately. So for example, if you are using GitLab.com,
-    this would be `https://gitlab.com/login/oauth/callback`.
+   For the `Redirect URI` field, enter `https://<your-gitlab-instance-domain>/login/oauth/callback`,
+   replacing `<your-gitlab-instance-domain>` appropriately. So for example, if you are using GitLab.com,
+   this would be `https://gitlab.com/login/oauth/callback`.
 
-    NOTE: **Note**:
-    If using a GitLab version earlier than 11.3 the `Redirect URI` value should be `https://<your-gitlab-instance-domain>/-/jira/login/oauth/callback`.
+   NOTE: **Note**:
+   If using a GitLab version earlier than 11.3 the `Redirect URI` value should be `https://<your-gitlab-instance-domain>/-/jira/login/oauth/callback`.
 
-    ![GitLab Application setup](img/jira_dev_panel_gl_setup_1.png)
-    - Check `api` in the Scopes section.
+   ![GitLab Application setup](img/jira_dev_panel_gl_setup_1.png)
 
-2. Click `Save application`. You will see the generated 'Application Id' and 'Secret' values.
-    Copy these values that you will use on the Jira configuration side.
+   - Check `api` in the Scopes section.
+
+1. Click `Save application`. You will see the generated 'Application Id' and 'Secret' values.
+   Copy these values that you will use on the Jira configuration side.
 
 ## Jira Configuration
 
 1. In Jira, from the gear menu at the top right, go to `Applications`. Navigate to `DVCS accounts`
-    from the left navigation menu. Click `Link GitHub account` to start creating a new integration.
-    (We are pretending to be GitHub in this integration until there is further platform support from Jira.)
+   from the left navigation menu. Click `Link GitHub account` to start creating a new integration.
+   (We are pretending to be GitHub in this integration until there is further platform support from Jira.)
 
-    ![Jira DVCS from Dashboard](img/jira_dev_panel_jira_setup_1.png)
+   ![Jira DVCS from Dashboard](img/jira_dev_panel_jira_setup_1.png)
 
-2. Complete the form
+1. Complete the form
 
-    Select GitHub Enterprise for the `Host` field.
+   Select GitHub Enterprise for the `Host` field.
 
-    For the `Team or User Account` field, enter the relative path of a top-level GitLab group that you have access to,
-    or the relative path of your personal namespace.
+   For the `Team or User Account` field, enter the relative path of a top-level GitLab group that you have access to,
+   or the relative path of your personal namespace.
 
-    ![Creation of Jira DVCS integration](img/jira_dev_panel_jira_setup_2.png)
+   ![Creation of Jira DVCS integration](img/jira_dev_panel_jira_setup_2.png)
 
-    For the `Host URL` field, enter `https://<your-gitlab-instance-domain>/`,
-    replacing `<your-gitlab-instance-domain>` appropriately. So for example, if you are using GitLab.com,
-    this would be `https://gitlab.com/`.
+   For the `Host URL` field, enter `https://<your-gitlab-instance-domain>/`,
+   replacing `<your-gitlab-instance-domain>` appropriately. So for example, if you are using GitLab.com,
+   this would be `https://gitlab.com/`.
 
-    NOTE: **Note**:
-    If using a GitLab version earlier than 11.3 the `Host URL` value should be `https://<your-gitlab-instance-domain>/-/jira`
+   NOTE: **Note**:
+   If using a GitLab version earlier than 11.3 the `Host URL` value should be `https://<your-gitlab-instance-domain>/-/jira`
 
-    For the `Client ID` field, use the `Application ID` value from the previous section.
+   For the `Client ID` field, use the `Application ID` value from the previous section.
 
-    For the `Client Secret` field, use the `Secret` value from the previous section.
+   For the `Client Secret` field, use the `Secret` value from the previous section.
 
-    Ensure that the rest of the checkboxes are checked.
+   Ensure that the rest of the checkboxes are checked.
 
-3. Click `Add` to complete and create the integration.
+1. Click `Add` to complete and create the integration.
 
-    Jira takes up to a few minutes to know about (import behind the scenes) all the commits and branches
-    for all the projects in the GitLab group you specified in the previous step. These are refreshed
-    every 60 minutes.
+   Jira takes up to a few minutes to know about (import behind the scenes) all the commits and branches
+   for all the projects in the GitLab group you specified in the previous step. These are refreshed
+   every 60 minutes.
 
-    > **Note:**
-    > In the future, we plan on implementating real-time integration. If you need
-    > to refresh the data manually, you can do this from the `Applications -> DVCS
-    > accounts` screen where you initially set up the integration:
-    >
-    > ![Refresh GitLab information in Jira](img/jira_dev_panel_manual_refresh.png)
+   > **Note:**
+   > In the future, we plan on implementating real-time integration. If you need
+   > to refresh the data manually, you can do this from the `Applications -> DVCS
+   > accounts` screen where you initially set up the integration:
+   >
+   > ![Refresh GitLab information in Jira](img/jira_dev_panel_manual_refresh.png)
 
 To connect additional GitLab projects from other GitLab top-level groups (or personal namespaces), repeat the above
 steps with additional Jira DVCS accounts.
diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md
index 44117755b83..b791cbd428d 100644
--- a/doc/integration/kerberos.md
+++ b/doc/integration/kerberos.md
@@ -1,4 +1,4 @@
-# Kerberos integration **[STARTER ONLY]**
+# Kerberos integration **(STARTER ONLY)**
 
 GitLab can integrate with [Kerberos][kerb] as an authentication mechanism.
 
@@ -50,41 +50,37 @@ For source installations, make sure the `kerberos` gem group
    authentication. In most cases, you only need to enable Kerberos and specify
    the location of the keytab:
 
-    ```yaml
-    omniauth:
-      enabled: true
-      allow_single_sign_on: ['kerberos']
+   ```yaml
+   omniauth:
+     enabled: true
+     allow_single_sign_on: ['kerberos']
 
-    kerberos:
-      # Allow the HTTP Negotiate authentication method for Git clients
-      enabled: true
+   kerberos:
+     # Allow the HTTP Negotiate authentication method for Git clients
+     enabled: true
 
-      # Kerberos 5 keytab file. The keytab file must be readable by the GitLab user,
-      # and should be different from other keytabs in the system.
-      # (default: use default keytab from Krb5 config)
-      keytab: /etc/http.keytab
-    ```
+     # Kerberos 5 keytab file. The keytab file must be readable by the GitLab user,
+     # and should be different from other keytabs in the system.
+     # (default: use default keytab from Krb5 config)
+     keytab: /etc/http.keytab
+   ```
 
 1. [Restart GitLab] for the changes to take effect.
 
----
-
 **Omnibus package installations**
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['omniauth_enabled'] = true
-    gitlab_rails['omniauth_allow_single_sign_on'] = ['kerberos']
+   ```ruby
+   gitlab_rails['omniauth_enabled'] = true
+   gitlab_rails['omniauth_allow_single_sign_on'] = ['kerberos']
 
-    gitlab_rails['kerberos_enabled'] = true
-    gitlab_rails['kerberos_keytab'] = "/etc/http.keytab"
-    ```
+   gitlab_rails['kerberos_enabled'] = true
+   gitlab_rails['kerberos_keytab'] = "/etc/http.keytab"
+   ```
 
 1. [Reconfigure GitLab] for the changes to take effect.
 
----
-
 GitLab will now offer the `negotiate` authentication method for signing in and
 HTTP Git access, enabling Git clients that support this authentication protocol
 to authenticate with Kerberos tokens.
@@ -149,45 +145,41 @@ keep offering only `basic` authentication.
    (e.g., `/etc/nginx/sites-available/gitlab-ssl`) and configure NGINX to
    listen to port `8443` in addition to the standard HTTPS port:
 
-    ```conf
-    server {
-      listen 0.0.0.0:443 ssl;
-      listen [::]:443 ipv6only=on ssl default_server;
-      listen 0.0.0.0:8443 ssl;
-      listen [::]:8443 ipv6only=on ssl;
-    ```
+   ```conf
+   server {
+     listen 0.0.0.0:443 ssl;
+     listen [::]:443 ipv6only=on ssl default_server;
+     listen 0.0.0.0:8443 ssl;
+     listen [::]:8443 ipv6only=on ssl;
+   ```
 
 1. Update the Kerberos section of [gitlab.yml]:
 
-    ```yaml
-    kerberos:
-      # Dedicated port: Git before 2.4 does not fall back to Basic authentication if Negotiate fails.
-      # To support both Basic and Negotiate methods with older versions of Git, configure
-      # nginx to proxy GitLab on an extra port (e.g. 8443) and uncomment the following lines
-      # to dedicate this port to Kerberos authentication. (default: false)
-      use_dedicated_port: true
-      port: 8443
-      https: true
-    ```
+   ```yaml
+   kerberos:
+     # Dedicated port: Git before 2.4 does not fall back to Basic authentication if Negotiate fails.
+     # To support both Basic and Negotiate methods with older versions of Git, configure
+     # nginx to proxy GitLab on an extra port (e.g. 8443) and uncomment the following lines
+     # to dedicate this port to Kerberos authentication. (default: false)
+     use_dedicated_port: true
+     port: 8443
+     https: true
+   ```
 
 1. [Restart GitLab] and NGINX for the changes to take effect.
 
----
-
 **For Omnibus package installations**
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['kerberos_use_dedicated_port'] = true
-    gitlab_rails['kerberos_port'] = 8443
-    gitlab_rails['kerberos_https'] = true
-    ```
+   ```ruby
+   gitlab_rails['kerberos_use_dedicated_port'] = true
+   gitlab_rails['kerberos_port'] = 8443
+   gitlab_rails['kerberos_https'] = true
+   ```
 
 1. [Reconfigure GitLab] for the changes to take effect.
 
----
-
 After this change, all Git remote URLs will have to be updated to
 `https://gitlab.example.com:8443/mygroup/myproject.git` in order to use
 Kerberos ticket-based authentication.
@@ -214,27 +206,25 @@ remove the OmniAuth provider named `kerberos` from your `gitlab.yml` /
 1. Edit [gitlab.yml] and remove the `- { name: 'kerberos' }` line under omniauth
    providers:
 
-    ```yaml
-    omniauth:
-      # ...
-      providers:
-        - { name: 'kerberos' } # <-- remove this line
-    ```
+   ```yaml
+   omniauth:
+     # ...
+     providers:
+       - { name: 'kerberos' } # <-- remove this line
+   ```
 
 1. [Restart GitLab] for the changes to take effect.
 
----
-
 **For Omnibus installations**
 
 1. Edit `/etc/gitlab/gitlab.rb` and remove the `{ "name" => "kerberos" }` line
    under `gitlab_rails['omniauth_providers']`:
 
-    ```ruby
-    gitlab_rails['omniauth_providers'] = [
-      { "name" => "kerberos" } # <-- remove this entry
-    ]
-    ```
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     { "name" => "kerberos" } # <-- remove this entry
+   ]
+   ```
 
 1. [Reconfigure GitLab] for the changes to take effect.
 
@@ -290,7 +280,7 @@ remote: HTTP Basic: Access denied
 fatal: Authentication failed for '<KRB5 path>'
 ```
 
-If you are using Git v2.11 or newer and see the above error when cloning, you can 
+If you are using Git v2.11 or newer and see the above error when cloning, you can
 set the `http.emptyAuth` Git option to `true` to fix this:
 
 ```
diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md
index 3e72589ce12..f4119b1d1ce 100644
--- a/doc/integration/oauth2_generic.md
+++ b/doc/integration/oauth2_generic.md
@@ -1,7 +1,7 @@
 # Sign into GitLab with (almost) any OAuth2 provider
 
 The `omniauth-oauth2-generic` gem allows Single Sign On between GitLab and your own OAuth2 provider
-(or any OAuth2 provider compatible with this gem) 
+(or any OAuth2 provider compatible with this gem)
 
 This strategy is designed to allow configuration of the simple OmniAuth SSO process outlined below:
 
@@ -12,7 +12,7 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc
 1. Strategy parses user information from the response, using a **configurable** format
 1. GitLab finds or creates the returned user and logs them in
 
-### Limitations of this Strategy:
+## Limitations of this Strategy:
 
 - It can only be used for Single Sign on, and will not provide any other access granted by any OAuth provider
   (importing projects or users, etc)
@@ -20,15 +20,15 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc
 - It is not able to fetch user information from more than one URL
 - It has not been tested with user information formats other than JSON
 
-### Config Instructions
+## Config Instructions
 
 1. Register your application in the OAuth2 provider you wish to authenticate with.
 
-    The redirect URI you provide when registering the application should be:
+   The redirect URI you provide when registering the application should be:
 
-    ```
-    http://your-gitlab.host.com/users/auth/oauth2_generic/callback
-    ```
+   ```
+   http://your-gitlab.host.com/users/auth/oauth2_generic/callback
+   ```
 
 1. You should now be able to get a Client ID and Client Secret.
    Where this shows up will differ for each provider.
@@ -36,18 +36,18 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc
 
 1. On your GitLab server, open the configuration file.
 
-    For Omnibus package:
+   For Omnibus package:
 
-    ```sh
-    sudo editor /etc/gitlab/gitlab.rb
-    ```
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```sh
-    cd /home/git/gitlab
-    sudo -u git -H editor config/gitlab.yml
-    ```
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H editor config/gitlab.yml
+   ```
 
 1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings
 
@@ -57,9 +57,9 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc
 
 1. Restart GitLab for the changes to take effect
 
-On the sign in page there should now be a new button below the regular sign in form. 
+On the sign in page there should now be a new button below the regular sign in form.
 Click the button to begin your provider's authentication process. This will direct
 the browser to your OAuth2 Provider's authentication page. If everything goes well
 the user will be returned to your GitLab instance and will be signed in.
 
-[1]: https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example
\ No newline at end of file
+[1]: https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example
diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md
index c02a29dffb4..36b4836e6b3 100644
--- a/doc/integration/oauth_provider.md
+++ b/doc/integration/oauth_provider.md
@@ -11,7 +11,7 @@ If you want to use:
 
 ## Introduction to OAuth
 
-[OAuth] provides to client applications a 'secure delegated access' to server
+[OAuth](https://oauth.net/2/) provides to client applications a 'secure delegated access' to server
 resources on behalf of a resource owner. In fact, OAuth allows an authorization
 server to issue access tokens to third-party clients with the approval of the
 resource owner, or the end-user.
@@ -25,8 +25,6 @@ can be used for authentication to your GitLab instance
 The 'GitLab Importer' feature is also using the OAuth protocol to give access
 to repositories without sharing user credentials to your GitLab.com account.
 
----
-
 GitLab supports two ways of adding a new OAuth2 application to an instance. You
 can either add an application as a regular user or add it in the admin area.
 What this means is that GitLab can actually have instance-wide and a user-wide
@@ -41,24 +39,18 @@ In order to add a new application via your profile, navigate to
 
 ![New OAuth application](img/oauth_provider_user_wide_applications.png)
 
----
-
 In the application form, enter a **Name** (arbitrary), and make sure to set up
 correctly the **Redirect URI** which is the URL where users will be sent after
 they authorize with GitLab.
 
 ![New OAuth application form](img/oauth_provider_application_form.png)
 
----
-
 When you hit **Submit** you will be provided with the application ID and
 the application secret which you can then use with your application that
 connects to GitLab.
 
 ![OAuth application ID and secret](img/oauth_provider_application_id_secret.png)
 
----
-
 ## OAuth applications in the admin area
 
 To create an application that does not belong to a certain user, you can create
@@ -69,8 +61,6 @@ it from the admin area.
 You're also able to mark an application as _trusted_ when creating it through the admin area. By doing that,
 the user authorization step is automatically skipped for this application.
 
----
-
 ## Authorized applications
 
 Every application you authorized to use your GitLab credentials will be shown
@@ -78,12 +68,8 @@ in the **Authorized applications** section under **Profile Settings > Applicatio
 
 ![Authorized_applications](img/oauth_provider_authorized_application.png)
 
----
-
 GitLab's OAuth applications support scopes, which allow various actions that any given
 application can perform such as `read_user` and `api`. There are many more scopes
 available.
 
 At any time you can revoke any access by just clicking **Revoke**.
-
-[oauth]: http://oauth.net/2/ "OAuth website"
diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md
index a13e9f73f48..7a92ed994c7 100644
--- a/doc/integration/omniauth.md
+++ b/doc/integration/omniauth.md
@@ -71,57 +71,57 @@ To change these settings:
 
 - **For omnibus package**
 
-    Open the configuration file:
+  Open the configuration file:
 
-    ```sh
-    sudo editor /etc/gitlab/gitlab.rb
-    ```
+  ```sh
+  sudo editor /etc/gitlab/gitlab.rb
+  ```
 
-    and change:
+  and change:
 
-    ```ruby
-    # Versions prior to 11.4 require this to be set to true
-    # gitlab_rails['omniauth_enabled'] = nil
+  ```ruby
+  # Versions prior to 11.4 require this to be set to true
+  # gitlab_rails['omniauth_enabled'] = nil
 
-    # CAUTION!
-    # This allows users to login without having a user account first. Define the allowed providers
-    # using an array, e.g. ["saml", "twitter"], or as true/false to allow all providers or none.
-    # User accounts will be created automatically when authentication was successful.
-    gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'twitter']
-    gitlab_rails['omniauth_auto_link_ldap_user'] = true
-    gitlab_rails['omniauth_block_auto_created_users'] = true
-    ```
+  # CAUTION!
+  # This allows users to login without having a user account first. Define the allowed providers
+  # using an array, e.g. ["saml", "twitter"], or as true/false to allow all providers or none.
+  # User accounts will be created automatically when authentication was successful.
+  gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'twitter']
+  gitlab_rails['omniauth_auto_link_ldap_user'] = true
+  gitlab_rails['omniauth_block_auto_created_users'] = true
+  ```
 
 - **For installations from source**
 
-    Open the configuration file:
+  Open the configuration file:
 
-    ```sh
-    cd /home/git/gitlab
+  ```sh
+  cd /home/git/gitlab
 
-    sudo -u git -H editor config/gitlab.yml
-    ```
+  sudo -u git -H editor config/gitlab.yml
+  ```
 
-    and change the following section:
+  and change the following section:
 
-    ```yaml
-     ## OmniAuth settings
-      omniauth:
-        # Allow login via Twitter, Google, etc. using OmniAuth providers
-        # Versions prior to 11.4 require this to be set to true
-        # enabled: true
+  ```yaml
+  ## OmniAuth settings
+   omniauth:
+     # Allow login via Twitter, Google, etc. using OmniAuth providers
+     # Versions prior to 11.4 require this to be set to true
+     # enabled: true
 
-        # CAUTION!
-        # This allows users to login without having a user account first. Define the allowed providers
-        # using an array, e.g. ["saml", "twitter"], or as true/false to allow all providers or none.
-        # User accounts will be created automatically when authentication was successful.
-        allow_single_sign_on: ["saml", "twitter"]
+     # CAUTION!
+     # This allows users to login without having a user account first. Define the allowed providers
+     # using an array, e.g. ["saml", "twitter"], or as true/false to allow all providers or none.
+     # User accounts will be created automatically when authentication was successful.
+     allow_single_sign_on: ["saml", "twitter"]
 
-        auto_link_ldap_user: true
+     auto_link_ldap_user: true
 
-        # Locks down those users until they have been cleared by the admin (default: true).
-        block_auto_created_users: true
-    ```
+     # Locks down those users until they have been cleared by the admin (default: true).
+     block_auto_created_users: true
+  ```
 
 Now we can choose one or more of the [Supported Providers](#supported-providers)
 listed above to continue the configuration process.
@@ -161,14 +161,14 @@ want their accounts to be upgraded to full internal accounts.
 **For Omnibus installations**
 
 ```ruby
-  gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2']
+gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2']
 ```
 
 **For installations from source**
 
 ```yaml
-  omniauth:
-    external_providers: ['twitter', 'google_oauth2']
+omniauth:
+  external_providers: ['twitter', 'google_oauth2']
 ```
 
 ## Using Custom Omniauth Providers
@@ -186,27 +186,31 @@ these cases you can use the Omniauth provider.
 These steps are fairly general and you will need to figure out the exact details
 from the Omniauth provider's documentation.
 
--   Stop GitLab:
+- Stop GitLab:
 
-        sudo service gitlab stop
+  ```sh
+  sudo service gitlab stop
+  ```
 
--   Add the gem to your [Gemfile](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/Gemfile):
+- Add the gem to your [Gemfile](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/Gemfile):
 
-        gem "omniauth-your-auth-provider"
+  ```sh
+  gem "omniauth-your-auth-provider"
+  ```
 
--   If you're using MySQL, install the new Omniauth provider gem by running the following command:
+- Install the new Omniauth provider gem by running the following command:
 
-        sudo -u git -H bundle install --without development test postgres --path vendor/bundle --no-deployment
+  ```sh
+  sudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployment
+  ```
 
--   If you're using PostgreSQL, install the new Omniauth provider gem by running the following command:
+  > These are the same commands you used during initial installation in the [Install Gems section](../install/installation.md#install-gems) with `--path vendor/bundle --no-deployment` instead of `--deployment`.
 
-        sudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployment
+- Start GitLab:
 
-    > These are the same commands you used during initial installation in the [Install Gems section](../install/installation.md#install-gems) with `--path vendor/bundle --no-deployment` instead of `--deployment`.
-
--   Start GitLab:
-
-        sudo service gitlab start
+  ```sh
+  sudo service gitlab start
+  ```
 
 ### Examples
 
@@ -251,8 +255,8 @@ gitlab_rails['omniauth_enabled'] = false
 **For installations from source**
 
 ```yaml
-  omniauth:
-    enabled: false
+omniauth:
+  enabled: false
 ```
 
 ## Keep OmniAuth user profiles up to date
@@ -262,14 +266,14 @@ You can enable profile syncing from selected OmniAuth providers and for all or f
 When authenticating using LDAP, the user's name and email are always synced.
 
 ```ruby
-  gitlab_rails['sync_profile_from_provider'] = ['twitter', 'google_oauth2']
-  gitlab_rails['sync_profile_attributes'] = ['name', 'email', 'location']
- ```
+gitlab_rails['sync_profile_from_provider'] = ['twitter', 'google_oauth2']
+gitlab_rails['sync_profile_attributes'] = ['name', 'email', 'location']
+```
 
 **For installations from source**
 
 ```yaml
-  omniauth:
-    sync_profile_from_provider: ['twitter', 'google_oauth2']
-    sync_profile_attributes: ['email', 'location']
+omniauth:
+  sync_profile_from_provider: ['twitter', 'google_oauth2']
+  sync_profile_attributes: ['email', 'location']
 ```
diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md
index a7f907254a1..89f4924d717 100644
--- a/doc/integration/openid_connect_provider.md
+++ b/doc/integration/openid_connect_provider.md
@@ -5,7 +5,7 @@ to sign in to other services.
 
 ## Introduction to OpenID Connect
 
-[OpenID Connect] \(OIDC) is a simple identity layer on top of the
+[OpenID Connect](https://openid.net/connect/) \(OIDC) is a simple identity layer on top of the
 OAuth 2.0 protocol. It allows clients to verify the identity of the end-user
 based on the authentication performed by GitLab, as well as to obtain
 basic profile information about the end-user in an interoperable and
@@ -14,7 +14,7 @@ but does so in a way that is API-friendly, and usable by native and
 mobile applications.
 
 On the client side, you can use [omniauth-openid-connect] for Rails
-applications, or any of the other available [client implementations].
+applications, or any of the other available [client implementations](https://openid.net/developers/libraries/#connect).
 
 GitLab's implementation uses the [doorkeeper-openid_connect] gem, refer
 to its README for more details about which parts of the specifications
@@ -46,8 +46,6 @@ Currently the following user information is shared with clients:
 
 Only the `sub` and `sub_legacy` claims are included in the ID token, all other claims are available from the `/oauth/userinfo` endpoint used by OIDC clients.
 
-[OpenID Connect]: http://openid.net/connect/ "OpenID Connect website"
 [doorkeeper-openid_connect]: https://github.com/doorkeeper-gem/doorkeeper-openid_connect "Doorkeeper::OpenidConnect website"
 [OAuth guide]: oauth_provider.md "GitLab as OAuth2 authentication service provider"
 [omniauth-openid-connect]: https://github.com/jjbohn/omniauth-openid-connect/ "OmniAuth::OpenIDConnect website"
-[client implementations]: http://openid.net/developers/libraries#connect "List of available client implementations"
diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md
index 1ef43cfcece..176622e8050 100644
--- a/doc/integration/salesforce.md
+++ b/doc/integration/salesforce.md
@@ -7,73 +7,77 @@ You can integrate your GitLab instance with [Salesforce](https://www.salesforce.
 To enable Salesforce OmniAuth provider, you must use Salesforce's credentials for your GitLab instance.
 To get the credentials (a pair of Client ID and Client Secret), you must [create a Connected App](https://help.salesforce.com/articleView?id=connected_app_create.htm&type=5) on Salesforce.
 
-1.  Sign in to [Salesforce](https://login.salesforce.com/).
+1. Sign in to [Salesforce](https://login.salesforce.com/).
 
-1.  In Setup, enter `App Manager` in the Quick Find box, click **App Manager**, then click **New Connected App**.
+1. In Setup, enter `App Manager` in the Quick Find box, click **App Manager**, then click **New Connected App**.
 
-1.  Fill in the application details into the following fields:
-    - **Connected App Name** and **API Name**: Set to any value but consider something like `<Organization>'s GitLab`, `<Your Name>'s GitLab`, or something else that is descriptive.
-    - **Contact Email**: Enter the contact email for Salesforce to use when contacting you or your support team.
-    - **Description**: Description for the application.
+1. Fill in the application details into the following fields:
+   - **Connected App Name** and **API Name**: Set to any value but consider something like `<Organization>'s GitLab`, `<Your Name>'s GitLab`, or something else that is descriptive.
+   - **Contact Email**: Enter the contact email for Salesforce to use when contacting you or your support team.
+   - **Description**: Description for the application.
 
-    ![Salesforce App Details](img/salesforce_app_details.png)
-1.  Select **API (Enable OAuth Settings)** and click on **Enable OAuth Settings**.
-1.  Fill in the application details into the following fields:
-    - **Callback URL**: The callback URL of your GitLab installation. For example, `https://gitlab.example.com/users/auth/salesforce/callback`.
-    - **Selected OAuth Scopes**: Move **Access your basic information (id, profile, email, address, phone)** and **Allow access to your unique identifier (openid)** to the right column.
+   ![Salesforce App Details](img/salesforce_app_details.png)
+
+1. Select **API (Enable OAuth Settings)** and click on **Enable OAuth Settings**.
+1. Fill in the application details into the following fields:
+   - **Callback URL**: The callback URL of your GitLab installation. For example, `https://gitlab.example.com/users/auth/salesforce/callback`.
+   - **Selected OAuth Scopes**: Move **Access your basic information (id, profile, email, address, phone)** and **Allow access to your unique identifier (openid)** to the right column.
+
+   ![Salesforce Oauth App Details](img/salesforce_oauth_app_details.png)
 
-    ![Salesforce Oauth App Details](img/salesforce_oauth_app_details.png)
 1. Click **Save**.
 
-1.  On your GitLab server, open the configuration file.
+1. On your GitLab server, open the configuration file.
+
+   For omnibus package:
+
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    For omnibus package:
+   For installations from source:
 
-    ```sh
-      sudo editor /etc/gitlab/gitlab.rb
-    ```
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H editor config/gitlab.yml
+   ```
 
-    For installations from source:
+1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
 
-    ```sh
-      cd /home/git/gitlab
-      sudo -u git -H editor config/gitlab.yml
-    ```
+1. Add the provider configuration:
 
-1.  See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+   For omnibus package:
 
-1.  Add the provider configuration:
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       "name" => "salesforce",
+       "app_id" => "SALESFORCE_CLIENT_ID",
+       "app_secret" => "SALESFORCE_CLIENT_SECRET"
+     }
+   ]
+   ```
 
-    For omnibus package:
+   For installation from source:
 
-    ```ruby
-      gitlab_rails['omniauth_providers'] = [
-        {
-          "name" => "salesforce",
-          "app_id" => "SALESFORCE_CLIENT_ID",
-          "app_secret" => "SALESFORCE_CLIENT_SECRET"
-        }
-      ]
-    ```
+   ```
+   - { name: 'salesforce',
+       app_id: 'SALESFORCE_CLIENT_ID',
+       app_secret: 'SALESFORCE_CLIENT_SECRET'
+     }
+   ```
 
-    For installation from source:
+1. Change `SALESFORCE_CLIENT_ID` to the Consumer Key from the Salesforce connected application page.
+1. Change `SALESFORCE_CLIENT_SECRET` to the Consumer Secret from the Salesforce connected application page.
 
-    ```
-      - { name: 'salesforce',
-          app_id: 'SALESFORCE_CLIENT_ID',
-          app_secret: 'SALESFORCE_CLIENT_SECRET'
-        }
-    ```
-1.  Change `SALESFORCE_CLIENT_ID` to the Consumer Key from the Salesforce connected application page.
-1.  Change `SALESFORCE_CLIENT_SECRET` to the Consumer Secret from the Salesforce connected application page.
-    ![Salesforce App Secret Details](img/salesforce_app_secret_details.png)
+   ![Salesforce App Secret Details](img/salesforce_app_secret_details.png)
 
-1.  Save the configuration file.
-1.  [Reconfigure GitLab]( ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure ) or [restart GitLab]( ../administration/restart_gitlab.md#installations-from-source ) for the changes to take effect if you installed GitLab via Omnibus or from source respectively.
+1. Save the configuration file.
+1. [Reconfigure GitLab]( ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure ) or [restart GitLab]( ../administration/restart_gitlab.md#installations-from-source ) for the changes to take effect if you installed GitLab via Omnibus or from source respectively.
 
 On the sign in page, there should now be a Salesforce icon below the regular sign in form.
 Click the icon to begin the authentication process. Salesforce will ask the user to sign in and authorize the GitLab application.
 If everything goes well, the user will be returned to GitLab and will be signed in.
 
 NOTE: **Note:**
-GitLab requires the email address of each new user. Once the user is logged in using Salesforce, GitLab will redirect the user to the profile page where they will have to provide the email and verify the email.
\ No newline at end of file
+GitLab requires the email address of each new user. Once the user is logged in using Salesforce, GitLab will redirect the user to the profile page where they will have to provide the email and verify the email.
diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md
index 616f3a76b2c..27355d25266 100644
--- a/doc/integration/shibboleth.md
+++ b/doc/integration/shibboleth.md
@@ -5,8 +5,8 @@ This documentation is for enabling shibboleth with omnibus-gitlab package.
 In order to enable Shibboleth support in gitlab we need to use Apache instead of Nginx (It may be possible to use Nginx, however this is difficult to configure using the bundled Nginx provided in the omnibus-gitlab package). Apache uses mod_shib2 module for shibboleth authentication and can pass attributes as headers to omniauth-shibboleth provider.
 
 To enable the Shibboleth OmniAuth provider you must configure Apache shibboleth module.
-Installation and configuration of module it self is out of scope of this document.
-Check <https://wiki.shibboleth.net/> for more info.
+The installation and configuration of the module itself is out of the scope of this document.
+Check <https://wiki.shibboleth.net/confluence/display/SP3/Apache> for more info.
 
 You can find Apache config in gitlab-recipes (<https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache>).
 
@@ -14,35 +14,35 @@ The following changes are needed to enable Shibboleth:
 
 1. Protect omniauth-shibboleth callback URL:
 
-    ```
-      <Location /users/auth/shibboleth/callback>
-        AuthType shibboleth
-        ShibRequestSetting requireSession 1
-        ShibUseHeaders On
-        require valid-user
-      </Location>
+   ```
+   <Location /users/auth/shibboleth/callback>
+     AuthType shibboleth
+     ShibRequestSetting requireSession 1
+     ShibUseHeaders On
+     require valid-user
+   </Location>
 
-      Alias /shibboleth-sp /usr/share/shibboleth
-      <Location /shibboleth-sp>
-        Satisfy any
-      </Location>
+   Alias /shibboleth-sp /usr/share/shibboleth
+   <Location /shibboleth-sp>
+     Satisfy any
+   </Location>
 
-      <Location /Shibboleth.sso>
-        SetHandler shib
-      </Location>
-    ```
+   <Location /Shibboleth.sso>
+     SetHandler shib
+   </Location>
+   ```
 
 1. Exclude shibboleth URLs from rewriting. Add `RewriteCond %{REQUEST_URI} !/Shibboleth.sso` and `RewriteCond %{REQUEST_URI} !/shibboleth-sp`. Config should look like this:
 
-    ```
-      # Apache equivalent of Nginx try files
-      RewriteEngine on
-      RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
-      RewriteCond %{REQUEST_URI} !/Shibboleth.sso
-      RewriteCond %{REQUEST_URI} !/shibboleth-sp
-      RewriteRule .* http://127.0.0.1:8080%{REQUEST_URI} [P,QSA]
-      RequestHeader set X_FORWARDED_PROTO 'https'
-    ```
+   ```
+   # Apache equivalent of Nginx try files
+   RewriteEngine on
+   RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
+   RewriteCond %{REQUEST_URI} !/Shibboleth.sso
+   RewriteCond %{REQUEST_URI} !/shibboleth-sp
+   RewriteRule .* http://127.0.0.1:8080%{REQUEST_URI} [P,QSA]
+   RequestHeader set X_FORWARDED_PROTO 'https'
+   ```
 
 1. Edit `/etc/gitlab/gitlab.rb` configuration file to enable OmniAuth and add
    Shibboleth as an OmniAuth provider. User attributes will be sent from the
@@ -60,31 +60,31 @@ The following changes are needed to enable Shibboleth:
 
    The file should look like this:
 
-    ```
-    external_url 'https://gitlab.example.com'
-    gitlab_rails['internal_api_url'] = 'https://gitlab.example.com'
-
-    # disable Nginx
-    nginx['enable'] = false
-
-    gitlab_rails['omniauth_allow_single_sign_on'] = true
-    gitlab_rails['omniauth_block_auto_created_users'] = false
-    gitlab_rails['omniauth_enabled'] = true
-    gitlab_rails['omniauth_providers'] = [
-      {
-        "name"  => "'shibboleth"',
-        "label" => "Text for Login Button",
-        "args"  => {
-            "shib_session_id_field"     => "HTTP_SHIB_SESSION_ID",
-            "shib_application_id_field" => "HTTP_SHIB_APPLICATION_ID",
-            "uid_field"                 => 'HTTP_EPPN',
-            "name_field"                => 'HTTP_CN',
-            "info_fields" => { "email" => 'HTTP_MAIL'}
-        }
-      }
-    ]
-
-    ```
+   ```
+   external_url 'https://gitlab.example.com'
+   gitlab_rails['internal_api_url'] = 'https://gitlab.example.com'
+
+   # disable Nginx
+   nginx['enable'] = false
+
+   gitlab_rails['omniauth_allow_single_sign_on'] = true
+   gitlab_rails['omniauth_block_auto_created_users'] = false
+   gitlab_rails['omniauth_enabled'] = true
+   gitlab_rails['omniauth_providers'] = [
+     {
+       "name"  => "'shibboleth"',
+       "label" => "Text for Login Button",
+       "args"  => {
+           "shib_session_id_field"     => "HTTP_SHIB_SESSION_ID",
+           "shib_application_id_field" => "HTTP_SHIB_APPLICATION_ID",
+           "uid_field"                 => 'HTTP_EPPN',
+           "name_field"                => 'HTTP_CN',
+           "info_fields" => { "email" => 'HTTP_MAIL'}
+       }
+     }
+   ]
+
+   ```
 
 1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect if you
    installed GitLab via Omnibus or from source respectively.
@@ -97,44 +97,44 @@ The order of the first 2 Location directives is important. If they are reversed,
 you will not get a shibboleth session!
 
 ```
-  <Location />
-    Require all granted
-    ProxyPassReverse http://127.0.0.1:8181
-    ProxyPassReverse http://YOUR_SERVER_FQDN/
-  </Location>
-
-  <Location /users/auth/shibboleth/callback>
-    AuthType shibboleth
-    ShibRequestSetting requireSession 1
-    ShibUseHeaders On
-    Require shib-session
-  </Location>
-
-  Alias /shibboleth-sp /usr/share/shibboleth
-
-  <Location /shibboleth-sp>
-    Require all granted
-  </Location>
-
-  <Location /Shibboleth.sso>
-    SetHandler shib
-  </Location>
-
-  RewriteEngine on
-
-  #Don't escape encoded characters in api requests
-  RewriteCond %{REQUEST_URI} ^/api/v4/.*
-  RewriteCond %{REQUEST_URI} !/Shibboleth.sso
-  RewriteCond %{REQUEST_URI} !/shibboleth-sp
-  RewriteRule .* http://127.0.0.1:8181%{REQUEST_URI} [P,QSA,NE]
-
-  #Forward all requests to gitlab-workhorse except existing files
-  RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f [OR]
-  RewriteCond %{REQUEST_URI} ^/uploads/.*
-  RewriteCond %{REQUEST_URI} !/Shibboleth.sso
-  RewriteCond %{REQUEST_URI} !/shibboleth-sp
-  RewriteRule .* http://127.0.0.1:8181%{REQUEST_URI} [P,QSA]
-
-  RequestHeader set X_FORWARDED_PROTO 'https'
-  RequestHeader set X-Forwarded-Ssl on
+<Location />
+  Require all granted
+  ProxyPassReverse http://127.0.0.1:8181
+  ProxyPassReverse http://YOUR_SERVER_FQDN/
+</Location>
+
+<Location /users/auth/shibboleth/callback>
+  AuthType shibboleth
+  ShibRequestSetting requireSession 1
+  ShibUseHeaders On
+  Require shib-session
+</Location>
+
+Alias /shibboleth-sp /usr/share/shibboleth
+
+<Location /shibboleth-sp>
+  Require all granted
+</Location>
+
+<Location /Shibboleth.sso>
+  SetHandler shib
+</Location>
+
+RewriteEngine on
+
+#Don't escape encoded characters in api requests
+RewriteCond %{REQUEST_URI} ^/api/v4/.*
+RewriteCond %{REQUEST_URI} !/Shibboleth.sso
+RewriteCond %{REQUEST_URI} !/shibboleth-sp
+RewriteRule .* http://127.0.0.1:8181%{REQUEST_URI} [P,QSA,NE]
+
+#Forward all requests to gitlab-workhorse except existing files
+RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f [OR]
+RewriteCond %{REQUEST_URI} ^/uploads/.*
+RewriteCond %{REQUEST_URI} !/Shibboleth.sso
+RewriteCond %{REQUEST_URI} !/shibboleth-sp
+RewriteRule .* http://127.0.0.1:8181%{REQUEST_URI} [P,QSA]
+
+RequestHeader set X_FORWARDED_PROTO 'https'
+RequestHeader set X-Forwarded-Ssl on
 ```
diff --git a/doc/integration/slack.md b/doc/integration/slack.md
index f84ab769218..9fcf2c2d99a 100644
--- a/doc/integration/slack.md
+++ b/doc/integration/slack.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: '../project_services/slack.md'
+redirect_to: '../user/project/integrations/slack.md'
 ---
 
-This document was moved to [project_services/slack.md](../project_services/slack.md).
+This document was moved to [project_services/slack.md](../user/project/integrations/slack.md).
diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md
index 1cbfd81dfa9..d8096993885 100644
--- a/doc/integration/twitter.md
+++ b/doc/integration/twitter.md
@@ -2,80 +2,81 @@
 
 To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter will generate a client ID and secret key for you to use.
 
-1.  Sign in to [Twitter Application Management](https://apps.twitter.com/).
+1. Sign in to [Twitter Application Management](https://developer.twitter.com/apps).
 
-1.  Select "Create new app"
+1. Select "Create new app"
 
-1.  Fill in the application details.
-    - Name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or
-    something else descriptive.
-    - Description: Create a description.
-    - Website: The URL to your GitLab installation. `https://gitlab.example.com`
-    - Callback URL: `https://gitlab.example.com/users/auth/twitter/callback`
-    - Agree to the "Developer Agreement".
+1. Fill in the application details.
+   - Name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or
+   something else descriptive.
+   - Description: Create a description.
+   - Website: The URL to your GitLab installation. `https://gitlab.example.com`
+   - Callback URL: `https://gitlab.example.com/users/auth/twitter/callback`
+   - Agree to the "Developer Agreement".
 
-    ![Twitter App Details](img/twitter_app_details.png)
-1.  Select "Create your Twitter application."
+   ![Twitter App Details](img/twitter_app_details.png)
 
-1.  Select the "Settings" tab.
+1. Select "Create your Twitter application."
 
-1.  Underneath the Callback URL check the box next to "Allow this application to be used to Sign in with Twitter."
+1. Select the "Settings" tab.
 
-1.  Select "Update settings" at the bottom to save changes.
+1. Underneath the Callback URL check the box next to "Allow this application to be used to Sign in with Twitter."
 
-1.  Select the "Keys and Access Tokens" tab.
+1. Select "Update settings" at the bottom to save changes.
 
-1.  You should now see an API key and API secret (see screenshot). Keep this page open as you continue configuration.
+1. Select the "Keys and Access Tokens" tab.
 
-    ![Twitter app](img/twitter_app_api_keys.png)
+1. You should now see an API key and API secret (see screenshot). Keep this page open as you continue configuration.
 
-1.  On your GitLab server, open the configuration file.
+   ![Twitter app](img/twitter_app_api_keys.png)
 
-    For omnibus package:
+1. On your GitLab server, open the configuration file.
 
-    ```sh
-      sudo editor /etc/gitlab/gitlab.rb
-    ```
+   For omnibus package:
 
-    For installations from source:
+   ```sh
+     sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    ```sh
-      cd /home/git/gitlab
+   For installations from source:
 
-      sudo -u git -H editor config/gitlab.yml
-    ```
+   ```sh
+     cd /home/git/gitlab
 
-1.  See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+     sudo -u git -H editor config/gitlab.yml
+   ```
 
-1.  Add the provider configuration:
+1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
 
-    For omnibus package:
+1. Add the provider configuration:
 
-    ```ruby
-      gitlab_rails['omniauth_providers'] = [
-        {
-          "name" => "twitter",
-          "app_id" => "YOUR_APP_ID",
-          "app_secret" => "YOUR_APP_SECRET"
-        }
-      ]
-    ```
+   For omnibus package:
 
-    For installations from source:
+   ```ruby
+     gitlab_rails['omniauth_providers'] = [
+       {
+         "name" => "twitter",
+         "app_id" => "YOUR_APP_ID",
+         "app_secret" => "YOUR_APP_SECRET"
+       }
+     ]
+   ```
 
-    ```
-      - { name: 'twitter', app_id: 'YOUR_APP_ID',
-        app_secret: 'YOUR_APP_SECRET' }
-    ```
+   For installations from source:
 
-1.  Change 'YOUR_APP_ID' to the API key from Twitter page in step 11.
+   ```
+     - { name: 'twitter', app_id: 'YOUR_APP_ID',
+       app_secret: 'YOUR_APP_SECRET' }
+   ```
 
-1.  Change 'YOUR_APP_SECRET' to the API secret from the Twitter page in step 11.
+1. Change 'YOUR_APP_ID' to the API key from Twitter page in step 11.
 
-1.  Save the configuration file.
+1. Change 'YOUR_APP_SECRET' to the API secret from the Twitter page in step 11.
 
-1.  [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
-    installed GitLab via Omnibus or from source respectively.
+1. Save the configuration file.
+
+1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
+   installed GitLab via Omnibus or from source respectively.
 
 On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in.
 
diff --git a/doc/integration/ultra_auth.md b/doc/integration/ultra_auth.md
index 139cca456aa..9ed1bdb4882 100644
--- a/doc/integration/ultra_auth.md
+++ b/doc/integration/ultra_auth.md
@@ -7,72 +7,81 @@ You can integrate your GitLab instance with [UltraAuth](https://ultraauth.com) t
 To enable UltraAuth OmniAuth provider, you must use UltraAuth's credentials for your GitLab instance.
 To get the credentials (a pair of Client ID and Client Secret), you must register an application on UltraAuth.
 
-1.  Sign in to [UltraAuth](https://ultraauth.com).
-1.  Navigate to [Create an App](https://ultraauth.com/select-strategy) and click on "Ruby on Rails".
-1.  Scroll down the page that is displayed to locate the **Client ID** and **Client Secret**.
-    Keep this page open as you continue configuration.
-    ![UltraAuth Credentials: OPENID_CLIENT_ID and OPENID_CLIENT_SECRET](img/ultra_auth_credentials.png)
-1.  Click on "Edit Callback URL" link.
-    ![Edit UltraAuth Callback URL](img/ultra_auth_edit_callback_url_highlighted.png)
-1.  The callback URL will be `http(s)://<your_domain>/users/auth/ultraauth/callback`
-    ![UltraAuth Callback URL](img/ultra_auth_edit_callback_url.png)
-1.  Select **Register application**.
-1.  On your GitLab server, open the configuration file.
-
-    For omnibus package:
-
-    ```sh
-      sudo editor /etc/gitlab/gitlab.rb
-    ```
-
-    For installations from source:
-
-    ```sh
-      cd /home/git/gitlab
-      sudo -u git -H editor config/gitlab.yml
-    ```
-1.  See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
-1.  Add the provider configuration:
-
-    For omnibus package:
-
-    ```ruby
-      gitlab_rails['omniauth_providers'] = [
-        {
-          "name" => "ultraauth",
-          "app_id" => "OPENID_CLIENT_ID",
-          "app_secret" => "OPENID_CLIENT_SECRET",
-          "args" => {
-            "client_options" => {
-              "redirect_uri" => "https://example.com/users/auth/ultraauth/callback"
-            }
-          }
-        }
-      ]
-    ```
-
-    For installation from source:
-
-    ```
-      - { name: 'ultraauth',
-          app_id: 'OPENID_CLIENT_ID',
-          app_secret: 'OPENID_CLIENT_SECRET',
-          args: {
-            client_options: {
-              redirect_uri: 'https://example.com/users/auth/ultraauth/callback'
-            }
-          }
-        }
-    ```
-    __Replace `https://example.com/users/auth/ultraauth/callback` with your application's Callback URL.__
-1.  Change `OPENID_CLIENT_ID` to the Client ID from the UltraAuth application page.
-1.  Change `OPENID_CLIENT_SECRET` to the Client Secret from the UltraAuth application page.
-1.  Save the configuration file.
-1.  [Reconfigure GitLab]( ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure ) or [restart GitLab]( ../administration/restart_gitlab.md#installations-from-source ) for the changes to take effect if you
-    installed GitLab via Omnibus or from source respectively.
-
-On the sign in page, there should now be a UltraAuth icon below the regular sign in form.
+1. Sign in to [UltraAuth](https://ultraauth.com).
+1. Navigate to [Create an App](https://ultraauth.com/select-strategy) and click on "Ruby on Rails".
+1. Scroll down the page that is displayed to locate the **Client ID** and **Client Secret**.
+   Keep this page open as you continue configuration.
+
+   ![UltraAuth Credentials: OPENID_CLIENT_ID and OPENID_CLIENT_SECRET](img/ultra_auth_credentials.png)
+
+1. Click on "Edit Callback URL" link.
+
+   ![Edit UltraAuth Callback URL](img/ultra_auth_edit_callback_url_highlighted.png)
+
+1. The callback URL will be `http(s)://<your_domain>/users/auth/ultraauth/callback`
+
+   ![UltraAuth Callback URL](img/ultra_auth_edit_callback_url.png)
+
+1. Select **Register application**.
+1. On your GitLab server, open the configuration file.
+
+   For omnibus package:
+
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
+
+   For installations from source:
+
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H editor config/gitlab.yml
+   ```
+
+1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. Add the provider configuration:
+
+   For omnibus package:
+
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       "name" => "ultraauth",
+       "app_id" => "OPENID_CLIENT_ID",
+       "app_secret" => "OPENID_CLIENT_SECRET",
+       "args" => {
+         "client_options" => {
+           "redirect_uri" => "https://example.com/users/auth/ultraauth/callback"
+         }
+       }
+     }
+   ]
+   ```
+
+   For installation from source:
+
+   ```
+   - { name: 'ultraauth',
+       app_id: 'OPENID_CLIENT_ID',
+       app_secret: 'OPENID_CLIENT_SECRET',
+       args: {
+         client_options: {
+           redirect_uri: 'https://example.com/users/auth/ultraauth/callback'
+         }
+       }
+     }
+   ```
+
+   __Replace `https://example.com/users/auth/ultraauth/callback` with your application's Callback URL.__
+
+1. Change `OPENID_CLIENT_ID` to the Client ID from the UltraAuth application page.
+1. Change `OPENID_CLIENT_SECRET` to the Client Secret from the UltraAuth application page.
+1. Save the configuration file.
+1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you
+   installed GitLab via Omnibus or from source respectively.
+
+On the sign in page, there should now be an UltraAuth icon below the regular sign in form.
 Click the icon to begin the authentication process. UltraAuth will ask the user to sign in and authorize the GitLab application.
 If everything goes well, the user will be returned to GitLab and will be signed in.
 
-**Note:** GitLab requires the email address of each new user. Once the user is logged in using UltraAuth, GitLab will redirect the user to the profile page where they will have to provide the email and verify the email.
+GitLab requires the email address of each new user. Once the user is logged in using UltraAuth, GitLab will redirect the user to the profile page where they will have to provide the email and verify the email. Password authentication will be disabled for UltraAuth users and two-factor authentication (2FA) will be enforced.
diff --git a/doc/intro/README.md b/doc/intro/README.md
index 9bc7c3d9ea4..33b23372280 100644
--- a/doc/intro/README.md
+++ b/doc/intro/README.md
@@ -15,7 +15,7 @@ Create projects and groups.
 
 Create issues, labels, milestones, cast your vote, and review issues.
 
-- [Create an issue](../user/project/issues/create_new_issue.md)
+- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue)
 - [Assign labels to issues](../user/project/labels.md)
 - [Use milestones as an overview of your project's tracker](../user/project/milestones/index.md)
 - [Use voting to express your like/dislike to issues and merge requests](../workflow/award_emoji.md)
@@ -26,7 +26,7 @@ Create merge requests and review code.
 
 - [Fork a project and contribute to it](../workflow/forking_workflow.md)
 - [Create a new merge request](../gitlab-basics/add-merge-request.md)
-- [Automatically close issues from merge requests](../user/project/issues/automatic_issue_closing.md)
+- [Automatically close issues from merge requests](../user/project/issues/managing_issues.md#closing-issues-automatically)
 - [Automatically merge when pipeline succeeds](../user/project/merge_requests/merge_when_pipeline_succeeds.md)
 - [Revert any commit](../user/project/merge_requests/revert_changes.md)
 - [Cherry-pick any commit](../user/project/merge_requests/cherry_pick_changes.md)
@@ -41,6 +41,6 @@ Use the built-in continuous integration in GitLab.
 
 Install and update your GitLab installation.
 
-- [Install GitLab](https://about.gitlab.com/installation/)
+- [Install GitLab](https://about.gitlab.com/install/)
 - [Update GitLab](https://about.gitlab.com/update/)
-- [Explore Omnibus GitLab configuration options](http://docs.gitlab.com/omnibus/settings/configuration.html)
+- [Explore Omnibus GitLab configuration options](https://docs.gitlab.com/omnibus/settings/configuration.html)
diff --git a/doc/legal/corporate_contributor_license_agreement.md b/doc/legal/corporate_contributor_license_agreement.md
index 7f08188bd65..8c1f4a126b1 100644
--- a/doc/legal/corporate_contributor_license_agreement.md
+++ b/doc/legal/corporate_contributor_license_agreement.md
@@ -2,28 +2,28 @@
 
 You accept and agree to the following terms and conditions for Your present and future Contributions submitted to GitLab B.V.. Except for the license granted herein to GitLab B.V. and recipients of software distributed by GitLab B.V., You reserve all right, title, and interest in and to Your Contributions.
 
-1.  Definitions.
+- **Definitions:**
 
-	"You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Agreement with GitLab B.V.. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+  "You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Agreement with GitLab B.V.. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
 
-	"Contribution" shall mean the code, documentation or other original works of authorship, including any modifications or additions to an existing work, that is submitted by You to GitLab B.V. for inclusion in, or documentation of, any of the products owned or managed by GitLab B.V. (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to GitLab B.V. or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, GitLab B.V. for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
+  "Contribution" shall mean the code, documentation or other original works of authorship, including any modifications or additions to an existing work, that is submitted by You to GitLab B.V. for inclusion in, or documentation of, any of the products owned or managed by GitLab B.V. (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to GitLab B.V. or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, GitLab B.V. for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
 
-2.  Grant of Copyright License.
+- **Grant of Copyright License:**
 
-Subject to the terms and conditions of this Agreement, You hereby grant to GitLab B.V. and to recipients of software distributed by GitLab B.V. a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works.
+  Subject to the terms and conditions of this Agreement, You hereby grant to GitLab B.V. and to recipients of software distributed by GitLab B.V. a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works.
 
-3.  Grant of Patent License.
+- **Grant of Patent License:**
 
-Subject to the terms and conditions of this Agreement, You hereby grant to GitLab B.V. and to recipients of software distributed by GitLab B.V. a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed.
+  Subject to the terms and conditions of this Agreement, You hereby grant to GitLab B.V. and to recipients of software distributed by GitLab B.V. a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed.
 
-4.  You represent that You are legally entitled to grant the above license. You represent further that each of Your employees is authorized to submit Contributions on Your behalf, but excluding employees that are designated in writing by You as "Not authorized to submit Contributions on behalf of [name of Your corporation here]." Such designations of exclusion for unauthorized employees are to be submitted via email to legal@gitlab.com.
+  You represent that You are legally entitled to grant the above license. You represent further that each of Your employees is authorized to submit Contributions on Your behalf, but excluding employees that are designated in writing by You as "Not authorized to submit Contributions on behalf of (name of Your corporation here)." Such designations of exclusion for unauthorized employees are to be submitted via email to legal@gitlab.com. It is Your responsibility to notify GitLab B.V. when any change is required to the list of designated employees excluded from submitting Contributions on Your behalf. Such notification should also be sent via email to legal@gitlab.com.
 
-5.  You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others).
+- **Contributions:**
 
-6.  You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+  You represent that each of Your Contributions is Your original creation.
+  
+  Should You wish to submit work that is not Your original creation, You may submit it to GitLab B.V. separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which you are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: (named here)".
 
-7.  Should You wish to submit work that is not Your original creation, You may submit it to GitLab B.V. separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which you are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [named here]".
-
-8.  It is Your responsibility to notify GitLab.com when any change is required to the list of designated employees excluded from submitting Contributions on Your behalf per Section 4. Such notification should be sent via email to legal@gitlab.com.
+  You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
 
 This text is licensed under the [Creative Commons Attribution 3.0 License](https://creativecommons.org/licenses/by/3.0/) and the original source is the Google Open Source Programs Office.
diff --git a/doc/legal/individual_contributor_license_agreement.md b/doc/legal/individual_contributor_license_agreement.md
index 59803aea080..7a071414629 100644
--- a/doc/legal/individual_contributor_license_agreement.md
+++ b/doc/legal/individual_contributor_license_agreement.md
@@ -2,24 +2,30 @@
 
 You accept and agree to the following terms and conditions for Your present and future Contributions submitted to GitLab B.V.. Except for the license granted herein to GitLab B.V. and recipients of software distributed by GitLab B.V., You reserve all right, title, and interest in and to Your Contributions.
 
-1.  Definitions.
+- **Definitions:**
 
-	"You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Agreement with GitLab B.V.. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+  "You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Agreement with GitLab B.V.. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
 
-	"Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to GitLab B.V. for inclusion in, or documentation of, any of the products owned or managed by GitLab B.V. (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to GitLab B.V. or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, GitLab B.V. for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
+  "Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to GitLab B.V. for inclusion in, or documentation of, any of the products owned or managed by GitLab B.V. (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to GitLab B.V. or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, GitLab B.V. for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
 
-2.  Grant of Copyright License. Subject to the terms and conditions of this Agreement, You hereby grant to GitLab B.V. and to recipients of software distributed by GitLab B.V. a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works.
+- **Grant of Copyright License:**
 
-3.  Grant of Patent License. Subject to the terms and conditions of this Agreement, You hereby grant to GitLab B.V. and to recipients of software distributed by GitLab B.V. a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed.
+  Subject to the terms and conditions of this Agreement, You hereby grant to GitLab B.V. and to recipients of software distributed by GitLab B.V. a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works.
 
-4.  You represent that you are legally entitled to grant the above license. If your employer(s) has rights to intellectual property that you create that includes your Contributions, you represent that you have received permission to make Contributions on behalf of that employer, that your employer has waived such rights for your Contributions to GitLab B.V., or that your employer has executed a separate Corporate CLA with GitLab B.V..
+- **Grant of Patent License:**
 
-5.  You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others). You represent that Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which you are personally aware and which are associated with any part of Your Contributions.
+  Subject to the terms and conditions of this Agreement, You hereby grant to GitLab B.V. and to recipients of software distributed by GitLab B.V. a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed.
 
-6.  You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON- INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+  You represent that you are legally entitled to grant the above license. If your employer(s) has rights to intellectual property that you create that includes your Contributions, you represent that you have received permission to make Contributions on behalf of that employer, that your employer has waived such rights for your Contributions to GitLab B.V., or that your employer has executed a separate Corporate CLA with GitLab B.V..
 
-7.  Should You wish to submit work that is not Your original creation, You may submit it to GitLab B.V. separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which you are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [insert_name_here]".
+- **Contributions:**
 
-8.  You agree to notify GitLab B.V. of any facts or circumstances of which you become aware that would make these representations inaccurate in any respect.
+  You represent that each of Your Contributions is Your original creation. You represent that Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which you are personally aware and which are associated with any part of Your Contributions.
+
+  Should You wish to submit work that is not Your original creation, You may submit it to GitLab B.V. separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which you are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: (insert_name_here)".
+
+  You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON- INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+You agree to notify GitLab B.V. of any facts or circumstances of which you become aware that would make these representations inaccurate in any respect.
 
 This text is licensed under the [Creative Commons Attribution 3.0 License](https://creativecommons.org/licenses/by/3.0/) and the original source is the Google Open Source Programs Office.
diff --git a/doc/migrate_ci_to_ce/README.md b/doc/migrate_ci_to_ce/README.md
index 7659b743311..9947c19a667 100644
--- a/doc/migrate_ci_to_ce/README.md
+++ b/doc/migrate_ci_to_ce/README.md
@@ -67,7 +67,7 @@ Also check on your GitLab server.
 ```
 # On your GitLab server:
 # Omnibus
-sudo gitlab-rake gitlab:backup:create SKIP=repositories,uploads
+sudo gitlab-backup create SKIP=repositories,uploads
 
 # Source
 cd /home/git/gitlab
@@ -181,7 +181,7 @@ sudo -u gitlab_ci -H bundle exec rake backup:show_secrets RAILS_ENV=production
 ### 2. SQL data and build traces
 
 Create your final CI data export. If you are converting from MySQL to
-  PostgreSQL, add ` MYSQL_TO_POSTGRESQL=1` to the end of the rake command. When
+PostgreSQL, add `MYSQL_TO_POSTGRESQL=1` to the end of the rake command. When
 the command finishes it will print the path to your data export archive; you
 will need this file later.
 
@@ -323,11 +323,15 @@ You should also make sure that you can:
 
 ### 2. Check Nginx configuration
 
-    sudo nginx -t
+```sh
+sudo nginx -t
+```
 
 ### 3. Restart Nginx
 
-    sudo /etc/init.d/nginx restart
+```sh
+sudo /etc/init.d/nginx restart
+```
 
 ### Restore from backup
 
@@ -352,11 +356,13 @@ The fix for this is to update to Omnibus 7.14 first and then update it to 8.0.
 ### Permission denied when accessing /var/opt/gitlab/gitlab-ci/builds
 
 To fix that issue you have to change builds/ folder permission before doing final backup:
+
 ```
 sudo chown -R gitlab-ci:gitlab-ci /var/opt/gitlab/gitlab-ci/builds
 ```
 
 Then before executing `ci:migrate` you need to fix builds folder permission:
+
 ```
 sudo chown git:git /var/opt/gitlab/gitlab-ci/builds
 ```
@@ -365,7 +371,7 @@ sudo chown git:git /var/opt/gitlab/gitlab-ci/builds
 
 If you were migrating CI database from MySQL to PostgreSQL manually you can see errors during import about missing sequences:
 
-```sql 
+```sql
 ALTER SEQUENCE
 ERROR:  relation "ci_builds_id_seq" does not exist
 ERROR:  relation "ci_commits_id_seq" does not exist
diff --git a/doc/pages/getting_started_part_three.md b/doc/pages/getting_started_part_three.md
index b65247ff7b7..31a01a6c83b 100644
--- a/doc/pages/getting_started_part_three.md
+++ b/doc/pages/getting_started_part_three.md
@@ -1,5 +1,5 @@
 ---
-redirect_to: '../user/project/pages/getting_started_part_three.md'
+redirect_to: '../user/project/pages/custom_domains_ssl_tls_certification/index.md'
 ---
 
-This document was moved to [another location](../user/project/pages/getting_started_part_three.md).
+This document was moved to [another location](../user/project/pages/custom_domains_ssl_tls_certification/index.md).
diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md
index 72bace3d282..018c273c51a 100644
--- a/doc/policy/maintenance.md
+++ b/doc/policy/maintenance.md
@@ -9,7 +9,7 @@ patch and security releases. New releases are usually announced on the [GitLab b
 
 ## Versioning
 
-GitLab uses [Semantic Versioning](http://semver.org/) for its releases:
+GitLab uses [Semantic Versioning](https://semver.org/) for its releases:
 `(Major).(Minor).(Patch)` in a [pragmatic way](https://gist.github.com/jashkenas/cbd2b088e20279ae2c8e).
 
 For example, for GitLab version 10.5.7:
diff --git a/doc/public_access/public_access.md b/doc/public_access/public_access.md
index b1637181855..0142e5075cc 100644
--- a/doc/public_access/public_access.md
+++ b/doc/public_access/public_access.md
@@ -12,7 +12,7 @@ public access directory (`/public` under your GitLab instance), like at [https:/
 
 ### Public projects
 
-Public projects can be cloned **without any** authentication.
+Public projects can be cloned **without any** authentication over https.
 
 They will be listed in the public access directory (`/public`) for all users.
 
@@ -29,9 +29,15 @@ in users.
 Any logged in user will have [Guest permissions](../user/permissions.md)
 on the repository.
 
+NOTE: **Note:**
+From July 2019, the `Internal` visibility setting is disabled for new projects, groups,
+and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal`
+visibility setting keep this setting. You can read more about the change in the
+[relevant issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/12388).
+
 ### Private projects
 
-Private projects can only be cloned and viewed by project members.
+Private projects can only be cloned and viewed by project members (except for guests).
 
 They will appear in the public access directory (`/public`) for project members only.
 
diff --git a/doc/push_rules/push_rules.md b/doc/push_rules/push_rules.md
index b2d626a0a74..b1754131e76 100644
--- a/doc/push_rules/push_rules.md
+++ b/doc/push_rules/push_rules.md
@@ -2,7 +2,7 @@
 type: reference, howto
 ---
 
-# Push Rules **[STARTER]**
+# Push Rules **(STARTER)**
 
 Gain additional control over what can and can't be pushed to your repository by using
 regular expressions to reject pushes based on commit contents, branch names or file details.
@@ -26,11 +26,11 @@ Every push rule could have its own use case, but let's consider some examples.
 
 Let's assume you have the following requirements for your workflow:
 
-- every commit should reference a JIRA issue, for example: `Refactored css. Fixes JIRA-123.`
+- every commit should reference a Jira issue, for example: `Refactored css. Fixes JIRA-123.`
 - users should not be able to remove git tags with `git push`
 
 All you need to do is write a simple regular expression that requires the mention
-of a JIRA issue in the commit message, like `JIRA\-\d+`.
+of a Jira issue in the commit message, like `JIRA\-\d+`.
 
 Now when a user tries to push a commit with a message `Bugfix`, their push will
 be declined. Only pushing commits with messages like `Bugfix according to JIRA-123`
diff --git a/doc/raketasks/README.md b/doc/raketasks/README.md
index 0729875daf8..dcc96507676 100644
--- a/doc/raketasks/README.md
+++ b/doc/raketasks/README.md
@@ -9,10 +9,10 @@ comments: false
 - [Cleanup](cleanup.md)
 - [Features](features.md)
 - [LDAP Maintenance](../administration/raketasks/ldap.md)
-- [General Maintenance](maintenance.md) and self-checks
+- [General Maintenance](../administration/raketasks/maintenance.md) and self-checks
 - [User management](user_management.md)
 - [Webhooks](web_hooks.md)
 - [Import](import.md) of git repositories in bulk
-- [Rebuild authorized_keys file](http://docs.gitlab.com/ce/raketasks/maintenance.html#rebuild-authorized_keys-file) task for administrators
+- [Rebuild authorized_keys file](../administration/raketasks/maintenance.md#rebuild-authorized_keys-file) task for administrators
 - [Migrate Uploads](../administration/raketasks/uploads/migrate.md)
 - [Sanitize Uploads](../administration/raketasks/uploads/sanitize.md)
diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md
index 764916ca82d..51f04df27c7 100644
--- a/doc/raketasks/backup_restore.md
+++ b/doc/raketasks/backup_restore.md
@@ -18,16 +18,16 @@ installed on your system.
 
 If you installed GitLab:
 
--   Using the Omnibus package, you're all set.
--   From source, make sure `rsync` is installed:
+- Using the Omnibus package, you're all set.
+- From source, make sure `rsync` is installed:
 
-    ```sh
-    # Debian/Ubuntu
-    sudo apt-get install rsync
+  ```sh
+  # Debian/Ubuntu
+  sudo apt-get install rsync
 
-    # RHEL/CentOS
-    sudo yum install rsync
-    ```
+  # RHEL/CentOS
+  sudo yum install rsync
+  ```
 
 ### Tar
 
@@ -77,7 +77,7 @@ You are highly advised to [read about storing configuration files](#storing-conf
 Use this command if you've installed GitLab with the Omnibus package:
 
 ```sh
-sudo gitlab-rake gitlab:backup:create
+sudo gitlab-backup create
 ```
 
 Use this if you've installed GitLab from source:
@@ -89,7 +89,7 @@ sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 If you are running GitLab within a Docker container, you can run the backup from the host:
 
 ```sh
-docker exec -t <container name> gitlab-rake gitlab:backup:create
+docker exec -t <container name> gitlab-backup create
 ```
 
 If you are using the [GitLab helm chart](https://gitlab.com/charts/gitlab) on a
@@ -199,7 +199,7 @@ To use the `copy` strategy instead of the default streaming strategy, specify
 `STRATEGY=copy` in the Rake task command. For example:
 
 ```sh
-sudo gitlab-rake gitlab:backup:create STRATEGY=copy
+sudo gitlab-backup create STRATEGY=copy
 ```
 
 ### Backup filename
@@ -207,7 +207,7 @@ sudo gitlab-rake gitlab:backup:create STRATEGY=copy
 By default a backup file is created according to the specification in [the Backup timestamp](#backup-timestamp) section above. You can however override the `[TIMESTAMP]` part of the filename by setting the `BACKUP` environment variable. For example:
 
 ```sh
-sudo gitlab-rake gitlab:backup:create BACKUP=dump
+sudo gitlab-backup create BACKUP=dump
 ```
 
 The resulting file will then be `dump_gitlab_backup.tar`. This is useful for systems that make use of rsync and incremental backups, and will result in considerably faster transfer speeds.
@@ -219,7 +219,7 @@ To make sure the generated archive is intelligently transferable by rsync, the `
 Note that the `--rsyncable` option in `gzip` is not guaranteed to be available on all distributions. To verify that it is available in your distribution you can run `gzip --help` or consult the man pages.
 
 ```sh
-sudo gitlab-rake gitlab:backup:create BACKUP=dump GZIP_RSYNCABLE=yes
+sudo gitlab-backup create BACKUP=dump GZIP_RSYNCABLE=yes
 ```
 
 ### Excluding specific directories from the backup
@@ -244,7 +244,7 @@ will be skipped during a backup.
 For Omnibus GitLab packages:
 
 ```sh
-sudo gitlab-rake gitlab:backup:create SKIP=db,uploads
+sudo gitlab-backup create SKIP=db,uploads
 ```
 
 For installations from source:
@@ -269,17 +269,17 @@ For Omnibus GitLab packages:
 
 1. Add the following to `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['backup_upload_connection'] = {
-      'provider' => 'AWS',
-      'region' => 'eu-west-1',
-      'aws_access_key_id' => 'AKIAKIAKI',
-      'aws_secret_access_key' => 'secret123'
-      # If using an IAM Profile, don't configure aws_access_key_id & aws_secret_access_key
-      # 'use_iam_profile' => true
-    }
-    gitlab_rails['backup_upload_remote_directory'] = 'my.s3.bucket'
-    ```
+   ```ruby
+   gitlab_rails['backup_upload_connection'] = {
+     'provider' => 'AWS',
+     'region' => 'eu-west-1',
+     'aws_access_key_id' => 'AKIAKIAKI',
+     'aws_secret_access_key' => 'secret123'
+     # If using an IAM Profile, don't configure aws_access_key_id & aws_secret_access_key
+     # 'use_iam_profile' => true
+   }
+   gitlab_rails['backup_upload_remote_directory'] = 'my.s3.bucket'
+   ```
 
 1. [Reconfigure GitLab] for the changes to take effect
 
@@ -289,16 +289,16 @@ This example can be used for a bucket in Amsterdam (AMS3).
 
 1. Add the following to `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['backup_upload_connection'] = {
-      'provider' => 'AWS',
-      'region' => 'ams3',
-      'aws_access_key_id' => 'AKIAKIAKI',
-      'aws_secret_access_key' => 'secret123',
-      'endpoint'              => 'https://ams3.digitaloceanspaces.com'
-    }
-    gitlab_rails['backup_upload_remote_directory'] = 'my.s3.bucket'
-    ```
+   ```ruby
+   gitlab_rails['backup_upload_connection'] = {
+     'provider' => 'AWS',
+     'region' => 'ams3',
+     'aws_access_key_id' => 'AKIAKIAKI',
+     'aws_secret_access_key' => 'secret123',
+     'endpoint'              => 'https://ams3.digitaloceanspaces.com'
+   }
+   gitlab_rails['backup_upload_remote_directory'] = 'my.s3.bucket'
+   ```
 
 1. [Reconfigure GitLab] for the changes to take effect
 
@@ -315,37 +315,35 @@ if you see `411 Length Required` errors after attempting to upload, you may
 need to downgrade the `aws_signature_version` value from the default value to
 2 [due to this issue](https://github.com/fog/fog-aws/issues/428).
 
----
-
 For installations from source:
 
 1. Edit `home/git/gitlab/config/gitlab.yml`:
 
-    ```yaml
-      backup:
-        # snip
-        upload:
-          # Fog storage connection settings, see http://fog.io/storage/ .
-          connection:
-            provider: AWS
-            region: eu-west-1
-            aws_access_key_id: AKIAKIAKI
-            aws_secret_access_key: 'secret123'
-            # If using an IAM Profile, leave aws_access_key_id & aws_secret_access_key empty
-            # ie. aws_access_key_id: ''
-            # use_iam_profile: 'true'
-          # The remote 'directory' to store your backups. For S3, this would be the bucket name.
-          remote_directory: 'my.s3.bucket'
-          # Turns on AWS Server-Side Encryption with Amazon S3-Managed Keys for backups, this is optional
-          # encryption: 'AES256'
-          # Turns on AWS Server-Side Encryption with Amazon Customer-Provided Encryption Keys for backups, this is optional
-          #   This should be set to the base64-encoded encryption key for Amazon S3 to use to encrypt or decrypt your data.
-          #   'encryption' must also be set in order for this to have any effect.
-          #   To avoid storing the key on disk, the key can also be specified via the `GITLAB_BACKUP_ENCRYPTION_KEY` environment variable.
-          # encryption_key: '<base64 key>'
-          # Specifies Amazon S3 storage class to use for backups, this is optional
-          # storage_class: 'STANDARD'
-    ```
+   ```yaml
+     backup:
+       # snip
+       upload:
+         # Fog storage connection settings, see http://fog.io/storage/ .
+         connection:
+           provider: AWS
+           region: eu-west-1
+           aws_access_key_id: AKIAKIAKI
+           aws_secret_access_key: 'secret123'
+           # If using an IAM Profile, leave aws_access_key_id & aws_secret_access_key empty
+           # ie. aws_access_key_id: ''
+           # use_iam_profile: 'true'
+         # The remote 'directory' to store your backups. For S3, this would be the bucket name.
+         remote_directory: 'my.s3.bucket'
+         # Turns on AWS Server-Side Encryption with Amazon S3-Managed Keys for backups, this is optional
+         # encryption: 'AES256'
+         # Turns on AWS Server-Side Encryption with Amazon Customer-Provided Encryption Keys for backups, this is optional
+         #   This should be set to the base64-encoded encryption key for Amazon S3 to use to encrypt or decrypt your data.
+         #   'encryption' must also be set in order for this to have any effect.
+         #   To avoid storing the key on disk, the key can also be specified via the `GITLAB_BACKUP_ENCRYPTION_KEY` environment variable.
+         # encryption_key: '<base64 key>'
+         # Specifies Amazon S3 storage class to use for backups, this is optional
+         # storage_class: 'STANDARD'
+   ```
 
 1. [Restart GitLab] for the changes to take effect
 
@@ -417,32 +415,30 @@ For Omnibus GitLab packages:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['backup_upload_connection'] = {
-      'provider' => 'Google',
-      'google_storage_access_key_id' => 'Access Key',
-      'google_storage_secret_access_key' => 'Secret'
-    }
-    gitlab_rails['backup_upload_remote_directory'] = 'my.google.bucket'
-    ```
+   ```ruby
+   gitlab_rails['backup_upload_connection'] = {
+     'provider' => 'Google',
+     'google_storage_access_key_id' => 'Access Key',
+     'google_storage_secret_access_key' => 'Secret'
+   }
+   gitlab_rails['backup_upload_remote_directory'] = 'my.google.bucket'
+   ```
 
 1. [Reconfigure GitLab] for the changes to take effect
 
----
-
 For installations from source:
 
 1. Edit `home/git/gitlab/config/gitlab.yml`:
 
-    ```yaml
-      backup:
-        upload:
-          connection:
-            provider: 'Google'
-            google_storage_access_key_id: 'Access Key'
-            google_storage_secret_access_key: 'Secret'
-          remote_directory: 'my.google.bucket'
-    ```
+   ```yaml
+     backup:
+       upload:
+         connection:
+           provider: 'Google'
+           google_storage_access_key_id: 'Access Key'
+           google_storage_secret_access_key: 'Secret'
+         remote_directory: 'my.google.bucket'
+   ```
 
 1. [Restart GitLab] for the changes to take effect
 
@@ -452,8 +448,8 @@ Note: This option only works for remote storage. If you want to group your backu
 you can pass a `DIRECTORY` environment variable:
 
 ```
-sudo gitlab-rake gitlab:backup:create DIRECTORY=daily
-sudo gitlab-rake gitlab:backup:create DIRECTORY=weekly
+sudo gitlab-backup create DIRECTORY=daily
+sudo gitlab-backup create DIRECTORY=weekly
 ```
 
 ### Uploading to locally mounted shares
@@ -477,36 +473,34 @@ For Omnibus GitLab packages:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['backup_upload_connection'] = {
-      :provider => 'Local',
-      :local_root => '/mnt/backups'
-    }
+   ```ruby
+   gitlab_rails['backup_upload_connection'] = {
+     :provider => 'Local',
+     :local_root => '/mnt/backups'
+   }
 
-    # The directory inside the mounted folder to copy backups to
-    # Use '.' to store them in the root directory
-    gitlab_rails['backup_upload_remote_directory'] = 'gitlab_backups'
-    ```
+   # The directory inside the mounted folder to copy backups to
+   # Use '.' to store them in the root directory
+   gitlab_rails['backup_upload_remote_directory'] = 'gitlab_backups'
+   ```
 
 1. [Reconfigure GitLab] for the changes to take effect.
 
----
-
 For installations from source:
 
 1. Edit `home/git/gitlab/config/gitlab.yml`:
 
-    ```yaml
-    backup:
-      upload:
-        # Fog storage connection settings, see http://fog.io/storage/ .
-        connection:
-          provider: Local
-          local_root: '/mnt/backups'
-        # The directory inside the mounted folder to copy backups to
-        # Use '.' to store them in the root directory
-        remote_directory: 'gitlab_backups'
-    ```
+   ```yaml
+   backup:
+     upload:
+       # Fog storage connection settings, see http://fog.io/storage/ .
+       connection:
+         provider: Local
+         local_root: '/mnt/backups'
+       # The directory inside the mounted folder to copy backups to
+       # Use '.' to store them in the root directory
+       remote_directory: 'gitlab_backups'
+   ```
 
 1. [Restart GitLab] for the changes to take effect.
 
@@ -521,22 +515,20 @@ For Omnibus GitLab packages:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['backup_archive_permissions'] = 0644 # Makes the backup archives world-readable
-    ```
+   ```ruby
+   gitlab_rails['backup_archive_permissions'] = 0644 # Makes the backup archives world-readable
+   ```
 
 1. [Reconfigure GitLab] for the changes to take effect.
 
----
-
 For installations from source:
 
 1. Edit `/home/git/gitlab/config/gitlab.yml`:
 
-    ```yaml
-    backup:
-      archive_permissions: 0644 # Makes the backup archives world-readable
-    ```
+   ```yaml
+   backup:
+     archive_permissions: 0644 # Makes the backup archives world-readable
+   ```
 
 1. [Restart GitLab] for the changes to take effect.
 
@@ -550,10 +542,10 @@ For Omnibus GitLab packages:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    ## Limit backup lifetime to 7 days - 604800 seconds
-    gitlab_rails['backup_keep_time'] = 604800
-    ```
+   ```ruby
+   ## Limit backup lifetime to 7 days - 604800 seconds
+   gitlab_rails['backup_keep_time'] = 604800
+   ```
 
 1. [Reconfigure GitLab] for the changes to take effect.
 
@@ -574,23 +566,21 @@ crontab -e
 There, add the following line to schedule the backup for everyday at 2 AM:
 
 ```
-0 2 * * * /opt/gitlab/bin/gitlab-rake gitlab:backup:create CRON=1
+0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1
 ```
 
 You may also want to set a limited lifetime for backups to prevent regular
 backups using all your disk space.
 
----
-
 For installations from source:
 
 1. Edit `home/git/gitlab/config/gitlab.yml`:
 
-    ```yaml
-    backup:
-      ## Limit backup lifetime to 7 days - 604800 seconds
-      keep_time: 604800
-    ```
+   ```yaml
+   backup:
+     ## Limit backup lifetime to 7 days - 604800 seconds
+     keep_time: 604800
+   ```
 
 1. [Restart GitLab] for the changes to take effect.
 
@@ -736,14 +726,15 @@ restore:
 
 ```shell
 # This command will overwrite the contents of your GitLab database!
-sudo gitlab-rake gitlab:backup:restore BACKUP=1493107454_2018_04_25_10.6.4-ce
+sudo gitlab-backup restore BACKUP=1493107454_2018_04_25_10.6.4-ce
 ```
 
 Next, restore `/etc/gitlab/gitlab-secrets.json` if necessary as mentioned above.
 
-Restart and check GitLab:
+Reconfigure, restart and check GitLab:
 
 ```shell
+sudo gitlab-ctl reconfigure
 sudo gitlab-ctl restart
 sudo gitlab-rake gitlab:check SANITIZE=true
 ```
@@ -769,7 +760,7 @@ backup location (default location is `/var/opt/gitlab/backups`).
 For docker installations, the restore task can be run from host:
 
 ```sh
-docker exec -it <name of container> gitlab-rake gitlab:backup:restore
+docker exec -it <name of container> gitlab-backup restore
 ```
 
 The GitLab helm chart uses a different process, documented in
@@ -814,6 +805,7 @@ will have all your repositories, but not any other data.
 ## Troubleshooting
 
 ### Restoring database backup using omnibus packages outputs warnings
+
 If you are using backup restore procedures you might encounter the following warnings:
 
 ```
@@ -840,13 +832,13 @@ columns containing sensitive information. If the key is lost, GitLab will be
 unable to decrypt those columns. This will break a wide range of functionality,
 including (but not restricted to):
 
-* [CI/CD variables](../ci/variables/README.md)
-* [Kubernetes / GCP integration](../user/project/clusters/index.md)
-* [Custom Pages domains](../user/project/pages/getting_started_part_three.md)
-* [Project error tracking](../user/project/operations/error_tracking.md)
-* [Runner authentication](../ci/runners/README.md)
-* [Project mirroring](../workflow/repository_mirroring.md)
-* [Web hooks](../user/project/integrations/webhooks.md)
+- [CI/CD variables](../ci/variables/README.md)
+- [Kubernetes / GCP integration](../user/project/clusters/index.md)
+- [Custom Pages domains](../user/project/pages/custom_domains_ssl_tls_certification/index.md)
+- [Project error tracking](../user/project/operations/error_tracking.md)
+- [Runner authentication](../ci/runners/README.md)
+- [Project mirroring](../workflow/repository_mirroring.md)
+- [Web hooks](../user/project/integrations/webhooks.md)
 
 In cases like CI/CD variables and Runner authentication, you might
 experience some unexpected behavior such as:
@@ -865,76 +857,125 @@ backup beforehand.
 
 #### Reset CI/CD variables
 
-1.  Enter the DB console:
+1. Enter the DB console:
 
-    For Omnibus GitLab packages:
+   For Omnibus GitLab packages:
 
-    ```sh
-    sudo gitlab-rails dbconsole
-    ```
+   ```sh
+   sudo gitlab-rails dbconsole
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```sh
-    sudo -u git -H bundle exec rails dbconsole RAILS_ENV=production
-    ```
+   ```sh
+   sudo -u git -H bundle exec rails dbconsole RAILS_ENV=production
+   ```
 
-1.  Check the `ci_group_variables` and `ci_variables` tables:
+1. Check the `ci_group_variables` and `ci_variables` tables:
 
-    ```sql
-    SELECT * FROM public."ci_group_variables";
-    SELECT * FROM public."ci_variables";
-    ```
+   ```sql
+   SELECT * FROM public."ci_group_variables";
+   SELECT * FROM public."ci_variables";
+   ```
 
-    Those are the variables that you need to delete.
+   Those are the variables that you need to delete.
 
-1.  Drop the table:
+1. Drop the table:
 
-    ```sql
-    DELETE FROM ci_group_variables;
-    DELETE FROM ci_variables;
-    ```
+   ```sql
+   DELETE FROM ci_group_variables;
+   DELETE FROM ci_variables;
+   ```
 
 1. You may need to reconfigure or restart GitLab for the changes to take
    effect.
 
-
 #### Reset Runner registration tokens
 
-1.  Enter the DB console:
+1. Enter the DB console:
 
-    For Omnibus GitLab packages:
+   For Omnibus GitLab packages:
 
-    ```sh
-    sudo gitlab-rails dbconsole
-    ```
+   ```sh
+   sudo gitlab-rails dbconsole
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```sh
-    sudo -u git -H bundle exec rails dbconsole RAILS_ENV=production
-    ```
+   ```sh
+   sudo -u git -H bundle exec rails dbconsole RAILS_ENV=production
+   ```
 
 1. Clear all the tokens for projects, groups, and the whole instance:
 
-    CAUTION: **Caution:**
-    The last UPDATE operation will stop the runners being able to pick up
-    new jobs. You must register new runners.
-
-    ```sql
-    -- Clear project tokens
-    UPDATE projects SET runners_token = null, runners_token_encrypted = null;
-    -- Clear group tokens
-    UPDATE namespaces SET runners_token = null, runners_token_encrypted = null;
-    -- Clear instance tokens
-    UPDATE application_settings SET runners_registration_token_encrypted = null;
-    -- Clear runner tokens
-    UPDATE ci_runners SET token = null, token_encrypted = null;
-    ```
+   CAUTION: **Caution:**
+   The last UPDATE operation will stop the runners being able to pick up
+   new jobs. You must register new runners.
+
+   ```sql
+   -- Clear project tokens
+   UPDATE projects SET runners_token = null, runners_token_encrypted = null;
+   -- Clear group tokens
+   UPDATE namespaces SET runners_token = null, runners_token_encrypted = null;
+   -- Clear instance tokens
+   UPDATE application_settings SET runners_registration_token_encrypted = null;
+   -- Clear runner tokens
+   UPDATE ci_runners SET token = null, token_encrypted = null;
+   ```
 
 A similar strategy can be employed for the remaining features - by removing the
 data that cannot be decrypted, GitLab can be brought back into working order,
 and the lost data can be manually replaced.
 
+### Container Registry push failures after restoring from a backup
+
+If you use the [Container Registry](../user/project/container_registry.md), you
+may see pushes to the registry fail after restoring your backup on an Omnibus
+GitLab instance after restoring the registry data.
+
+These failures will mention permission issues in the registry logs, like:
+
+```
+level=error
+msg="response completed with error"
+err.code=unknown
+err.detail="filesystem: mkdir /var/opt/gitlab/gitlab-rails/shared/registry/docker/registry/v2/repositories/...: permission denied"
+err.message="unknown error"
+```
+
+This is caused by the restore being run as the unprivileged user `git` which was
+unable to assign the correct ownership to the registry files during the restore
+([issue 62759](https://gitlab.com/gitlab-org/gitlab-ce/issues/62759 "Incorrect permissions on registry filesystem after restore")).
+
+To get your registry working again:
+
+```bash
+sudo chown -R registry:registry /var/opt/gitlab/gitlab-rails/shared/registry/docker
+```
+
+NOTE: **Note:**
+If you have changed the default filesystem location for the registry, you will
+want to run the chown against your custom location instead of
+`/var/opt/gitlab/gitlab-rails/shared/registry/docker`.
+
 [reconfigure GitLab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure
 [restart GitLab]: ../administration/restart_gitlab.md#installations-from-source
+
+### Backup fails to complete with Gzip error
+
+While running the backup, you may receive a gzip error:
+
+```sh
+sudo /opt/gitlab/bin/gitlab-backup create
+Dumping ...
+...
+gzip: stdout: Input/output error
+
+Backup failed
+```
+
+If this happens, check the following:
+
+1. Confirm there is sufficent diskspace for the gzip operation.
+1. If NFS is being used, check if the mount option `timeo` is set. The default is `600`, and changing this to smaller values have resulted in this error.
+
diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md
index f5c788af578..832078d23cb 100644
--- a/doc/raketasks/cleanup.md
+++ b/doc/raketasks/cleanup.md
@@ -92,3 +92,58 @@ I, [2018-08-02T10:26:47.598424 #45087]  INFO -- : Looking for orphaned remote up
 I, [2018-08-02T10:26:47.753131 #45087]  INFO -- : Moved to lost and found: @hashed/6b/DSC_6152.JPG -> lost_and_found/@hashed/6b/DSC_6152.JPG
 I, [2018-08-02T10:26:47.764356 #45087]  INFO -- : Moved to lost and found: @hashed/79/02/7902699be42c8a8e46fbbb4501726517e86b22c56a189f7625a6da49081b2451/711491b29d3eb08837798c4909e2aa4d/DSC00314.jpg -> lost_and_found/@hashed/79/02/7902699be42c8a8e46fbbb4501726517e86b22c56a189f7625a6da49081b2451/711491b29d3eb08837798c4909e2aa4d/DSC00314.jpg
 ```
+
+## Remove orphan artifact files
+
+When you notice there are more job artifacts files on disk than there
+should be, you can run:
+
+```shell
+gitlab-rake gitlab:cleanup:orphan_job_artifact_files
+```
+
+This command:
+
+- Scans through the entire artifacts folder.
+- Checks which files still have a record in the database.
+- If no database record is found, the file is deleted from disk.
+
+By default, this task does not delete anything but shows what it can
+delete. Run the command with `DRY_RUN=false` if you actually want to
+delete the files:
+
+```shell
+gitlab-rake gitlab:cleanup:orphan_job_artifact_files DRY_RUN=false
+```
+
+You can also limit the number of files to delete with `LIMIT`:
+
+```shell
+gitlab-rake gitlab:cleanup:orphan_job_artifact_files LIMIT=100`
+```
+
+This will only delete up to 100 files from disk. You can use this to
+delete a small set for testing purposes.
+
+If you provide `DEBUG=1`, you'll see the full path of every file that
+is detected as being an orphan.
+
+If `ionice` is installed, the tasks uses it to ensure the command is
+not causing too much load on the disk. You can configure the niceness
+level with `NICENESS`. Below are the valid levels, but consult
+`man 1 ionice` to be sure.
+
+- `0` or `None`
+- `1` or `Realtime`
+- `2` or `Best-effort` (default)
+- `3` or `Idle`
+
+## Remove expired ActiveSession lookup keys
+
+```
+# omnibus-gitlab
+sudo gitlab-rake gitlab:cleanup:sessions:active_sessions_lookup_keys
+
+# installation from source
+bundle exec rake gitlab:cleanup:sessions:active_sessions_lookup_keys RAILS_ENV=production
+```
diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md
index b59c06a24ea..8f65fab366e 100644
--- a/doc/raketasks/import.md
+++ b/doc/raketasks/import.md
@@ -100,7 +100,7 @@ the git repository's config file. This section is formatted as follows:
 
 ```
 [gitlab]
-	fullpath = gitlab-org/gitlab-ce
+  fullpath = gitlab-org/gitlab-ce
 ```
 
 However, existing repositories were not migrated to include this path.
diff --git a/doc/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md
index df3dab118b2..cc1166a04cc 100644
--- a/doc/raketasks/web_hooks.md
+++ b/doc/raketasks/web_hooks.md
@@ -1,43 +1,60 @@
-# Webhooks administration **[CORE ONLY]**
+# Webhooks administration **(CORE ONLY)**
 
 ## Add a webhook for **ALL** projects:
 
-    # omnibus-gitlab
-    sudo gitlab-rake gitlab:web_hook:add URL="http://example.com/hook"
-    # source installations
-    bundle exec rake gitlab:web_hook:add URL="http://example.com/hook" RAILS_ENV=production
+```sh
+# omnibus-gitlab
+sudo gitlab-rake gitlab:web_hook:add URL="http://example.com/hook"
+# source installations
+bundle exec rake gitlab:web_hook:add URL="http://example.com/hook" RAILS_ENV=production
+```
 
 ## Add a webhook for projects in a given **NAMESPACE**:
 
-    # omnibus-gitlab
-    sudo gitlab-rake gitlab:web_hook:add URL="http://example.com/hook" NAMESPACE=acme
-    # source installations
-    bundle exec rake gitlab:web_hook:add URL="http://example.com/hook" NAMESPACE=acme RAILS_ENV=production
+```sh
+# omnibus-gitlab
+sudo gitlab-rake gitlab:web_hook:add URL="http://example.com/hook" NAMESPACE=acme
+# source installations
+bundle exec rake gitlab:web_hook:add URL="http://example.com/hook" NAMESPACE=acme RAILS_ENV=production
+```
 
 ## Remove a webhook from **ALL** projects using:
 
-    # omnibus-gitlab
-    sudo gitlab-rake gitlab:web_hook:rm URL="http://example.com/hook"
-    # source installations
-    bundle exec rake gitlab:web_hook:rm URL="http://example.com/hook" RAILS_ENV=production
+```sh
+# omnibus-gitlab
+sudo gitlab-rake gitlab:web_hook:rm URL="http://example.com/hook"
+# source installations
+bundle exec rake gitlab:web_hook:rm URL="http://example.com/hook" RAILS_ENV=production
+```
 
 ## Remove a webhook from projects in a given **NAMESPACE**:
 
-    # omnibus-gitlab
-    sudo gitlab-rake gitlab:web_hook:rm URL="http://example.com/hook" NAMESPACE=acme
-    # source installations
-    bundle exec rake gitlab:web_hook:rm URL="http://example.com/hook" NAMESPACE=acme RAILS_ENV=production
+```sh
+# omnibus-gitlab
+sudo gitlab-rake gitlab:web_hook:rm URL="http://example.com/hook" NAMESPACE=acme
+# source installations
+bundle exec rake gitlab:web_hook:rm URL="http://example.com/hook" NAMESPACE=acme RAILS_ENV=production
+```
 
 ## List **ALL** webhooks:
 
-    # omnibus-gitlab
-    sudo gitlab-rake gitlab:web_hook:list
-    # source installations
-    bundle exec rake gitlab:web_hook:list RAILS_ENV=production
+```sh
+# omnibus-gitlab
+sudo gitlab-rake gitlab:web_hook:list
+# source installations
+bundle exec rake gitlab:web_hook:list RAILS_ENV=production
+```
 
 ## List the webhooks from projects in a given **NAMESPACE**:
 
-    # omnibus-gitlab
-    sudo gitlab-rake gitlab:web_hook:list NAMESPACE=acme
-    # source installations
-    bundle exec rake gitlab:web_hook:list NAMESPACE=acme RAILS_ENV=production
+```sh
+# omnibus-gitlab
+sudo gitlab-rake gitlab:web_hook:list NAMESPACE=acme
+# source installations
+bundle exec rake gitlab:web_hook:list NAMESPACE=acme RAILS_ENV=production
+```
+
+## Local requests in webhooks
+
+[Requests to local network by webhooks](../security/webhooks.md) can be allowed
+or blocked by an administrator.
diff --git a/doc/security/README.md b/doc/security/README.md
index c48d5bc2065..5d498ac7602 100644
--- a/doc/security/README.md
+++ b/doc/security/README.md
@@ -7,7 +7,7 @@ type: index
 
 - [Password length limits](password_length_limits.md)
 - [Restrict SSH key technologies and minimum length](ssh_keys_restrictions.md)
-- [Rack attack](rack_attack.md)
+- [Rate limits](rate_limits.md)
 - [Webhooks and insecure internal web services](webhooks.md)
 - [Information exclusivity](information_exclusivity.md)
 - [Reset your root password](reset_root_password.md)
diff --git a/doc/security/img/outbound_requests_section.png b/doc/security/img/outbound_requests_section.png
deleted file mode 100644
index f7783f34cdd..00000000000
--- a/doc/security/img/outbound_requests_section.png
+++ /dev/null
diff --git a/doc/security/img/outbound_requests_section_v12_2.png b/doc/security/img/outbound_requests_section_v12_2.png
new file mode 100644
index 00000000000..3dc99868a35
--- /dev/null
+++ b/doc/security/img/outbound_requests_section_v12_2.png
diff --git a/doc/security/img/whitelist.png b/doc/security/img/whitelist.png
new file mode 100644
index 00000000000..897000e804d
--- /dev/null
+++ b/doc/security/img/whitelist.png
diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md
index 62a20d3f257..749ccf924b5 100644
--- a/doc/security/information_exclusivity.md
+++ b/doc/security/information_exclusivity.md
@@ -1,6 +1,7 @@
 ---
 type: concepts
 ---
+
 # Information exclusivity
 
 Git is a distributed version control system (DVCS). This means that everyone
diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md
index d78293c75c6..9909ef4a8e4 100644
--- a/doc/security/password_length_limits.md
+++ b/doc/security/password_length_limits.md
@@ -1,19 +1,31 @@
 ---
 type: reference, howto
 ---
+
 # Custom password length limits
 
-If you want to enforce longer user passwords you can create an extra Devise
-initializer with the steps below.
+The user password length is set to a minimum of 8 characters by default.
+To change that for installations from source:
+
+1. Edit `devise_password_length.rb`:
+
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H cp config/initializers/devise_password_length.rb.example config/initializers/devise_password_length.rb
+   sudo -u git -H editor config/initializers/devise_password_length.rb
+   ```
+
+1. Change the new password length limits:
+
+   ```ruby
+   config.password_length = 12..128
+   ```
 
-If you do not use the `devise_password_length.rb` initializer the password
-length is set to a minimum of 8 characters in `config/initializers/devise.rb`.
+   In this example, the minimum length is 12 characters, and the maximum length
+   is 128 characters.
 
-```bash
-cd /home/git/gitlab
-sudo -u git -H cp config/initializers/devise_password_length.rb.example config/initializers/devise_password_length.rb
-sudo -u git -H editor config/initializers/devise_password_length.rb   # inspect and edit the new password length limits
-```
+1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source)
+   for the changes to take effect.
 
 <!-- ## Troubleshooting
 
diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md
index fa4b0d1fb09..b99bfb16829 100644
--- a/doc/security/rack_attack.md
+++ b/doc/security/rack_attack.md
@@ -1,7 +1,10 @@
 ---
 type: reference, howto
 ---
-# Rack Attack
+
+# Rack Attack initializer
+
+## Overview
 
 [Rack Attack](https://github.com/kickstarter/rack-attack), also known as Rack::Attack, is a Ruby gem
 that is meant to protect GitLab with the ability to customize throttling and
@@ -13,19 +16,72 @@ If you find throttling is not enough to protect you against abusive clients,
 Rack Attack offers IP whitelisting, blacklisting, Fail2ban style filtering, and
 tracking.
 
-**Note:** Starting with 11.2, Rack Attack is disabled by default. To continue
-using Rack Attack, please enable it by [configuring `gitlab.rb` as described in Settings](#settings).
+For more information on how to use these options see the [Rack Attack README](https://github.com/kickstarter/rack-attack/blob/master/README.md).
+
+NOTE: **Note:** See
+[User and IP rate limits](../user/admin_area/settings/user_and_ip_rate_limits.md)
+for simpler limits that are configured in the UI.
+
+NOTE: **Note:** Starting with GitLab 11.2, Rack Attack is disabled by default. If your
+instance is not exposed to the public internet, it is recommended that you leave
+Rack Attack disabled.
+
+## Behavior
+
+If set up as described in the [Settings](#settings) section below, two behaviors
+will be enabled:
+
+- Protected paths will be throttled.
+- Failed authentications for Git and container registry requests will trigger a temporary IP ban.
+
+### Protected paths throttle
+
+GitLab responds with HTTP status code `429` to POST requests at protected paths
+that exceed 10 requests per minute per IP address.
+
+By default, protected paths are:
+
+```ruby
+default['gitlab']['gitlab-rails']['rack_attack_protected_paths'] = [
+  '/users/password',
+  '/users/sign_in',
+  '/api/#{API::API.version}/session.json',
+  '/api/#{API::API.version}/session',
+  '/users',
+  '/users/confirmation',
+  '/unsubscribes/',
+  '/import/github/personal_access_token'
+]
+```
+
+This header is included in responses to blocked requests:
+
+```
+Retry-After: 60
+```
+
+For example, the following are limited to a maximum 10 requests per minute:
+
+- User sign-in
+- User sign-up (if enabled)
+- User password reset
+
+After 10 requests, the client must wait a minute before it can
+try again.
+
+### Git and container registry failed authentication ban
+
+GitLab responds with HTTP status code `403` for 1 hour, if 30 failed
+authentication requests were received in a 3-minute period from a single IP address.
 
-By default, user sign-in, user sign-up (if enabled), and user password reset is
-limited to 6 requests per minute. After trying for 6 times, the client will
-have to wait for the next minute to be able to try again.
+This applies only to Git requests and container registry (`/jwt/auth`) requests
+(combined).
 
-If you installed or upgraded GitLab by following the [official guides](../install/README.md),
-Rack Attack should be disabled by default. If your instance is not exposed to any incoming
-connections, it is recommended that you leave Rack Attack disabled.
+This limit is reset by requests that authenticate successfully. For example, 29
+failed authentication requests followed by 1 successful request, followed by 29
+more failed authentication requests would not trigger a ban.
 
-For more information on how to use these options check out
-[rack-attack README](https://github.com/kickstarter/rack-attack/blob/master/README.md).
+No response headers are provided.
 
 ## Settings
 
@@ -34,33 +90,34 @@ For more information on how to use these options check out
 1. Open `/etc/gitlab/gitlab.rb` with your editor
 1. Add the following:
 
-    ```ruby
-    gitlab_rails['rack_attack_git_basic_auth'] = {
-      'enabled' => true,
-      'ip_whitelist' => ["127.0.0.1"],
-      'maxretry' => 10, # Limit the number of Git HTTP authentication attempts per IP
-      'findtime' => 60, # Reset the auth attempt counter per IP after 60 seconds
-      'bantime' => 3600 # Ban an IP for one hour (3600s) after too many auth attempts
-    }
-    ```
+   ```ruby
+   gitlab_rails['rack_attack_git_basic_auth'] = {
+     'enabled' => true,
+     'ip_whitelist' => ["127.0.0.1"],
+     'maxretry' => 10, # Limit the number of Git HTTP authentication attempts per IP
+     'findtime' => 60, # Reset the auth attempt counter per IP after 60 seconds
+     'bantime' => 3600 # Ban an IP for one hour (3600s) after too many auth attempts
+   }
+   ```
 
 1. Reconfigure GitLab:
 
-    ```
-    sudo gitlab-ctl reconfigure
-    ```
+   ```
+   sudo gitlab-ctl reconfigure
+   ```
 
 The following settings can be configured:
 
 - `enabled`: By default this is set to `false`. Set this to `true` to enable Rack Attack.
-- `ip_whitelist`: Whitelist any IPs from being blocked. They must be formatted as strings within a ruby array.
-   For example, `["127.0.0.1", "127.0.0.2", "127.0.0.3"]`.
+- `ip_whitelist`: Whitelist any IPs from being blocked. They must be formatted as strings within a Ruby array.
+  CIDR notation is supported in GitLab v12.1 and up.
+  For example, `["127.0.0.1", "127.0.0.2", "127.0.0.3", "192.168.0.1/24"]`.
 - `maxretry`: The maximum amount of times a request can be made in the
-   specified time.
+  specified time.
 - `findtime`: The maximum amount of time that failed requests can count against an IP
-   before it's blacklisted (in seconds).
+  before it's blacklisted (in seconds).
 - `bantime`: The total amount of time that a blacklisted IP will be blocked (in
-   seconds).
+  seconds).
 
 **Installations from source**
 
@@ -70,25 +127,25 @@ taken in order to enable protection for your GitLab instance:
 
 1. In `config/application.rb` find and uncomment the following line:
 
-    ```ruby
-    config.middleware.use Rack::Attack
-    ```
+   ```ruby
+   config.middleware.use Rack::Attack
+   ```
 
 1. Copy `config/initializers/rack_attack.rb.example` to `config/initializers/rack_attack.rb`
 1. Open `config/initializers/rack_attack.rb`, review the
    `paths_to_be_protected`, and add any other path you need protecting
 1. Restart GitLab:
 
-    ```sh
-    sudo service gitlab restart
-    ```
+   ```sh
+   sudo service gitlab restart
+   ```
 
 If you want more restrictive/relaxed throttle rules, edit
 `config/initializers/rack_attack.rb` and change the `limit` or `period` values.
 For example, more relaxed throttle rules will be if you set
 `limit: 3` and `period: 1.seconds` (this will allow 3 requests per second).
 You can also add other paths to the protected list by adding to `paths_to_be_protected`
-variable. If you change any of these settings do not forget to restart your
+variable. If you change any of these settings you must restart your
 GitLab instance.
 
 ## Remove blocked IPs from Rack Attack via Redis
@@ -97,28 +154,28 @@ In case you want to remove a blocked IP, follow these steps:
 
 1. Find the IPs that have been blocked in the production log:
 
-    ```sh
-    grep "Rack_Attack" /var/log/gitlab/gitlab-rails/auth.log
-    ```
+   ```sh
+   grep "Rack_Attack" /var/log/gitlab/gitlab-rails/auth.log
+   ```
 
 1. Since the blacklist is stored in Redis, you need to open up `redis-cli`:
 
-    ```sh
-    /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket
-    ```
+   ```sh
+   /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket
+   ```
 
 1. You can remove the block using the following syntax, replacing `<ip>` with
    the actual IP that is blacklisted:
 
-    ```
-    del cache:gitlab:rack::attack:allow2ban:ban:<ip>
-    ```
+   ```
+   del cache:gitlab:rack::attack:allow2ban:ban:<ip>
+   ```
 
 1. Confirm that the key with the IP no longer shows up:
 
-    ```
-    keys *rack::attack*
-    ```
+   ```
+   keys *rack::attack*
+   ```
 
 1. Optionally, add the IP to the whitelist to prevent it from being blacklisted
    again (see [settings](#settings)).
@@ -135,8 +192,8 @@ the load balancer. In that case, you will need to:
 1. Whitelist the load balancer's IP address(es) in the Rack Attack [settings](#settings).
 1. Reconfigure GitLab:
 
-    ```
-    sudo gitlab-ctl reconfigure
-    ```
+   ```
+   sudo gitlab-ctl reconfigure
+   ```
 
 1. [Remove the block via Redis.](#remove-blocked-ips-from-rack-attack-via-redis)
diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md
new file mode 100644
index 00000000000..c80f2f264b2
--- /dev/null
+++ b/doc/security/rate_limits.md
@@ -0,0 +1,33 @@
+---
+type: reference, howto
+---
+
+# Rate limits
+
+NOTE: **Note:**
+For GitLab.com, please see
+[GitLab.com-specific rate limits](../user/gitlab_com/index.md#gitlabcom-specific-rate-limits).
+
+Rate limiting is a common technique used to improve the security and durability
+of a web application.
+
+For example, a simple script can make thousands of web requests per second.
+Whether malicious, apathetic, or just a bug, your application and infrastructure
+may not be able to cope with the load. For more details, see
+[Denial-of-service attack](https://en.wikipedia.org/wiki/Denial-of-service_attack).
+Most cases can be mitigated by limiting the rate of requests from a single IP address.
+
+Most [brute-force attacks](https://en.wikipedia.org/wiki/Brute-force_attack) are
+similarly mitigated by a rate limit.
+
+## Admin Area settings
+
+- [User and IP rate limits](../user/admin_area/settings/user_and_ip_rate_limits.md).
+- [Rate limits on raw endpoints](../user/admin_area/settings/rate_limits_on_raw_endpoints.md)
+
+## Rack Attack initializer
+
+This method of rate limiting is cumbersome, but has some advantages. It allows
+throttling of specific paths, and is also integrated into Git and container
+registry requests. See [Rack Attack initializer](rack_attack.md).
+
diff --git a/doc/security/reset_root_password.md b/doc/security/reset_root_password.md
index a58d70f0ff2..ec360e2d338 100644
--- a/doc/security/reset_root_password.md
+++ b/doc/security/reset_root_password.md
@@ -1,6 +1,7 @@
 ---
 type: howto
 ---
+
 # How to reset your root password
 
 To reset your root password, first log into your server with root privileges.
@@ -22,7 +23,7 @@ user = User.where(id: 1).first
 or
 
 ```bash
-user = User.find_by(email: 'admin@local.host')
+user = User.find_by(email: 'admin@example.com')
 ```
 
 Now you can change your password:
diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md
index ae4cc44519e..4c60daf77f4 100644
--- a/doc/security/ssh_keys_restrictions.md
+++ b/doc/security/ssh_keys_restrictions.md
@@ -1,6 +1,7 @@
 ---
 type: reference, howto
 ---
+
 # Restrict allowed SSH key technologies and minimum length
 
 `ssh-keygen` allows users to create RSA keys with as few as 768 bits, which
diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md
index 49dadd5abc2..b08d9ffa26e 100644
--- a/doc/security/two_factor_authentication.md
+++ b/doc/security/two_factor_authentication.md
@@ -1,6 +1,7 @@
 ---
 type: howto
 ---
+
 # Enforce Two-factor Authentication (2FA)
 
 Two-factor Authentication (2FA) provides an additional level of security to your
@@ -48,11 +49,11 @@ need to be administrator or owner of the group.
 The following are important notes about 2FA:
 
 - Projects belonging to a 2FA-enabled group that
-  [is shared](../user/project/members/share_project_with_groups.md) 
+  [is shared](../user/project/members/share_project_with_groups.md)
   with a 2FA-disabled group will *not* require members of the 2FA-disabled group to use
-  2FA for the project. For example, if project *P* belongs to 2FA-enabled group *A* and 
+  2FA for the project. For example, if project *P* belongs to 2FA-enabled group *A* and
   is shared with 2FA-disabled group *B*, members of group *B* can access project *P*
-  without 2FA. To ensure this scenario doesn't occur, 
+  without 2FA. To ensure this scenario doesn't occur,
   [prevent sharing of projects](../user/group/index.md#share-with-group-lock)
   for the 2FA-enabled group.
 - If you add additional members to a project within a group or subgroup that has
diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md
index 75cf754e197..d34826c853c 100644
--- a/doc/security/unlock_user.md
+++ b/doc/security/unlock_user.md
@@ -1,38 +1,45 @@
 ---
 type: howto
 ---
-# How to unlock a locked user
 
-To unlock a locked user, first log into your server with root privileges.
+# How to unlock a locked user from the command line
 
-Start a Ruby on Rails console with this command:
+After six failed login attempts a user gets in a locked state.
 
+To unlock a locked user:
 
-```bash
-gitlab-rails console production
-```
+1. SSH into your GitLab server.
+1. Start a Ruby on Rails console:
 
-Wait until the console has loaded.
+   ```sh
+   ## For Omnibus GitLab
+   sudo gitlab-rails console production
 
-There are multiple ways to find your user. You can search for email or username.
+   ## For installations from source
+   sudo -u git -H bundle exec rails console RAILS_ENV=production
+   ```
 
-```bash
-user = User.where(id: 1).first
-```
+1. Find the user to unlock. You can search by email or ID.
 
-or
+   ```ruby
+   user = User.find_by(email: 'admin@local.host')
+   ```
 
-```bash
-user = User.find_by(email: 'admin@local.host')
-```
+   or
 
-Unlock the user:
+   ```ruby
+   user = User.where(id: 1).first
+   ```
 
-```bash
-user.unlock_access!
-```
+1. Unlock the user:
 
-Exit the console, the user should now be able to log in again.
+   ```ruby
+   user.unlock_access!
+   ```
+
+1. Exit the console with <kbd>Ctrl</kbd>+<kbd>d</kbd>
+
+The user should now be able to log in.
 
 <!-- ## Troubleshooting
 
diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md
index f0af0a7ac6a..7ba50acbb06 100644
--- a/doc/security/user_email_confirmation.md
+++ b/doc/security/user_email_confirmation.md
@@ -1,6 +1,7 @@
 ---
 type: howto
 ---
+
 # User email confirmation at sign-up
 
 GitLab can be configured to require confirmation of a user's email address when
diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md
index 00a2607b607..9fc8f7ec985 100644
--- a/doc/security/user_file_uploads.md
+++ b/doc/security/user_file_uploads.md
@@ -1,6 +1,7 @@
 ---
 type: reference
 ---
+
 # User File Uploads
 
 Images that are attached to issues, merge requests, or comments
@@ -12,7 +13,7 @@ image contains sensitive information.
 Authentication is not enabled because images must be visible in the body of
 notification emails, which are often read from email clients that are not
 authenticated with GitLab, such as Outlook, Apple Mail, or the Mail app on your
-mobile device. 
+mobile device.
 
 >**Note:**
 Non-image attachments do require authentication to be viewed.
diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md
index d4fa088cb15..e39bc9a9626 100644
--- a/doc/security/webhooks.md
+++ b/doc/security/webhooks.md
@@ -1,6 +1,7 @@
 ---
 type: concepts, reference, howto
 ---
+
 # Webhooks and insecure internal web services
 
 If you have non-GitLab web services running on your GitLab server or within its
@@ -33,15 +34,46 @@ to 127.0.0.1, ::1 and 0.0.0.0, as well as IPv4 10.0.0.0/8, 172.16.0.0/12,
 192.168.0.0/16 and IPv6 site-local (ffc0::/10) addresses won't be allowed.
 
 This behavior can be overridden by enabling the option *"Allow requests to the
-local network from hooks and services"* in the *"Outbound requests"* section
+local network from web hooks and services"* in the *"Outbound requests"* section
 inside the Admin area under **Settings**
 (`/admin/application_settings/network`):
 
-![Outbound requests admin settings](img/outbound_requests_section.png)
+![Outbound requests admin settings](img/outbound_requests_section_v12_2.png)
+
+NOTE: **Note:**
+*System hooks* are enabled to make requests to local network by default since they are
+set up by administrators. However, you can turn this off by disabling the
+**Allow requests to the local network from system hooks** option.
+
+## Whitelist for local requests
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/44496) in GitLab 12.2
+
+You can allow certain domains and IP addresses to be accessible to both *system hooks*
+and *webhooks* even when local requests are not allowed by adding them to the
+whitelist. Navigate to **Admin Area > Settings > Network** (`/admin/application_settings/network`)
+and expand **Outbound requests**:
+
+![Outbound local requests whitelist](img/whitelist.png)
+
+The whilelist entries can be separated by semicolons, commas or whitespaces
+(including newlines) and be in different formats like hostnames, IP addresses and/or
+IP ranges. IPv6 is supported. Hostnames that contain unicode characters should
+use IDNA encoding.
+
+The whitelist can hold a maximum of 1000 entries. Each entry can be a maximum of
+255 characters.
+
+Example:
+
+```text
+example.com;gitlab.example.com
+127.0.0.1,1:0:0:0:0:0:0:1
+127.0.0.0/8 1:0:0:0:0:0:0:0/124
+```
 
->**Note:**
-*System hooks* are exempt from this protection because they are set up by
-admins.
+NOTE: **Note:**
+Wildcards (`*.example.com`) and ports (`127.0.0.1:3000`) are not currently supported.
 
 <!-- ## Troubleshooting
 
diff --git a/doc/ssh/README.md b/doc/ssh/README.md
index 09b5fbd9260..e18f49de3f0 100644
--- a/doc/ssh/README.md
+++ b/doc/ssh/README.md
@@ -64,9 +64,14 @@ Following [best practices](https://linux-audit.com/using-ed25519-openssh-keys-in
 you should always favor [ED25519](https://ed25519.cr.yp.to/) SSH keys, since they
 are more secure and have better performance over the other types.
 
-They were introduced in OpenSSH 6.5, so any modern OS should include the
-option to create them. If for any reason your OS or the GitLab instance you
-interact with doesn't support this, you can fallback to RSA.
+ED25519 SSH keys were introduced in OpenSSH 6.5,
+so any modern OS should include the option to create them.
+If for any reason your OS or the GitLab instance you interact with doesn't
+support ED25519, you can fallback to RSA.
+
+NOTE: **Note:**
+Omnibus does not ship with OpenSSH, so it uses the version on your GitLab server. If using
+Omnibus, ensure the version of OpenSSH installed is version 6.5 or newer if you want to use ED25519 SSH keys.
 
 ### RSA SSH keys
 
@@ -102,18 +107,18 @@ To create a new SSH key pair:
 1. Open a terminal on Linux or macOS, or Git Bash / WSL on Windows.
 1. Generate a new ED25519 SSH key pair:
 
-    ```bash
-    ssh-keygen -t ed25519 -C "email@example.com"
-    ```
+   ```bash
+   ssh-keygen -t ed25519 -C "email@example.com"
+   ```
 
-    Or, if you want to use RSA:
+   Or, if you want to use RSA:
 
-    ```bash
-    ssh-keygen -o -t rsa -b 4096 -C "email@example.com"
-    ```
+   ```bash
+   ssh-keygen -o -t rsa -b 4096 -C "email@example.com"
+   ```
 
-    The `-C` flag adds a comment in the key in case you have multiple of them
-    and want to tell which is which. It is optional.
+   The `-C` flag adds a comment in the key in case you have multiple of them
+   and want to tell which is which. It is optional.
 
 1. Next, you will be prompted to input a file path to save your SSH key pair to.
    If you don't already have an SSH key pair and aren't generating a [deploy key](#deploy-keys),
@@ -121,21 +126,21 @@ To create a new SSH key pair:
    <kbd>Enter</kbd>. Using the suggested path will normally allow your SSH client
    to automatically use the SSH key pair with no additional configuration.
 
-    If you already have an SSH key pair with the suggested file path, you will need
-    to input a new file path and [declare what host](#working-with-non-default-ssh-key-pair-paths)
-    this SSH key pair will be used for in your `~/.ssh/config` file.
+   If you already have an SSH key pair with the suggested file path, you will need
+   to input a new file path and [declare what host](#working-with-non-default-ssh-key-pair-paths)
+   this SSH key pair will be used for in your `~/.ssh/config` file.
 
 1. Once the path is decided, you will be prompted to input a password to
    secure your new SSH key pair. It's a best practice to use a password,
    but it's not required and you can skip creating it by pressing
    <kbd>Enter</kbd> twice.
 
-    If, in any case, you want to add or change the password of your SSH key pair,
-    you can use the `-p` flag:
+   If, in any case, you want to add or change the password of your SSH key pair,
+   you can use the `-p` flag:
 
-    ```
-    ssh-keygen -p -o -f <keyname>
-    ```
+   ```
+   ssh-keygen -p -o -f <keyname>
+   ```
 
 Now, it's time to add the newly created public key to your GitLab account.
 
@@ -144,41 +149,40 @@ Now, it's time to add the newly created public key to your GitLab account.
 1. Copy your **public** SSH key to the clipboard by using one of the commands below
    depending on your Operating System:
 
-    **macOS:**
+   **macOS:**
 
-    ```bash
-    pbcopy < ~/.ssh/id_ed25519.pub
-    ```
+   ```bash
+   pbcopy < ~/.ssh/id_ed25519.pub
+   ```
 
-    **WSL / GNU/Linux (requires the xclip package):**
+   **WSL / GNU/Linux (requires the xclip package):**
 
-    ```bash
-    xclip -sel clip < ~/.ssh/id_ed25519.pub
-    ```
+   ```bash
+   xclip -sel clip < ~/.ssh/id_ed25519.pub
+   ```
 
-    **Git Bash on Windows:**
+   **Git Bash on Windows:**
 
-    ```bash
-    cat ~/.ssh/id_ed25519.pub | clip
-    ```
+   ```bash
+   cat ~/.ssh/id_ed25519.pub | clip
+   ```
 
-    You can also open the key in a graphical editor and copy it from there,
-    but be careful not to accidentally change anything.
+   You can also open the key in a graphical editor and copy it from there,
+   but be careful not to accidentally change anything.
 
-    NOTE: **Note:**
-    If you opted to create an RSA key, the name might differ.
+   NOTE: **Note:**
+   If you opted to create an RSA key, the name might differ.
 
 1. Add your **public** SSH key to your GitLab account by:
    1. Clicking your avatar in the upper right corner and selecting **Settings**.
    1. Navigating to **SSH Keys** and pasting your **public** key in the **Key** field. If you:
-
       - Created the key with a comment, this will appear in the **Title** field.
       - Created the key without a comment, give your key an identifiable title like _Work Laptop_ or _Home Workstation_.
    1. Click the **Add key** button.
 
-    NOTE: **Note:**
-    If you manually copied your public SSH key make sure you copied the entire
-    key starting with `ssh-ed25519` (or `ssh-rsa`) and ending with your email.
+   NOTE: **Note:**
+   If you manually copied your public SSH key make sure you copied the entire
+   key starting with `ssh-ed25519` (or `ssh-rsa`) and ending with your email.
 
 ## Testing that everything is set up correctly
 
diff --git a/doc/subscriptions/billing_table.png b/doc/subscriptions/billing_table.png
deleted file mode 100644
index acd1b6193ec..00000000000
--- a/doc/subscriptions/billing_table.png
+++ /dev/null
diff --git a/doc/subscriptions/img/additional_minutes.png b/doc/subscriptions/img/additional_minutes.png
new file mode 100644
index 00000000000..b159b98c9ce
--- /dev/null
+++ b/doc/subscriptions/img/additional_minutes.png
diff --git a/doc/subscriptions/img/buy_btn.png b/doc/subscriptions/img/buy_btn.png
new file mode 100644
index 00000000000..4fd05c0fba7
--- /dev/null
+++ b/doc/subscriptions/img/buy_btn.png
diff --git a/doc/subscriptions/img/buy_minutes_card.png b/doc/subscriptions/img/buy_minutes_card.png
new file mode 100644
index 00000000000..cab098300cd
--- /dev/null
+++ b/doc/subscriptions/img/buy_minutes_card.png
diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md
index 37051f6b10f..13c406727ab 100644
--- a/doc/subscriptions/index.md
+++ b/doc/subscriptions/index.md
@@ -2,118 +2,314 @@
 type: index, reference
 ---
 
-# Subscription setup and management
+# Customer Docs
 
-This page will help get you started with your new subscription or manage an existing one, whether you have subscribed to GitLab.com or self-managed GitLab.
+This section contains information for:
 
-To subscribe, upgrade, or read more about the types of subscriptions, please see [Subscribe to GitLab](../README.md#subscribe-to-gitlab) on the GitLab Documentation landing page.
+- New customers about choosing [which GitLab](#which-gitlab) is right for you.
+- Existing customers about [managing subscriptions](#managing-subscriptions).
 
-## Set up GitLab
+Also see our [subscription FAQ](https://about.gitlab.com/pricing/licensing-faq/).
 
-Learn how GitLab helps you in the stages of the DevOps lifecycle by learning more [about the GitLab product](https://about.gitlab.com/product/), [GitLab features](https://about.gitlab.com/features/), and [GitLab Documentation](../README.md).
+## Which GitLab?
 
-### Self-managed: Install GitLab
+There are two ways to use GitLab:
 
-Take a look at [installing GitLab](https://about.gitlab.com/install/) and our [administrator documentation](../administration/index.md). Then, follow the instructions below under [Your subscription](#your-subscription) to apply your license file. 
+- [GitLab.com](#gitlabcom): GitLab's SaaS offering. You don't need to install
+  anything to use GitLab.com, you only need to
+  [sign up](https://gitlab.com/users/sign_in) and start using GitLab straight away.
+- [GitLab self-managed](#gitlab-self-managed): Install, administer, and maintain
+  your own GitLab instance.
 
-### GitLab.com: Create a user and group
+The following sections outline tiers and features within GitLab.com
+and GitLab self-managed.
 
-Start with creating a user account for yourself using our [sign up page](https://gitlab.com/users/sign_in#register-pane).
+### GitLab.com
+
+GitLab.com is hosted, managed, and administered by GitLab, Inc., with
+[free and paid subscriptions](https://about.gitlab.com/pricing/) for individuals
+and teams in the following tiers:
 
-[GitLab groups](../user/group/index.md) help assemble related projects together allowing you to grant members access to several projects at once. A group is not required if you plan on having [projects](../user/project/) inside a personal namespace.
+| Tier   | Includes same features available in                 |
+|:-------|:----------------------------------------------------|
+| Free   | [Core](#gitlab-self-managed) self-managed tier.     |
+| Bronze | [Starter](#gitlab-self-managed) self-managed tier.  |
+| Silver | [Premium](#gitlab-self-managed) self-managed tier.  |
+| Gold   | [Ultimate](#gitlab-self-managed) self-managed tier. |
 
-## Your subscription
+GitLab.com subscriptions grant access
+to the same features available in GitLab self-managed, **except
+[administration](../administration/index.md) tools and settings**.
 
-You can view and manage subscriptions through our [Customers portal](https://customers.gitlab.com/). Information on applying your subscription is below.
+GitLab.com allows you to apply your subscription to a group or your personal user.
 
-Please also see our [subscription FAQ](https://about.gitlab.com/pricing/licensing-faq/)
+When applied to:
 
-### View subscription and seats
+- A **group**, the group, all subgroups, and all projects under the selected
+  group on GitLab.com will have the features of the associated plan. It is
+  recommended to go with a group plan when managing projects and users of an
+  organization.
+- A **personal userspace** instead, all projects will have features with the
+  subscription applied, but as it is not a group, group features will not be available.
 
-To view and manage the subscriptions you have purchased and the number of seats associated with the subscription, please visit and log into the [Customers’ Portal](https://customers.gitlab.com/subscriptions). For more information, please see our [subscription FAQ](https://about.gitlab.com/pricing/licensing-faq/) and [pricing page](https://about.gitlab.com/pricing/), which includes information on our [true-up pricing policy](https://about.gitlab.com/handbook/product/pricing/#true-up-pricing) when adding more users than at the time of purchase.
+TIP: **Tip:**
+To support the open source community and encourage the development of open
+source projects, GitLab grants access to **Gold** features for all GitLab.com
+**public** projects, regardless of the subscription.
 
-Please note that this account may have the same email, but is a _separate_ login from your GitLab.com account. If the two accounts are linked together, then you can use the "sign in with GitLab.com account" link underneath the `Sign In` button.
+The following resources are available for more information on GitLab.com:
 
-### Change billing information
+- [Feature comparison](https://about.gitlab.com/pricing/gitlab-com/feature-comparison/), for information on what features are available at each tier.
+- [GitLab pricing page](https://about.gitlab.com/pricing/), for subscription information and a free trial.
+- Our [product marketing page](https://about.gitlab.com/handbook/marketing/product-marketing/), for additional information including:
+  - How [different tiers are licensed](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers).
+  - The different [GitLab distributions](https://about.gitlab.com/handbook/marketing/product-marketing/#distributions).
+
+#### Subscribing to GitLab.com
+
+To subscribe to GitLab.com:
+
+1. Create a user account for yourself using our
+   [sign up page](https://gitlab.com/users/sign_in#register-pane).
+1. Create a [group](../user/group/index.md). GitLab groups help assemble related
+   projects together allowing you to grant members access to several projects
+   at once. A group is not required if you plan on having projects inside a personal
+   namespace.
+1. Create additional users and
+   [add them to the group](../user/group/index.md#add-users-to-a-group).
+1. Select the **Bronze**, **Silver**, or **Gold** GitLab.com plan through the
+   [GitLab Subscription Manager](https://customers.gitlab.com/).
+1. Link your GitLab.com account with your GitLab Subscription Manager account.
+   Once signed into the GitLab Subscription Manager, if your account is not
+   already linked, you will prompted to link your account with a
+   **Link my GitLab Account** button.
+1. Associate the group with the subscription.
+
+TIP: **Tip:**
+You can also go to the [**My Account**](https://customers.gitlab.com/customers/edit)
+page to add or change the GitLab.com account link.
+
+### GitLab self-managed
+
+With GitLab self-managed, you deploy your own GitLab instance on-premises or on a cloud of your choice.
+GitLab self-managed is available for [free and with paid subscriptions](https://about.gitlab.com/pricing/#self-managed) in the following tiers:
+
+| Tier     | Includes                                       |
+|:---------|:-----------------------------------------------|
+| Core     | Core features.                                 |
+| Starter  | Core and Starter features.                     |
+| Premium  | Core, Starter, and Premium features.           |
+| Ultimate | Core, Starter, Premium, and Ultimate features. |
+
+The following resources are available for more information on GitLab self-managed:
 
-In the customers portal, go to the `My Account` page, then revise the `Account Details` information and click on the `Update Account` button.
+- [Feature comparison](https://about.gitlab.com/pricing/self-managed/feature-comparison/), for information on what features are available at each tier.
+- [GitLab pricing page](https://about.gitlab.com/pricing/#self-managed), for subscription information and a free trial.
+- Our [product marketing page](https://about.gitlab.com/handbook/marketing/product-marketing/), for additional information including:
+  - How [different tiers are licensed](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers).
+  - The different [GitLab distributions](https://about.gitlab.com/handbook/marketing/product-marketing/#distributions).
 
-Future purchases will use the information in this section. The email listed in this section is used for the Customers Portal login and for license related email communication.
+#### Subscribing through GitLab self-managed
 
-### Self-managed: Apply your license file
+To subscribe to GitLab through a self-managed installation:
+
+1. [Install](https://about.gitlab.com/install/) GitLab.
+1. Complete the installation with
+   [administration tasks](https://docs.gitlab.com/ee/administration/).
+1. Select the **Starter**, **Premium**, or **Ultimate** self-managed plan
+   through the [GitLab Subscription Manager](https://customers.gitlab.com/).
+1. Apply your license file. After purchase, a license file is sent to the email
+   address associated to the GitLab Subscription Manager account,
+   which needs to be
+   [uploaded to your GitLab instance](../user/admin_area/license.md#uploading-your-license).
+
+TIP: **Tip:**
+If you are purchasing a subscription for an existing **Core** self-managed
+instance, ensure you are purchasing enough seats to
+[cover your users](../user/admin_area/index.md#administering-users).
+
+## Managing subscriptions
+
+You can view and manage subscriptions through our
+[GitLab Subscription Manager](https://customers.gitlab.com/).
 
-After purchase, the license file is sent to the email address tied to the Customers portal account, which needs to be [uploaded to the GitLab instance](../user/admin_area/license.md#uploading-your-license).
+### View subscription and seats
+
+Visit the
+[GitLab Subscription Manager](https://customers.gitlab.com/subscriptions) to
+view and manage:
+
+- The subscriptions you have purchased.
+- The number of seats associated with the subscription.
+- Retrieve copies of invoices.
+- Change the credit card on file.
 
-### Link your GitLab.com account with your Customers Portal account
+For more information, please see our:
+
+- [Subscription FAQ](https://about.gitlab.com/pricing/licensing-faq/).
+- [Pricing page](https://about.gitlab.com/pricing/), which includes information
+  on our [true-up pricing policy](https://about.gitlab.com/handbook/product/pricing/#true-up-pricing)
+  when adding more users other than at the time of purchase.
 
 NOTE: **Note:**
-This is *required* for GitLab.com subscriptions.
+The GitLab Subscription Manager account can have the same email address as your
+GitLab.com account, but is a _separate_ login. If the two accounts are
+linked together, you can use the **Or sign in with GitLab.com**
+link underneath the **Sign In** button.
+
+### Change billing information
+
+To change billing information:
 
-Once signed into the customers portal, if your account is not already linked, you should be prompted to link your account with a "Link my GitLab Account" button.
+1. Log in to [GitLab Subscription Manager](https://customers.gitlab.com/customers/sign_in).
+1. Go to the **My Account** page.
+1. Make the required changes to the **Account Details** information.
+1. Click **Update Account**.
 
-You can also go to the [My Account](https://customers.gitlab.com/customers/edit) page to add or change the GitLab.com account link.
+NOTE: **Note:**
+Future purchases will use the information in this section.
+The email listed in this section is used for the GitLab Subscription Manager
+login and for license-related email communication.
 
-### Change the linked GitLab.com account for your Customers Portal account
+### Manage GitLab.com account
 
-To change which GitLab.com account is associated with a Customers Portal account, please follow these steps:
+This section provided information specific to managing subscriptions with a
+GitLab.com account.
 
-1. Log into the [Customers Portal](https://customers.gitlab.com/customers/sign_in).
-1. In a separate browser tab, visit [GitLab.com](https://gitlab.com) to ensure you are not logged in, or if you are, log out.
-1. Back on the Customers Portal page, click [My Account](https://customers.gitlab.com/customers/edit) in the top menu.
-1. Under `Your GitLab.com account`, click the `Change linked account` button.
-1. Have the user you want associated log in to their [GitLab.com](https://gitlab.com) account.
+#### Change linked account
 
-### GitLab.com: Associate your namespace with your subscription
+To change the GitLab.com account associated with a GitLab Subscription Manager
+account:
 
-Once your GitLab.com account is linked, you can go to your [Subscriptions](https://customers.gitlab.com/subscriptions) page to choose or change the namespace your subscription applies to.
+1. Log in to the
+   [GitLab Subscription Manager](https://customers.gitlab.com/customers/sign_in).
+1. Go to [GitLab.com](https://gitlab.com) in a separate browser tab. Ensure you
+   are not logged in.
+1. On the GitLab Subscription Manager page, click
+   [**My Account**](https://customers.gitlab.com/customers/edit) in the top menu.
+1. Under **Your GitLab.com account**, click **Change linked account** button.
+1. Log in to [GitLab.com](https://gitlab.com) account to link to.
 
-Please note that you need to be a group owner to associate a group to your subscription.
+#### Change associated namespace
 
-### Confirm or upgrade your GitLab.com subscription details within GitLab
+With a linked GitLab.com account, go to the
+[**Subscriptions**](https://customers.gitlab.com/subscriptions) page to choose
+or change the namespace your subscription applies to.
+
+NOTE: **Note:**
+Please note that you need to be a group owner to associate a group to your
+subscription.
 
-To see the status of your GitLab.com subscription, you can click on the Billings
-section of the relevant namespace:
+### Confirm or upgrade your subscription
 
-* For individuals, this is located at https://gitlab.com/profile/billings under
-in your Settings,
-* For groups, this is located under the group's Settings dropdown, under Billing.
+To see the status of your GitLab.com subscription, you can click on the
+**Billings** section of the relevant namespace:
 
-For groups, you can see details of your subscription - including your current 
-plan - in the included table:
+- For individuals:
+  1. Go to **User Avatar > Settings**.
+  1. Click **Billing**.
+- For groups, go to the group's **Settings** dropdown, under **Billing**.
 
-![Billing table](billing_table.png)
+The following table describes details of your subscription for groups:
 
 | Field | Description |
 | ------ | ------ |
-| Seats in subscription | If this is a paid plan, this represents the number of seats you've paid to support in your group. |
-| Seats currently in use | The number of active seats currently in use. | 
-| Max seats used | The highest number of seats you've used. If this exceeds the seats in subscription, you may owe an additional fee for the additional users. | 
-| Seats owed | If your max seats used exceeds the seats in your subscription, you'll owe an additional fee for the users you've added. | 
-| Subscription start date | The date your subscription started. If this is for a Free plan, this is the date you transitioned off your group's paid plan. | 
-| Subscription end date | The date your current subscription will end. This does not apply to Free plans. | 
+| Seats in subscription | If this is a paid plan, represents the number of seats you've paid to support in your group. |
+| Seats currently in use | Number of active seats currently in use. |
+| Max seats used | Highest number of seats you've used. If this exceeds the seats in subscription, you may owe an additional fee for the additional users. |
+| Seats owed | If your max seats used exceeds the seats in your subscription, you'll owe an additional fee for the users you've added. |
+| Subscription start date | Date your subscription started. If this is for a Free plan, is the date you transitioned off your group's paid plan. |
+| Subscription end date | Date your current subscription will end. Does not apply to Free plans. |
 
-### Subscription changes and your data
+#### Extra Shared Runners pipeline minutes
 
-When your subscription or trial expires, GitLab does not delete your data, however, depending on the tier and feature, it may become inaccessible. Please note that some features may not behave as expected if a graceful fallback is not currently implemented, such as [environment specific variables not being passed](https://gitlab.com/gitlab-org/gitlab-ce/issues/52825).
+If you're using GitLab.com, you can purchase additional CI minutes so your
+pipelines will not be blocked after you have used all your CI minutes from your
+main quota. Additional minutes:
+
+- Are only used once the shared quota included in your subscription runs out.
+- Roll over month to month.
+
+In order to purchase additional minutes, you should follow these steps:
+
+1. Go to **Group > Settings > Pipelines quota**. Once you are on that page, click on **Buy additional minutes**.
+
+   ![Buy additional minutes](img/buy_btn.png)
+
+1. Locate the subscription card that is linked to your group on GitLab.com,
+   click on **Buy more CI minutes**, and complete the details about the transaction.
+
+   ![Buy additional minutes](img/buy_minutes_card.png)
+
+1. Once we have processed your payment, the extra CI minutes
+   will be synced to your Group and you can visualize it from the
+   **Group > Settings > Pipelines quota** page:
+
+   ![Additional minutes](img/additional_minutes.png)
+
+Be aware that:
+
+1. If you have purchased extra CI minutes before the purchase of a paid plan,
+   we will calculate a pro-rated charge for your paid plan. That means you may
+   be charged for less than one year since your subscription was previously
+   created with the extra CI minutes.
+1. Once the extra CI minutes has been assigned to a Group they cannot be transferred
+   to a different Group.
+1. If you have some minutes used over your default quota, these minutes will
+   be deducted from your Additional Minutes quota immediately after your purchase of additional
+   minutes.
+
+##### What happens when my CI minutes run out
+
+When the CI minutes run out, an email is sent automatically to notify the owner(s)
+of the group/namespace, including a link to [purchase more minutes](https://customers.gitlab.com/plans).
+
+If you are not the owner of the group, you will need to contact them to let them know they need to
+[purchase more minutes](https://customers.gitlab.com/plans).
+
+## Subscription changes and your data
+
+When your subscription or trial expires, GitLab does not delete your data.
+
+However, depending on the tier and feature, your data may become inaccessible.
+
+Please note that some features may not behave as expected if a graceful
+fallback is not currently implemented. For example,
+[environment specific variables not being passed](https://gitlab.com/gitlab-org/gitlab-ce/issues/52825).
 
 If you renew or upgrade, your data will again be accessible.
 
-For self-managed customers, there is a two-week grace period when your features will continue to work as-is, after which the entire instance will become read only. However, if you remove the license, you will immediately revert to Core features.
+### Self-managed data
+
+For self-managed customers, there is a two-week grace period when your features
+will continue to work as-is, after which the entire instance will become read
+only.
+
+However, if you remove the license, you will immediately revert to Core
+features.
 
 ## Need help?
 
-[GitLab's Documentation](https://docs.gitlab.com/) offers a wide range of topics covering the use and administration of GitLab.
+[GitLab's Documentation](https://docs.gitlab.com/) offers a wide range of
+topics covering the use and administration of GitLab.
 
-We also encourage all users to search our project trackers for known issues and existing feature requests in:
+We also encourage all users to search our project trackers for known issues and
+existing feature requests in:
 
-- [GitLab CE](https://gitlab.com/gitlab-org/gitlab-ce/issues/) for features included in all tiers, and
-- [GitLab EE](https://gitlab.com/gitlab-org/gitlab-ee/issues/) for paid-tier features.
+- [GitLab CE](https://gitlab.com/gitlab-org/gitlab-ce/issues/) for features
+  included in all tiers.
+- [GitLab EE](https://gitlab.com/gitlab-org/gitlab-ee/issues/) for paid-tier
+  features.
 
-These issues are the best avenue for getting updates on specific product plans and for communicating directly with the relevant GitLab team members.
+These issues are the best avenue for getting updates on specific product plans
+and for communicating directly with the relevant GitLab team members.
 
 ### Contacting Support
 
-Learn more about the tiers of [GitLab Support](https://about.gitlab.com/support/) or [submit a request via the Support Portal](https://support.gitlab.com/hc/en-us/requests/new).
+Learn more about:
+
+- The tiers of [GitLab Support](https://about.gitlab.com/support/).
+- [Submit a request via the Support Portal](https://support.gitlab.com/hc/en-us/requests/new).
 
 <!-- ## Troubleshooting
 
diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md
index a46f7d30892..1e9eb15533a 100644
--- a/doc/system_hooks/system_hooks.md
+++ b/doc/system_hooks/system_hooks.md
@@ -330,6 +330,7 @@ If the user is blocked via LDAP, `state` will be `ldap_blocked`.
        "user_id": 41
 }
 ```
+
 **Group Member Removed:**
 
 ```json
@@ -643,6 +644,11 @@ X-Gitlab-Event: System Hook
 }
 ```
 
+## Local requests in system hooks
+
+[Requests to local network by system hooks](../security/webhooks.md) can be allowed
+or blocked by an administrator.
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues
diff --git a/doc/tools/email.md b/doc/tools/email.md
index a2d677484f0..3088b0b63e7 100644
--- a/doc/tools/email.md
+++ b/doc/tools/email.md
@@ -2,7 +2,7 @@
 type: howto, reference
 ---
 
-# Email from GitLab **[STARTER ONLY]**
+# Email from GitLab **(STARTER ONLY)**
 
 GitLab provides a simple tool to administrators for emailing all users, or users of
 a chosen group or project, right from the admin area. Users will receive the email
@@ -19,12 +19,12 @@ at their primary email address.
 1. Go to the admin area using the wrench icon in the top right corner and
    navigate to **Overview > Users > Send email to users**.
 
-    ![admin users](email1.png)
+   ![admin users](email1.png)
 
 1. Compose an email and choose where it will be sent (all users or users of a
    chosen group or project):
 
-    ![compose an email](email2.png)
+   ![compose an email](email2.png)
 
 ## Unsubscribing from emails
 
diff --git a/doc/topics/application_development_platform/index.md b/doc/topics/application_development_platform/index.md
new file mode 100644
index 00000000000..2ea561eb943
--- /dev/null
+++ b/doc/topics/application_development_platform/index.md
@@ -0,0 +1,62 @@
+# Application Development Platform
+
+The GitLab Application Development Platform refers to the set of GitLab features used to create, configure, and manage
+a complete software development environment. It provides development, operations, and security teams with a robust feature set aimed at supporting best practices out of the box.
+
+## Overview
+
+The GitLab Application Development Platform aims to:
+
+- Reduce and even eliminate the time it takes for an Operations team
+  to provide a full environment for software developers.
+- Get developers up and running fast so they can focus on writing
+  great applications with a robust development feature set.
+- Provide best-of-breed security features so that applications developed
+  with GitLab are not affected by vulnerabilities that may lead to security
+  problems and unintended use.
+
+It is comprised of the following high-level elements:
+
+1. Compute
+1. Build, test, and deploy a wide range of applications
+1. Security
+1. Observability
+
+We believe the use of these common building blocks equate to big gains for teams of all sizes, resulting from the adoption
+of newer, more efficient, more profitable, and less error-prone techniques for shipping software applications.
+
+### Compute
+
+Because at GitLab we are [cloud-native first](https://about.gitlab.com/handbook/product/#cloud-native-first) our
+Application Development Platform initially focuses on providing robust support for Kubernetes, with other platforms
+to follow. Teams can bring their own clusters and we will additionally make it easy to create new infrastructure
+with various cloud providers.
+
+### Build, test, deploy
+
+In order to provide modern DevOps workflows, our Application Development Platform will rely on
+[Auto DevOps](../autodevops/index.md) to provide those workflows. Auto DevOps works with
+any Kubernetes cluster; you're not limited to running on GitLab's infrastructure. Additionally, Auto DevOps offers
+an incremental consumption path. Because it is [composable](../autodevops/index.md#using-components-of-auto-devops),
+you can use as much or as little of the default pipeline as you'd like, and deeply customize without having to integrate a completely different platform.
+
+### Security
+
+The Application Development Platform helps you ensure that the applications you create are not affected by vulnerabilities
+that may lead to security problems and unintended use. This can be achieved by making use of the embedded security features of Auto DevOps,
+which inform security teams and developers if there is something to consider changing in their apps
+before it is too late to create a preventative fix. The following features are included:
+
+- [Auto SAST (Static Application Security Testing)](../autodevops/index.md#auto-sast-ultimate)
+- [Auto Dependency Scanning](../autodevops/index.md#auto-dependency-scanning-ultimate)
+- [Auto Container Scanning](../autodevops/index.md#auto-container-scanning-ultimate)
+- [Auto DAST (Dynamic Application Security Testing)](../autodevops/index.md#auto-dast-ultimate)
+
+### Observability
+
+Performance is a critical aspect of the user experience, and ensuring your application is responsive and available is everyone's
+responsibility. The Application Development Platform integrates key performance analytics and feedback
+into GitLab, automatically. The following features are included:
+
+- [Auto Monitoring](../autodevops/index.md#auto-monitoring)
+- [In-app Kubernetes Pod Logs](../../user/project/clusters/kubernetes_pod_logs.md)
diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md
index 228da2d1f57..ad196e27f53 100644
--- a/doc/topics/authentication/index.md
+++ b/doc/topics/authentication/index.md
@@ -17,23 +17,23 @@ This page gathers all the resources for the topic **Authentication** within GitL
 ## GitLab administrators
 
 - [LDAP (Community Edition)](../../administration/auth/ldap.md)
-- [LDAP (Enterprise Edition)](../../administration/auth/ldap-ee.md) **[STARTER]**
+- [LDAP (Enterprise Edition)](../../administration/auth/ldap-ee.md) **(STARTER)**
 - [Enforce Two-factor Authentication (2FA)](../../security/two_factor_authentication.md#enforce-two-factor-authentication-2fa)
 - **Articles:**
   - [How to Configure LDAP with GitLab CE](../../administration/auth/how_to_configure_ldap_gitlab_ce/index.md)
-  - [How to Configure LDAP with GitLab EE](../../administration/auth/how_to_configure_ldap_gitlab_ee/index.md) **[STARTER]**
+  - [How to Configure LDAP with GitLab EE](../../administration/auth/how_to_configure_ldap_gitlab_ee/index.md) **(STARTER)**
   - [Feature Highlight: LDAP Integration](https://about.gitlab.com/2014/07/10/feature-highlight-ldap-sync/)
-  - [Debugging LDAP](https://about.gitlab.com/handbook/support/workflows/support-engineering/ldap/debugging_ldap.html)
+  - [Debugging LDAP](https://about.gitlab.com/handbook/support/workflows/debugging_ldap.html)
 - **Integrations:**
   - [OmniAuth](../../integration/omniauth.md)
   - [Authentiq OmniAuth Provider](../../administration/auth/authentiq.md#authentiq-omniauth-provider)
   - [Atlassian Crowd OmniAuth Provider](../../administration/auth/crowd.md)
   - [CAS OmniAuth Provider](../../integration/cas.md)
   - [SAML OmniAuth Provider](../../integration/saml.md)
-  - [SAML for GitLab.com Groups](../../user/group/saml_sso/index.md) **[SILVER ONLY]**
-  - [SCIM user provisioning for GitLab.com Groups](../../user/group/saml_sso/scim_setup.md) **[SILVER ONLY]**
+  - [SAML for GitLab.com Groups](../../user/group/saml_sso/index.md) **(SILVER ONLY)**
+  - [SCIM user provisioning for GitLab.com Groups](../../user/group/saml_sso/scim_setup.md) **(SILVER ONLY)**
   - [Okta SSO provider](../../administration/auth/okta.md)
-  - [Kerberos integration (GitLab EE)](../../integration/kerberos.md) **[STARTER]**
+  - [Kerberos integration (GitLab EE)](../../integration/kerberos.md) **(STARTER)**
 
 ## API
 
diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md
index 34140a3260e..4bfcd4aad96 100644
--- a/doc/topics/autodevops/index.md
+++ b/doc/topics/autodevops/index.md
@@ -1,6 +1,7 @@
 # Auto DevOps
 
-> [Introduced][ce-37115] in GitLab 10.0. Generally available on GitLab 11.0.
+> - [Introduced][ce-37115] in GitLab 10.0.
+> - Generally available on GitLab 11.0.
 
 Auto DevOps provides pre-defined CI/CD configuration which allows you to automatically detect, build, test,
 deploy, and monitor your applications. Leveraging CI/CD best practices and tools, Auto DevOps aims
@@ -43,16 +44,16 @@ platform or a Platform as a Service (PaaS). It takes inspiration from the
 innovative work done by [Heroku](https://www.heroku.com/) and goes beyond it
 in multiple ways:
 
-1. Auto DevOps works with any Kubernetes cluster; you're not limited to running
-   on GitLab's infrastructure. (Note that many features also work without Kubernetes.)
-1. There is no additional cost (no markup on the infrastructure costs), and you
-   can use a self-hosted Kubernetes cluster or Containers as a Service on any
-   public cloud (for example, [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/)).
-1. Auto DevOps has more features including security testing, performance testing,
-   and code quality testing.
-1. Auto DevOps offers an incremental graduation path. If you need advanced customizations,
-   you can start modifying the templates without having to start over on a
-   completely different platform. Review the [customizing](#customizing) section for more information.
+- Auto DevOps works with any Kubernetes cluster; you're not limited to running
+  on GitLab's infrastructure. (Note that many features also work without Kubernetes).
+- There is no additional cost (no markup on the infrastructure costs), and you
+  can use a self-hosted Kubernetes cluster or Containers as a Service on any
+  public cloud (for example, [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/)).
+- Auto DevOps has more features including security testing, performance testing,
+  and code quality testing.
+- Auto DevOps offers an incremental graduation path. If you need advanced customizations,
+  you can start modifying the templates without having to start over on a
+  completely different platform. Review the [customizing](#customizing) section for more information.
 
 ## Features
 
@@ -61,15 +62,15 @@ project in a simple and automatic way:
 
 1. [Auto Build](#auto-build)
 1. [Auto Test](#auto-test)
-1. [Auto Code Quality](#auto-code-quality-starter) **[STARTER]**
-1. [Auto SAST (Static Application Security Testing)](#auto-sast-ultimate) **[ULTIMATE]**
-1. [Auto Dependency Scanning](#auto-dependency-scanning-ultimate) **[ULTIMATE]**
-1. [Auto License Management](#auto-license-management-ultimate) **[ULTIMATE]**
-1. [Auto Container Scanning](#auto-container-scanning-ultimate) **[ULTIMATE]**
+1. [Auto Code Quality](#auto-code-quality-starter) **(STARTER)**
+1. [Auto SAST (Static Application Security Testing)](#auto-sast-ultimate) **(ULTIMATE)**
+1. [Auto Dependency Scanning](#auto-dependency-scanning-ultimate) **(ULTIMATE)**
+1. [Auto License Management](#auto-license-management-ultimate) **(ULTIMATE)**
+1. [Auto Container Scanning](#auto-container-scanning-ultimate) **(ULTIMATE)**
 1. [Auto Review Apps](#auto-review-apps)
-1. [Auto DAST (Dynamic Application Security Testing)](#auto-dast-ultimate) **[ULTIMATE]**
+1. [Auto DAST (Dynamic Application Security Testing)](#auto-dast-ultimate) **(ULTIMATE)**
 1. [Auto Deploy](#auto-deploy)
-1. [Auto Browser Performance Testing](#auto-browser-performance-testing-premium) **[PREMIUM]**
+1. [Auto Browser Performance Testing](#auto-browser-performance-testing-premium) **(PREMIUM)**
 1. [Auto Monitoring](#auto-monitoring)
 
 As Auto DevOps relies on many different components, it's good to have a basic
@@ -86,42 +87,46 @@ Auto DevOps provides great defaults for all the stages; you can, however,
 
 For an overview on the creation of Auto DevOps, read the blog post [From 2/3 of the Self-Hosted Git Market, to the Next-Generation CI System, to Auto DevOps](https://about.gitlab.com/2017/06/29/whats-next-for-gitlab-ci/).
 
+NOTE: **Note**
+Kubernetes clusters can [be used without](../../user/project/clusters/index.md)
+Auto DevOps.
+
 ## Requirements
 
 To make full use of Auto DevOps, you will need:
 
-1. **GitLab Runner** (needed for all stages) - Your Runner needs to be
-   configured to be able to run Docker. Generally this means using the
-   [Docker](https://docs.gitlab.com/runner/executors/docker.html) or [Kubernetes
-   executor](https://docs.gitlab.com/runner/executors/kubernetes.html), with
-   [privileged mode enabled](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode).
-   The Runners do not need to be installed in the Kubernetes cluster, but the
-   Kubernetes executor is easy to use and is automatically autoscaling.
-   Docker-based Runners can be configured to autoscale as well, using [Docker
-   Machine](https://docs.gitlab.com/runner/install/autoscaling.html). Runners
-   should be registered as [shared Runners](../../ci/runners/README.md#registering-a-shared-runner)
-   for the entire GitLab instance, or [specific Runners](../../ci/runners/README.md#registering-a-specific-runner)
-   that are assigned to specific projects.
-1. **Base domain** (needed for Auto Review Apps and Auto Deploy) - You will need
-   a domain configured with wildcard DNS which is going to be used by all of your
-   Auto DevOps applications. [Read the specifics](#auto-devops-base-domain).
-1. **Kubernetes** (needed for Auto Review Apps, Auto Deploy, and Auto Monitoring) -
-   To enable deployments, you will need Kubernetes 1.5+. You need a [Kubernetes cluster][kubernetes-clusters]
-   for the project, or a Kubernetes [default service template](../../user/project/integrations/services_templates.md)
-   for the entire GitLab installation.
-    1. **A load balancer** - You can use NGINX ingress by deploying it to your
-       Kubernetes cluster using the
-       [`nginx-ingress`](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress)
-       Helm chart.
-1. **Prometheus** (needed for Auto Monitoring) - To enable Auto Monitoring, you
-   will need Prometheus installed somewhere (inside or outside your cluster) and
-   configured to scrape your Kubernetes cluster. To get response metrics
-   (in addition to system metrics), you need to
-   [configure Prometheus to monitor NGINX](../../user/project/integrations/prometheus_library/nginx_ingress.md#configuring-nginx-ingress-monitoring).
-   The [Prometheus service](../../user/project/integrations/prometheus.md)
-   integration needs to be enabled for the project, or enabled as a
-   [default service template](../../user/project/integrations/services_templates.md)
-   for the entire GitLab installation.
+- **GitLab Runner** (needed for all stages) - Your Runner needs to be
+  configured to be able to run Docker. Generally this means using the
+  [Docker](https://docs.gitlab.com/runner/executors/docker.html) or [Kubernetes
+  executor](https://docs.gitlab.com/runner/executors/kubernetes.html), with
+  [privileged mode enabled](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode).
+  The Runners do not need to be installed in the Kubernetes cluster, but the
+  Kubernetes executor is easy to use and is automatically autoscaling.
+  Docker-based Runners can be configured to autoscale as well, using [Docker
+  Machine](https://docs.gitlab.com/runner/install/autoscaling.html). Runners
+  should be registered as [shared Runners](../../ci/runners/README.md#registering-a-shared-runner)
+  for the entire GitLab instance, or [specific Runners](../../ci/runners/README.md#registering-a-specific-runner)
+  that are assigned to specific projects.
+- **Base domain** (needed for Auto Review Apps and Auto Deploy) - You will need
+  a domain configured with wildcard DNS which is going to be used by all of your
+  Auto DevOps applications. [Read the specifics](#auto-devops-base-domain).
+- **Kubernetes** (needed for Auto Review Apps, Auto Deploy, and Auto Monitoring) -
+  To enable deployments, you will need Kubernetes 1.5+. You need a [Kubernetes cluster][kubernetes-clusters]
+  for the project, or a Kubernetes [default service template](../../user/project/integrations/services_templates.md)
+  for the entire GitLab installation.
+  - **A load balancer** - You can use NGINX ingress by deploying it to your
+    Kubernetes cluster using the
+    [`nginx-ingress`](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress)
+    Helm chart.
+- **Prometheus** (needed for Auto Monitoring) - To enable Auto Monitoring, you
+  will need Prometheus installed somewhere (inside or outside your cluster) and
+  configured to scrape your Kubernetes cluster. To get response metrics
+  (in addition to system metrics), you need to
+  [configure Prometheus to monitor NGINX](../../user/project/integrations/prometheus_library/nginx_ingress.md#configuring-nginx-ingress-monitoring).
+  The [Prometheus service](../../user/project/integrations/prometheus.md)
+  integration needs to be enabled for the project, or enabled as a
+  [default service template](../../user/project/integrations/services_templates.md)
+  for the entire GitLab installation.
 
 If you do not have Kubernetes or Prometheus installed, then Auto Review Apps,
 Auto Deploy, and Auto Monitoring will be silently skipped.
@@ -147,7 +152,7 @@ NOTE: **Note**
 A wildcard DNS A record matching the base domain(s) is required, for example,
 given a base domain of `example.com`, you'd need a DNS entry like:
 
-```
+```text
 *.example.com   3600     A     1.2.3.4
 ```
 
@@ -168,15 +173,14 @@ From GitLab 11.8, `KUBE_INGRESS_BASE_DOMAIN` replaces `AUTO_DEVOPS_DOMAIN`.
 Support for `AUTO_DEVOPS_DOMAIN` was [removed in GitLab
 12.0](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959).
 
-
-## Using multiple Kubernetes clusters **[PREMIUM]**
+## Using multiple Kubernetes clusters **(PREMIUM)**
 
 When using Auto DevOps, you may want to deploy different environments to
 different Kubernetes clusters. This is possible due to the 1:1 connection that
 [exists between them](../../user/project/clusters/index.md#multiple-kubernetes-clusters-premium).
 
-In the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml)
-(used behind the scenes by Auto DevOps), there are currently 3 defined environment names that you need to know:
+In the [Auto DevOps template] (used behind the scenes by Auto DevOps), there
+are currently 3 defined environment names that you need to know:
 
 - `review/` (every environment starting with `review/`)
 - `staging`
@@ -186,23 +190,23 @@ Those environments are tied to jobs that use [Auto Deploy](#auto-deploy), so
 except for the environment scope, they would also need to have a different
 domain they would be deployed to. This is why you need to define a separate
 `KUBE_INGRESS_BASE_DOMAIN` variable for all the above
-[based on the environment](../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables-premium).
+[based on the environment](../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables).
 
 The following table is an example of how the three different clusters would
 be configured.
 
 | Cluster name | Cluster environment scope | `KUBE_INGRESS_BASE_DOMAIN` variable value | Variable environment scope | Notes |
-| ------------ | -------------- | ----------------------------- | ------------- | ------ |
-| review       |  `review/*`    | `review.example.com`  | `review/*`      | The review cluster which will run all [Review Apps](../../ci/review_apps/index.md). `*` is a wildcard, which means it will be used by every environment name starting with `review/`. |
-| staging      |  `staging`     | `staging.example.com` | `staging`       | (Optional) The staging cluster which will run the deployments of the staging environments. You need to [enable it first](#deploy-policy-for-staging-and-production-environments). |
-| production   |  `production`  | `example.com`         | `production`    | The production cluster which will run the deployments of the production environment. You can use [incremental rollouts](#incremental-rollout-to-production-premium). |
+|--------------|---------------------------|-------------------------------------------|----------------------------|---|
+| review       | `review/*`                | `review.example.com`                      | `review/*`                 | The review cluster which will run all [Review Apps](../../ci/review_apps/index.md). `*` is a wildcard, which means it will be used by every environment name starting with `review/`. |
+| staging      | `staging`                 | `staging.example.com`                     | `staging`                  | (Optional) The staging cluster which will run the deployments of the staging environments. You need to [enable it first](#deploy-policy-for-staging-and-production-environments). |
+| production   | `production`              | `example.com`                             | `production`               | The production cluster which will run the deployments of the production environment. You can use [incremental rollouts](#incremental-rollout-to-production-premium). |
 
 To add a different cluster for each environment:
 
 1. Navigate to your project's **Operations > Kubernetes** and create the Kubernetes clusters
    with their respective environment scope as described from the table above.
 
-    ![Auto DevOps multiple clusters](img/autodevops_multiple_clusters.png)
+   ![Auto DevOps multiple clusters](img/autodevops_multiple_clusters.png)
 
 1. After the clusters are created, navigate to each one and install Helm Tiller
    and Ingress. Wait for the Ingress IP address to be assigned.
@@ -223,9 +227,9 @@ full use of Auto DevOps are available. If this is your fist time, we recommend y
 [quick start guide](quick_start_guide.md).
 
 GitLab.com users can enable/disable Auto DevOps at the project-level only. Self-managed users
-can enable/disable Auto DevOps at either the project-level or instance-level.
+can enable/disable Auto DevOps at the project-level, group-level or instance-level.
 
-### Enabling/disabling Auto DevOps at the instance-level (Administrators only)
+### At the instance level (Administrators only)
 
 Even when disabled at the instance level, group owners and project maintainers can still enable
 Auto DevOps at the group and project level, respectively.
@@ -235,7 +239,7 @@ Auto DevOps at the group and project level, respectively.
 1. If enabling, optionally set up the Auto DevOps [base domain](#auto-devops-base-domain) which will be used for Auto Deploy and Auto Review Apps.
 1. Click **Save changes** for the changes to take effect.
 
-### Enabling/disabling Auto DevOps at the group-level
+### At the group level
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/52447) in GitLab 11.10.
 
@@ -251,7 +255,7 @@ When enabling or disabling Auto DevOps at group-level, group configuration will
 the subgroups and projects inside that group, unless Auto DevOps is specifically enabled or disabled on
 the subgroup or project.
 
-### Enabling/disabling Auto DevOps at the project-level
+### At the project level
 
 If enabling, check that your project doesn't have a `.gitlab-ci.yml`, or if one exists, remove it.
 
@@ -264,7 +268,7 @@ If enabling, check that your project doesn't have a `.gitlab-ci.yml`, or if one
 
 When the feature has been enabled, an Auto DevOps pipeline is triggered on the default branch.
 
-### Feature flag to enable for a percentage of projects
+### Enable for a percentage of projects
 
 There is also a feature flag to enable Auto DevOps by default to your chosen percentage of projects.
 
@@ -315,7 +319,8 @@ If a project's repository contains a `Dockerfile`, Auto Build will use
 
 If you are also using Auto Review Apps and Auto Deploy and choose to provide
 your own `Dockerfile`, make sure you expose your application to port
-`5000` as this is the port assumed by the default Helm chart.
+`5000` as this is the port assumed by the
+[default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app). Alternatively you can override the default values by [customizing the Auto Deploy helm chart](#custom-helm-chart)
 
 #### Auto Build using Heroku buildpacks
 
@@ -353,7 +358,7 @@ you may succeed with a [custom buildpack](#custom-buildpacks). Check the
 Auto Test uses tests you already have in your application. If there are no
 tests, it's up to you to add them.
 
-### Auto Code Quality **[STARTER]**
+### Auto Code Quality **(STARTER)**
 
 Auto Code Quality uses the
 [Code Quality image](https://gitlab.com/gitlab-org/security-products/codequality) to run
@@ -364,14 +369,14 @@ out.
 Any differences between the source and target branches are also
 [shown in the merge request widget](../../user/project/merge_requests/code_quality.md).
 
-### Auto SAST **[ULTIMATE]**
+### Auto SAST **(ULTIMATE)**
 
 > Introduced in [GitLab Ultimate][ee] 10.3.
 
 Static Application Security Testing (SAST) uses the
 [SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast) to run static
 analysis on the current code and checks for potential security issues. The
-the Auto SAST stage will be skipped on licenses other than Ultimate and requires GitLab Runner 11.5 or above.
+Auto SAST stage will be skipped on licenses other than Ultimate and requires GitLab Runner 11.5 or above.
 
 Once the report is created, it's uploaded as an artifact which you can later download and
 check out.
@@ -379,7 +384,7 @@ check out.
 Any security warnings are also shown in the merge request widget. Read more how
 [SAST works](../../user/application_security/sast/index.md).
 
-### Auto Dependency Scanning **[ULTIMATE]**
+### Auto Dependency Scanning **(ULTIMATE)**
 
 > Introduced in [GitLab Ultimate][ee] 10.7.
 
@@ -396,7 +401,7 @@ check out.
 Any security warnings are also shown in the merge request widget. Read more about
 [Dependency Scanning](../../user/application_security/dependency_scanning/index.md).
 
-### Auto License Management **[ULTIMATE]**
+### Auto License Management **(ULTIMATE)**
 
 > Introduced in [GitLab Ultimate][ee] 11.0.
 
@@ -412,7 +417,7 @@ check out.
 Any licenses are also shown in the merge request widget. Read more how
 [License Management works](../../user/application_security/license_management/index.md).
 
-### Auto Container Scanning **[ULTIMATE]**
+### Auto Container Scanning **(ULTIMATE)**
 
 > Introduced in GitLab 10.4.
 
@@ -451,7 +456,7 @@ be deleted.
 
 Review apps are deployed using the
 [auto-deploy-app](https://gitlab.com/gitlab-org/charts/auto-deploy-app) chart with
-Helm. The app will be deployed into the [Kubernetes
+Helm, which can be [customized](#custom-helm-chart). The app will be deployed into the [Kubernetes
 namespace](../../user/project/clusters/index.md#deployment-variables)
 for the environment.
 
@@ -467,7 +472,7 @@ deploys with Auto DevOps can undo your changes. Also, if you change something
 and want to undo it by deploying again, Helm may not detect that anything changed
 in the first place, and thus not realize that it needs to re-apply the old config.
 
-### Auto DAST **[ULTIMATE]**
+### Auto DAST **(ULTIMATE)**
 
 > Introduced in [GitLab Ultimate][ee] 10.4.
 
@@ -482,13 +487,13 @@ later download and check out.
 Any security warnings are also shown in the merge request widget. Read how
 [DAST works](../../user/application_security/dast/index.md).
 
-### Auto Browser Performance Testing **[PREMIUM]**
+### Auto Browser Performance Testing **(PREMIUM)**
 
 > Introduced in [GitLab Premium][ee] 10.4.
 
 Auto Browser Performance Testing utilizes the [Sitespeed.io container](https://hub.docker.com/r/sitespeedio/sitespeed.io/) to measure the performance of a web page. A JSON report is created and uploaded as an artifact, which includes the overall performance score for each page. By default, the root page of Review and Production environments will be tested. If you would like to add additional URL's to test, simply add the paths to a file named `.gitlab-urls.txt` in the root directory, one per line. For example:
 
-```
+```text
 /
 /features
 /direction
@@ -513,7 +518,7 @@ Auto Deploy doesn't include deployments to staging or canary by default, but the
 enable them.
 
 You can make use of [environment variables](#environment-variables) to automatically
-scale your pod replicas.
+scale your pod replicas and to apply custom arguments to the Auto DevOps `helm upgrade` commands. This is an easy way to [customize the Auto Deploy helm chart](#custom-helm-chart).
 
 Apps are deployed using the
 [auto-deploy-app](https://gitlab.com/gitlab-org/charts/auto-deploy-app) chart with
@@ -579,6 +584,52 @@ Unless you have a `Dockerfile` in your repo, your image is built with
 Herokuish, and you must prefix commands run in these images with `/bin/herokuish
 procfile exec` to replicate the environment where your application will run.
 
+#### Workers
+
+Some web applications need to run extra deployments for "worker processes". For
+example it is common in a Rails application to have a separate worker process
+to run background tasks like sending emails.
+
+The [default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app)
+used in Auto Deploy [has support for running worker
+processes](https://gitlab.com/gitlab-org/charts/auto-deploy-app/merge_requests/9).
+
+In order to run a worker you'll need to ensure that it is able to respond to
+the standard health checks which expect a successful HTTP response on port
+`5000`. For sidekiq you could make use of the
+[sidekiq_alive gem](https://rubygems.org/gems/sidekiq_alive) to do this. 
+
+In order to work with sidekiq you'll also need to ensure your deployments have
+access to a redis instance. Auto DevOps won't deploy this for you so you'll
+need to manage this separately and then set a CI variable
+`K8S_SECRET_REDIS_URL` which the URL of this instance to ensure it's passed
+into your deployments.
+
+Once you have configured your worker to respond to health checks you you will
+need to configure a CI variable `HELM_UPGRADE_EXTRA_ARGS` with the value
+`--values helm-values.yaml`. Then you can, for example, run a
+[sidekiq](https://github.com/mperham/sidekiq) worker for your rails application
+by adding a file named `helm-values.yaml` to your repo with the following
+content:
+
+```yml
+workers:
+  sidekiq:
+    replicaCount: 1
+    command:
+    - /bin/herokuish
+    - procfile
+    - exec
+    - sidekiq
+    preStopCommand:
+    - /bin/herokuish
+    - procfile
+    - exec
+    - sidekiqctl
+    - quiet
+    terminationGracePeriodSeconds: 60
+```
+
 ### Auto Monitoring
 
 See the [requirements](#requirements) for Auto Monitoring to enable this stage.
@@ -654,32 +705,38 @@ repo or by specifying a project variable:
 - **Project variable** - Create a [project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables)
   `AUTO_DEVOPS_CHART` with the URL of a custom chart to use or create two project variables `AUTO_DEVOPS_CHART_REPOSITORY` with the URL of a custom chart repository and `AUTO_DEVOPS_CHART` with the path to the chart.
 
-### Custom Helm chart per environment **[PREMIUM]**
+You can also make use of the `HELM_UPGRADE_EXTRA_ARGS` environment variable to override the default values in the `values.yaml` file in the [default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app).
+To apply your own `values.yaml` file to all Helm upgrade commands in Auto Deploy set `HELM_UPGRADE_EXTRA_ARGS` to `--values my-values.yaml`.
+
+### Custom Helm chart per environment
 
 You can specify the use of a custom Helm chart per environment by scoping the environment variable
-to the desired environment. See [Limiting environment scopes of variables](../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables-premium).
+to the desired environment. See [Limiting environment scopes of variables](../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables).
 
 ### Customizing `.gitlab-ci.yml`
 
-If you want to modify the CI/CD pipeline used by Auto DevOps, you can copy the
-[Auto DevOps template] into your project's repo and edit as you see fit.
+Auto DevOps is completely customizable because the [Auto DevOps template]:
+
+- Is just an implementation of a [`.gitlab-ci.yml`](../../ci/yaml/README.md) file.
+- Uses only features available to any implementation of `.gitlab-ci.yml`.
 
-Assuming that your project is new or it doesn't have a `.gitlab-ci.yml` file
-present:
+If you want to modify the CI/CD pipeline used by Auto DevOps, you can [`include`
+the template](../../ci/yaml/README.md#includetemplate) and customize as
+needed. To do this, add a `.gitlab-ci.yml` file to the root of your repository
+containing the following:
+
+```yml
+include:
+  - template: Auto-DevOps.gitlab-ci.yml
+```
 
-1. From your project home page, either click on the "Set up CI/CD" button, or click
-   on the plus button and (`+`), then "New file"
-1. Pick `.gitlab-ci.yml` as the template type
-1. Select "Auto-DevOps" from the template dropdown
-1. Edit the template or add any jobs needed
-1. Give an appropriate commit message and hit "Commit changes"
+Then add any extra changes you want. Your additions will be merged with the
+[Auto DevOps template] using the behaviour described for
+[`include`](../../ci/yaml/README.md#include).
 
-TIP: **Tip:** The Auto DevOps template includes useful comments to help you
-customize it. For example, if you want deployments to go to a staging environment
-instead of directly to a production one, you can enable the `staging` job by
-renaming `.staging` to `staging`. Then make sure to uncomment the `when` key of
-the `production` job to turn it into a manual action instead of deploying
-automatically.
+It is also possible to copy and paste the contents of the [Auto DevOps
+template] into your project and edit this as needed. You may prefer to do it
+that way if you want to specifically remove any part of it.
 
 ### Using components of Auto-DevOps
 
@@ -714,46 +771,34 @@ The following variables can be used for setting up the Auto DevOps domain,
 providing a custom Helm chart, or scaling your application. PostgreSQL can
 also be customized, and you can easily use a [custom buildpack](#custom-buildpacks).
 
-| **Variable**                 | **Description**                                                                                                                                                                                                               |
-| ------------                 | ---------------                                                                                                                                                                                                               |
-| `AUTO_DEVOPS_CHART`          | The Helm Chart used to deploy your apps; defaults to the one [provided by GitLab](https://gitlab.com/gitlab-org/charts/auto-deploy-app).                                                             |
-| `AUTO_DEVOPS_CHART_REPOSITORY` | The Helm Chart repository used to search for charts; defaults to `https://charts.gitlab.io`. |
-| `AUTO_DEVOPS_CHART_REPOSITORY_NAME` | From Gitlab 11.11, this variable can be used to set the name of the helm repository; defaults to "gitlab" |
-| `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME` | From Gitlab 11.11, this variable can be used to set a username to connect to the helm repository. Defaults to no credentials. (Also set AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD) |
-| `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD` | From Gitlab 11.11, this variable can be used to set a password to connect to the helm repository. Defaults to no credentials. (Also set AUTO_DEVOPS_CHART_REPOSITORY_USERNAME) |
-| `REPLICAS`                   | The number of replicas to deploy; defaults to 1.                                                                                                                                                                              |
-| `PRODUCTION_REPLICAS`        | The number of replicas to deploy in the production environment. This takes precedence over `REPLICAS`; defaults to 1.                                                                                                         |
-| `CANARY_REPLICAS`            | The number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md); defaults to 1                                                                              |
-| `CANARY_PRODUCTION_REPLICAS` | The number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md) in the production environment. This takes precedence over `CANARY_REPLICAS`; defaults to 1  |
-| `ADDITIONAL_HOSTS`           | Fully qualified domain names specified as a comma-separated list that are added to the ingress hosts.                                                                                                                         |
-| `<ENVIRONMENT>_ADDITIONAL_HOSTS` | For a specific environment, the fully qualified domain names specified as a comma-separated list that are added to the ingress hosts. This takes precedence over `ADDITIONAL_HOSTS`.                                      |
-| `POSTGRES_ENABLED`           | Whether PostgreSQL is enabled; defaults to `"true"`. Set to `false` to disable the automatic deployment of PostgreSQL.                                                                                                        |
-| `POSTGRES_USER`              | The PostgreSQL user; defaults to `user`. Set it to use a custom username.                                                                                                                                                     |
-| `POSTGRES_PASSWORD`          | The PostgreSQL password; defaults to `testing-password`. Set it to use a custom password.                                                                                                                                     |
-| `POSTGRES_DB`                | The PostgreSQL database name; defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-environment-variables). Set it to use a custom database name.                               |
-| `POSTGRES_VERSION`           | Tag for the [`postgres` Docker image](https://hub.docker.com/_/postgres) to use. Defaults to `9.6.2`. |
-| `BUILDPACK_URL`              | The buildpack's full URL. It can point to either Git repositories or a tarball URL. For Git repositories, it is possible to point to a specific `ref`, for example `https://github.com/heroku/heroku-buildpack-ruby.git#v142` |
-| `SAST_CONFIDENCE_LEVEL`      | The minimum confidence level of security issues you want to be reported; `1` for Low, `2` for Medium, `3` for High; defaults to `3`.|
-| `DEP_SCAN_DISABLE_REMOTE_CHECKS` | Whether remote Dependency Scanning checks are disabled; defaults to `"false"`. Set to `"true"` to disable checks that send data to GitLab central servers. [Read more about remote checks](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks).|
-| `DB_INITIALIZE`              | From GitLab 11.4, this variable can be used to specify the command to run to initialize the application's PostgreSQL database. It runs inside the application pod. |
-| `DB_MIGRATE`                 | From GitLab 11.4, this variable can be used to specify the command to run to migrate the application's PostgreSQL database. It runs inside the application pod. |
-| `STAGING_ENABLED`            | From GitLab 10.8, this variable can be used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). |
-| `CANARY_ENABLED`             | From GitLab 11.0, this variable can be used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments-premium). |
-| `INCREMENTAL_ROLLOUT_MODE`| From GitLab 11.4, this variable, if present, can be used to enable an [incremental rollout](#incremental-rollout-to-production-premium) of your application for the production environment.<br/>Set to: <ul><li>`manual`, for manual deployment jobs.</li><li>`timed`, for automatic rollout deployments with a 5 minute delay each one.</li></ul> |
-| `TEST_DISABLED`              | From GitLab 11.0, this variable can be used to disable the `test` job. If the variable is present, the job will not be created. |
-| `CODE_QUALITY_DISABLED`       | From GitLab 11.0, this variable can be used to disable the `codequality` job. If the variable is present, the job will not be created. |
-| `LICENSE_MANAGEMENT_DISABLED` | From GitLab 11.0, this variable can be used to disable the `license_management` job. If the variable is present, the job will not be created. |
-| `SAST_DISABLED`              | From GitLab 11.0, this variable can be used to disable the `sast` job. If the variable is present, the job will not be created. |
-| `DEPENDENCY_SCANNING_DISABLED` | From GitLab 11.0, this variable can be used to disable the `dependency_scanning` job. If the variable is present, the job will not be created. |
-| `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0, this variable can be used to disable the `sast:container` job. If the variable is present, the job will not be created. |
-| `REVIEW_DISABLED`            | From GitLab 11.0, this variable can be used to disable the `review` and the manual `review:stop` job. If the variable is present, these jobs will not be created. |
-| `DAST_DISABLED`              | From GitLab 11.0, this variable can be used to disable the `dast` job. If the variable is present, the job will not be created. |
-| `PERFORMANCE_DISABLED`       | From GitLab 11.0, this variable can be used to disable the `performance` job. If the variable is present, the job will not be created. |
-| `K8S_SECRET_*`               | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) will be made available by Auto DevOps as environment variables to the deployed application. |
-| `KUBE_INGRESS_BASE_DOMAIN`   | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/index.md#base-domain) for more information. |
-| `ROLLOUT_RESOURCE_TYPE`     | From GitLab 11.9, this variable allows specification of the resource type being deployed when using a custom helm chart. Default value is `deployment`. |
-| `ROLLOUT_STATUS_DISABLED`   | From GitLab 12.0, this variable allows to disable rollout status check because it doesn't support all resource types, for example, `cronjob`. |
-| `HELM_UPGRADE_EXTRA_ARGS`   | From GitLab 11.11, this variable allows extra arguments in `helm` commands when deploying the application. Note that using quotes will not prevent word splitting. |
+#### Build and deployment
+
+The following table lists variables related to building and deploying
+applications.
+
+| **Variable**                            | **Description**                    |
+|-----------------------------------------|------------------------------------|
+| `ADDITIONAL_HOSTS`                      | Fully qualified domain names specified as a comma-separated list that are added to the ingress hosts. |
+| `<ENVIRONMENT>_ADDITIONAL_HOSTS`        | For a specific environment, the fully qualified domain names specified as a comma-separated list that are added to the ingress hosts. This takes precedence over `ADDITIONAL_HOSTS`. |
+| `AUTO_DEVOPS_CHART`                     | Helm Chart used to deploy your apps. Defaults to the one [provided by GitLab](https://gitlab.com/gitlab-org/charts/auto-deploy-app). |
+| `AUTO_DEVOPS_CHART_REPOSITORY`          | Helm Chart repository used to search for charts. Defaults to `https://charts.gitlab.io`. |
+| `AUTO_DEVOPS_CHART_REPOSITORY_NAME`     | From Gitlab 11.11, used to set the name of the helm repository. Defaults to `gitlab`. |
+| `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME` | From Gitlab 11.11, used to set a username to connect to the helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD`. |
+| `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD` | From Gitlab 11.11, used to set a password to connect to the helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME`. |
+| `BUILDPACK_URL`                         | Buildpack's full URL. Can point to either Git repositories or a tarball URL. For Git repositories, it is possible to point to a specific `ref`. For example `https://github.com/heroku/heroku-buildpack-ruby.git#v142`. |
+| `CANARY_ENABLED`                        | From GitLab 11.0, used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments-premium). |
+| `CANARY_PRODUCTION_REPLICAS`            | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md) in the production environment. Takes precedence over `CANARY_REPLICAS`. Defaults to 1. |
+| `CANARY_REPLICAS`                       | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md). Defaults to 1. |
+| `HELM_RELEASE_NAME`                     | From GitLab 12.1, allows the `helm` release name to be overridden. Can be used to assign unique release names when deploying multiple projects to a single namespace. |
+| `HELM_UPGRADE_EXTRA_ARGS`               | From GitLab 11.11, allows extra arguments in `helm` commands when deploying the application. Note that using quotes will not prevent word splitting. **Tip:** you can use this variable to [customize the Auto Deploy helm chart](#custom-helm-chart) by applying custom override values with `--values my-values.yaml`. |
+| `INCREMENTAL_ROLLOUT_MODE`              | From GitLab 11.4, if present, can be used to enable an [incremental rollout](#incremental-rollout-to-production-premium) of your application for the production environment. Set to `manual` for manual deployment jobs or `timed` for automatic rollout deployments with a 5 minute delay each one. |
+| `K8S_SECRET_*`                          | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) will be made available by Auto DevOps as environment variables to the deployed application. |
+| `KUBE_INGRESS_BASE_DOMAIN`              | From GitLab 11.8, can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/index.md#base-domain) for more information. |
+| `PRODUCTION_REPLICAS`                   | Number of replicas to deploy in the production environment. Takes precedence over `REPLICAS` and defaults to 1. For zero downtime upgrades, set to 2 or greater. |
+| `REPLICAS`                              | Number of replicas to deploy. Defaults to 1. |
+| `ROLLOUT_RESOURCE_TYPE`                 | From GitLab 11.9, allows specification of the resource type being deployed when using a custom helm chart. Default value is `deployment`. |
+| `ROLLOUT_STATUS_DISABLED`               | From GitLab 12.0, used to disable rollout status check because it doesn't support all resource types, for example, `cronjob`. |
+| `STAGING_ENABLED`                       | From GitLab 10.8, used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). |
 
 TIP: **Tip:**
 Set up the replica variables using a
@@ -765,6 +810,42 @@ You should *not* scale your application using Kubernetes directly. This can
 cause confusion with Helm not detecting the change, and subsequent deploys with
 Auto DevOps can undo your changes.
 
+#### Database
+
+The following table lists variables related to the database.
+
+| **Variable**                            | **Description**                    |
+| `DB_INITIALIZE`                         | From GitLab 11.4, used to specify the command to run to initialize the application's PostgreSQL database. Runs inside the application pod. |
+| `DB_MIGRATE`                            | From GitLab 11.4, used to specify the command to run to migrate the application's PostgreSQL database. Runs inside the application pod. |
+| `POSTGRES_ENABLED`                      | Whether PostgreSQL is enabled. Defaults to `"true"`. Set to `false` to disable the automatic deployment of PostgreSQL. |
+| `POSTGRES_USER`                         | The PostgreSQL user. Defaults to `user`. Set it to use a custom username. |
+| `POSTGRES_PASSWORD`                     | The PostgreSQL password. Defaults to `testing-password`. Set it to use a custom password. |
+| `POSTGRES_DB`                           | The PostgreSQL database name. Defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-environment-variables). Set it to use a custom database name. |
+| `POSTGRES_VERSION`                      | Tag for the [`postgres` Docker image](https://hub.docker.com/_/postgres) to use. Defaults to `9.6.2`. |
+
+#### Security tools
+
+The following table lists variables related to security tools.
+
+| **Variable**                            | **Description**                    |
+| `SAST_CONFIDENCE_LEVEL`                 | Minimum confidence level of security issues you want to be reported; `1` for Low, `2` for Medium, `3` for High. Defaults to `3`. |
+| `DS_DISABLE_REMOTE_CHECKS`              | Whether remote Dependency Scanning checks are disabled. Defaults to `"false"`. Set to `"true"` to disable checks that send data to GitLab central servers. [Read more about remote checks](../../user/application_security/dependency_scanning/index.md#remote-checks). |
+
+#### Disable jobs
+
+The following table lists variables used to disable jobs.
+
+| **Variable**                            | **Description**                    |
+| `CODE_QUALITY_DISABLED`                 | From GitLab 11.0, used to disable the `codequality` job. If the variable is present, the job will not be created. |
+| `CONTAINER_SCANNING_DISABLED`           | From GitLab 11.0, used to disable the `sast:container` job. If the variable is present, the job will not be created. |
+| `DAST_DISABLED`                         | From GitLab 11.0, used to disable the `dast` job. If the variable is present, the job will not be created. |
+| `DEPENDENCY_SCANNING_DISABLED`          | From GitLab 11.0, used to disable the `dependency_scanning` job. If the variable is present, the job will not be created. |
+| `LICENSE_MANAGEMENT_DISABLED`           | From GitLab 11.0, used to disable the `license_management` job. If the variable is present, the job will not be created. |
+| `PERFORMANCE_DISABLED`                  | From GitLab 11.0, used to disable the `performance` job. If the variable is present, the job will not be created. |
+| `REVIEW_DISABLED`                       | From GitLab 11.0, used to disable the `review` and the manual `review:stop` job. If the variable is present, these jobs will not be created. |
+| `SAST_DISABLED`                         | From GitLab 11.0, used to disable the `sast` job. If the variable is present, the job will not be created. |
+| `TEST_DISABLED`                         | From GitLab 11.0, used to disable the `test` job. If the variable is present, the job will not be created. |
+
 #### Application secret variables
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/49056) in GitLab 11.7.
@@ -779,11 +860,11 @@ To configure your application variables:
 1. Go to your project's **Settings > CI/CD**, then expand the section
    called **Variables**.
 
-2. Create a CI Variable, ensuring the key is prefixed with
+1. Create a CI Variable, ensuring the key is prefixed with
    `K8S_SECRET_`. For example, you can create a variable with key
-`K8S_SECRET_RAILS_MASTER_KEY`.
+   `K8S_SECRET_RAILS_MASTER_KEY`.
 
-3. Run an Auto Devops pipeline either by manually creating a new
+1. Run an Auto Devops pipeline either by manually creating a new
    pipeline or by pushing a code change to GitLab.
 
 Auto DevOps pipelines will take your application secret variables to
@@ -895,7 +976,7 @@ If `STAGING_ENABLED` is defined in your project (e.g., set `STAGING_ENABLED` to
 to a `staging` environment, and a  `production_manual` job will be created for
 you when you're ready to manually deploy to production.
 
-#### Deploy policy for canary environments **[PREMIUM]**
+#### Deploy policy for canary environments **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ci-yml/merge_requests/171)
 in GitLab 11.0.
@@ -910,7 +991,7 @@ If `CANARY_ENABLED` is defined in your project (e.g., set `CANARY_ENABLED` to
 - `production_manual` which is to be used by you when you're ready to manually
   deploy to production.
 
-#### Incremental rollout to production **[PREMIUM]**
+#### Incremental rollout to production **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5415) in GitLab 10.8.
 
@@ -968,7 +1049,7 @@ Before GitLab 11.4 this feature was enabled by the presence of the
 `INCREMENTAL_ROLLOUT_ENABLED` environment variable.
 This configuration is deprecated and will be removed in the future.
 
-#### Timed incremental rollout to production **[PREMIUM]**
+#### Timed incremental rollout to production **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7545) in GitLab 11.4.
 
@@ -982,10 +1063,10 @@ Everything behaves the same way, except:
 
 - It's enabled by setting the `INCREMENTAL_ROLLOUT_MODE` variable to `timed`.
 - Instead of the standard `production` job, the following jobs with a 5 minute delay between each are created:
-    1. `timed rollout 10%`
-    1. `timed rollout 25%`
-    1. `timed rollout 50%`
-    1. `timed rollout 100%`
+  1. `timed rollout 10%`
+  1. `timed rollout 25%`
+  1. `timed rollout 50%`
+  1. `timed rollout 100%`
 
 ## Currently supported languages
 
@@ -998,7 +1079,7 @@ multi-buildpack does not.
 
 As of GitLab 10.0, the supported buildpacks are:
 
-```
+```text
 - heroku-buildpack-multi     v1.0.0
 - heroku-buildpack-ruby      v168
 - heroku-buildpack-nodejs    v99
@@ -1034,6 +1115,12 @@ Container Registry. **Restarting a pod, scaling a service, or other actions whic
 require on-going access to the registry may fail**. On-going secure access is
 planned for a subsequent release.
 
+### Private registry support
+
+There is no documented way of using private container registry with Auto DevOps.
+We strongly advise using GitLab Container Registry with Auto DevOps in order to
+simplify configuration and prevent any unforeseen issues.
+
 ## Troubleshooting
 
 - Auto Build and Auto Test may fail in detecting your language/framework. There
@@ -1046,7 +1133,7 @@ planned for a subsequent release.
   case, you may need to customize your `.gitlab-ci.yml` with your test commands.
 - Auto Deploy will fail if GitLab can not create a Kubernetes namespace and
   service account for your project. For help debugging this issue, see
-  [Troubleshooting failed deployment jobs](../../user/project/clusters/index.md#troubleshooting-failed-deployment-jobs).
+  [Troubleshooting failed deployment jobs](../../user/project/clusters/index.md#troubleshooting).
 
 ### Disable the banner instance wide
 
diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md
index 6717e95266e..7ab59b80374 100644
--- a/doc/topics/autodevops/quick_start_guide.md
+++ b/doc/topics/autodevops/quick_start_guide.md
@@ -38,13 +38,13 @@ those projects provide a barebones application built on some well-known framewor
    Rails, Spring, or NodeJS Express project. For this example,
    we'll use the Ruby on Rails template.
 
-    ![Select project template](img/guide_project_template.png)
+   ![Select project template](img/guide_project_template.png)
 
 1. Give your project a name, optionally a description, and make it public so that
    you can take advantage of the features available in the
    [GitLab Gold plan](https://about.gitlab.com/pricing/#gitlab-com).
 
-    ![Create project](img/guide_create_project.png)
+   ![Create project](img/guide_create_project.png)
 
 1. Click **Create project**.
 
@@ -56,20 +56,20 @@ under which this application will be deployed.
 1. On the project's landing page, click the button labeled **Add Kubernetes cluster**
    (note that this option is also available when you navigate to **Operations > Kubernetes**).
 
-    ![Project landing page](img/guide_project_landing_page.png)
+   ![Project landing page](img/guide_project_landing_page.png)
 
 1. Choose **Create on Google Kubernetes Engine**.
 
-    ![Choose GKE](img/guide_choose_gke.png)
+   ![Choose GKE](img/guide_choose_gke.png)
 
 1. Sign in with Google.
 
-    ![Google sign in](img/guide_google_signin.png)
+   ![Google sign in](img/guide_google_signin.png)
 
 1. Connect with your Google account and press **Allow** when asked (this will
    be shown only the first time you connect GitLab with your Google account).
 
-    ![Google auth](img/guide_google_auth.png)
+   ![Google auth](img/guide_google_auth.png)
 
 1. The last step is to fill in the cluster details. Give it a name, leave the
    environment scope as is, and choose the GCP project under which the cluster
@@ -80,7 +80,7 @@ under which this application will be deployed.
    cluster will be created, enter the number of nodes you want it to have, and
    finally choose their [machine type](https://cloud.google.com/compute/docs/machine-types).
 
-    ![GitLab GKE cluster details](img/guide_gitlab_gke_details.png)
+   ![GitLab GKE cluster details](img/guide_gitlab_gke_details.png)
 
 1. Once ready, click **Create Kubernetes cluster**.
 
@@ -133,7 +133,7 @@ Now that the Kubernetes cluster is set up and ready, let's enable Auto DevOps.
    successfully runs on the `master` branch.
 1. Click **Save changes**.
 
-    ![Auto DevOps settings](img/guide_enable_autodevops.png)
+   ![Auto DevOps settings](img/guide_enable_autodevops.png)
 
 Once you complete all the above and save your changes, a new pipeline is
 automatically created. To view the pipeline, go to **CI/CD > Pipelines**.
@@ -159,15 +159,15 @@ In the **test** stage, GitLab runs various checks on the application:
 - The `test` job runs unit and integration tests by detecting the language and
   framework ([Auto Test](index.md#auto-test))
 - The `code_quality` job checks the code quality and is allowed to fail
-  ([Auto Code Quality](index.md#auto-code-quality-starter)) **[STARTER]**
+  ([Auto Code Quality](index.md#auto-code-quality-starter)) **(STARTER)**
 - The `container_scanning` job checks the Docker container if it has any
   vulnerabilities and is allowed to fail ([Auto Container Scanning](index.md#auto-container-scanning-ultimate))
 - The `dependency_scanning` job checks if the application has any dependencies
-  susceptible to vulnerabilities and is allowed to fail ([Auto Dependency Scanning](index.md#auto-dependency-scanning-ultimate)) **[ULTIMATE]**
+  susceptible to vulnerabilities and is allowed to fail ([Auto Dependency Scanning](index.md#auto-dependency-scanning-ultimate)) **(ULTIMATE)**
 - The `sast` job runs static analysis on the current code to check for potential
-  security issues and is allowed to fail([Auto SAST](index.md#auto-sast-ultimate)) **[ULTIMATE]**
+  security issues and is allowed to fail([Auto SAST](index.md#auto-sast-ultimate)) **(ULTIMATE)**
 - The `license_management` job searches the application's dependencies to determine each of their
-  licenses and is allowed to fail ([Auto License Management](index.md#auto-license-management-ultimate)) **[ULTIMATE]**
+  licenses and is allowed to fail ([Auto License Management](index.md#auto-license-management-ultimate)) **(ULTIMATE)**
 
 NOTE: **Note:**
 As you might have noticed, all jobs except `test` are allowed to fail in the
@@ -178,7 +178,7 @@ deploys the application in Kubernetes ([Auto Deploy](index.md#auto-deploy)).
 
 Lastly, in the **performance** stage, some performance tests will run
 on the deployed application
-([Auto Browser Performance Testing](index.md#auto-browser-performance-testing-premium)). **[PREMIUM]**
+([Auto Browser Performance Testing](index.md#auto-browser-performance-testing-premium)). **(PREMIUM)**
 
 ---
 
@@ -201,7 +201,7 @@ applications. In the rightmost column for the production environment, you can ma
   Prometheus collects data about the Kubernetes cluster and how the application
   affects it (in terms of memory/CPU usage, latency, etc.).
 
-    ![Environments metrics](img/guide_environments_metrics.png)
+  ![Environments metrics](img/guide_environments_metrics.png)
 
 - The third icon is the [web terminal](../../ci/environments.md#web-terminals)
   and it will open a terminal session right inside the container where the
@@ -285,8 +285,8 @@ all within GitLab. Despite its automatic nature, Auto DevOps can also be configu
 and customized to fit your workflow. Here are some helpful resources for further reading:
 
 1. [Auto DevOps](index.md)
-1. [Multiple Kubernetes clusters](index.md#using-multiple-kubernetes-clusters-premium) **[PREMIUM]**
-1. [Incremental rollout to production](index.md#incremental-rollout-to-production-premium) **[PREMIUM]**
+1. [Multiple Kubernetes clusters](index.md#using-multiple-kubernetes-clusters-premium) **(PREMIUM)**
+1. [Incremental rollout to production](index.md#incremental-rollout-to-production-premium) **(PREMIUM)**
 1. [Disable jobs you don't need with environment variables](index.md#environment-variables)
 1. [Use a static IP for your cluster](../../user/project/clusters/index.md#using-a-static-ip)
 1. [Use your own buildpacks to build your application](index.md#custom-buildpacks)
diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md
index cdcd8215b23..6a539b526f3 100644
--- a/doc/topics/git/index.md
+++ b/doc/topics/git/index.md
@@ -48,6 +48,7 @@ The following are resources about version control concepts:
 
 The following resources may help you become more efficient at using Git:
 
+- [Useful Git commands](useful_git_commands.md) collected by the GitLab support team.
 - [Git Tips & Tricks](https://about.gitlab.com/2016/12/08/git-tips-and-tricks/)
 - [Eight Tips to help you work better with Git](https://about.gitlab.com/2015/02/19/8-tips-to-help-you-work-better-with-git/)
 
@@ -71,6 +72,7 @@ The following are advanced topics for those who want to get the most out of Git:
 - [Custom Git Hooks](../../administration/custom_hooks.md)
 - [Git Attributes](../../user/project/git_attributes.md)
 - Git Submodules: [Using Git submodules with GitLab CI](../../ci/git_submodules.md#using-git-submodules-with-gitlab-ci)
+- [Partial Clone](partial_clone.md)
 
 ## API
 
@@ -82,6 +84,8 @@ Git-related queries from GitLab.
 The following relate to Git Large File Storage:
 
 - [Getting Started with Git LFS](https://about.gitlab.com/2017/01/30/getting-started-with-git-lfs-tutorial/)
-- [GitLab Git LFS documentation](../../workflow/lfs/manage_large_binaries_with_git_lfs.md)
+- [Migrate an existing Git repo with Git LFS](migrate_to_git_lfs/index.md)
+- [GitLab Git LFS user documentation](../../workflow/lfs/manage_large_binaries_with_git_lfs.md)
+- [GitLab Git LFS admin documentation](../../workflow/lfs/lfs_administration.md)
 - [Git-Annex to Git-LFS migration guide](../../workflow/lfs/migrate_from_git_annex_to_git_lfs.md)
 - [Towards a production quality open source Git LFS server](https://about.gitlab.com/2015/08/13/towards-a-production-quality-open-source-git-lfs-server/)
diff --git a/doc/topics/git/migrate_to_git_lfs/index.md b/doc/topics/git/migrate_to_git_lfs/index.md
new file mode 100644
index 00000000000..c879e404997
--- /dev/null
+++ b/doc/topics/git/migrate_to_git_lfs/index.md
@@ -0,0 +1,174 @@
+---
+type: tutorial, concepts
+description: "How to migrate an existing Git repository to Git LFS with BFG."
+last_updated: 2019-07-11
+---
+
+# Migrate a Git repo into Git LFS with BFG
+
+Using Git LFS can help you to reduce the size of your Git
+repository and improve its performance.
+
+However, simply adding the
+large files that are already in your repository to Git LFS,
+will not actually reduce the size of your repository because
+the files are still referenced by previous commits.
+
+Through the method described on this document, first migrate
+to Git LFS with [BFG](https://rtyley.github.io/bfg-repo-cleaner/)
+through a mirror repo, then clean up the repository's history,
+and lastly create LFS tracking rules to prevent new binary files
+from being added.
+
+This tutorial was inspired by the guide
+[Use BFG to migrate a repo to Git LFS](https://confluence.atlassian.com/bitbucket/use-bfg-to-migrate-a-repo-to-git-lfs-834233484.html).
+For more information on Git LFS, see the [references](#references)
+below.
+
+CAUTION: **Warning:**
+The method described on this guide rewrites Git history. Make
+sure to back up your repo before beginning and use it at your
+own risk.
+
+## Requirements
+
+Before beginning, make sure:
+
+- You have enough LFS storage for the files you want to convert.
+  Storage is required for the entire history of all files.
+- All the team members you share the repository with have pushed all changes.
+  Branches based on the repository before applying this method cannot be merged.
+  Branches based on the repo before applying this method cannot be merged.
+
+To follow this tutorial, you'll need:
+
+- Maintainer permissions to the existing Git repository
+  you'd like to migrate to LFS with access through the command line.
+- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+  and [Java Runtime Environment](https://www.java.com/en/download/manual.jsp)
+  (Java 7 or above) installed locally.
+- BFG installed locally:
+
+   ```bash
+   brew install bfg
+   ```
+
+- Git LFS installed locally:
+
+   ```bash
+   brew install git-lfs
+   ```
+
+NOTE: **Note:**
+This guide was tested on macOS Mojave.
+
+## Steps
+
+Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs-repo-migration.git`.
+
+1. Back up your repository:
+
+   Create a copy of your repository so that you can
+   recover it in case something goes wrong.
+
+1. Clone `--mirror` the repo:
+
+   Cloning with the mirror flag will create a bare repository.
+   This ensures you get all the branches within the repo.
+
+   It creates a directory called `<repo-name>.git`
+   (in our example, `test-git-lfs-repo-migration.git`),
+   mirroring the upstream project:
+
+   ```bash
+   git clone --mirror git@gitlab.com:gitlab-tests/test-git-lfs-repo-migration.git
+   ```
+
+1. Convert the Git history with BFG:
+
+   ```bash
+   bfg --convert-to-git-lfs "*.{png,mp4,jpg,gif}" --no-blob-protection test-git-lfs-repo-migration.git
+   ```
+
+   It is scanning all the history, and looking for any files with
+   that extension, and then converting them to an LFS pointer.
+
+1. Clean up the repository:
+
+   ```bash
+   # cd path/to/mirror/repo:
+   cd test-git-lfs-repo-migration.git
+   # clean up the repo:
+   git reflog expire --expire=now --all && git gc --prune=now --aggressive
+   ```
+
+   You can also take a look on how to further [clean the repo](../../../user/project/repository/reducing_the_repo_size_using_git.md),
+   but it's not necessary for the purposes of this guide.
+
+1. Install Git LFS in the mirror repository:
+
+   ```bash
+   git lfs install
+   ```
+
+1. [Unprotect the default branch](../../../user/project/protected_branches.md),
+   so that we can force-push the rewritten repository:
+
+   1. Navigate to your project's **Settings > Repository** and
+   expand **Protected Branches**.
+   1. Scroll down to locate the protected branches and click
+   **Unprotect** the default branch.
+
+1. Force-push to GitLab:
+
+   ```bash
+   git push --force
+   ```
+
+1. Track the files you want with LFS:
+
+   ```bash
+   # cd path/to/upstream/repo:
+   cd test-git-lfs-repo-migration
+   # You may need to reset your local copy with upstream's `master` after force-pushing from the mirror:
+   git reset --hard origin/master
+   # Track the files with LFS:
+   git lfs track "*.gif" "*.png" "*.jpg" "*.psd" "*.mp4" ".gitattributes" "img/"
+   ```
+
+   Now all existing the files you converted, as well as the new
+   ones you add, will be properly tracked with LFS.
+
+1. [Re-protect the default branch](../../../user/project/protected_branches.md):
+
+   1. Navigate to your project's **Settings > Repository** and
+   expand **Protected Branches**.
+   1. Select the default branch from the **Branch** dropdown menu,
+   and set up the
+   **Allowed to push** and **Allowed to merge** rules.
+   1. Click **Protect**.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
+
+## References
+
+- [Getting Started with Git LFS](https://about.gitlab.com/2017/01/30/getting-started-with-git-lfs-tutorial/)
+- [Migrate from Git Annex to Git LFS](../../../workflow/lfs/migrate_from_git_annex_to_git_lfs.md)
+- [GitLab's Git LFS user documentation](../../../workflow/lfs/manage_large_binaries_with_git_lfs.md)
+- [GitLab's Git LFS administrator documentation](../../../workflow/lfs/lfs_administration.md)
+- Alternative method to [migrate an existing repo to Git LFS](https://github.com/git-lfs/git-lfs/wiki/Tutorial#migrating-existing-repository-data-to-lfs)
+
+<!--
+Test project:
+https://gitlab.com/gitlab-tests/test-git-lfs-repo-migration
+-->
diff --git a/doc/topics/git/numerous_undo_possibilities_in_git/index.md b/doc/topics/git/numerous_undo_possibilities_in_git/index.md
index 84201e11831..5cae532bf54 100644
--- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md
+++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md
@@ -110,21 +110,21 @@ At this point there are 3 options to undo the local changes you have:
 
 - Discard all local changes, but save them for possible re-use [later](#quickly-save-local-changes):
 
-    ```shell
-    git stash
-    ```
+  ```shell
+  git stash
+  ```
 
 - Discarding local changes (permanently) to a file:
 
-    ```shell
-    git checkout -- <file>
-    ```
+  ```shell
+  git checkout -- <file>
+  ```
 
 - Discard all local changes to all files permanently:
 
-    ```shell
-    git reset --hard
-    ```
+  ```shell
+  git reset --hard
+  ```
 
 Before executing `git reset --hard`, keep in mind that there is also a way to
 just temporary store the changes without committing them using `git stash`.
@@ -182,27 +182,27 @@ Now you have 4 options to undo your changes:
 
 - Unstage the file to current commit (HEAD):
 
-    ```shell
-    git reset HEAD <file>
-    ```
+  ```shell
+  git reset HEAD <file>
+  ```
 
 - Unstage everything - retain changes:
 
-    ```shell
-    git reset
-    ```
+  ```shell
+  git reset
+  ```
 
 - Discard all local changes, but save them for [later](#quickly-save-local-changes):
 
-    ```shell
-    git stash
-    ```
+  ```shell
+  git stash
+  ```
 
 - Discard everything permanently:
 
-    ```shell
-    git reset --hard
-    ```
+  ```shell
+  git reset --hard
+  ```
 
 ## Committed local changes
 
@@ -240,21 +240,21 @@ In our example we will end up with commit `B`, that introduced bug/error. We hav
 
 - Undo (swap additions and deletions) changes introduced by commit `B`:
 
-    ```shell
-    git revert commit-B-id
-    ```
+  ```shell
+  git revert commit-B-id
+  ```
 
 - Undo changes on a single file or directory from commit `B`, but retain them in the staged state:
 
-    ```shell
-    git checkout commit-B-id <file>
-    ```
+  ```shell
+  git checkout commit-B-id <file>
+  ```
 
 - Undo changes on a single file or directory from commit `B`, but retain them in the unstaged state:
 
-    ```shell
-    git reset  commit-B-id <file>
-    ```
+  ```shell
+  git reset  commit-B-id <file>
+  ```
 
 - There is one command we also must not forget: **creating a new branch**
   from the point where changes are not applicable or where the development has hit a
@@ -270,14 +270,14 @@ In our example we will end up with commit `B`, that introduced bug/error. We hav
   you can [cherry-pick](../../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit)
   that commit into a new merge request.
 
-    ![Create a new branch to avoid clashing](img/branching.png)
+  ![Create a new branch to avoid clashing](img/branching.png)
 
-    ```shell
-    git checkout commit-B-id
-    git checkout -b new-path-of-feature
-    # Create <commit F>
-    git commit -a
-    ```
+  ```shell
+  git checkout commit-B-id
+  git checkout -b new-path-of-feature
+  # Create <commit F>
+  git commit -a
+  ```
 
 ### With history modification
 
@@ -297,9 +297,9 @@ delete commit `B`.
 
 - Rebase the range from current commit D to A:
 
-    ```shell
-    git rebase -i A
-    ```
+  ```shell
+  git rebase -i A
+  ```
 
 - Command opens your favorite editor where you write `drop` in front of commit
  `B`, but you leave default `pick` with all other commits. Save and exit the
@@ -310,9 +310,9 @@ In case you want to modify something introduced in commit `B`.
 
 - Rebase the range from current commit D to A:
 
-    ```shell
-    git rebase -i A
-    ```
+  ```shell
+  git rebase -i A
+  ```
 
 - Command opens your favorite text editor where you write `edit` in front of commit
  `B`, but leave default `pick` with all other commits. Save and exit the editor to
@@ -320,9 +320,9 @@ In case you want to modify something introduced in commit `B`.
 
 - Now do your edits and commit changes:
 
-    ```shell
-    git commit -a
-    ```
+  ```shell
+  git commit -a
+  ```
 
 You can find some more examples in [below section where we explain how to modify
 history](#how-modifying-history-is-done)
diff --git a/doc/topics/git/partial_clone.md b/doc/topics/git/partial_clone.md
new file mode 100644
index 00000000000..ea4223355d8
--- /dev/null
+++ b/doc/topics/git/partial_clone.md
@@ -0,0 +1,147 @@
+# Partial Clone for Large Repositories
+
+CAUTION: **Alpha:**
+Partial Clone is an experimental feature, and will significantly increase
+Gitaly resource utilization when performing a partial clone, and decrease
+performance of subsequent fetch operations.
+
+As Git repositories become very large, usability decreases as performance
+decreases. One major challenge is cloning the repository, because Git will
+download the entire repository including every commit and every version of
+every object. This can be slow to transfer, and require large amounts of disk
+space.
+
+Historically, performing a **shallow clone**
+([`--depth`](https://www.git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt))
+has been the only way to reduce the amount of data transferred when cloning
+a Git repository. This does not, however, allow filtering by sub-tree which is
+important for monolithic repositories containing many projects, or by object
+size preventing unnecessary large objects being downloaded.
+
+[Partial clone](https://github.com/git/git/blob/master/Documentation/technical/partial-clone.txt)
+is a performance optimization that "allows Git to function without having a
+complete copy of the repository. The goal of this work is to allow Git better
+handle extremely large repositories."
+
+Specifically, using partial clone, it should be possible for Git to natively
+support:
+
+- large objects, instead of using [Git LFS](https://git-lfs.github.com/)
+- enormous repositories
+
+Briefly, partial clone works by:
+
+- excluding objects from being transferred when cloning or fetching a
+  repository using a new `--filter` flag
+- downloading missing objects on demand
+
+Follow [Git for enormous repositories](https://gitlab.com/groups/gitlab-org/-/epics/773) for roadmap and updates.
+
+## Enabling partial clone
+
+GitLab 12.1 uses Git 2.21.0 which has an arbitrary file access security
+vulnerability when `uploadpack.allowFilter` is enabled, and should not be
+enabled in production environments.
+
+A feature flag is planned to enable `uploadpack.allowFilter` and
+`uploadpack.allowAnySHA1InWant` once the version of Git used by GitLab has been
+updated to Git 2.22.0.
+
+Follow [this issue](https://gitlab.com/gitlab-org/gitaly/issues/1553) for
+updated.
+
+## Excluding objects by size
+
+Partial Clone allows large objects to be stored directly in the Git repository,
+and be excluded from clones as desired by the user. This eliminates the error
+prone process of deciding which objects should be stored in LFS or not. Using
+partial clone, all files – large or small – may be treated the same.
+
+With the `uploadpack.allowFilter` and `uploadpack.allowAnySHA1InWant` options
+enabled on the Git server:
+
+```bash
+# clone the repo, excluding blobs larger than 1 megabyte
+git clone --filter=blob:limit=1m <url>
+
+# in the checkout step of the clone, and any subsequent operations
+# any blobs that are needed will be downloaded on demand
+git checkout feature-branch
+```
+
+## Excluding objects by path
+
+Partial Clone allows clones to be filtered by path using a format similar to a
+`.gitignore` file stored inside the repository.
+
+With the `uploadpack.allowFilter` and `uploadpack.allowAnySHA1InWant` options
+enabled on the Git server:
+
+1. **Create a filter spec.** For example, consider a monolithic repository with
+   many applications, each in a different subdirectory in the root. Create a file
+   `shiny-app/.filterspec` using the GitLab web interface:
+
+   ```.gitignore
+   # Only the paths listed in the file will be downloaded when performing a
+   # partial clone using `--filter=sparse:oid=shiny-app/.gitfilterspec`
+
+   # Explicitly include filterspec needed to configure sparse checkout with
+   # git config --local core.sparsecheckout true
+   # git show master:snazzy-app/.gitfilterspec >> .git/info/sparse-checkout
+   shiny-app/.gitfilterspec
+
+   # Shiny App
+   shiny-app/
+
+   # Dependencies
+   shimmery-app/
+   shared-component-a/
+   shared-component-b/
+   ```
+
+1. *Create a new Git repository and fetch.* Support for `--filter=sparse:oid`
+   using the clone command is incomplete, so we will emulate the clone command
+   by hand, using `git init` and `git fetch`. Follow
+   [gitaly#1769](https://gitlab.com/gitlab-org/gitaly/issues/1769) for updates.
+
+   ```bash
+   # Create a new directory for the Git repository
+   mkdir jumbo-repo && cd jumbo-repo
+
+   # Initialize a new Git repository
+   git init
+
+   # Add the remote
+   git remote add origin git@gitlab.com/example/jumbo-repo
+
+   # Enable partial clone support for the remote
+   git config --local extensions.partialClone origin
+
+   # Fetch the filtered set of objects using the filterspec stored on the
+   # server. WARNING: this step is slow!
+   git fetch --filter=sparse:oid=master:shiny-app/.gitfilterspec origin
+
+   # Optional: observe there are missing objects that we have not fetched
+   git rev-list --all --quiet --objects --missing=print | wc -l
+   ```
+
+   CAUTION: **IDE and Shell integrations:**
+   Git integrations with `bash`, `zsh`, etc and editors that automatically
+   show Git status information often run `git fetch` which will fetch the
+   entire repository. You many need to disable or reconfigure these
+   integrations.
+
+1. **Sparse checkout** must be enabled and configured to prevent objects from
+   other paths being downloaded automatically when checking out branches. Follow
+   [gitaly#1765](https://gitlab.com/gitlab-org/gitaly/issues/1765) for updates.
+
+   ```bash
+   # Enable sparse checkout
+   git config --local core.sparsecheckout true
+
+   # Configure sparse checkout
+   git show master:snazzy-app/.gitfilterspec >> .git/info/sparse-checkout
+
+   # Checkout master
+   git checkout master
+   ```
diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md
index 417d91bf834..11284da30af 100644
--- a/doc/topics/git/troubleshooting_git.md
+++ b/doc/topics/git/troubleshooting_git.md
@@ -51,11 +51,11 @@ Configuring *both* the client and the server is unnecessary.
 - On UNIX, edit `~/.ssh/config` (create the file if it doesn’t exist) and
   add or edit:
 
-    ```text
-    Host your-gitlab-instance-url.com
-      ServerAliveInterval 60
-      ServerAliveCountMax 5
-    ```
+  ```text
+  Host your-gitlab-instance-url.com
+    ServerAliveInterval 60
+    ServerAliveCountMax 5
+  ```
 
 - On Windows, if you are using PuTTY, go to your session properties, then
   navigate to "Connection" and under "Sending of null packets to keep
diff --git a/doc/topics/git/useful_git_commands.md b/doc/topics/git/useful_git_commands.md
new file mode 100644
index 00000000000..030e62f485a
--- /dev/null
+++ b/doc/topics/git/useful_git_commands.md
@@ -0,0 +1,210 @@
+---
+type: reference
+---
+
+# Useful Git commands
+
+Here are some useful Git commands collected by the GitLab support team. You may not
+need to use often, but they can can come in handy when needed.
+
+## Remotes
+
+### Add another URL to a remote, so both remotes get updated on each push
+
+```sh
+git remote set-url --add <remote_name> <remote_url>
+```
+
+## Staging and reverting changes
+
+### Remove last commit and leave the changes in unstaged
+
+```sh
+git reset --soft HEAD^
+```
+
+### Unstage a certain number of commits from HEAD
+
+To unstage 3 commits, for example, run:
+
+```sh
+git reset HEAD^3
+```
+
+### Unstage changes to a certain file from HEAD
+
+```sh
+git reset <filename>
+```
+
+### Revert a file to HEAD state and remove changes
+
+There are two options to revert changes to a file:
+
+- `git checkout <filename>`
+- `git reset --hard <filename>`
+
+### Undo a previous commit by creating a new replacement commit
+
+```sh
+git revert <commit-sha>
+```
+
+### Create a new message for last commit
+
+```sh
+git commit --amend
+```
+
+### Add a file to the last commit
+
+```sh
+git add <filename>
+git commit --amend
+```
+
+Append `--no-edit` to the `commit` command if you do not want to edit the commit
+message.
+
+## Stashing
+
+### Stash changes
+
+```sh
+git stash save
+```
+
+The default behavor of `stash` is to save, so you can also use just:
+
+```sh
+git stash
+```
+
+### Unstash your changes
+
+```sh
+git stash apply
+```
+
+### Discard your stashed changes
+
+```sh
+git stash drop
+```
+
+### Apply and drop your stashed changes
+
+```sh
+git stash pop
+```
+
+## Refs and Log
+
+### Use reflog to show the log of reference changes to HEAD
+
+```sh
+git reflog
+```
+
+### Check the Git history of a file
+
+The basic command to check the git history of a file:
+
+```sh
+git log <file>
+```
+
+If you get this error message:
+
+```text
+fatal: ambiguous argument <file_name>: unknown revision or path not in the working tree.
+Use '--' to separate paths from revisions, like this:
+```
+
+Use this to check the Git history of the file:
+
+```sh
+git log -- <file>
+```
+
+### Find the tags that contain a particular SHA
+
+```sh
+git tag --contains <sha>
+```
+
+### Check the content of each change to a file
+
+```sh
+gitk <file>
+```
+
+### Check the content of each change to a file, follows it past file renames
+
+```sh
+gitk --follow <file>
+```
+
+## Debugging
+
+### Use a custom SSH key for a git command
+
+```sh
+GIT_SSH_COMMAND="ssh -i ~/.ssh/gitlabadmin" git <command>
+```
+
+### Debug cloning
+
+With SSH:
+
+```sh
+GIT_SSH_COMMAND="ssh -vvv" git clone <git@url>
+```
+
+With HTTPS:
+
+```sh
+GIT_TRACE_PACKET=1 GIT_TRACE=2 GIT_CURL_VERBOSE=1 git clone <url>
+```
+
+## Rebasing
+
+### Rebase your branch onto master
+
+The -i flag stands for 'interactive':
+
+```sh
+git rebase -i master
+```
+
+### Continue the rebase if paused
+
+```sh
+git rebase --continue
+```
+
+### Use git rerere
+
+To _reuse_ recorded solutions to the same problems when repeated:
+
+```sh
+git rerere
+```
+
+To enable `rerere` functionality:
+
+```sh
+git config --global rerere.enabled true
+```
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/university/README.md b/doc/university/README.md
index c116e54ad48..b17f40b91a5 100644
--- a/doc/university/README.md
+++ b/doc/university/README.md
@@ -9,6 +9,10 @@ GitLab University is a great place to start when learning about version control
 
 If you're looking for a GitLab subscription for _your university_, see our [Education](https://about.gitlab.com/solutions/education/) page.
 
+CAUTION: **Caution:**
+Some of the content in GitLab University may be out of date and we plan to
+[evaluate](https://gitlab.com/gitlab-org/gitlab-ce/issues/41064) it.
+
 The GitLab University curriculum is composed of GitLab videos, screencasts, presentations, projects and external GitLab content hosted on other services and has been organized into the following sections:
 
 1. [GitLab Beginner](#1-gitlab-beginner).
@@ -73,7 +77,7 @@ The GitLab University curriculum is composed of GitLab videos, screencasts, pres
    - Being part of our Great Community and Contributing to GitLab
 1. [Getting Started with the GitLab Development Kit (GDK)](https://about.gitlab.com/2016/06/08/getting-started-with-gitlab-development-kit/)
 1. [Contributing Technical Articles to the GitLab Blog](https://about.gitlab.com/2016/01/26/call-for-writers/)
-1. [GitLab Training Workshops](https://docs.gitlab.com/ce/university/training/end-user/)
+1. [GitLab Training Workshops](training/end-user/README.md)
 1. [GitLab Professional Services](https://about.gitlab.com/services/)
 
 ### 1.8 GitLab Training Material
@@ -149,7 +153,6 @@ The GitLab University curriculum is composed of GitLab videos, screencasts, pres
 1. [How to Install GitLab with Omnibus - Video](https://www.youtube.com/watch?v=Q69YaOjqNhg)
 1. [Installing GitLab - Online Course](https://courses.platzi.com/classes/git-gitlab/concepto/part-1/part-3/material/)
 1. [Using a Non-Packaged PostgreSQL Database](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#using-a-non-packaged-postgresql-database-management-server)
-1. [Using a MySQL Database](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#using-a-mysql-database-management-server-enterprise-edition-only)
 1. [Installing GitLab on Microsoft Azure](https://about.gitlab.com/2016/07/13/how-to-setup-a-gitlab-instance-on-microsoft-azure/)
 1. [Installing GitLab on Digital Ocean](https://about.gitlab.com/2016/04/27/getting-started-with-gitlab-and-digitalocean/)
 
@@ -182,7 +185,7 @@ The GitLab University curriculum is composed of GitLab videos, screencasts, pres
 
 ### 3.9. Integrations
 
-1. [How to Integrate JIRA and Jenkins with GitLab - Video](https://gitlabmeetings.webex.com/gitlabmeetings/ldr.php?RCID=44b548147a67ab4d8a62274047146415)
+1. [How to Integrate Jira and Jenkins with GitLab - Video](https://gitlabmeetings.webex.com/gitlabmeetings/ldr.php?RCID=44b548147a67ab4d8a62274047146415)
 1. [How to Integrate Jira with GitLab](../user/project/integrations/jira.md)
 1. [How to Integrate Jenkins with GitLab](../integration/jenkins.md)
 1. [How to Integrate Bamboo with GitLab](../user/project/integrations/bamboo.md)
diff --git a/doc/university/process/README.md b/doc/university/process/README.md
index fdf6224f7f6..b278e02ccd5 100644
--- a/doc/university/process/README.md
+++ b/doc/university/process/README.md
@@ -9,11 +9,11 @@ title: University | Process
 # Suggesting improvements
 
 If you would like to teach a class or participate or help in any way please
-submit a merge request and assign it to [Job](https://gitlab.com/u/JobV).
+submit a merge request and assign it to [Job](https://gitlab.com/JobV).
 
 If you have suggestions for additional courses you would like to see,
 please submit a merge request to add an upcoming class, assign to
-[Chad](https://gitlab.com/u/chadmalchow) and /cc [Job](https://gitlab.com/u/JobV).
+[Chad](https://gitlab.com/chadmalchow) and /cc [Job](https://gitlab.com/JobV).
 
 ## Adding classes
 
@@ -31,4 +31,4 @@ please submit a merge request to add an upcoming class, assign to
 1. Please upload any video recordings to our Youtube channel. We prefer them to
    be public, if needed they can be unlisted but if so they should be linked from
    this page.
-1. Please create a merge request and assign to [Erica](https://gitlab.com/u/Erica).
+1. Please create a merge request and assign to [Erica](https://gitlab.com/Erica).
diff --git a/doc/university/support/README.md b/doc/university/support/README.md
index 9563492c137..fdeba89f9c8 100644
--- a/doc/university/support/README.md
+++ b/doc/university/support/README.md
@@ -45,7 +45,7 @@ It's important to understand how to install GitLab in the same way that our user
 
 Sometimes we need to upgrade customers from old versions of GitLab to latest, so it's good to get some experience of doing that now.
 
-- [Installation Methods](https://about.gitlab.com/installation/):
+- [Installation Methods](https://about.gitlab.com/install/):
   - [Omnibus](https://gitlab.com/gitlab-org/omnibus-gitlab/)
   - [Docker](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/docker)
   - [Source](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md)
@@ -80,7 +80,7 @@ Our integrations add great value to GitLab. User questions often relate to integ
 
 - Learn about our Integrations (specially, not only):
   - [LDAP](../../integration/ldap.md)
-  - [JIRA](../../project_services/jira.md)
+  - [Jira](../../project_services/jira.md)
   - [Jenkins](../../integration/jenkins.md)
   - [SAML](../../integration/saml.md)
 
@@ -145,7 +145,7 @@ Zendesk is our Support Centre and our main communication line with our Customers
 
 Some tickets need specific knowledge or a deep understanding of a particular component and will need to be escalated to a Senior Service Engineer or Developer
 
-- Read about [Escalation](https://about.gitlab.com/handbook/support/onboarding/#create-issuesa-namecreate-issuea)
+- Read about [Escalation](https://about.gitlab.com/handbook/support/workflows/shared/support_workflows/issue_escalations.html)
 - Find the macros in Zendesk for ticket escalations
 - Take a look at the [GitLab.com Team page](https://about.gitlab.com/team/) to find the resident experts in their fields
 
diff --git a/doc/university/training/end-user/README.md b/doc/university/training/end-user/README.md
index 99fb5e83387..1218465c87a 100644
--- a/doc/university/training/end-user/README.md
+++ b/doc/university/training/end-user/README.md
@@ -9,12 +9,8 @@ which can be found at [End User Slides](https://gitlab-org.gitlab.io/end-user-tr
 through it's [RevealJS](https://gitlab.com/gitlab-org/end-user-training-slides)
 project.
 
----
-
 ## Git Intro
 
----
-
 ### What is a Version Control System (VCS)
 
 - Records changes to a file
@@ -22,8 +18,6 @@ project.
 - Disaster Recovery
 - Types of VCS: Local, Centralized and Distributed
 
----
-
 ### Short Story of Git
 
 - 1991-2002: The Linux kernel was being maintained by sharing archived files
@@ -31,8 +25,6 @@ project.
 - 2002: The Linux kernel project began using a DVCS called BitKeeper
 - 2005: BitKeeper revoked the free-of-charge status and Git was created
 
----
-
 ### What is Git
 
 - Distributed Version Control System
@@ -42,8 +34,6 @@ project.
 - Disaster recovery friendly
 - Open Source
 
----
-
 ### Getting Help
 
 - Use the tools at your disposal when you get stuck.
@@ -51,12 +41,9 @@ project.
   - Use Google (i.e. StackOverflow, Google groups)
   - Read documentation at <https://git-scm.com>
 
----
-
 ## Git Setup
-Workshop Time!
 
----
+Workshop Time!
 
 ### Setup
 
@@ -68,8 +55,6 @@ Workshop Time!
   - Debian: `sudo apt-get install git-all`
   - Red Hat `sudo yum install git-all`
 
----
-
 ### Configure
 
 - One-time configuration of the Git client:
@@ -88,9 +73,7 @@ git config --global --list
 ```
 
 - You might want or be required to use an SSH key.
-    - Instructions: [SSH](http://doc.gitlab.com/ce/ssh/README.html)
-
----
+  - Instructions: [SSH](http://doc.gitlab.com/ce/ssh/README.html)
 
 ### Workspace
 
@@ -98,8 +81,6 @@ git config --global --list
 - Create a workspace or development directory
 - This is where we'll be working and adding content
 
----
-
 ```bash
 mkdir ~/development
 cd ~/development
@@ -110,24 +91,18 @@ mkdir ~/workspace
 cd ~/workspace
 ```
 
----
-
 ## Git Basics
 
----
-
 ### Git Workflow
 
 - Untracked files
-    - New files that Git has not been told to track previously.
+  - New files that Git has not been told to track previously.
 - Working area (Workspace)
-    - Files that have been modified but are not committed.
+  - Files that have been modified but are not committed.
 - Staging area (Index)
-    - Modified files that have been marked to go in the next commit.
+  - Modified files that have been marked to go in the next commit.
 - Upstream
-    - Hosted repository on a shared server
-
----
+  - Hosted repository on a shared server
 
 ### GitLab
 
@@ -136,8 +111,6 @@ cd ~/workspace
   issue tracking, Merge Requests, and other features.
 - The hosted version of GitLab is gitlab.com
 
----
-
 ### New Project
 
 - Sign in into your gitlab.com account
@@ -145,8 +118,6 @@ cd ~/workspace
 - Choose to import from 'Any Repo by URL' and use <https://gitlab.com/gitlab-org/training-examples.git>
 - On your machine clone the `training-examples` project
 
----
-
 ### Git and GitLab basics
 
 1. Edit `edit_this_file.rb` in `training-examples`
@@ -157,8 +128,6 @@ cd ~/workspace
 1. Push the commit to the remote
 1. View the git log
 
----
-
 ```shell
 # Edit `edit_this_file.rb`
 git status
@@ -169,8 +138,6 @@ git push origin master
 git log
 ```
 
----
-
 ### Feature Branching
 
 1. Create a new feature branch called `squash_some_bugs`
@@ -178,8 +145,6 @@ git log
 1. Commit
 1. Push
 
----
-
 ```shell
 git checkout -b squash_some_bugs
 # Edit `bugs.rb`
@@ -189,14 +154,8 @@ git commit -m 'Fix some buggy code'
 git push origin squash_some_bugs
 ```
 
----
-
 ## Merge Request
 
----
-
-### Merge requests
-
 - When you want feedback create a merge request
 - Target is the ‘default’ branch (usually master)
 - Assign or mention the person you would like to review
@@ -205,8 +164,6 @@ git push origin squash_some_bugs
 - Anyone can comment, not just the assignee
 - Push corrections to the same branch
 
----
-
 ### Merge request example
 
 - Create your first merge request
@@ -215,8 +172,6 @@ git push origin squash_some_bugs
   - Push a new commit to the same branch
   - Review the changes again and notice the update
 
----
-
 ### Feedback and Collaboration
 
 - Merge requests are a time for feedback and collaboration
@@ -229,26 +184,17 @@ git push origin squash_some_bugs
 
 ---
 
-### Feedback and Collaboration
-
-- Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests:[Thoughtbot](https://github.com/thoughtbot/guides/tree/master/code-review)
+- Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests:
+  [Thoughtbot](https://github.com/thoughtbot/guides/tree/master/code-review)
 - See GitLab merge requests for examples: [Merge Requests](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests)
 
----
-
 ## Merge Conflicts
 
----
-
-### Merge Conflicts
-
 - Happen often
 - Learning to fix conflicts is hard
 - Practice makes perfect
 - Force push after fixing conflicts. Be careful!
 
----
-
 ### Example Plan
 
 1. Checkout a new branch and edit conflicts.rb. Add 'Line4' and 'Line5'.
@@ -262,47 +208,45 @@ git push origin squash_some_bugs
 1. Force push the changes
 1. Finally continue with the Merge Request
 
----
-
 ### Example 1/2
 
-    git checkout -b conflicts_branch
+```sh
+git checkout -b conflicts_branch
 
-    # vi conflicts.rb
-    # Add 'Line4' and 'Line5'
+# vi conflicts.rb
+# Add 'Line4' and 'Line5'
 
-    git commit -am "add line4 and line5"
-    git push origin conflicts_branch
+git commit -am "add line4 and line5"
+git push origin conflicts_branch
 
-    git checkout master
+git checkout master
 
-    # vi conflicts.rb
-    # Add 'Line6' and 'Line7'
-    git commit -am "add line6 and line7"
-    git push origin master
-
----
+# vi conflicts.rb
+# Add 'Line6' and 'Line7'
+git commit -am "add line6 and line7"
+git push origin master
+```
 
 ### Example 2/2
 
 Create a merge request on the GitLab web UI. You'll see a conflict warning.
 
-    git checkout conflicts_branch
-    git fetch
-    git rebase master
-
-    # Fix conflicts by editing the files.
+```sh
+git checkout conflicts_branch
+git fetch
+git rebase master
 
-    git add conflicts.rb
-    # No need to commit this file
+# Fix conflicts by editing the files.
 
-    git rebase --continue
+git add conflicts.rb
+# No need to commit this file
 
-    # Remember that we have rewritten our commit history so we
-    # need to force push so that our remote branch is restructured
-    git push origin conflicts_branch -f
+git rebase --continue
 
----
+# Remember that we have rewritten our commit history so we
+# need to force push so that our remote branch is restructured
+git push origin conflicts_branch -f
+```
 
 ### Notes
 
@@ -311,55 +255,63 @@ Create a merge request on the GitLab web UI. You'll see a conflict warning.
 - Merge when bringing changes from feature to master
 - Reference: <https://www.atlassian.com/git/tutorials/merging-vs-rebasing/>
 
----
-
 ## Revert and Unstage
 
----
-
 ### Unstage
 
 To remove files from stage use reset HEAD. Where HEAD is the last commit of the current branch:
 
-    git reset HEAD <file>
+```sh
+git reset HEAD <file>
+```
 
 This will unstage the file but maintain the modifications. To revert the file back to the state it was in before the changes we can use:
 
-    git checkout -- <file>
+```sh
+git checkout -- <file>
+```
 
 To remove a file from disk and repo use 'git rm' and to rm a dir use the '-r' flag:
 
-    git rm '*.txt'
-    git rm -r <dirname>
+```sh
+git rm '*.txt'
+git rm -r <dirname>
+```
 
 If we want to remove a file from the repository but keep it on disk, say we forgot to add it to our .gitignore file then use `--cache`:
 
-    git rm <filename> --cache
-
----
+```sh
+git rm <filename> --cache
+```
 
 ### Undo Commits
 
 Undo last commit putting everything back into the staging area:
 
-    git reset --soft HEAD^
+```sh
+git reset --soft HEAD^
+```
 
 Add files and change message with:
 
-    git commit --amend -m "New Message"
+```sh
+git commit --amend -m "New Message"
+```
 
 Undo last and remove changes
 
-    git reset --hard HEAD^
+```sh
+git reset --hard HEAD^
+```
 
 Same as last one but for two commits back:
 
-    git reset --hard HEAD^^
+```sh
+git reset --hard HEAD^^
+```
 
 Don't reset after pushing
 
----
-
 ### Reset Workflow
 
 1. Edit file again 'edit_this_file.rb'
@@ -373,53 +325,46 @@ Don't reset after pushing
 1. Pull for updates
 1. Push changes
 
-----
-
-    # Change file edit_this_file.rb
-    git status
-    git commit -am "kjkfjkg"
-    git log
-    git commit --amend -m "New comment added"
-    git log
-    git reset --soft HEAD^
-    git log
-    git pull origin master
-    git push origin master
-
----
+```sh
+# Change file edit_this_file.rb
+git status
+git commit -am "kjkfjkg"
+git log
+git commit --amend -m "New comment added"
+git log
+git reset --soft HEAD^
+git log
+git pull origin master
+git push origin master
+```
 
-### Note
+### git revert vs git reset
 
-git revert vs git reset
 Reset removes the commit while revert removes the changes but leaves the commit
 Revert is safer considering we can revert a revert
 
-    # Changed file
-    git commit -am "bug introduced"
-    git revert HEAD
-    # New commit created reverting changes
-    # Now we want to re apply the reverted commit
-    git log # take hash from the revert commit
-    git revert <rev commit hash>
-    # reverted commit is back (new commit created again)
-
----
+```sh
+# Changed file
+git commit -am "bug introduced"
+git revert HEAD
+# New commit created reverting changes
+# Now we want to re apply the reverted commit
+git log # take hash from the revert commit
+git revert <rev commit hash>
+# reverted commit is back (new commit created again)
+```
 
 ## Questions
 
----
-
 ## Instructor Notes
 
----
-
 ### Version Control
 
- - Local VCS was used with a filesystem or a simple db.
- - Centralized VCS such as Subversion includes collaboration but
-   still is prone to data loss as the main server is the single point of
-   failure.
- - Distributed VCS enables the team to have a complete copy of the project
-   and work with little dependency to the main server. In case of a main
-   server failing the project can be recovered by any of the latest copies
-   from the team
+- Local VCS was used with a filesystem or a simple db.
+- Centralized VCS such as Subversion includes collaboration but
+  still is prone to data loss as the main server is the single point of
+  failure.
+- Distributed VCS enables the team to have a complete copy of the project
+  and work with little dependency to the main server. In case of a main
+  server failing the project can be recovered by any of the latest copies
+  from the team
diff --git a/doc/university/training/index.md b/doc/university/training/index.md
index ddfc662123d..61fde9d8336 100644
--- a/doc/university/training/index.md
+++ b/doc/university/training/index.md
@@ -6,7 +6,7 @@ type: index
 # GitLab Training Material
 
 All GitLab training material is stored in markdown format. Slides are
-generated using [Deskset](http://www.decksetapp.com/).
+generated using [Deskset](https://www.deckset.com/).
 
 All training material is open to public contribution.
 
@@ -34,9 +34,9 @@ This section contains the following topics:
 
 ## Additional Resources
 
-1. [GitLab Documentation](http://docs.gitlab.com)
-1. [GUI Clients](http://git-scm.com/downloads/guis)
-1. [Pro Git book](http://git-scm.com/book)
+1. [GitLab Documentation](https://docs.gitlab.com)
+1. [GUI Clients](https://git-scm.com/downloads/guis)
+1. [Pro Git book](https://git-scm.com/book/en/v2)
 1. [Platzi Course](https://courses.platzi.com/courses/git-gitlab/)
 1. [Code School tutorial](http://try.github.io/)
 1. Contact us at `subscribers@gitlab.com`
diff --git a/doc/university/training/topics/bisect.md b/doc/university/training/topics/bisect.md
index 4178afa2086..24dc670d9d5 100644
--- a/doc/university/training/topics/bisect.md
+++ b/doc/university/training/topics/bisect.md
@@ -4,13 +4,11 @@ comments: false
 
 # Bisect
 
-## Bisect
-
 - Find a commit that introduced a bug
 - Works through a process of elimination
 - Specify a known good and bad revision to begin
 
-## Bisect
+## Bisect sample workflow
 
 1. Start the bisect process
 1. Enter the bad revision (usually latest commit)
diff --git a/doc/university/training/topics/cherry_picking.md b/doc/university/training/topics/cherry_picking.md
index fa0cb5fe6a4..f5bcdfcbf12 100644
--- a/doc/university/training/topics/cherry_picking.md
+++ b/doc/university/training/topics/cherry_picking.md
@@ -4,13 +4,11 @@ comments: false
 
 # Cherry Pick
 
-## Cherry Pick
-
 - Given an existing commit on one branch, apply the change to another branch
 - Useful for backporting bug fixes to previous release branches
 - Make the commit on the master branch and pick in to stable
 
-## Cherry Pick
+## Cherry Pick sample workflow
 
 1. Check out a new 'stable' branch from 'master'
 1. Change back to 'master'
@@ -19,8 +17,6 @@ comments: false
 1. Check out the 'stable' branch
 1. Cherry pick the commit using the SHA obtained earlier
 
-## Commands
-
 ```bash
 git checkout master
 git checkout -b stable
diff --git a/doc/university/training/topics/env_setup.md b/doc/university/training/topics/env_setup.md
index 305f5ecb1fb..92d2613c5d2 100644
--- a/doc/university/training/topics/env_setup.md
+++ b/doc/university/training/topics/env_setup.md
@@ -14,9 +14,11 @@ comments: false
   - If it's not installed, it will prompt you to install it.
 
 - **Linux**
+
   ```bash
   sudo yum install git-all
   ```
+
   ```bash
   sudo apt-get install git-all
   ```
diff --git a/doc/university/training/topics/feature_branching.md b/doc/university/training/topics/feature_branching.md
index d2efe634533..f530389d4da 100644
--- a/doc/university/training/topics/feature_branching.md
+++ b/doc/university/training/topics/feature_branching.md
@@ -11,15 +11,13 @@ comments: false
 - Push branches to the server frequently
   - Hint: This is a cheap backup for your work-in-progress code
 
-## Feature branching
+## Feature branching sample workflow
 
 1. Create a new feature branch called 'squash_some_bugs'
 1. Edit '`bugs.rb`' and remove all the bugs.
 1. Commit
 1. Push
 
-## Commands
-
 ```sh
 git checkout -b squash_some_bugs
 # Edit `bugs.rb`
diff --git a/doc/university/training/topics/getting_started.md b/doc/university/training/topics/getting_started.md
index 08027c5d15b..3fadb58e804 100644
--- a/doc/university/training/topics/getting_started.md
+++ b/doc/university/training/topics/getting_started.md
@@ -8,14 +8,15 @@ comments: false
 
 - Create a new repository by instantiating it through:
 
-    ```bash
-    git init
-    ```
+  ```bash
+  git init
+  ```
+
 - Copy an existing project by cloning the repository through:
 
-    ```bash
-    git clone <url>
-    ```
+  ```bash
+  git clone <url>
+  ```
 
 ## Central Repos
 
@@ -23,9 +24,9 @@ comments: false
 - Bare repositories don't allow file editing or committing changes.
 - Create a bare repo with:
 
-    ```bash
-    git init --bare project-name.git
-    ```
+  ```bash
+  git init --bare project-name.git
+  ```
 
 ## Instantiate workflow with clone
 
@@ -34,8 +35,6 @@ comments: false
 1. Create a '`Workspace`' directory in your home directory.
 1. Clone the '`training-examples`' project.
 
-## Commands
-
 ```sh
 mkdir ~/workspace
 cd ~/workspace
@@ -68,8 +67,6 @@ Modified files that have been marked to go in the next commit.
 1. Push the commit to the remote
 1. View the git log
 
-## Commands
-
 ```sh
 # Edit `edit_this_file.rb`
 git status
diff --git a/doc/university/training/topics/git_add.md b/doc/university/training/topics/git_add.md
index 4c61d5eb175..0c9a50bb5e1 100644
--- a/doc/university/training/topics/git_add.md
+++ b/doc/university/training/topics/git_add.md
@@ -4,38 +4,34 @@ comments: false
 
 # Git Add
 
-## Git Add
-
 Adds content to the index or staging area.
 
 - Adds a list of file:
 
-    ```bash
-    git add <files>
-    ```
+  ```bash
+  git add <files>
+  ```
 
 - Adds all files including deleted ones:
 
-    ```bash
-    git add -A
-    ```
-
-## Git add continued
+  ```bash
+  git add -A
+  ```
 
 - Add all text files in current dir:
 
-    ```bash
-    git add *.txt
-    ```
+  ```bash
+  git add *.txt
+  ```
 
 - Add all text file in the project:
 
-    ```bash
-    git add "*.txt*"
-    ```
+  ```bash
+  git add "*.txt*"
+  ```
 
 - Adds all files in directory:
 
-    ```bash
-    git add views/layouts/
-    ```
+  ```bash
+  git add views/layouts/
+  ```
diff --git a/doc/university/training/topics/git_log.md b/doc/university/training/topics/git_log.md
index 11addcd3ee1..bae734554f5 100644
--- a/doc/university/training/topics/git_log.md
+++ b/doc/university/training/topics/git_log.md
@@ -8,33 +8,33 @@ Git log lists commit history. It allows searching and filtering.
 
 - Initiate log:
 
-    ```sh
-    git log
-    ```
+  ```sh
+  git log
+  ```
 
 - Retrieve set number of records:
 
-    ```sh
-    git log -n 2
-    ```
+  ```sh
+  git log -n 2
+  ```
 
 - Search commits by author. Allows user name or a regular expression.
 
-    ```sh
-    git log --author="user_name"
-    ```
+  ```sh
+  git log --author="user_name"
+  ```
 
 - Search by comment message:
 
-    ```sh
-    git log --grep="<pattern>"
-    ```
+  ```sh
+  git log --grep="<pattern>"
+  ```
 
 - Search by date:
 
-    ```sh
-    git log --since=1.month.ago --until=3.weeks.ago
-    ```
+  ```sh
+  git log --since=1.month.ago --until=3.weeks.ago
+  ```
 
 ## Git Log Workflow
 
diff --git a/doc/university/training/topics/merge_conflicts.md b/doc/university/training/topics/merge_conflicts.md
index dd235fe3a81..97bb038f405 100644
--- a/doc/university/training/topics/merge_conflicts.md
+++ b/doc/university/training/topics/merge_conflicts.md
@@ -9,7 +9,7 @@ comments: false
 - Practice makes perfect
 - Force push after fixing conflicts. Be careful!
 
-## Merge conflicts
+## Merge conflicts sample workflow
 
 1. Checkout a new branch and edit `conflicts.rb`. Add 'Line4' and 'Line5'.
 1. Commit and push.
@@ -22,8 +22,6 @@ comments: false
 1. Force push the changes.
 1. Finally continue with the Merge Request.
 
-## Commands
-
 ```sh
 git checkout -b conflicts_branch
 
diff --git a/doc/university/training/topics/merge_requests.md b/doc/university/training/topics/merge_requests.md
index b5bbe7b2e1e..656871ae5b2 100644
--- a/doc/university/training/topics/merge_requests.md
+++ b/doc/university/training/topics/merge_requests.md
@@ -30,8 +30,6 @@ comments: false
 - Be as receptive as possible
 - Feedback is about the best code, not the person. You are not your code
 
-## Feedback and Collaboration
-
 Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests:
 [https://github.com/thoughtbot/guides/tree/master/code-review](https://github.com/thoughtbot/guides/tree/master/code-review)
 
diff --git a/doc/university/training/topics/rollback_commits.md b/doc/university/training/topics/rollback_commits.md
index 1e6602deef2..c17e8d59737 100644
--- a/doc/university/training/topics/rollback_commits.md
+++ b/doc/university/training/topics/rollback_commits.md
@@ -8,29 +8,29 @@ comments: false
 
 - Undo last commit putting everything back into the staging area:
 
-    ```sh
-    git reset --soft HEAD^
-    ```
+  ```sh
+  git reset --soft HEAD^
+  ```
 
 - Add files and change message with:
 
-    ```sh
-    git commit --amend -m "New Message"
-    ```
+  ```sh
+  git commit --amend -m "New Message"
+  ```
 
 - Undo last and remove changes:
 
-    ```sh
-    git reset --hard HEAD^
-    ```
+  ```sh
+  git reset --hard HEAD^
+  ```
 
 - Same as last one but for two commits back:
 
-    ```sh
-    git reset --hard HEAD^^
-    ```
+  ```sh
+  git reset --hard HEAD^^
+  ```
 
-** Don't reset after pushing **
+**Don't reset after pushing**
 
 ## Reset Workflow
 
diff --git a/doc/university/training/topics/stash.md b/doc/university/training/topics/stash.md
index 02b2f610266..d3e63db0c6a 100644
--- a/doc/university/training/topics/stash.md
+++ b/doc/university/training/topics/stash.md
@@ -9,52 +9,52 @@ and we need to change to a different branch.
 
 - Stash:
 
-    ```sh
-    git stash save
-    # or
-    git stash
-    # or with a message
-    git stash save "this is a message to display on the list"
-    ```
+  ```sh
+  git stash save
+  # or
+  git stash
+  # or with a message
+  git stash save "this is a message to display on the list"
+  ```
 
 - Apply stash to keep working on it:
 
-    ```sh
-    git stash apply
-    # or apply a specific one from out stack
-    git stash apply stash@{3}
-    ```
+  ```sh
+  git stash apply
+  # or apply a specific one from out stack
+  git stash apply stash@{3}
+  ```
 
-- Every time we save a stash it gets stacked so by using list we can see all our
+- Every time we save a stash it gets stacked so by using `list` we can see all our
   stashes.
 
-    ```sh
-    git stash list
-    # or for more information (log methods)
-    git stash list --stat
-    ```
+  ```sh
+  git stash list
+  # or for more information (log methods)
+  git stash list --stat
+  ```
 
 - To clean our stack we need to manually remove them:
 
-    ```sh
-    # drop top stash
-    git stash drop
-    # or
-    git stash drop <name>
-    # to clear all history we can use
-    git stash clear
-    ```
+  ```sh
+  # drop top stash
+  git stash drop
+  # or
+  git stash drop <name>
+  # to clear all history we can use
+  git stash clear
+  ```
 
 - Apply and drop on one command:
 
-    ```sh
-      git stash pop
-    ```
+  ```sh
+  git stash pop
+  ```
 
 - If we meet conflicts we need to either reset or commit our changes.
 - Conflicts through `pop` will not drop a stash afterwards.
 
-## Git Stash
+## Git Stash sample workflow
 
 1. Modify a file
 1. Stage file
@@ -64,8 +64,6 @@ and we need to change to a different branch.
 1. Apply with pop
 1. View list to confirm changes
 
-## Commands
-
 ```sh
 # Modify edit_this_file.rb file
 git add .
diff --git a/doc/university/training/topics/tags.md b/doc/university/training/topics/tags.md
index cdbb8a2da7c..631b93cc384 100644
--- a/doc/university/training/topics/tags.md
+++ b/doc/university/training/topics/tags.md
@@ -11,18 +11,12 @@ type: reference
 - Many projects combine an annotated release tag with a stable branch
 - Consider setting deployment/release tags automatically
 
-# Tags
+## Tags sample workflow
 
 - Create a lightweight tag
 - Create an annotated tag
 - Push the tags to the remote repository
 
-**Additional resources**
-
-<https://git-scm.com/book/en/Git-Basics-Tagging>
-
-# Commands
-
 ```sh
 git checkout master
 
@@ -36,6 +30,10 @@ git tag
 git push origin --tags
 ```
 
+**Additional resources**
+
+<https://git-scm.com/book/en/Git-Basics-Tagging>
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues
diff --git a/doc/university/training/topics/unstage.md b/doc/university/training/topics/unstage.md
index af16afdc5d1..d7482bf2bd5 100644
--- a/doc/university/training/topics/unstage.md
+++ b/doc/university/training/topics/unstage.md
@@ -4,29 +4,27 @@ comments: false
 
 # Unstage
 
-## Unstage
+- To remove files from stage use reset HEAD where HEAD is the last commit of the current branch. This will unstage the file but maintain the modifications.
 
-- To remove files from stage use reset HEAD where HEAD is the last commit of the current branch. This will unstage the file but maintain the modifications. 
-
-    ```bash
-    git reset HEAD <file>
-    ```
+  ```bash
+  git reset HEAD <file>
+  ```
 
 - To revert the file back to the state it was in before the changes we can use:
 
-    ```bash
-    git checkout -- <file>
-    ```
+  ```bash
+  git checkout -- <file>
+  ```
 
 - To remove a file from disk and repo use 'git rm' and to rm a dir use the '-r' flag:
 
-    ```sh
-    git rm '*.txt'
-    git rm -r <dirname>
-    ```
+  ```sh
+  git rm '*.txt'
+  git rm -r <dirname>
+  ```
 
 - If we want to remove a file from the repository but keep it on disk, say we forgot to add it to our `.gitignore` file then use `--cache`:
 
-    ```sh
-    git rm <filename> --cache
-    ```
+  ```sh
+  git rm <filename> --cache
+  ```
diff --git a/doc/update/README.md b/doc/update/README.md
index e2fffadb1ea..42c43110a19 100644
--- a/doc/update/README.md
+++ b/doc/update/README.md
@@ -49,8 +49,7 @@ However, for this to work there are the following requirements:
 - You have to use [post-deployment
    migrations](../development/post_deployment_migrations.md) (included in
    zero downtime update steps below).
-- You are using PostgreSQL. If you are using MySQL please look at the release
-   post to see if downtime is required.
+- You are using PostgreSQL. Starting from GitLab 12.1, MySQL is not supported.
 
 Most of the time you can safely upgrade from a patch release to the next minor
 release if the patch release is not the latest. For example, upgrading from
@@ -136,17 +135,39 @@ If you need to downgrade your Enterprise Edition installation back to Community
 Edition, you can follow [this guide][ee-ce] to make the process as smooth as
 possible.
 
+## Version specific upgrading instructions
+
+### 12.2.0
+
+In 12.2.0, we enabled Rails' authenticated cookie encryption. Old sessions are
+automatically upgraded.
+
+However, session cookie downgrades are not supported. So after upgrading to 12.2.0,
+any downgrades would result to all sessions being invalidated and users are logged out.
+
+### 12.0.0
+
+In 12.0.0 we made various database related changes. These changes require that
+users first upgrade to the latest 11.11 patch release. Once upgraded to 11.11.x,
+users can upgrade to 12.x. Failure to do so may result in database migrations
+not being applied, which could lead to application errors.
+
+Example 1: you are currently using GitLab 11.11.3, which is the latest patch
+release for 11.11.x. You can upgrade as usual to 12.0.0, 12.1.0, etc.
+
+Example 2: you are currently using a version of GitLab 10.x. To upgrade, first
+upgrade to 11.11.3. Once upgraded to 11.11.3 you can safely upgrade to 12.0.0
+or future versions.
+
 ## Miscellaneous
 
 - [MySQL to PostgreSQL](mysql_to_postgresql.md) guides you through migrating
   your database from MySQL to PostgreSQL.
-- [MySQL installation guide](../install/database_mysql.md) contains additional
-  information about configuring GitLab to work with a MySQL database.
 - [Restoring from backup after a failed upgrade](restore_after_failure.md)
 - [Upgrading PostgreSQL Using Slony](upgrading_postgresql_using_slony.md), for
   upgrading a PostgreSQL database with minimal downtime.
 
-[omnidocker]: http://docs.gitlab.com/omnibus/docker/README.html
+[omnidocker]: https://docs.gitlab.com/omnibus/docker/README.html
 [old-ee-upgrade-docs]: https://gitlab.com/gitlab-org/gitlab-ee/tree/11-8-stable-ee/doc/update
 [old-ce-upgrade-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/11-8-stable/doc/update
 [source-ce-to-ee]: upgrading_from_ce_to_ee.md
diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md
index b83abcd36f7..f6a1b6abdbf 100644
--- a/doc/update/mysql_to_postgresql.md
+++ b/doc/update/mysql_to_postgresql.md
@@ -1,5 +1,5 @@
 ---
-last_updated: 2019-03-27
+last_updated: 2019-06-18
 ---
 
 # Migrating from MySQL to PostgreSQL
@@ -9,7 +9,11 @@ migrate it to a PostgreSQL database.
 
 ## Requirements
 
-[pgloader](http://pgloader.io) 3.4.1+ is required.
+NOTE: **Note:**
+Support for MySQL was removed in GitLab 12.1. This procedure should be performed
+**before** installing GitLab 12.1.
+
+[pgloader](https://pgloader.io/) 3.4.1+ is required.
 
 You can install it directly from your distribution, for example in
 Debian/Ubuntu:
@@ -55,7 +59,7 @@ pgloader within the container as it is not included in the container image.
    ```
 
 1. Install pgloader:
-    
+
    ``` bash
    apt-get update
    apt-get -y install pgloader
@@ -68,15 +72,15 @@ need to enable the bundled PostgreSQL:
 
 1. Stop GitLab:
 
-    ```bash
-    sudo gitlab-ctl stop
-    ```
+   ```bash
+   sudo gitlab-ctl stop
+   ```
 
 1. Edit `/etc/gitlab/gitlab.rb` to enable bundled PostgreSQL:
 
-    ```
-    postgresql['enable'] = true
-    ```
+   ```
+   postgresql['enable'] = true
+   ```
 
 1. Edit `/etc/gitlab/gitlab.rb` to use the bundled PostgreSQL. Please check
    all the settings beginning with `db_`, such as `gitlab_rails['db_adapter']`
@@ -87,22 +91,22 @@ need to enable the bundled PostgreSQL:
    for the changes to take effect.
 1. Start Unicorn and PostgreSQL so that we can prepare the schema:
 
-    ```bash
-    sudo gitlab-ctl start unicorn
-    sudo gitlab-ctl start postgresql
-    ```
+   ```bash
+   sudo gitlab-ctl start unicorn
+   sudo gitlab-ctl start postgresql
+   ```
 
 1. Run the following commands to prepare the schema:
 
-    ```bash
-    sudo gitlab-rake db:create db:migrate
-    ```
+   ```bash
+   sudo gitlab-rake db:create db:migrate
+   ```
 
 1. Stop Unicorn to prevent other database access from interfering with the loading of data:
 
-    ```bash
-    sudo gitlab-ctl stop unicorn
-    ```
+   ```bash
+   sudo gitlab-ctl stop unicorn
+   ```
 
 After these steps, you'll have a fresh PostgreSQL database with up-to-date schema.
 
@@ -112,57 +116,57 @@ new PostgreSQL one:
 1. Save the following snippet in a `commands.load` file, and edit with your
    MySQL database `username`, `password` and `host`:
 
-    ```
-    LOAD DATABASE
-         FROM mysql://username:password@host/gitlabhq_production
-         INTO postgresql://gitlab-psql@unix://var/opt/gitlab/postgresql:/gitlabhq_production
+   ```
+   LOAD DATABASE
+        FROM mysql://username:password@host/gitlabhq_production
+        INTO postgresql://gitlab-psql@unix://var/opt/gitlab/postgresql:/gitlabhq_production
 
-    WITH include no drop, truncate, disable triggers, create no tables,
-         create no indexes, preserve index names, no foreign keys,
-         data only
+   WITH include no drop, truncate, disable triggers, create no tables,
+        create no indexes, preserve index names, no foreign keys,
+        data only
 
-    ALTER SCHEMA 'gitlabhq_production' RENAME TO 'public'
+   ALTER SCHEMA 'gitlabhq_production' RENAME TO 'public'
 
-    ;
-    ```
+   ;
+   ```
 
 1. Start the migration:
 
-    ```bash
-    sudo -u gitlab-psql pgloader commands.load
-    ```
+   ```bash
+   sudo -u gitlab-psql pgloader commands.load
+   ```
 
 1. Once the migration finishes, you should see a summary table that looks like
    the following:
 
-    ```
-                                     table name       read   imported     errors      total time
-    -----------------------------------------------  ---------  ---------  ---------  --------------
-                                    fetch meta data        119        119          0          0.388s
-                                           Truncate        119        119          0          1.134s
-    -----------------------------------------------  ---------  ---------  ---------  --------------
-                               public.abuse_reports          0          0          0          0.490s
-                                 public.appearances          0          0          0          0.488s
-                                           .
-                                           .
-                                           .
-                               public.web_hook_logs          0          0          0          1.080s
-    -----------------------------------------------  ---------  ---------  ---------  --------------
-                            COPY Threads Completion          4          4          0          2.008s
-                                    Reset Sequences        113        113          0          0.304s
-                                   Install Comments          0          0          0          0.000s
-    -----------------------------------------------  ---------  ---------  ---------  --------------
-                                  Total import time       1894       1894          0         12.497s
-    ```
-
-    If there is no output for more than 30 minutes, it's possible `pgloader` encountered an error. See
-    the [troubleshooting guide](#troubleshooting) for more details.
+   ```
+                                    table name       read   imported     errors      total time
+   -----------------------------------------------  ---------  ---------  ---------  --------------
+                                   fetch meta data        119        119          0          0.388s
+                                          Truncate        119        119          0          1.134s
+   -----------------------------------------------  ---------  ---------  ---------  --------------
+                              public.abuse_reports          0          0          0          0.490s
+                                public.appearances          0          0          0          0.488s
+                                          .
+                                          .
+                                          .
+                              public.web_hook_logs          0          0          0          1.080s
+   -----------------------------------------------  ---------  ---------  ---------  --------------
+                           COPY Threads Completion          4          4          0          2.008s
+                                   Reset Sequences        113        113          0          0.304s
+                                  Install Comments          0          0          0          0.000s
+   -----------------------------------------------  ---------  ---------  ---------  --------------
+                                 Total import time       1894       1894          0         12.497s
+   ```
+
+   If there is no output for more than 30 minutes, it's possible `pgloader` encountered an error. See
+   the [troubleshooting guide](#troubleshooting) for more details.
 
 1. Start GitLab:
 
-    ```bash
-    sudo gitlab-ctl start
-    ```
+   ```bash
+   sudo gitlab-ctl start
+   ```
 
 You can now verify that everything works as expected by visiting GitLab.
 
diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md
index f2df4277ca8..0506d992d4b 100644
--- a/doc/update/patch_versions.md
+++ b/doc/update/patch_versions.md
@@ -13,8 +13,6 @@ You can select the tag in the version dropdown in the top left corner of GitLab
 ### 0. Backup
 
 It's useful to make a backup just in case things go south:
-(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab
-user on the database version)
 
 ```bash
 cd /home/git/gitlab
@@ -48,12 +46,8 @@ sudo -u git -H git checkout LATEST_TAG -b LATEST_TAG
 ```bash
 cd /home/git/gitlab
 
-# PostgreSQL
 sudo -u git -H bundle install --without development test mysql --deployment
 
-# MySQL
-sudo -u git -H bundle install --without development test postgres --deployment
-
 # Optional: clean up old gems
 sudo -u git -H bundle clean
 
@@ -106,7 +100,7 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
 sudo -u git -H make
 ```
 
-### 8. Install/Update `gitlab-elasticsearch-indexer` (optional) **[STARTER ONLY]**
+### 8. Install/Update `gitlab-elasticsearch-indexer` (optional) **(STARTER ONLY)**
 
 If you're interested in using GitLab's new [elasticsearch repository indexer](../integration/elasticsearch.md#elasticsearch-repository-indexer-beta) (currently in beta)
 please follow the instructions on the document linked above and enable the
diff --git a/doc/update/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md
index 428377adb19..bea5bcd9dd7 100644
--- a/doc/update/upgrading_from_ce_to_ee.md
+++ b/doc/update/upgrading_from_ce_to_ee.md
@@ -25,14 +25,14 @@ Branch names use the format `major-minor-stable-ee` for Enterprise Edition, and
 `major-minor-stable` for Community Edition. For example, for 11.8.0 you would
 use the following branches:
 
-* Enterprise Edition: `11-8-stable-ee`
-* Community Edition: `11-8-stable`
+- Enterprise Edition: `11-8-stable-ee`
+- Community Edition: `11-8-stable`
 
 ### 0. Backup
 
 Make a backup just in case something goes wrong:
 
-```bash
+```sh
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
@@ -42,13 +42,13 @@ privileges to the GitLab user on the database version.
 
 ### 1. Stop server
 
-```bash
+```sh
 sudo service gitlab stop
 ```
 
 ### 2. Get the EE code
 
-```bash
+```sh
 cd /home/git/gitlab
 sudo -u git -H git remote add -f ee https://gitlab.com/gitlab-org/gitlab-ee.git
 sudo -u git -H git checkout EE_BRANCH
@@ -56,7 +56,7 @@ sudo -u git -H git checkout EE_BRANCH
 
 ### 3. Install libs, migrations, etc.
 
-```bash
+```sh
 cd /home/git/gitlab
 
 # MySQL installations (note: the line below states '--without postgres')
@@ -72,7 +72,7 @@ sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production
 sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production
 ```
 
-### 4. Install `gitlab-elasticsearch-indexer` (optional) **[STARTER ONLY]**
+### 4. Install `gitlab-elasticsearch-indexer` (optional) **(STARTER ONLY)**
 
 If you're interested in using GitLab's new [elasticsearch repository
 indexer](../integration/elasticsearch.md) (currently in beta) please follow the instructions on the
@@ -80,7 +80,7 @@ document linked above and enable the indexer usage in the GitLab admin settings.
 
 ### 5. Start application
 
-```bash
+```sh
 sudo service gitlab start
 sudo service nginx restart
 ```
@@ -89,13 +89,13 @@ sudo service nginx restart
 
 Check if GitLab and its environment are configured correctly:
 
-```bash
+```sh
 sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production
 ```
 
 To make sure you didn't miss anything run a more thorough check with:
 
-```bash
+```sh
 sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production
 ```
 
@@ -105,14 +105,14 @@ If all items are green, then congratulations upgrade complete!
 
 ### 1. Revert the code to the previous version
 
-```bash
+```sh
 cd /home/git/gitlab
 sudo -u git -H git checkout CE_BRANCH
 ```
 
 ### 2. Restore from the backup
 
-```bash
+```sh
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
 ```
diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md
index bc8e5fed774..df35638cba2 100644
--- a/doc/update/upgrading_from_source.md
+++ b/doc/update/upgrading_from_source.md
@@ -4,6 +4,10 @@ comments: false
 
 # Upgrading Community Edition and Enterprise Edition from source
 
+NOTE: **Note:**
+Users wishing to upgrade to 12.0.0 will have to take some extra steps. See the
+version specific upgrade instructions for 12.0.0 for more details.
+
 Make sure you view this update guide from the branch (version) of GitLab you
 would like to install (e.g., `11.8`. You can select the version in the version
 dropdown at the top left corner of GitLab (below the menu bar).
@@ -43,8 +47,8 @@ sudo service gitlab stop
 
 ### 3. Update Ruby
 
-NOTE: Beginning in GitLab 11.6, we only support Ruby 2.5 or higher, and dropped
-support for Ruby 2.4. Be sure to upgrade if necessary.
+NOTE: Beginning in GitLab 12.2, we only support Ruby 2.6 or higher, and dropped
+support for Ruby 2.5. Be sure to upgrade if necessary.
 
 You can check which version you are running with `ruby -v`.
 
@@ -72,7 +76,7 @@ sudo gem install bundler --no-document --version '< 2'
 NOTE: Beginning in GitLab 11.8, we only support node 8 or higher, and dropped
 support for node 6. Be sure to upgrade if necessary.
 
-GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets.
+GitLab utilizes [webpack](https://webpack.js.org/) to compile frontend assets.
 This requires a minimum version of node v8.10.0.
 
 You can check which version you are running with `node -v`. If you are running
@@ -235,29 +239,7 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
 sudo -u git -H make
 ```
 
-### 12. Update MySQL permissions
-
-If you are using MySQL you need to grant the GitLab user the necessary
-permissions on the database:
-
-```bash
-mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';"
-```
-
-If you use MySQL with replication, or just have MySQL configured with binary logging,
-you will need to also run the following on all of your MySQL servers:
-
-```bash
-mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;"
-```
-
-You can make this setting permanent by adding it to your `my.cnf`:
-
-```
-log_bin_trust_function_creators=1
-```
-
-### 13. Update configuration files
+### 12. Update configuration files
 
 #### New configuration options for `gitlab.yml`
 
@@ -331,18 +313,13 @@ For Ubuntu 16.04.1 LTS:
 sudo systemctl daemon-reload
 ```
 
-### 14. Install libs, migrations, etc.
+### 13. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
 
-# PostgreSQL installations (note: the line below states '--without mysql')
 sudo -u git -H bundle install --deployment --without development test mysql aws kerberos
 
-# MySQL installations (note: the line below states '--without postgres')
-sudo -u git -H bundle install --deployment --without development test postgres aws kerberos
-
-
 # Optional: clean up old gems
 sudo -u git -H bundle clean
 
@@ -360,17 +337,14 @@ sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:c
 sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production
 ```
 
-**MySQL installations**: Run through the `MySQL strings limits` and `Tables and
-data conversion to utf8mb4` [tasks](../install/database_mysql.md).
-
-### 15. Start application
+### 14. Start application
 
 ```bash
 sudo service gitlab start
 sudo service nginx restart
 ```
 
-### 16. Check application status
+### 15. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md
index 41ee7e62b2c..e6c86cc8f2e 100644
--- a/doc/user/abuse_reports.md
+++ b/doc/user/abuse_reports.md
@@ -1,6 +1,12 @@
 # Abuse reports
 
-Report abuse from users to GitLab administrators.
+You can report abuse from other GitLab users to GitLab administrators.
+
+A GitLab administrator [can then choose](admin_area/abuse_reports.md) to:
+
+- Remove the user, which deletes them from the instance.
+- Block the user, which denies them access to the instance.
+- Or remove the report, which retains the users access to the instance.
 
 You can report a user through their:
 
@@ -12,7 +18,8 @@ You can report a user through their:
 
 To report abuse from a user's profile page:
 
-1. Click on the exclamation point report abuse button at the top right of the user's profile.
+1. Click on the exclamation point report abuse button at the top right of the
+   user's profile.
 1. Complete an abuse report.
 1. Click the **Send report** button.
 
@@ -26,15 +33,18 @@ To report abuse from a user's comment:
 1. Click the **Send report** button.
 
 NOTE: **Note:**
-A URL to the reported user's comment will be
-pre-filled in the abuse report's **Message** field.
+A URL to the reported user's comment will be pre-filled in the abuse report's
+**Message** field.
 
 ## Reporting abuse through a user's issue or merge request
 
 The **Report abuse** button is displayed at the top right of the issue or merge request:
 
-- When **Report abuse** is selected from the menu that appears when the **Close issue** or **Close merge request** button is clicked, for users that have permission to close the issue or merge request.
-- When viewing the issue or merge request, for users that don't have permission to close the issue or merge request.
+- When **Report abuse** is selected from the menu that appears when the
+  **Close issue** or **Close merge request** button is clicked, for users that
+  have permission to close the issue or merge request.
+- When viewing the issue or merge request, for users that don't have permission
+  to close the issue or merge request.
 
 With the **Report abuse** button displayed, to submit an abuse report:
 
diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md
index 01c2d9607f5..0c5d2f81e25 100644
--- a/doc/user/admin_area/abuse_reports.md
+++ b/doc/user/admin_area/abuse_reports.md
@@ -1,31 +1,77 @@
+---
+type: reference, howto
+---
+
 # Abuse reports
 
 View and resolve abuse reports from GitLab users.
 
-Admins can view abuse reports in the admin area and are able to
-resolve the reports by removing the reported user, blocking the reported user, or removing the report.
+GitLab administrators can view and [resolve](#resolving-abuse-reports) abuse
+reports in the Admin Area.
 
 ## Reporting abuse
 
-To find out more about reporting abuse, see [abuse reports user documentation](../abuse_reports.md).
+To find out more about reporting abuse, see [abuse reports user
+documentation](../abuse_reports.md).
 
 ## Resolving abuse reports
 
-To access abuse reports, go to **Admin area > Abuse Reports**.
+To access abuse reports, go to **Admin Area > Abuse Reports**.
 
 There are 3 ways to resolve an abuse report, with a button for each method:
 
-- Remove user & report: [Deletes the reported user](../profile/account/delete_account.md) from the instance and removes the abuse report from the list.
-- Block user: Blocks the reported user from the instance and does not remove the abuse report from the list.
-- Remove report: Removes the abuse report from the list and does not restrict the access for the reported user.
+- Remove user & report. This will:
+  - [Delete the reported user](../profile/account/delete_account.md) from the
+    instance.
+  - Remove the abuse report from the list.
+- [Block user](#blocking-users).
+- Remove report. This will:
+  - Remove the abuse report from the list.
+  - Remove access restrictions for the reported user.
+
+The following is an example of the **Abuse Reports** page:
 
 ![abuse-reports-page-image](img/abuse_reports_page.png)
 
-## Blocked users
+### Blocking users
+
+A blocked user cannot log in or access any repositories, but all of their data
+remains.
+
+Blocking a user:
+
+- Leaves them in the abuse report list.
+- Changes the **Block user** button to a disabled **Already blocked** button.
+
+The user will be notified with the
+[following message](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/app/workers/email_receiver_worker.rb#L38):
 
-Blocking a user will not remove the abuse report from the list.
+```text
+Your account has been blocked. If you believe this is in error, contact a staff member.
+```
 
-Instead, the block button will be disabled and explain that the user is "Already blocked".
-You are still able to remove the user and/or report if necessary.
+After blocking, you can still either:
+
+- Remove the user and report if necessary.
+- Remove the report.
+
+The following is an example of a blocked user listed on the **Abuse Reports**
+page:
 
 ![abuse-report-blocked-user-image](img/abuse_report_blocked_user.png)
+
+NOTE: **Note:**
+Users can be [blocked](../../api/users.md#block-user) and
+[unblocked](../../api/users.md#unblock-user) using the GitLab API.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md
index 02445abdb37..01b6558bdbe 100644
--- a/doc/user/admin_area/broadcast_messages.md
+++ b/doc/user/admin_area/broadcast_messages.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # Broadcast Messages
 
 GitLab can display messages to all users of a GitLab instance in a banner that appears in the UI.
@@ -51,3 +55,15 @@ Once deleted, the broadcast message is removed from the list of broadcast messag
 
 NOTE: **Note:**
 Broadcast messages can be deleted while active.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md
index e34ba045c54..02c2efaa4f3 100644
--- a/doc/user/admin_area/custom_project_templates.md
+++ b/doc/user/admin_area/custom_project_templates.md
@@ -1,26 +1,49 @@
-# Custom instance-level project templates **[PREMIUM ONLY]**
+---
+type: reference
+---
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing) 11.2.
+# Custom instance-level project templates **(PREMIUM ONLY)**
 
-When you create a new [project](../project/index.md), creating it based on custom project templates is
-a convenient bootstrap option.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2.
 
-GitLab administrators can configure a GitLab group that serves as template
-source for an entire GitLab instance under **Admin area > Settings > Custom project templates**.
+GitLab administrators can configure the group where all the custom project
+templates are sourced.
+
+Every project directly under the group namespace will be
+available to the user if they have access to them. For example:
+
+- Public project in the group will be available to every logged in user.
+- Private projects will be available only if the user is a member of the project.
+
+Repository and database information that are copied over to each new project are
+identical to the data exported with
+[GitLab's Project Import/Export](../project/settings/import_export.md).
 
 NOTE: **Note:**
 To set project templates at a group level,
 see [Custom group-level project templates](../group/custom_project_templates.md).
 
-Within this section, you can configure the group where all the custom project
-templates are sourced. Every project directly under the group namespace will be
-available to the user if they have access to them. For example, every public
-project in the group will be available to every logged in user.
+## Configuring
 
-However, private projects will be available only if the user is a member of the project.
+GitLab administrators can configure a GitLab group that serves as template
+source for an entire GitLab instance by:
+
+1. Navigating to **Admin area > Settings > Templates**.
+1. Expanding **Custom project templates**.
+1. Selecting a group to use.
+1. Pressing **Save changes**.
 
 NOTE: **Note:**
 Projects below subgroups of the template group are **not** supported.
 
-Repository and database information that are copied over to each new project are
-identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md).
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md
index d99b87cbc5c..39753fd885e 100644
--- a/doc/user/admin_area/geo_nodes.md
+++ b/doc/user/admin_area/geo_nodes.md
@@ -2,7 +2,7 @@
 type: howto
 ---
 
-# Geo nodes admin area **[PREMIUM ONLY]**
+# Geo nodes admin area **(PREMIUM ONLY)**
 
 You can configure various settings for GitLab Geo nodes. For more information, see
 [Geo documentation](../../administration/geo/replication/index.md).
@@ -61,6 +61,12 @@ which is used by users. Internal URL does not need to be a private address.
 Internal URL defaults to External URL, but you can customize it under
 **Admin area > Geo Nodes**.
 
+CAUTION: **Warning:**
+We recommend using an HTTPS connection while configuring the Geo nodes. To avoid
+breaking communication between **primary** and **secondary** nodes when using
+HTTPS, customize your Internal URL to point to a load balancer with TLS
+terminated at the load balancer.
+
 ## Multiple secondary nodes behind a load balancer
 
 In GitLab 11.11, **secondary** nodes can use identical external URLs as long as
@@ -83,4 +89,4 @@ questions that you know someone might ask.
 
 Each scenario can be a third-level heading, e.g. `### Getting error message X`.
 If you have none to add when creating a doc, leave this section in place
-but commented out to help encourage others to add to it in the future. -->
\ No newline at end of file
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/admin_area/img/abuse_report_blocked_user.png b/doc/user/admin_area/img/abuse_report_blocked_user.png
index 0cb4c7bb8ac..435d8dfe821 100644
--- a/doc/user/admin_area/img/abuse_report_blocked_user.png
+++ b/doc/user/admin_area/img/abuse_report_blocked_user.png
diff --git a/doc/user/admin_area/img/abuse_reports_page.png b/doc/user/admin_area/img/abuse_reports_page.png
index 81dbe976cda..30e932211cb 100644
--- a/doc/user/admin_area/img/abuse_reports_page.png
+++ b/doc/user/admin_area/img/abuse_reports_page.png
diff --git a/doc/user/admin_area/img/broadcast_messages.png b/doc/user/admin_area/img/broadcast_messages.png
index 926d38ae049..f0ae92f8c17 100644
--- a/doc/user/admin_area/img/broadcast_messages.png
+++ b/doc/user/admin_area/img/broadcast_messages.png
diff --git a/doc/user/admin_area/img/license_details.png b/doc/user/admin_area/img/license_details.png
index 2085bb437ad..3e980d9316d 100644
--- a/doc/user/admin_area/img/license_details.png
+++ b/doc/user/admin_area/img/license_details.png
diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md
index 91c771764f8..9bc0f64b68d 100644
--- a/doc/user/admin_area/index.md
+++ b/doc/user/admin_area/index.md
@@ -2,7 +2,7 @@
 type: reference
 ---
 
-# GitLab Admin Area **[CORE ONLY]**
+# GitLab Admin Area **(CORE ONLY)**
 
 The Admin Area provides a web UI for administering some features of GitLab self-managed instances.
 
@@ -18,22 +18,22 @@ Only admin users can access the Admin Area.
 
 The Admin Area is made up of the following sections:
 
-| Section                    | Description                                                                                                                                              |
-|:---------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Overview                   | View your GitLab [Dashboard](#admin-dashboard), and administer [projects](#administer-projects), [users](#administer-users), [groups](#administer-groups), [jobs](#administer-jobs), [Runners](#administer-runners), and [Gitaly servers](#administer-gitaly-servers).       |
-| Monitoring                 | View GitLab system information, and information on background jobs, logs, [health checks](monitoring/health_check.md), request profiles, and audit logs. |
-| Messages                   | Send and manage [broadcast messages](broadcast_messages.md) for your users.                                                                              |
-| System Hooks               | Configure [system hooks](../../system_hooks/system_hooks.md) for many events.                                                                            |
-| Applications               | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services.                                            |
-| Abuse Reports              | Manage [abuse reports](abuse_reports.md) submitted by your users.                                                                                        |
-| License **[STARTER ONLY]** | Upload, display, and remove [licenses](license.md).                                                                                                      |
-| Push Rules **[STARTER]**   | Configure pre-defined git [push rules](../../push_rules/push_rules.md) for projects.                                              |
-| Geo **[PREMIUM ONLY]**     | Configure and maintain [Geo nodes](geo_nodes.md).                                                                                                        |
-| Deploy Keys                | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys).                                                                                 |
-| Service Templates          | Create [service templates](../project/integrations/services_templates.md) for projects.                                                                  |
-| Labels                     | Create and maintain [labels](labels.md) for your GitLab instance.                                                                                        |
-| Appearance                 | Customize [GitLab's appearance](../../customization/index.md).                                                                                           |
-| Settings                   | Modify the [settings](settings/index.md) for your GitLab instance.                                                                                       |
+| Section                       | Description                                                                                                                                                                                                                                                                              |
+|:------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [Overview](#overview-section) | View your GitLab [Dashboard](#admin-dashboard), and administer [projects](#administering-projects), [users](#administering-users), [groups](#administering-groups), [jobs](#administering-jobs), [Runners](#administering-runners), and [Gitaly servers](#administering-gitaly-servers). |
+| Monitoring                    | View GitLab [system information](#system-info), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), [requests profiles](#requests-profiles), and [audit logs](#audit-log-premium-only).                                                                                                                                 |
+| Messages                      | Send and manage [broadcast messages](broadcast_messages.md) for your users.                                                                                                                                                                                                              |
+| System Hooks                  | Configure [system hooks](../../system_hooks/system_hooks.md) for many events.                                                                                                                                                                                                            |
+| Applications                  | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services.                                                                                                                                                                            |
+| Abuse Reports                 | Manage [abuse reports](abuse_reports.md) submitted by your users.                                                                                                                                                                                                                        |
+| License **(STARTER ONLY)**    | Upload, display, and remove [licenses](license.md).                                                                                                                                                                                                                                      |
+| Push Rules **(STARTER)**      | Configure pre-defined git [push rules](../../push_rules/push_rules.md) for projects.                                                                                                                                                                                                     |
+| Geo **(PREMIUM ONLY)**        | Configure and maintain [Geo nodes](geo_nodes.md).                                                                                                                                                                                                                                        |
+| Deploy Keys                   | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys).                                                                                                                                                                                                                 |
+| Service Templates             | Create [service templates](../project/integrations/services_templates.md) for projects.                                                                                                                                                                                                  |
+| Labels                        | Create and maintain [labels](labels.md) for your GitLab instance.                                                                                                                                                                                                                        |
+| Appearance                    | Customize [GitLab's appearance](../../customization/index.md).                                                                                                                                                                                                                           |
+| Settings                      | Modify the [settings](settings/index.md) for your GitLab instance.                                                                                                                                                                                                                       |
 
 ## Admin Dashboard
 
@@ -46,16 +46,20 @@ To access the Dashboard, either:
 
 The Dashboard is the default view of the Admin Area, and is made up of the following sections:
 
-| Section    | Description   |
-|------------|---------------|
-| Projects   | The total number of projects, up to 10 of the latest projects, and the option of creating a new project. |
-| Users      | The total number of users, up to 10 of the latest users, and the option of creating a new user. |
-| Groups     | The total number of groups, up to 10 of the latest groups, and the option of creating a new group. |
-| Statistics | Totals of all elements of the GitLab instance. |
+| Section    | Description                                                                                                                                              |
+|:-----------|:---------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Projects   | The total number of projects, up to 10 of the latest projects, and the option of creating a new project.                                                 |
+| Users      | The total number of users, up to 10 of the latest users, and the option of creating a new user.                                                          |
+| Groups     | The total number of groups, up to 10 of the latest groups, and the option of creating a new group.                                                       |
+| Statistics | Totals of all elements of the GitLab instance.                                                                                                           |
 | Features   | All features available on the GitLab instance. Enabled features are marked with a green circle icon, and disabled features are marked with a power icon. |
-| Components | The major components of GitLab and the version number of each. A link to the Gitaly Servers is also included. |
+| Components | The major components of GitLab and the version number of each. A link to the Gitaly Servers is also included.                                            |
 
-## Administer Projects
+## Overview section
+
+The following topics document the **Overview** section of the Admin Area.
+
+### Administering Projects
 
 You can administer all projects in the GitLab instance from the Admin Area's Projects page.
 
@@ -95,7 +99,7 @@ You can combine the filter options. For example, to list only public projects wi
 1. Click the **Public** tab.
 1. Enter `score` in the **Filter by name...** input box.
 
-## Administer Users
+### Administering Users
 
 You can administer all users in the GitLab instance from the Admin Area's Users page.
 
@@ -120,7 +124,7 @@ To search for users, enter your criteria in the search field. The user search is
 insensitive, and applies partial matching to name and username. To search for an email address,
 you must provide the complete email address.
 
-## Administer Groups
+### Administering Groups
 
 You can administer all groups in the GitLab instance from the Admin Area's Groups page.
 
@@ -139,7 +143,7 @@ insensitive, and applies partial matching.
 
 To [Create a new group](../group/index.md#create-a-new-group) click **New group**.
 
-## Administer Jobs
+### Administering Jobs
 
 You can administer all jobs in the GitLab instance from the Admin Area's Jobs page.
 
@@ -163,9 +167,9 @@ For each job, the following details are listed:
 | Timing   | Duration of the job, and how long ago the job completed.                |
 | Coverage | Percentage of tests coverage.                                           |
 
-## Administer Runners
+### Administering Runners
 
-You can adminster all Runners in the GitLab instance from the Admin Area's **Runners** page. See
+You can administer all Runners in the GitLab instance from the Admin Area's **Runners** page. See
 [GitLab Runner](https://docs.gitlab.com/runner/) for more information on Runner itself.
 
 To access the **Runners** page, go to **Admin Area > Overview > Runners**.
@@ -182,7 +186,7 @@ the sort order to *Last Contacted* from the dropdown beside the search field.
 To search Runners' descriptions:
 
 1. In the **Search or filter results...** field, type the description of the Runner you want to
-find.
+   find.
 1. Press Enter.
 
 You can also filter Runners by status, type, and tag. To filter:
@@ -209,7 +213,7 @@ For each Runner, the following attributes are listed:
 
 You can also edit, pause, or remove each Runner.
 
-## Administer Gitaly servers
+### Administering Gitaly servers
 
 You can list all Gitaly servers in the GitLab instance from the Admin Area's **Gitaly Servers**
 page. For more details, see [Gitaly](../../administration/gitaly/index.md).
@@ -225,3 +229,66 @@ For each Gitaly server, the following details are listed:
 | Server version | Gitaly version |
 | Git version    | Version of Git installed on the Gitaly server |
 | Up to date     | Indicates if the Gitaly server version is the latest version available. A green dot indicates the server is up to date. |
+
+## Monitoring section
+
+The following topics document the **Monitoring** section of the Admin Area.
+
+### System Info
+
+The **System Info** page provides the following statistics:
+
+| Field        | Description |
+| :----------- | :---------- |
+| CPU          | Number of CPU cores available |
+| Memory Usage | Memory in use, and total memory available |
+| Disk Usage   | Disk space in use, and total disk space available |
+| Uptime       | Approximate uptime of the GitLab instance |
+
+These statistics are updated only when you navigate to the **System Info** page, or you refresh the page in your browser.
+
+### Background Jobs
+
+The **Background Jobs** page displays the Sidekiq dashboard. Sidekiq is used by GitLab to
+perform processing in the background.
+
+The Sidekiq dashboard consists of the following elements:
+
+- A tab per jobs' status.
+- A breakdown of background job statistics.
+- A live graph of **Processed** and **Failed** jobs, with a selectable polling interval.
+- An historical graph of **Processed** and **Failed** jobs, with a selectable time span.
+- Redis statistics, including:
+  - Version number
+  - Uptime, measured in days
+  - Number of connections
+  - Current memory usage, measured in MB
+  - Peak memory usage, measured in MB
+
+### Logs
+
+The **Logs** page provides access to the following log files:
+
+| Log file                | Contents |
+| :---------------------- | :------- |
+| `application.log`       | GitLab user activity |
+| `git_json.log`          | Failed GitLab interaction with Git repositories |
+| `production.log`        | Requests received from Unicorn, and the actions taken to serve those requests |
+| `sidekiq.log`           | Background jobs |
+| `repocheck.log`         | Repository activity |
+| `integrations_json.log` | Activity between GitLab and integrated systems |
+| `kubernetes.log`        | Kubernetes activity |
+
+The contents of these log files can be useful when troubleshooting a problem. Access is available to GitLab admins, without requiring direct access to the log files.
+
+For details of these log files and their contents, see [Log system](../../administration/logs.md).
+
+The content of each log file is listed in chronological order. To minimize performance issues, a maximum 2000 lines of each log file are shown.
+
+### Requests Profiles
+
+The **Requests Profiles** page contains the token required for profiling. For more details, see [Request Profiling](../../administration/monitoring/performance/request_profiling.md).
+
+### Audit Log **(PREMIUM ONLY)**
+
+The **Audit Log** page lists changes made within the GitLab server. With this information you can control, analyze, and track every change.
diff --git a/doc/user/admin_area/labels.md b/doc/user/admin_area/labels.md
index eba27548f86..1d15be89bd5 100644
--- a/doc/user/admin_area/labels.md
+++ b/doc/user/admin_area/labels.md
@@ -2,7 +2,7 @@
 type: reference
 ---
 
-# Labels administration **[CORE ONLY]**
+# Labels administration **(CORE ONLY)**
 
 In the Admin Area, you can manage labels for the GitLab instance. For more details, see [Labels](../project/labels.md).
 
diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md
index 8ddb9c3d707..f5864e1f828 100644
--- a/doc/user/admin_area/license.md
+++ b/doc/user/admin_area/license.md
@@ -2,7 +2,7 @@
 type: howto
 ---
 
-# Activate all GitLab Enterprise Edition functionality with a license **[STARTER ONLY]**
+# Activate all GitLab Enterprise Edition functionality with a license **(STARTER ONLY)**
 
 To activate all GitLab Enterprise Edition (EE) functionality, you need to upload
 a license. Once you've received your license from GitLab Inc., you can upload it
@@ -30,22 +30,22 @@ Otherwise, you can:
 
 1. Navigate manually to the **Admin Area** by clicking the wrench icon in the menu bar.
 
-    ![Admin area icon](img/admin_wrench.png)
+   ![Admin area icon](img/admin_wrench.png)
 
 1. And then going to the **License** tab and click on **Upload New License**.
 
-    ![License admin area](img/license_admin_area.png)
+   ![License admin area](img/license_admin_area.png)
 
 1. If you've received a `.gitlab-license` file, you should have already downloaded
    it in your local machine. You can then upload it directly by choosing the
    license file and clicking the **Upload license** button. In the image below,
    you can see that the selected license file is named `GitLab.gitlab-license`.
 
-    ![Upload license](img/license_upload.png)
+   ![Upload license](img/license_upload.png)
 
-    If you've received your license as plain text, you need to select the
-    "Enter license key" option, copy the license, paste it into the "License key"
-    field and click **Upload license**.
+   If you've received your license as plain text, you need to select the
+   "Enter license key" option, copy the license, paste it into the "License key"
+   field and click **Upload license**.
 
 ## Add your license at install time
 
diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md
index f80d4e9d2aa..35e7b6fb541 100644
--- a/doc/user/admin_area/monitoring/health_check.md
+++ b/doc/user/admin_area/monitoring/health_check.md
@@ -41,42 +41,51 @@ The readiness and liveness probes will provide a report of system health in JSON
 
 ```json
 {
-   "queues_check" : {
-      "status" : "ok"
+   "db_check":{
+      "status":"ok"
    },
-   "redis_check" : {
-      "status" : "ok"
+   "redis_check":{
+      "status":"ok"
    },
-   "shared_state_check" : {
-      "status" : "ok"
+   "cache_check":{
+      "status":"ok"
    },
-   "db_check" : {
-      "status" : "ok"
+   "queues_check":{
+      "status":"ok"
    },
-   "cache_check" : {
-      "status" : "ok"
+   "shared_state_check":{
+      "status":"ok"
+   },
+   "gitaly_check":{
+      "status":"ok",
+      "labels":{
+         "shard":"default"
+         }
+      }
    }
-}
 ```
 
 `liveness` probe example output:
 
 ```json
 {
-   "cache_check" : {
-      "status" : "ok"
+   "db_check":{
+      "status":"ok"
+   },
+   "redis_check":{
+      "status":"ok"
    },
-   "db_check" : {
-      "status" : "ok"
+   "cache_check":{
+      "status":"ok"
    },
-   "redis_check" : {
-      "status" : "ok"
+   "queues_check":{
+      "status":"ok"
    },
-   "queues_check" : {
-      "status" : "ok"
+   "shared_state_check":{
+      "status":"ok"
    },
-   "shared_state_check" : {
-      "status" : "ok"
+   "gitaly_check":{
+      "status":"ok"
    }
 }
 ```
diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md
index 001e4b6bf48..6faab685b26 100644
--- a/doc/user/admin_area/settings/account_and_limit_settings.md
+++ b/doc/user/admin_area/settings/account_and_limit_settings.md
@@ -4,7 +4,18 @@ type: reference
 
 # Account and limit settings
 
-## Repository size limit **[STARTER]**
+## Max attachment size
+
+You can change the maximum file size for attachments in comments and replies in GitLab.
+Navigate to **Admin Area (wrench icon) > Settings > General**, then expand **Account and Limit**.
+From here, you can increase or decrease by changing the value in `Maximum attachment size (MB)`.
+
+NOTE: **Note:**
+If you choose a size larger than what is currently configured for the web server,
+you will likely get errors. See the [troubleshooting section](#troubleshooting) for more
+details.
+
+## Repository size limit **(STARTER)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/740) in [GitLab Enterprise Edition 8.12](https://about.gitlab.com/2016/09/22/gitlab-8-12-released/#limit-project-size-ee).
 > Available in [GitLab Starter](https://about.gitlab.com/pricing/).
@@ -41,22 +52,28 @@ These settings can be found within:
   - The path `/admin/application_settings`.
 
 The first push of a new project, including LFS objects, will be checked for size
-and **will** be rejected if the sum of their sizes exceeds the maximum allowed 
+and **will** be rejected if the sum of their sizes exceeds the maximum allowed
 repository size.
 
+**Note:** The repository size limit includes repository files and LFS, and does not include artifacts.
+
 For details on manually purging files, see [reducing the repository size using Git](../../project/repository/reducing_the_repo_size_using_git.md).
 
 NOTE: **Note:**
-For GitLab.com, the repository size limit is 10 GB.
+GitLab.com repository size [is set by GitLab](../../gitlab_com/index.md#repository-size-limit).
+
+## Troubleshooting
+
+### 413 Request Entity Too Large
 
-<!-- ## Troubleshooting
+If you are attaching a file to a comment or reply in GitLab and receive the `413 Request Entity Too Large`
+error, it is likely caused by having a [max attachment size](#max-attachment-size)
+larger than what the web server is configured to allow.
 
-Include any troubleshooting steps that you can foresee. If you know beforehand what issues
-one might have when setting this up, or when something is changed, or on upgrading, it's
-important to describe those, too. Think of things that may go wrong and include them here.
-This is important to minimize requests for support, and to avoid doc comments with
-questions that you know someone might ask.
+If you wanted to increase the max attachment size to 200m in a GitLab
+[Omnibus](https://docs.gitlab.com/omnibus/) install, for example, you might need to
+add the line below to `/etc/gitlab/gitlab.rb` before increasing the max attachment size:
 
-Each scenario can be a third-level heading, e.g. `### Getting error message X`.
-If you have none to add when creating a doc, leave this section in place
-but commented out to help encourage others to add to it in the future. -->
+```
+nginx['client_max_body_size'] = "200m"
+```
diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md
index d2605cbfb5e..bd76b052422 100644
--- a/doc/user/admin_area/settings/continuous_integration.md
+++ b/doc/user/admin_area/settings/continuous_integration.md
@@ -2,14 +2,14 @@
 type: reference
 ---
 
-# Continuous Integration and Deployment Admin settings **[CORE ONLY]**
+# Continuous Integration and Deployment Admin settings **(CORE ONLY)**
 
 In this area, you will find settings for Auto DevOps, Runners and job artifacts.
 You can find it in the admin area, under **Settings > Continuous Integration and Deployment**.
 
 ![Admin area settings button](../img/admin_area_settings_button.png)
 
-## Auto DevOps **[CORE ONLY]**
+## Auto DevOps **(CORE ONLY)**
 
 To enable (or disable) [Auto DevOps](../../../topics/autodevops/index.md)
 for all projects:
@@ -26,7 +26,7 @@ From now on, every existing project and newly created ones that don't have a
 If you want to disable it for a specific project, you can do so in
 [its settings](../../../topics/autodevops/index.md#enablingdisabling-auto-devops).
 
-## Maximum artifacts size **[CORE ONLY]**
+## Maximum artifacts size **(CORE ONLY)**
 
 The maximum size of the [job artifacts](../../../administration/job_artifacts.md)
 can be set in the Admin area of your GitLab instance. The value is in *MB* and
@@ -38,7 +38,7 @@ To change it:
 1. Change the value of maximum artifacts size (in MB).
 1. Hit **Save changes** for the changes to take effect.
 
-## Default artifacts expiration **[CORE ONLY]**
+## Default artifacts expiration **(CORE ONLY)**
 
 The default expiration time of the [job artifacts](../../../administration/job_artifacts.md)
 can be set in the Admin area of your GitLab instance. The syntax of duration is
@@ -54,7 +54,7 @@ This setting is set per job and can be overridden in
 [`.gitlab-ci.yml`](../../../ci/yaml/README.md#artifactsexpire_in).
 To disable the expiration, set it to `0`. The default unit is in seconds.
 
-## Shared Runners pipeline minutes quota **[STARTER ONLY]**
+## Shared Runners pipeline minutes quota **(STARTER ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1078)
 in GitLab Starter 8.16.
@@ -89,60 +89,12 @@ are enabled.
 
 ![Project admin info](img/admin_project_quota_view.png)
 
-When the pipeline minutes quota for a group is set to a value different than 0,
-the **Pipelines quota** page is available to the group page settings list.
-You can see there an overview of the pipeline minutes quota of all projects of
-the group.
+You can see an overview of the pipeline minutes quota of all projects of
+a group in the **Usage Quotas** page available to the group page settings list.
 
 ![Group pipelines quota](img/group_pipelines_quota.png)
 
-
-## Extra Shared Runners pipeline minutes quota
-
-NOTE: **Note:**
-Only available on GitLab.com.
-
-You can purchase additional CI minutes so your pipelines will not be blocked after you have
-used all your CI minutes from your main quota.
-
-In order to purchase additional minutes, you should follow these steps:
-
-1. Go to **Group > Settings > Pipelines quota**. Once you are on that page, click on **Buy additional minutes**.
-
-    ![Buy additional minutes](img/buy_btn.png)
-
-1. Locate the subscription card that is linked to your group on GitLab.com,
-click on **Buy more CI minutes**, and complete the details about the transaction.
-
-    ![Buy additional minutes](img/buy_minutes_card.png)
-
-1. Once we have processed your payment, the extra CI minutes
-will be synced to your Group and you can visualize it from  the
-**Group > Settings > Pipelines quota** page:
-
-    ![Additional minutes](img/additional_minutes.png)
-
-Be aware that:
-
-1. If you have purchased extra CI minutes before the purchase of a paid plan,
-we will calculate a pro-rated charge for your paid plan. That means you may
-be charged for less than one year since your subscription was previously
-created with the extra CI minutes.
-1. Once the extra CI minutes has been assigned to a Group they cannot be transferred
-to a different Group.
-1. If you have some minutes used over your default quota, these minutes will
-be deducted from your Additional Minutes quota immediately after your purchase of additional
-minutes.
-
-## What happens when my CI minutes quota run out
-
-When the CI minutes quota run out, an email is sent automatically to notifies the owner(s) of the group/namespace which
-includes a link to [purchase more minutes](https://customers.gitlab.com/plans).
-
-If you are not the owner of the group, you will need to contact them to let them know they need to
-[purchase more minutes](https://customers.gitlab.com/plans).
-
-## Archive jobs **[CORE ONLY]**
+## Archive jobs **(CORE ONLY)**
 
 Archiving jobs is useful for reducing the CI/CD footprint on the system by
 removing some of the capabilities of the jobs (metadata needed to run the job),
@@ -169,3 +121,23 @@ questions that you know someone might ask.
 Each scenario can be a third-level heading, e.g. `### Getting error message X`.
 If you have none to add when creating a doc, leave this section in place
 but commented out to help encourage others to add to it in the future. -->
+
+## Required pipeline configuration **(PREMIUM ONLY)**
+
+GitLab administrators can force a pipeline configuration to run on every
+pipeline.
+
+The configuration applies to all pipelines for a GitLab instance and is 
+sourced from:
+
+- The [instance template repository](instance_template_repository.md).
+- GitLab-supplied configuration.
+
+To set required pipeline configuration:
+
+1. Go to **Admin area > Settings > CI/CD**.
+1. Expand the **Required pipeline configuration** section.
+1. Select the required configuration from the provided dropdown.
+1. Click **Save changes**.
+
+![Required pipeline](img/admin_required_pipeline.png)
diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md
index 9555a695b13..490163c1816 100644
--- a/doc/user/admin_area/settings/email.md
+++ b/doc/user/admin_area/settings/email.md
@@ -10,18 +10,17 @@ You can customize some of the content in emails sent from your GitLab instance.
 
 The logo in the header of some emails can be customized, see the [logo customization section](../../../customization/branded_page_and_email_header.md).
 
-## Custom additional text **[PREMIUM ONLY]**
+## Custom additional text **(PREMIUM ONLY)**
 
 > [Introduced][ee-5031] in [GitLab Premium][eep] 10.7.
 
 The additional text will appear at the bottom of any email and can be used for
 legal/auditing/compliance reasons.
 
-1. Go to **Admin area > Settings** (`/admin/application_settings`).
-1. Under the **Email** section, change the **Additional text** field.
-1. Hit **Save** for the changes to take effect.
-
-![Admin email settings](img/email_settings.png)
+1. Go to **Admin Area > Settings > Preferences** (`/admin/application_settings/preferences`).
+1. Expand the **Email** section.
+1. Enter your text in the **Additional text** field.
+1. Click **Save**.
 
 [ee-5031]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5031
 [eep]: https://about.gitlab.com/pricing/
@@ -35,11 +34,13 @@ This configuration option sets the email hostname for [private commit emails](..
 
 In order to change this option:
 
-1. Go to **Admin area > Settings** (`/admin/application_settings`).
-1. Under the **Email** section, change the **Custom hostname (for private commit emails)** field.
-1. Hit **Save** for the changes to take effect.
+1. Go to **Admin Area > Settings > Preferences** (`/admin/application_settings/preferences`).
+1. Expand the **Email** section.
+1. Enter the desire hostname in the **Custom hostname (for private commit emails)** field.
+1. Click **Save changes**.
 
-NOTE: **Note**: Once the hostname gets configured, every private commit email using the previous hostname, will not get
+NOTE: **Note:**
+Once the hostname gets configured, every private commit email using the previous hostname, will not get
 recognized by GitLab. This can directly conflict with certain [Push rules](../../../push_rules/push_rules.md) such as
 `Check whether author is a GitLab user` and `Check whether committer is the current authenticated user`.
 
@@ -53,4 +54,4 @@ questions that you know someone might ask.
 
 Each scenario can be a third-level heading, e.g. `### Getting error message X`.
 If you have none to add when creating a doc, leave this section in place
-but commented out to help encourage others to add to it in the future. -->
\ No newline at end of file
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md
index 11c0867da17..4fde7477490 100644
--- a/doc/user/admin_area/settings/external_authorization.md
+++ b/doc/user/admin_area/settings/external_authorization.md
@@ -2,10 +2,10 @@
 type: reference
 ---
 
-# External authorization control **[CORE ONLY]**
+# External authorization control **(CORE ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4216) in
-> [GitLab Premium](https://about.gitlab.com/pricing) 10.6.
+> [GitLab Premium](https://about.gitlab.com/pricing/) 10.6.
 > [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27056) to
 > [GitLab Core](https://about.gitlab.com/pricing/) in 11.10.
 
@@ -76,13 +76,19 @@ service with this body:
 {
   "user_identifier": "jane@acme.org",
   "project_classification_label": "project-label",
-  "user_ldap_dn": "CN=Jane Doe,CN=admin,DC=acme"
+  "user_ldap_dn": "CN=Jane Doe,CN=admin,DC=acme",
+  "identities": [
+    { "provider": "ldap", "extern_uid": "CN=Jane Doe,CN=admin,DC=acme" },
+    { "provider": "bitbucket", "extern_uid": "2435223452345" }
+  ]
 }
 ```
 
 The `user_ldap_dn` is optional and is only sent when the user is logged in
 through LDAP.
 
+`identities` will contain the details of all the identities associated with the user. This will be an empty array if there are no identities associated with the user.
+
 When the external authorization service responds with a status code 200, the
 user is granted access. When the external service responds with a status code
 401 or 403, the user is denied access. In any case, the request is cached for 6 hours.
diff --git a/doc/user/admin_area/settings/img/additional_minutes.png b/doc/user/admin_area/settings/img/additional_minutes.png
deleted file mode 100644
index d148ed79b92..00000000000
--- a/doc/user/admin_area/settings/img/additional_minutes.png
+++ /dev/null
diff --git a/doc/user/admin_area/settings/img/admin_required_pipeline.png b/doc/user/admin_area/settings/img/admin_required_pipeline.png
new file mode 100644
index 00000000000..501b1e3ba0a
--- /dev/null
+++ b/doc/user/admin_area/settings/img/admin_required_pipeline.png
diff --git a/doc/user/admin_area/settings/img/buy_btn.png b/doc/user/admin_area/settings/img/buy_btn.png
deleted file mode 100644
index 0cc88b8a48f..00000000000
--- a/doc/user/admin_area/settings/img/buy_btn.png
+++ /dev/null
diff --git a/doc/user/admin_area/settings/img/buy_minutes_card.png b/doc/user/admin_area/settings/img/buy_minutes_card.png
deleted file mode 100644
index cf4ad34ead7..00000000000
--- a/doc/user/admin_area/settings/img/buy_minutes_card.png
+++ /dev/null
diff --git a/doc/user/admin_area/settings/img/email_confirmation.png b/doc/user/admin_area/settings/img/email_confirmation.png
new file mode 100644
index 00000000000..987aa10c3ce
--- /dev/null
+++ b/doc/user/admin_area/settings/img/email_confirmation.png
diff --git a/doc/user/admin_area/settings/img/email_settings.png b/doc/user/admin_area/settings/img/email_settings.png
deleted file mode 100644
index ed0a80d10ce..00000000000
--- a/doc/user/admin_area/settings/img/email_settings.png
+++ /dev/null
diff --git a/doc/user/admin_area/settings/img/group_pipelines_quota.png b/doc/user/admin_area/settings/img/group_pipelines_quota.png
index d94b609ad6f..318527426bd 100644
--- a/doc/user/admin_area/settings/img/group_pipelines_quota.png
+++ b/doc/user/admin_area/settings/img/group_pipelines_quota.png
diff --git a/doc/user/admin_area/settings/img/rate_limits_on_raw_endpoints.png b/doc/user/admin_area/settings/img/rate_limits_on_raw_endpoints.png
new file mode 100644
index 00000000000..c32eb93c8a8
--- /dev/null
+++ b/doc/user/admin_area/settings/img/rate_limits_on_raw_endpoints.png
diff --git a/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png b/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png
new file mode 100644
index 00000000000..53dc0e4ac87
--- /dev/null
+++ b/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png
diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md
index eed087ae52b..2a12614e325 100644
--- a/doc/user/admin_area/settings/index.md
+++ b/doc/user/admin_area/settings/index.md
@@ -2,7 +2,7 @@
 type: index
 ---
 
-# Admin Area settings **[CORE ONLY]**
+# Admin Area settings **(CORE ONLY)**
 
 In the Admin Area **Settings** page, you can find various options for your GitLab
 instance like sign-up restrictions, account limits and quota, metrics, etc.
@@ -10,7 +10,7 @@ instance like sign-up restrictions, account limits and quota, metrics, etc.
 Navigate to it by going to **Admin Area > Settings**. Some of the settings
 include:
 
-- [Account and limit settings](account_and_limit_settings.md) **[STARTER]**
+- [Account and limit settings](account_and_limit_settings.md) **(STARTER)**
 - [Continuous Integration and Deployment](continuous_integration.md)
 - [Email](email.md)
 - [Sign up restrictions](sign_up_restrictions.md)
@@ -18,7 +18,8 @@ include:
 - [Third party offers](third_party_offers.md)
 - [Usage statistics](usage_statistics.md)
 - [Visibility and access controls](visibility_and_access_controls.md)
-- [Custom templates repository](instance_template_repository.md) **[PREMIUM]**
+- [User and IP rate limits](user_and_ip_rate_limits.md)
+- [Custom templates repository](instance_template_repository.md) **(PREMIUM)**
 
 NOTE: **Note:**
 You can change the [first day of the week](../../profile/preferences.md) for the entire GitLab instance
diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md
index 91286a67c31..f2ba131d17b 100644
--- a/doc/user/admin_area/settings/instance_template_repository.md
+++ b/doc/user/admin_area/settings/instance_template_repository.md
@@ -2,10 +2,10 @@
 type: reference
 ---
 
-# Instance template repository **[PREMIUM ONLY]**
+# Instance template repository **(PREMIUM ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5986) in
-> [GitLab Premium](https://about.gitlab.com/pricing) 11.3.
+> [GitLab Premium](https://about.gitlab.com/pricing/) 11.3.
 
 ## Overview
 
diff --git a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md
new file mode 100644
index 00000000000..8e53a6995fb
--- /dev/null
+++ b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md
@@ -0,0 +1,22 @@
+---
+type: reference
+---
+
+# Rate limits on raw endpoints **(CORE ONLY)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30829) in GitLab 12.2.
+
+This setting allows you to rate limit the requests to raw endpoints, defaults to `300` requests per minute. 
+It can be modified in **Admin Area > Network > Performance Optimization**.
+
+For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/controllers/application_controller.rb` will be blocked. Access to the raw file will be released after 1 minute.
+
+![Rate limits on raw endpoints](img/rate_limits_on_raw_endpoints.png)
+
+This limit is:
+
+- Applied independently per project, per commit and per file path.
+- Not applied per IP address.
+- Active by default. To disable, set the option to `0`.
+
+Requests over the rate limit are logged into `auth.log`.
diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md
index cebf36c7ec1..1b1bcbcd6e8 100644
--- a/doc/user/admin_area/settings/sign_up_restrictions.md
+++ b/doc/user/admin_area/settings/sign_up_restrictions.md
@@ -4,19 +4,26 @@ type: reference
 
 # Sign-up restrictions
 
-You can block email addresses of specific domains, or whitelist only some
-specific domains via the **Application Settings** in the Admin area.
+You can use sign-up restrictions to require user email confirmation, as well as
+to blacklist or whitelist email addresses belonging to specific domains.
 
 >**Note**: These restrictions are only applied during sign-up. An admin is
 able to add a user through the admin panel with a disallowed domain. Also
 note that the users can change their email addresses after signup to
 disallowed domains.
 
+## Require email confirmation
+
+You can send confirmation emails during sign-up and require that users confirm
+their email address before they are allowed to sign in.
+
+![Email confirmation](img/email_confirmation.png)
+
 ## Whitelist email domains
 
 > [Introduced][ce-598] in GitLab 7.11.0
 
-You can restrict users to only signup using email addresses matching the given
+You can restrict users to only sign up using email addresses matching the given
 domains list.
 
 ## Blacklist email domains
@@ -24,17 +31,23 @@ domains list.
 > [Introduced][ce-5259] in GitLab 8.10.
 
 With this feature enabled, you can block email addresses of a specific domain
-from creating an account on your GitLab server. This is particularly useful to
-prevent spam. Disposable email addresses are usually used by malicious users to
-create dummy accounts and spam issues.
+from creating an account on your GitLab server. This is particularly useful
+to prevent malicious users from creating spam accounts with disposable email
+addresses.
 
 ## Settings
 
-This feature can be activated via the **Application Settings** in the Admin area,
-and you have the option of entering the list manually, or uploading a file with
-the list.
+To access this feature:
+
+1. Navigate to the **Settings > General** in the Admin area.
+1. Expand the **Sign-up restrictions** section.
+
+For the blacklist, you can enter the list manually or upload a `.txt` file that
+contains list entries.
+
+For the whitelist, you must enter the list manually.
 
-Both whitelist and blacklist accept wildcards, so for example, you can use
+Both the whitelist and blacklist accept wildcards. For example, you can use
 `*.company.com` to accept every `company.com` subdomain, or `*.io` to block all
 domains ending in `.io`. Domains should be separated by a whitespace,
 semicolon, comma, or a new line.
diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md
index a5f8d05f662..a1bce5a6c69 100644
--- a/doc/user/admin_area/settings/terms.md
+++ b/doc/user/admin_area/settings/terms.md
@@ -17,7 +17,7 @@ To enforce acceptance of a Terms of Service and Privacy Policy:
 1. Go to **Admin Area > Settings > General**.
 1. Expand the **Terms of Service and Privacy Policy** section.
 1. Check the **Require all users to accept Terms of Service and Privacy Policy when they access
-GitLab.** checkbox.
+   GitLab.** checkbox.
 1. Input the text of the **Terms of Service and Privacy Policy**. Markdown formatting can be used in this input box.
 1. Click **Save changes**.
 1. When you are presented with the **Terms of Service** statement, click **Accept terms**.
diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md
index 652d6ad2cdd..516600c9d99 100644
--- a/doc/user/admin_area/settings/usage_statistics.md
+++ b/doc/user/admin_area/settings/usage_statistics.md
@@ -10,7 +10,7 @@ to perform various actions.
 All statistics are opt-out, you can enable/disable them from the admin panel
 under **Admin area > Settings > Metrics and profiling > Usage statistics**.
 
-## Version check **[CORE ONLY]**
+## Version check **(CORE ONLY)**
 
 If enabled, version check will inform you if a new version is available and the
 importance of it through a status. This is shown on the help page (i.e. `/help`)
@@ -33,7 +33,7 @@ secure.
 If you disable version check, this information will not be collected.  Enable or
 disable the version check at **Admin area > Settings > Usage statistics**.
 
-## Usage ping **[CORE ONLY]**
+## Usage ping **(CORE ONLY)**
 
 > [Introduced][ee-557] in GitLab Enterprise Edition 8.10. More statistics
 [were added][ee-735] in GitLab Enterprise Edition
@@ -52,8 +52,8 @@ You can view the exact JSON payload in the administration panel. To view the pay
 1. Expand **Settings** in the left sidebar and click on **Metrics and profiling**.
 1. Expand **Usage statistics** and click on the **Preview payload** button.
 
-You can see how [the usage ping data maps to different stages of the product](https://gitlab.com/gitlab-data/analytics/blob/master/transform/snowflake-dbt/data/ping_metrics_to_stage_mapping_data.csv). 
- 
+You can see how [the usage ping data maps to different stages of the product](https://gitlab.com/gitlab-data/analytics/blob/master/transform/snowflake-dbt/data/ping_metrics_to_stage_mapping_data.csv).
+
 ### Deactivate the usage ping
 
 The usage ping is opt-out. If you want to deactivate this feature, go to
@@ -78,7 +78,7 @@ production: &base
     usage_ping_enabled: false
 ```
 
-## Instance statistics visibility **[CORE ONLY]**
+## Instance statistics visibility **(CORE ONLY)**
 
 Once usage ping is enabled, GitLab will gather data from other instances and
 will be able to show [usage statistics](../../instance_statistics/index.md)
diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md
new file mode 100644
index 00000000000..e3a495750f2
--- /dev/null
+++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md
@@ -0,0 +1,32 @@
+---
+type: reference
+---
+
+# User and IP rate limits
+
+Rate limiting is a common technique used to improve the security and durability
+of a web application. For more details, see
+[Rate limits](../../../security/rate_limits.md).
+
+The following limits can be enforced in **Admin Area > Network > User and
+IP rate limits**:
+
+- Unauthenticated requests
+- Authenticated API requests
+- Authenticated web requests
+
+These limits are disabled by default.
+
+![user-and-ip-rate-limits](img/user_and_ip_rate_limits.png)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md
index a1229484388..bf59f49b993 100644
--- a/doc/user/admin_area/settings/visibility_and_access_controls.md
+++ b/doc/user/admin_area/settings/visibility_and_access_controls.md
@@ -4,12 +4,15 @@ type: reference
 
 # Visibility and access controls
 
-GitLab allows admins to:
+GitLab allows administrators to:
 
 - Control access and visibility to GitLab resources including branches and projects.
 - Select from which hosting sites code can be imported into GitLab.
 - Select the protocols permitted to access GitLab.
 - Enable or disable repository mirroring.
+- Prevent non-administrators from deleting projects
+  ([introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5615) in GitLab 12.0).
+  **(PREMIUM ONLY)**
 
 To access the visibility and access control options:
 
diff --git a/doc/user/analytics/cycle_analytics.md b/doc/user/analytics/cycle_analytics.md
new file mode 100644
index 00000000000..b7389c8689d
--- /dev/null
+++ b/doc/user/analytics/cycle_analytics.md
@@ -0,0 +1,182 @@
+# Cycle Analytics
+
+> - Introduced prior to GitLab 12.2 at the project level.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12077) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2 at the group level (enabled by feature flag `analytics`).
+
+Cycle Analytics measures the time spent to go from an [idea to production] - also known
+as cycle time - for each of your projects. Cycle Analytics displays the median time for an idea to
+reach production, along with the time typically spent in each DevOps stage along the way.
+
+Cycle Analytics is useful in order to quickly determine the velocity of a given
+project. It points to bottlenecks in the development process, enabling management
+to uncover, triage, and identify the root cause of slowdowns in the software development life cycle.
+
+Cycle Analytics is tightly coupled with the [GitLab flow] and
+calculates a separate median for each stage.
+
+## Overview
+
+Cycle Analytics is available:
+
+- From GitLab 12.2, at the group level in the analytics workspace at
+  **Analytics > Cycle Analytics**. **(PREMIUM)**
+
+  In the future, multiple groups will be selectable which will effectively make this an
+  instance-level feature.
+
+  NOTE: **Note:**
+  Requires the [analytics workspace](index.md) to be enabled.
+
+- At the project level via **Project > Cycle Analytics**.
+
+There are seven stages that are tracked as part of the Cycle Analytics calculations.
+
+- **Issue** (Tracker)
+  - Time to schedule an issue (by milestone or by adding it to an issue board)
+- **Plan** (Board)
+  - Time to first commit
+- **Code** (IDE)
+  - Time to create a merge request
+- **Test** (CI)
+  - Time it takes GitLab CI/CD to test your code
+- **Review** (Merge Request/MR)
+  - Time spent on code review
+- **Staging** (Continuous Deployment)
+  - Time between merging and deploying to production
+- **Production** (Total)
+  - Total lifecycle time; i.e. the velocity of the project or team
+
+## How the data is measured
+
+Cycle Analytics records cycle time and data based on the project issues with the
+exception of the staging and production stages, where only data deployed to
+production are measured.
+
+Specifically, if your CI is not set up and you have not defined a `production`
+or `production/*` [environment], then you will not have any data for those stages.
+
+Each stage of Cycle Analytics is further described in the table below.
+
+| **Stage** | **Description** |
+| --------- | --------------- |
+| Issue     | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label will be tracked only if it already has an [Issue Board list](../project/issue_board.md#creating-a-new-list) created for it. |
+| Plan      | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (e.g., `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. |
+| Code      | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the issue closing pattern is not present in the merge request description, the MR is not considered to the measurement time of the stage. |
+| Test      | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. |
+| Review    | Measures the median time taken to review the merge request that has closing issue pattern, between its creation and until it's merged. |
+| Staging   | Measures the median time between merging the merge request with closing issue pattern until the very first deployment to production. It's tracked by the [environment] set to `production` or matching `production/*` (case-sensitive, `Production` won't work) in your GitLab CI configuration. If there isn't a production environment, this is not tracked. |
+| Production| The sum of all time (medians) taken to run the entire process, from issue creation to deploying the code to production. |
+
+---
+
+How this works, behind the scenes:
+
+1. Issues and merge requests are grouped together in pairs, such that for each
+   `<issue, merge request>` pair, the merge request has the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically)
+   for the corresponding issue. All other issues and merge requests are **not**
+   considered.
+1. Then the `<issue, merge request>` pairs are filtered out by last XX days (specified
+   by the UI - default is 90 days). So it prohibits these pairs from being considered.
+1. For the remaining `<issue, merge request>` pairs, we check the information that
+   we need for the stages, like issue creation date, merge request merge time,
+   etc.
+
+To sum up, anything that doesn't follow [GitLab flow] will not be tracked and the
+Cycle Analytics dashboard will not present any data for:
+
+- merge requests that do not close an issue.
+- issues not labeled with a label present in the Issue Board or for issues not assigned a milestone.
+- staging and production stages, if the project has no `production` or `production/*`
+  environment.
+
+## Example workflow
+
+Below is a simple fictional workflow of a single cycle that happens in a
+single day passing through all seven stages. Note that if a stage does not have
+a start and a stop mark, it is not measured and hence not calculated in the median
+time. It is assumed that milestones are created and CI for testing and setting
+environments is configured.
+
+1. Issue is created at 09:00 (start of **Issue** stage).
+1. Issue is added to a milestone at 11:00 (stop of **Issue** stage / start of
+   **Plan** stage).
+1. Start working on the issue, create a branch locally and make one commit at
+   12:00.
+1. Make a second commit to the branch which mentions the issue number at 12.30
+   (stop of **Plan** stage / start of **Code** stage).
+1. Push branch and create a merge request that contains the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically)
+   in its description at 14:00 (stop of **Code** stage / start of **Test** and
+   **Review** stages).
+1. The CI starts running your scripts defined in [`.gitlab-ci.yml`][yml] and
+   takes 5min (stop of **Test** stage).
+1. Review merge request, ensure that everything is OK and merge the merge
+   request at 19:00. (stop of **Review** stage / start of **Staging** stage).
+1. Now that the merge request is merged, a deployment to the `production`
+   environment starts and finishes at 19:30 (stop of **Staging** stage).
+1. The cycle completes and the sum of the median times of the previous stages
+   is recorded to the **Production** stage. That is the time between creating an
+   issue and deploying its relevant merge request to production.
+
+From the above example you can conclude the time it took each stage to complete
+as long as their total time:
+
+- **Issue**:  2h (11:00 - 09:00)
+- **Plan**:   1h (12:00 - 11:00)
+- **Code**:   2h (14:00 - 12:00)
+- **Test**:   5min
+- **Review**: 5h (19:00 - 14:00)
+- **Staging**:  30min (19:30 - 19:00)
+- **Production**: Since this stage measures the sum of median time off all
+  previous stages, we cannot calculate it if we don't know the status of the
+  stages before. In case this is the very first cycle that is run in the project,
+  then the **Production** time is 10h 30min (19:30 - 09:00)
+
+A few notes:
+
+- In the above example we demonstrated that it doesn't matter if your first
+  commit doesn't mention the issue number, you can do this later in any commit
+  of the branch you are working on.
+- You can see that the **Test** stage is not calculated to the overall time of
+  the cycle since it is included in the **Review** process (every MR should be
+  tested).
+- The example above was just **one cycle** of the seven stages. Add multiple
+  cycles, calculate their median time and the result is what the dashboard of
+  Cycle Analytics is showing.
+
+## Permissions
+
+The current permissions on the Project Cycle Analytics dashboard are:
+
+- Public projects - anyone can access
+- Internal projects - any authenticated user can access
+- Private projects - any member Guest and above can access
+
+You can [read more about permissions][permissions] in general.
+
+NOTE: **Note:**
+As of GitLab 12.2, the project-level page is deprecated. You should access
+project-level Cycle Analytics from **Analytics > Cycle Analytics** in the top
+navigation bar. We will ensure that the same project-level functionality is available
+to CE users in the new analytics space.
+
+For Cycle Analytics functionality introduced in GitLab 12.2 and later:
+
+- Users must have Reporter access or above.
+- Features are available only on
+  [Premium or Silver tiers](https://about.gitlab.com/pricing/) and above.
+
+## More resources
+
+Learn more about Cycle Analytics in the following resources:
+
+- [Cycle Analytics feature page](https://about.gitlab.com/features/cycle-analytics/)
+- [Cycle Analytics feature preview](https://about.gitlab.com/2016/09/16/feature-preview-introducing-cycle-analytics/)
+- [Cycle Analytics feature highlight](https://about.gitlab.com/2016/09/21/cycle-analytics-feature-highlight/)
+
+[ce-5986]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5986
+[ce-20975]: https://gitlab.com/gitlab-org/gitlab-ce/issues/20975
+[environment]: ../../ci/yaml/README.md#environment
+[GitLab flow]: ../../workflow/gitlab_flow.md
+[idea to production]: https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab
+[permissions]: ../permissions.md
+[yml]: ../../ci/yaml/README.md
diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md
new file mode 100644
index 00000000000..ec719c0b4a1
--- /dev/null
+++ b/doc/user/analytics/index.md
@@ -0,0 +1,22 @@
+# Analytics workspace
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12077) in GitLab 12.2 (enabled using `analytics` feature flag).
+
+The Analytics workspace will make it possible to aggregate analytics across
+GitLab, so that users can view information across multiple projects and groups
+in one place.
+
+To access the centralized analytics workspace:
+
+1. Ensure it's enabled. Requires a GitLab administrator to enable it with the `analytics` feature
+   flag.
+1. Once enabled, click on **Analytics** from the top navigation bar.
+
+## Available analytics
+
+From the centralized analytics workspace, the following analytics are available:
+
+- [Cycle Analytics](cycle_analytics.md).
+
+NOTE: **Note:**
+Project-level Cycle Analytics are still available at a project's **Project > Cycle Analytics**.
diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md
index a24374dff1d..86491c7d74e 100644
--- a/doc/user/application_security/container_scanning/index.md
+++ b/doc/user/application_security/container_scanning/index.md
@@ -1,4 +1,8 @@
-# Container Scanning **[ULTIMATE]**
+---
+type: reference, howto
+---
+
+# Container Scanning **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3672)
 in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4.
@@ -10,7 +14,7 @@ images (or more precisely the containers) for known vulnerabilities by using
 [Clair](https://github.com/coreos/clair) and [clair-scanner](https://github.com/arminc/clair-scanner),
 two open source tools for Vulnerability Static Analysis for containers.
 
-You can take advantage of Container Scanning by either [including the CI job](#including-the-provided-template) in
+You can take advantage of Container Scanning by either [including the CI job](#configuration) in
 your existing `.gitlab-ci.yml` file or by implicitly using
 [Auto Container Scanning](../../../topics/autodevops/index.md#auto-container-scanning-ultimate)
 that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
@@ -40,11 +44,14 @@ To enable Container Scanning in your pipeline, you need:
   [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html#running-privileged-containers-for-the-runners)
   executor running in privileged mode. If you're using the shared Runners on GitLab.com,
   this is enabled by default.
+- Docker `18.09.03` or higher installed on the machine where the Runners are
+  running. If you're using the shared Runners on GitLab.com, this is already
+  the case.
 - To [build and push](../../../ci/docker/using_docker_build.md#container-registry-examples)
   your Docker image to your project's [Container Registry](../../project/container_registry.md).
   The name of the Docker image should match the following scheme:
 
-  ```
+  ```text
   $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA
   ```
 
@@ -52,32 +59,16 @@ To enable Container Scanning in your pipeline, you need:
   [predefined environment variables](../../../ci/variables/predefined_variables.md)
   document.
 
-## Configuring Container Scanning
-
-To enable Container Scanning in your project, define a job in your
-`.gitlab-ci.yml` file that generates the
-[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate).
-
-This can be done in two ways:
-
-- For GitLab 11.9 and later, including the provided
-  `Container-Scanning.gitlab-ci.yml` template (recommended).
-- Manually specifying the job definition. Not recommended unless using GitLab
-  11.8 and earlier.
-
-### Including the provided template
-
-NOTE: **Note:**
-The CI/CD Container Scanning template is supported on GitLab 11.9 and later versions.
-For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later).
+## Configuration
 
-A CI/CD [Container Scanning template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml)
-with the default Container Scanning job definition is provided as a part of your GitLab
-installation that you can [include](../../../ci/yaml/README.md#includetemplate)
-in your `.gitlab-ci.yml` file.
+For GitLab 11.9 and later, to enable Container Scanning, you must
+[include](../../../ci/yaml/README.md#includetemplate) the
+[`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml)
+that's provided as a part of your GitLab installation.
+For GitLab versions earlier than 11.9, you can copy and use the job as defined
+in that template.
 
-To enable Container Scanning using the provided template, add the following to
-your `.gitlab-ci.yml` file:
+Add the following to your `.gitlab-ci.yml` file:
 
 ```yaml
 include:
@@ -86,12 +77,12 @@ include:
 
 The included template will:
 
-- Create a `container_scanning` job in your CI/CD pipeline.
-- Pull the already built Docker image from your project's
-  [Container Registry](../../project/container_registry.md) (see [requirements](#requirements))
-  and scan it for possible vulnerabilities.
+1. Create a `container_scanning` job in your CI/CD pipeline.
+1. Pull the already built Docker image from your project's
+   [Container Registry](../../project/container_registry.md) (see [requirements](#requirements))
+   and scan it for possible vulnerabilities.
 
-The report will be saved as a
+The results will be saved as a
 [Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate)
 that you can later download and analyze.
 Due to implementation limitations, we always take the latest Container Scanning
@@ -103,95 +94,6 @@ If you want to whitelist some specific vulnerabilities, you can do so by definin
 them in a YAML file named `clair-whitelist.yml`. Read more in the
 [Clair documentation](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file).
 
-### Manual job definition for GitLab 11.5 and later
-
-CAUTION: **Caution:**
-The job definition shown below is supported on GitLab 11.5 and later versions.
-However, if you're using GitLab 11.9+, it's recommended to use
-[the provided Container Scanning template](#including-the-provided-template).
-
-For GitLab 11.5 and GitLab Runner 11.5 and later, the following `container_scanning`
-job can be added:
-
-```yaml
-container_scanning:
-  image: docker:stable
-  variables:
-    DOCKER_DRIVER: overlay2
-    ## Define two new variables based on GitLab's CI/CD predefined variables
-    ## https://docs.gitlab.com/ee/ci/variables/README.html#predefined-environment-variables
-    CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG
-    CI_APPLICATION_TAG: $CI_COMMIT_SHA
-    CLAIR_LOCAL_SCAN_VERSION: v2.0.8_fe9b059d930314b54c78f75afe265955faf4fdc1
-  allow_failure: true
-  services:
-    - docker:stable-dind
-  script:
-    - docker run -d --name db arminc/clair-db:latest
-    - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:${CLAIR_LOCAL_SCAN_VERSION}
-    - apk add -U wget ca-certificates
-    - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG}
-    - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64
-    - mv clair-scanner_linux_amd64 clair-scanner
-    - chmod +x clair-scanner
-    - touch clair-whitelist.yml
-    - while( ! wget -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; done
-    - retries=0
-    - echo "Waiting for clair daemon to start"
-    - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done
-    - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true
-  artifacts:
-    reports:
-      container_scanning: gl-container-scanning-report.json
-```
-
-### Manual job definition for GitLab 11.4 and earlier (deprecated)
-
-CAUTION: **Deprecated:**
-Before GitLab 11.5, the Container Scanning job and artifact had to be named specifically
-to automatically extract report data and show it in the merge request widget.
-While these old job definitions are still maintained, they have been deprecated
-and may be removed in the next major release, GitLab 12.0. You are strongly
-advised to update your current `.gitlab-ci.yml` configuration to reflect that change.
-
-For GitLab 11.4 and earlier, the Container Scanning job should look like:
-
-```yaml
-container_scanning:
-  image: docker:stable
-  variables:
-    DOCKER_DRIVER: overlay2
-    ## Define two new variables based on GitLab's CI/CD predefined variables
-    ## https://docs.gitlab.com/ee/ci/variables/README.html#predefined-environment-variables
-    CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG
-    CI_APPLICATION_TAG: $CI_COMMIT_SHA
-    CLAIR_LOCAL_SCAN_VERSION: v2.0.8_fe9b059d930314b54c78f75afe265955faf4fdc1
-  allow_failure: true
-  services:
-    - docker:stable-dind
-  script:
-    - docker run -d --name db arminc/clair-db:latest
-    - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:${CLAIR_LOCAL_SCAN_VERSION}
-    - apk add -U wget ca-certificates
-    - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG}
-    - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64
-    - mv clair-scanner_linux_amd64 clair-scanner
-    - chmod +x clair-scanner
-    - touch clair-whitelist.yml
-    - while( ! wget -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; done
-    - retries=0
-    - echo "Waiting for clair daemon to start"
-    - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done
-    - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true
-  artifacts:
-    paths: [gl-container-scanning-report.json]
-```
-
-Alternatively, the job name could be `sast:container`
-and the artifact name could be `gl-sast-container-report.json`.
-These names have been deprecated with GitLab 11.0
-and may be removed in the next major release, GitLab 12.0.
-
 ## Security Dashboard
 
 The Security Dashboard is a good place to get an overview of all the security
@@ -202,3 +104,25 @@ vulnerabilities in your groups and projects. Read more about the
 
 Once a vulnerability is found, you can interact with it. Read more on how to
 [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities).
+
+## Vulnerabilities database update
+
+For more information about the vulnerabilities database update, check the
+[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database).
+
+## Troubleshooting
+
+### docker: Error response from daemon: failed to copy xattrs
+
+When the GitLab Runner uses the Docker executor and NFS is used
+(e.g., `/var/lib/docker` is on an NFS mount), Container Scanning might fail with
+an error like the following:
+
+```text
+docker: Error response from daemon: failed to copy xattrs: failed to set xattr "security.selinux" on /path/to/file: operation not supported.
+```
+
+This is a result of a bug in Docker which is now [fixed](https://github.com/containerd/continuity/pull/138 "fs: add WithAllowXAttrErrors CopyOpt").
+To prevent the error, ensure the Docker version that the Runner is using is
+`18.09.03` or higher. For more information, see
+[issue #10241](https://gitlab.com/gitlab-org/gitlab-ee/issues/10241 "Investigate why Container Scanning is not working with NFS mounts").
diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md
index a722aa88f9d..fa84f995e58 100644
--- a/doc/user/application_security/dast/index.md
+++ b/doc/user/application_security/dast/index.md
@@ -1,8 +1,17 @@
-# Dynamic Application Security Testing (DAST) **[ULTIMATE]**
+---
+type: reference, howto
+---
+
+# Dynamic Application Security Testing (DAST) **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4348)
 in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4.
 
+NOTE: **4 of the top 6 attacks were application based.**
+Download our whitepaper,
+["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/)
+to learn how to protect your organization.
+
 Running [static checks](../sast/index.md) on your code is the first step to detect
 vulnerabilities that can put the security of your code at risk. Yet, once
 deployed, your application is exposed to a new category of possible attacks,
@@ -14,7 +23,7 @@ Dynamic Application Security Testing (DAST) comes into place.
 If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web application(s)
 for known vulnerabilities using Dynamic Application Security Testing (DAST).
 
-You can take advantage of DAST by either [including the CI job](#configuring-dast) in
+You can take advantage of DAST by either [including the CI job](#configuration) in
 your existing `.gitlab-ci.yml` file or by implicitly using
 [Auto DAST](../../../topics/autodevops/index.md#auto-dast-ultimate)
 that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
@@ -51,30 +60,16 @@ applications while you are developing and testing your applications.
 To run a DAST job, you need GitLab Runner with the
 [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html).
 
-## Configuring DAST
-
-To enable DAST in your project, define a job in your `.gitlab-ci.yml` file that generates the
-[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate).
-
-This can be done in two ways:
-
-- For GitLab 11.9 and later, including the provided `DAST.gitlab-ci.yml` template (recommended).
-- Manually specifying the job definition. Not recommended unless using GitLab
-  11.8 and earlier.
-
-### Including the provided template
+## Configuration
 
-NOTE: **Note:**
-The CI/CD DAST template is supported on GitLab 11.9 and later versions.
-For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later).
+For GitLab 11.9 and later, to enable DAST, you must
+[include](../../../ci/yaml/README.md#includetemplate) the
+[`DAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml)
+that's provided as a part of your GitLab installation.
+For GitLab versions earlier than 11.9, you can copy and use the job as defined
+in that template.
 
-A CI/CD [DAST template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml)
-with the default DAST job definition is provided as a part of your GitLab
-installation which you can [include](../../../ci/yaml/README.md#includetemplate)
-in your `.gitlab-ci.yml` file.
-
-To enable DAST using the provided template, add the following to your `.gitlab-ci.yml`
-file:
+Add the following to your `.gitlab-ci.yml` file:
 
 ```yaml
 include:
@@ -84,22 +79,22 @@ variables:
   DAST_WEBSITE: https://example.com
 ```
 
+There are two ways to define the URL to be scanned by DAST:
+
+- Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables).
+- Add it in an `environment_url.txt` file at the root of your project.
+
 The included template will create a `dast` job in your CI/CD pipeline and scan
 your project's source code for possible vulnerabilities.
 
-The report will be saved as a
+The results will be saved as a
 [DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate)
 that you can later download and analyze. Due to implementation limitations we
 always take the latest DAST artifact available. Behind the scenes, the
 [GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast)
 is used to run the tests on the specified URL and scan it for possible vulnerabilities.
 
-There are two ways to define the URL to be scanned by DAST:
-
-- Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables).
-- Add it in an `environment_url.txt` file at the root of your project.
-
-#### Authenticated scan
+### Authenticated scan
 
 It's also possible to authenticate the user before performing the DAST checks:
 
@@ -117,12 +112,12 @@ variables:
   DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between
 ```
 
-The report will be saved as a
+The results will be saved as a
 [DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate)
 that you can later download and analyze.
 Due to implementation limitations, we always take the latest DAST artifact available.
 
-#### Full scan
+### Full scan
 
 DAST can be configured to perform [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan), which
 includes both passive and active scanning against the same target website:
@@ -135,7 +130,7 @@ variables:
   DAST_FULL_SCAN_ENABLED: "true"
 ```
 
-#### Customizing the DAST settings
+### Customizing the DAST settings
 
 The DAST settings can be changed through environment variables by using the
 [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
@@ -155,7 +150,7 @@ variables:
 Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline
 configuration, the last mention of the variable will take precedence.
 
-#### Overriding the DAST template
+### Overriding the DAST template
 
 If you want to override the job definition (for example, change properties like
 `variables` or `dependencies`), you need to declare a `dast` job after the
@@ -176,78 +171,27 @@ As the DAST job belongs to a separate `dast` stage that runs after all
 [default stages](../../../ci/yaml/README.md#stages),
 don't forget to add `stage: dast` when you override the template job definition.
 
-### Manual job definition for GitLab 11.5 and later
-
-For GitLab 11.5 and GitLab Runner 11.5 and later, the following `dast`
-job can be added:
-
-```yaml
-dast:
-  image: registry.gitlab.com/gitlab-org/security-products/zaproxy
-  variables:
-    website: "https://example.com"
-  allow_failure: true
-  script:
-    - mkdir /zap/wrk/
-    - /zap/zap-baseline.py -J gl-dast-report.json -t $website || true
-    - cp /zap/wrk/gl-dast-report.json .
-  artifacts:
-    reports:
-      dast: gl-dast-report.json
-```
-
-Where the `website` variable holds the URL to run the tests against.
-
-For an authenticated scan, use the following definition:
-
-```yaml
-dast:
-  image: registry.gitlab.com/gitlab-org/security-products/zaproxy
-  variables:
-    website: "https://example.com"
-    login_url: "https://example.com/sign-in"
-    username: "john.doe@example.com"
-    password: "john-doe-password"
-  allow_failure: true
-  script:
-    - mkdir /zap/wrk/
-    - /zap/zap-baseline.py -J gl-dast-report.json -t $website
-        --auth-url $login_url
-        --auth-username $username
-        --auth-password $password || true
-    - cp /zap/wrk/gl-dast-report.json .
-  artifacts:
-    reports:
-      dast: gl-dast-report.json
-```
-
-See the [zaproxy documentation](https://gitlab.com/gitlab-org/security-products/zaproxy)
-to learn more about the authentication settings.
-
-### Manual job definition for GitLab 11.4 and earlier (deprecated)
-
-CAUTION: **Caution:**
-Before GitLab 11.5, DAST job and artifact had to be named specifically
-to automatically extract report data and show it in the merge request widget.
-While these old job definitions are still maintained they have been deprecated
-and may be removed in next major release, GitLab 12.0. You are strongly advised
-to update your current `.gitlab-ci.yml` configuration to reflect that change.
-
-For GitLab 11.4 and earlier, the job should look like:
-
-```yaml
-dast:
-  image: registry.gitlab.com/gitlab-org/security-products/zaproxy
-  variables:
-    website: "https://example.com"
-  allow_failure: true
-  script:
-    - mkdir /zap/wrk/
-    - /zap/zap-baseline.py -J gl-dast-report.json -t $website || true
-    - cp /zap/wrk/gl-dast-report.json .
-  artifacts:
-    paths: [gl-dast-report.json]
-```
+## Available variables
+
+DAST can be [configured](#customizing-the-dast-settings) using environment variables.
+Since it's a wrapper around the ZAP scanning scripts
+([baseline](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan)
+or [full](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) scan), it
+accepts all arguments those scripts recognize (the arguments are the same).
+The choice of the scan type depends on the `DAST_FULL_SCAN_ENABLED` environment
+variable value.
+
+| Environment variable        | Required   | Description                                                                    |
+|-----------------------------| ----------|--------------------------------------------------------------------------------|
+| `DAST_WEBSITE`  | yes | The URL of the website to scan. |
+| `DAST_AUTH_URL` | no | The authentication URL of the website to scan. |
+| `DAST_USERNAME` | no | The username to authenticate to in the website. |
+| `DAST_PASSWORD` | no | The password to authenticate to in the website. |
+| `DAST_USERNAME_FIELD` | no | The name of username field at the sign-in HTML form. |
+| `DAST_PASSWORD_FIELD` | no | The name of password field at the sign-in HTML form. |
+| `DAST_AUTH_EXCLUDE_URLS` | no | The URLs to skip during the authenticated scan; comma-separated, no spaces in between. |
+| `DAST_TARGET_AVAILABILITY_TIMEOUT` | no | Time limit in seconds to wait for target availability. Scan is attempted nevertheless if it runs out. Integer. Defaults to `60`. |
+| `DAST_FULL_SCAN_ENABLED` | no | Switches the tool to execute [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. |
 
 ## Security Dashboard
 
@@ -259,3 +203,20 @@ vulnerabilities in your groups and projects. Read more about the
 
 Once a vulnerability is found, you can interact with it. Read more on how to
 [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities).
+
+## Vulnerabilities database update
+
+For more information about the vulnerabilities database update, check the
+[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database).
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v12_2.png b/doc/user/application_security/dependency_list/img/dependency_list_v12_2.png
new file mode 100644
index 00000000000..af9cee08d71
--- /dev/null
+++ b/doc/user/application_security/dependency_list/img/dependency_list_v12_2.png
diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md
new file mode 100644
index 00000000000..38c38bbd8a9
--- /dev/null
+++ b/doc/user/application_security/dependency_list/index.md
@@ -0,0 +1,49 @@
+# Dependency List **(ULTIMATE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/10075) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0.
+
+The Dependency list allows you to see your project's dependencies, and key
+details about them, including their known vulnerabilities. To see it,
+navigate to **Security & Compliance > Dependency List** in your project's
+sidebar.
+
+## Requirements
+
+1. The [Dependency Scanning](../dependency_scanning/index.md) CI job must be
+   configured for your project.
+1. Your project uses at least one of the
+   [languages and package managers](../dependency_scanning/index.md#supported-languages-and-package-managers)
+   supported by Gemnasium.
+
+## Viewing dependencies
+
+![Dependency List](img/dependency_list_v12_2.png)
+
+Dependencies are displayed with the following information:
+
+| Field     | Description |
+| --------- | ----------- |
+| Status    | Displays whether or not the dependency has any known vulnerabilities |
+| Component | The dependency's name |
+| Version   | The exact locked version of the dependency your project uses |
+| Packager  | The packager used to install the depedency |
+| Location  | A link to the packager-specific lockfile in your project that declared the dependency |
+
+Dependencies shown are initially sorted by their names. They can also be sorted
+by the packager they were installed by, or by the severity of their known
+vulnerabilities.
+
+There is a second list under the `Vulnerable components` tab displaying only
+those dependencies with known vulnerabilities. If there are none, this tab is
+disabled.
+
+### Vulnerabilities
+
+If a dependency has known vulnerabilities, they can be viewed by clicking on the
+`Status` cell of that dependency. The severity and description of each
+vulnerability will then be displayed below it.
+
+## Downloading the Dependency List
+
+Your project's full list of dependencies and their details can be downloaded in
+`JSON` format by clicking on the download button.
diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md
new file mode 100644
index 00000000000..3b4b341739b
--- /dev/null
+++ b/doc/user/application_security/dependency_scanning/analyzers.md
@@ -0,0 +1,133 @@
+# Dependency Scanning Analyzers **(ULTIMATE)**
+
+Dependency Scanning relies on underlying third party tools that are wrapped into
+what we call "Analyzers". An analyzer is a
+[dedicated project](https://gitlab.com/gitlab-org/security-products/analyzers)
+that wraps a particular tool to:
+
+- Expose its detection logic.
+- Handle its execution.
+- Convert its output to the common format.
+
+This is achieved by implementing the [common API](https://gitlab.com/gitlab-org/security-products/analyzers/common).
+
+Dependency Scanning supports the following official analyzers:
+
+- [`bundler-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit)
+- [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium)
+- [`gemnasium-maven`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven)
+- [`gemnasium-python`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python)
+- [`retire.js`](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js)
+
+The analyzers are published as Docker images that Dependency Scanning will use
+to launch dedicated containers for each analysis.
+
+Dependency Scanning is pre-configured with a set of **default images** that are
+maintained by GitLab, but users can also integrate their own **custom images**.
+
+## Official default analyzers
+
+Any custom change to the official analyzers can be achieved by using an
+[environment variable in your `.gitlab-ci.yml`](index.md#customizing-the-dependency-scanning-settings).
+
+### Using a custom Docker mirror
+
+You can switch to a custom Docker registry that provides the official analyzer
+images under a different prefix. For instance, the following instructs Dependency
+Scanning to pull `my-docker-registry/gl-images/gemnasium`
+instead of `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium`.
+In `.gitlab-ci.yml` define:
+
+```yaml
+include:
+  template: Dependency-Scanning.gitlab-ci.yml
+
+variables:
+  DS_ANALYZER_IMAGE_PREFIX: my-docker-registry/gl-images
+```
+
+This configuration requires that your custom registry provides images for all
+the official analyzers.
+
+### Selecting specific analyzers
+
+You can select the official analyzers you want to run. Here's how to enable
+`bundler-audit` and `gemnasium` while disabling all the other default ones.
+In `.gitlab-ci.yml` define:
+
+```yaml
+include:
+  template: Dependency-Scanning.gitlab-ci.yml
+
+variables:
+  DS_DEFAULT_ANALYZERS: "bundler-audit,gemnasium"
+```
+
+`bundler-audit` runs first. When merging the reports, Dependency Scanning will
+remove the duplicates and will keep the `bundler-audit` entries.
+
+### Disabling default analyzers
+
+Setting `DS_DEFAULT_ANALYZERS` to an empty string will disable all the official
+default analyzers. In `.gitlab-ci.yml` define:
+
+```yaml
+include:
+  template: Dependency-Scanning.gitlab-ci.yml
+
+variables:
+  DS_DEFAULT_ANALYZERS: ""
+```
+
+That's needed when one totally relies on [custom analyzers](#custom-analyzers).
+
+## Custom analyzers
+
+You can provide your own analyzers as a comma separated list of Docker images.
+Here's how to add `analyzers/nugget` and `analyzers/perl` to the default images.
+In `.gitlab-ci.yml` define:
+
+```yaml
+include:
+  template: Dependency-Scanning.gitlab-ci.yml
+
+variables:
+  DS_ANALYZER_IMAGES: "my-docker-registry/analyzers/nugget,amy-docker-registry/nalyzers/perl"
+```
+
+The values must be the full path to the container registry images,
+like what you would feed to the `docker pull` command.
+
+NOTE: **Note:**
+This configuration doesn't benefit from the integrated detection step. Dependency
+Scanning has to fetch and spawn each Docker image to establish whether the
+custom analyzer can scan the source code.
+
+## Analyzers data
+
+The following table lists the data available for each official analyzer.
+
+| Property \ Tool                       |      Gemnasium     |    bundler-audit   |     Retire.js      |
+|---------------------------------------|:------------------:|:------------------:|:------------------:|
+| Severity                              | 𐄂                  | ✓                  | ✓                  |
+| Title                                 | ✓                  | ✓                  | ✓                  |
+| File                                  | ✓                  | ⚠                  | ✓                  |
+| Start line                            | 𐄂                  | 𐄂                  | 𐄂                  |
+| End line                              | 𐄂                  | 𐄂                  | 𐄂                  |
+| External ID (e.g., CVE)               | ✓                  | ✓                  | ⚠                  |
+| URLs                                  | ✓                  | ✓                  | ✓                  |
+| Internal doc/explanation              | ✓                  | 𐄂                  | 𐄂                  |
+| Solution                              | ✓                  | ✓                  | 𐄂                  |
+| Confidence                            | 𐄂                  | 𐄂                  | 𐄂                  |
+| Affected item (e.g. class or package) | ✓                  | ✓                  | ✓                  |
+| Source code extract                   | 𐄂                  | 𐄂                  | 𐄂                  |
+| Internal ID                           | ✓                  | 𐄂                  | 𐄂                  |
+| Date                                  | ✓                  | 𐄂                  | 𐄂                  |
+| Credits                               | ✓                  | 𐄂                  | 𐄂                  |
+
+- ✓ => we have that data
+- ⚠ => we have that data but it's partially reliable, or we need to extract that data from unstructured content
+- 𐄂 => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it.
+
+The values provided by these tools are heterogeneous so they are sometimes
+normalized into common values (e.g., `severity`, `confidence`, etc).
diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md
index f3bf743ad03..3148ec63c79 100644
--- a/doc/user/application_security/dependency_scanning/index.md
+++ b/doc/user/application_security/dependency_scanning/index.md
@@ -1,4 +1,8 @@
-# Dependency Scanning **[ULTIMATE]**
+---
+type: reference, howto
+---
+
+# Dependency Scanning **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5105)
 in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7.
@@ -8,7 +12,7 @@ in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7.
 If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your dependencies for known
 vulnerabilities using Dependency Scanning.
 
-You can take advantage of Dependency Scanning by either [including the CI job](#including-the-provided-template)
+You can take advantage of Dependency Scanning by either [including the CI job](#configuration)
 in your existing `.gitlab-ci.yml` file or by implicitly using
 [Auto Dependency Scanning](../../../topics/autodevops/index.md#auto-dependency-scanning-ultimate)
 that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
@@ -46,43 +50,45 @@ this is enabled by default.
 
 The following languages and dependency managers are supported.
 
-| Language (package managers)                                                 | Scan tool                                                                                                                         |
-|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/en/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general), [Retire.js](https://retirejs.github.io/retire.js)         |
-| Python ([pip](https://pip.pypa.io/en/stable/)) (only `requirements.txt` supported)  | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general)                                                            |
-| Ruby ([gem](https://rubygems.org/))                                         | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general), [bundler-audit](https://github.com/rubysec/bundler-audit) |
-| Java ([Maven](https://maven.apache.org/))                                   | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general)                                                            |
-| PHP ([Composer](https://getcomposer.org/))                                  | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general)                                                            |
-
-Some scanners require to send a list of project dependencies to GitLab's central
-servers to check for vulnerabilities. To learn more about this or to disable it,
-refer to the [GitLab Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks).
+| Language (package managers)  | Supported | Scan tool(s) |
+|----------------------------- | --------- | ------------ |
+| Java ([Gradle](https://gradle.org/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/13075 "Dependency Scanning for Gradle" )) | not available |
+| Java ([Maven](https://maven.apache.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
+| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/en/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js)         |
+| Go ([Golang](https://golang.org/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/7132 "Dependency Scanning for Go")) | not available |
+| PHP ([Composer](https://getcomposer.org/))  | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
+| Python ([pip](https://pip.pypa.io/en/stable/)) (only `requirements.txt` supported)  | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
+| Python ([Pipfile](https://docs.pipenv.org/en/latest/basics/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/11756 "Pipfile.lock support for Dependency Scanning"))| not available |
+| Python ([poetry](https://poetry.eustace.io/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/7006 "Support Poetry in Dependency Scanning")) | not available |
+| Ruby ([gem](https://rubygems.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) |
 
-## Configuring Dependency Scanning
+## Remote checks
 
-To enable Dependency Scanning in your project, define a job in your `.gitlab-ci.yml`
-file that generates the
-[Dependency Scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate).
+While some tools pull a local database to check vulnerabilities, some others
+like Gemnasium require sending data to GitLab central servers to analyze them:
 
-This can be done in two ways:
+1. Gemnasium scans the dependencies of your project locally and sends a list of
+   packages to GitLab central servers.
+1. The servers return the list of known vulnerabilities for all versions of
+   these packages.
+1. The client picks up the relevant vulnerabilities by comparing with the versions
+   of the packages that are used by the project.
 
-- For GitLab 11.9 and later, including the provided `Dependency-Scanning.gitlab-ci.yml` template (recommended).
-- Manually specifying the job definition. Not recommended unless using GitLab
-  11.8 and earlier.
+The Gemnasium client does **NOT** send the exact package versions your project relies on.
 
-### Including the provided template
+You can disable the remote checks by [using](#customizing-the-dependency-scanning-settings)
+the `DS_DISABLE_REMOTE_CHECKS` environment variable and setting it to `true`.
 
-NOTE: **Note:**
-The CI/CD Dependency Scanning template is supported on GitLab 11.9 and later versions.
-For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later).
+## Configuration
 
-A CI/CD [Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml)
-with the default Dependency Scanning job definition is provided as a part of your GitLab
-installation which you can [include](../../../ci/yaml/README.md#includetemplate)
-in your `.gitlab-ci.yml` file.
+For GitLab 11.9 and later, to enable Dependency Scanning, you must
+[include](../../../ci/yaml/README.md#includetemplate) the
+[`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml)
+that's provided as a part of your GitLab installation.
+For GitLab versions earlier than 11.9, you can copy and use the job as defined
+that template.
 
-To enable Dependency Scanning using the provided template, add the following to
-your `.gitlab-ci.yml` file:
+Add the following to your `.gitlab-ci.yml` file:
 
 ```yaml
 include:
@@ -92,22 +98,15 @@ include:
 The included template will create a `dependency_scanning` job in your CI/CD
 pipeline and scan your project's source code for possible vulnerabilities.
 
-The report will be saved as a
+The results will be saved as a
 [Dependency Scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate)
 that you can later download and analyze. Due to implementation limitations, we
 always take the latest Dependency Scanning artifact available.
 
-Some security scanners require to send a list of project dependencies to GitLab
-central servers to check for vulnerabilities. To learn more about this or to
-disable it, check the
-[GitLab Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks).
-
-#### Customizing the Dependency Scanning settings
+### Customizing the Dependency Scanning settings
 
-The Dependency Scanning settings can be changed through environment variables by using the
+The Dependency Scanning settings can be changed through [environment variables](#available-variables) by using the
 [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
-These variables are documented in the
-[Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings).
 
 For example:
 
@@ -116,13 +115,13 @@ include:
   template: Dependency-Scanning.gitlab-ci.yml
 
 variables:
-  DEP_SCAN_DISABLE_REMOTE_CHECKS: true
+  DS_DISABLE_REMOTE_CHECKS: true
 ```
 
 Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline
 configuration, the last mention of the variable will take precedence.
 
-#### Overriding the Dependency Scanning template
+### Overriding the Dependency Scanning template
 
 If you want to override the job definition (for example, change properties like
 `variables` or `dependencies`), you need to declare a `dependency_scanning` job
@@ -137,88 +136,34 @@ dependency_scanning:
     CI_DEBUG_TRACE: "true"
 ```
 
-### Manual job definition for GitLab 11.5 and later
-
-For GitLab 11.5 and GitLab Runner 11.5 and later, the following `dependency_scanning`
-job can be added:
-
-```yaml
-dependency_scanning:
-  image: docker:stable
-  variables:
-    DOCKER_DRIVER: overlay2
-  allow_failure: true
-  services:
-    - docker:stable-dind
-  script:
-    - export DS_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')}
-    - |
-      docker run \
-      --env DS_ANALYZER_IMAGES \
-      --env DS_ANALYZER_IMAGE_PREFIX \
-      --env DS_ANALYZER_IMAGE_TAG \
-      --env DS_DEFAULT_ANALYZERS \
-      --env DEP_SCAN_DISABLE_REMOTE_CHECKS \
-      --env DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \
-      --env DS_PULL_ANALYZER_IMAGE_TIMEOUT \
-      --env DS_RUN_ANALYZER_TIMEOUT \
-      --volume "$PWD:/code" \
-      --volume /var/run/docker.sock:/var/run/docker.sock \
-      "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$DS_VERSION" /code
-  dependencies: []
-  artifacts:
-    reports:
-      dependency_scanning: gl-dependency-scanning-report.json
-```
-
-You can supply many other [settings variables](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings)
-via `docker run --env` to customize your job execution.
-
-### Manual job definition for GitLab 11.4 and earlier (deprecated)
-
-CAUTION: **Caution:**
-Before GitLab 11.5, the Dependency Scanning job and artifact had to be named specifically
-to automatically extract the report data and show it in the merge request widget.
-While these old job definitions are still maintained, they have been deprecated
-and may be removed in the next major release, GitLab 12.0. You are strongly advised
-to update your current `.gitlab-ci.yml` configuration to reflect that change.
-
-For GitLab 11.4 and earlier, the job should look like:
-
-```yaml
-dependency_scanning:
-  image: docker:stable
-  variables:
-    DOCKER_DRIVER: overlay2
-  allow_failure: true
-  services:
-    - docker:stable-dind
-  script:
-    - export DS_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')}
-    - |
-      docker run \
-      --env DS_ANALYZER_IMAGES \
-      --env DS_ANALYZER_IMAGE_PREFIX \
-      --env DS_ANALYZER_IMAGE_TAG \
-      --env DS_DEFAULT_ANALYZERS \
-      --env DS_EXCLUDED_PATHS \
-      --env DEP_SCAN_DISABLE_REMOTE_CHECKS \
-      --env DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \
-      --env DS_PULL_ANALYZER_IMAGE_TIMEOUT \
-      --env DS_RUN_ANALYZER_TIMEOUT \
-      --volume "$PWD:/code" \
-      --volume /var/run/docker.sock:/var/run/docker.sock \
-      "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$DS_VERSION" /code
-  artifacts:
-    paths: [gl-dependency-scanning-report.json]
-```
+### Available variables
+
+Dependency Scanning can be [configured](#customizing-the-dependency-scanning-settings)
+using environment variables.
+
+| Environment variable                    | Function |
+|--------------------------------         |----------|
+| `DS_ANALYZER_IMAGES`                    | Comma separated list of custom images. The official default images are still enabled. Read more about [customizing analyzers](analyzers.md). |
+| `DS_ANALYZER_IMAGE_PREFIX`              | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). |
+| `DS_ANALYZER_IMAGE_TAG`                 | Override the Docker tag of the official default images. Read more about [customizing analyzers](analyzers.md). |
+| `DS_PYTHON_VERSION`                     | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12296) in GitLab 12.1)|
+| `DS_PIP_DEPENDENCY_PATH`                | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12412) in GitLab 12.2) |
+| `DS_DEFAULT_ANALYZERS`                  | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). |
+| `DS_DISABLE_REMOTE_CHECKS`              | Do not send any data to GitLab. Used in the [Gemnasium analyzer](#remote-checks). |
+| `DS_PULL_ANALYZER_IMAGES`               | Pull the images from the Docker registry (set to `0` to disable). |
+| `DS_EXCLUDED_PATHS`                     | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, file or folder paths. Parent directories will also match patterns. |
+| `DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT`  | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. |
+| `DS_PULL_ANALYZER_IMAGE_TIMEOUT`        | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. |
+| `DS_RUN_ANALYZER_TIMEOUT`               | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. |
+| `PIP_INDEX_URL`                         | Base URL of Python Package Index (default `https://pypi.org/simple`). |
+| `PIP_EXTRA_INDEX_URL`                   | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma separated. |
 
 ## Reports JSON format
 
 CAUTION: **Caution:**
 The JSON report artifacts are not a public API of Dependency Scanning and their format may change in future.
 
-The Dependency Scanning tool emits a JSON report file. Here is an example of a structure for a report will all important parts of
+The Dependency Scanning tool emits a JSON report file. Here is an example of the report structure with all important parts of
 it highlighted:
 
 ```json-doc
@@ -343,10 +288,10 @@ the report JSON unless stated otherwise. Presence of optional fields depends on
 | `vulnerabilities[].severity`                         | How much the vulnerability impacts the software. Possible values: `Undefined` (an analyzer has not provided this info), `Info`, `Unknown`, `Low`, `Medium`, `High`, `Critical`. |
 | `vulnerabilities[].confidence`                       | How reliable the vulnerability's assessment is. Possible values: `Undefined` (an analyzer has not provided this info), `Ignore`, `Unknown`, `Experimental`, `Low`, `Medium`, `High`, `Confirmed`. |
 | `vulnerabilities[].solution`                         | Explanation of how to fix the vulnerability. Optional. |
-| `vulnerabilities[].scanner`                          | A node that describes the analyzer used find this vulnerability. |
+| `vulnerabilities[].scanner`                          | A node that describes the analyzer used to find this vulnerability. |
 | `vulnerabilities[].scanner.id`                       | Id of the scanner as a snake_case string. |
 | `vulnerabilities[].scanner.name`                     | Name of the scanner, for display purposes. |
-| `vulnerabilities[].location`                         | A node that tells which class and/or method is affected by the vulnerability. | 
+| `vulnerabilities[].location`                         | A node that tells where the vulnerability is located. |
 | `vulnerabilities[].location.file`                    | Path to the dependencies file (e.g., `yarn.lock`). Optional. |
 | `vulnerabilities[].location.dependency`              | A node that describes the dependency of a project where the vulnerability is located. |
 | `vulnerabilities[].location.dependency.package`      | A node that provides the information on the package where the vulnerability is located. |
@@ -360,7 +305,7 @@ the report JSON unless stated otherwise. Presence of optional fields depends on
 | `vulnerabilities[].links`                            | An array of references to external documentation pieces or articles that describe the vulnerability further. Optional. |
 | `vulnerabilities[].links[].name`                     | Name of the vulnerability details link. Optional. |
 | `vulnerabilities[].links[].url`                      | URL of the vulnerability details document. Optional. |
-| `remediations`                                       | An array of objects containing information on cured vulnerabilities along with patch diffs to apply. |
+| `remediations`                                       | An array of objects containing information on cured vulnerabilities along with patch diffs to apply. Empty if no remediations provided by an underlying analyzer. |
 | `remediations[].fixes`                               | An array of strings that represent references to vulnerabilities fixed by this particular remediation. |
 | `remediations[].fixes[].cve`                         | A string value that describes a fixed vulnerability occurrence in the same format as `vulnerabilities[].cve`. |
 | `remediations[].summary`                             | Overview of how the vulnerabilities have been fixed. |
@@ -377,19 +322,35 @@ vulnerabilities in your groups and projects. Read more about the
 Once a vulnerability is found, you can interact with it. Read more on how to
 [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities).
 
-## Dependency List
+## Vulnerabilities database update
+
+For more information about the vulnerabilities database update, check the
+[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database).
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/10075)
-in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0.
+## Dependency List **(ULTIMATE)**
 
-An additional benefit of Dependency Scanning is the ability to get a list of your project's dependencies with their versions. 
+An additional benefit of Dependency Scanning is the ability to view your
+project's dependencies and their known vulnerabilities. Read more about
+the [Dependency List](../dependency_list/index.md).
 
-This list can be generated only for [supported languages and package managers](#supported-languages-and-package-managers).
+## Versioning and release process
 
-To see the generated dependency list, navigate to the Dependency List page under your project's left sidebar menu **Project > Dependency List**.
+Please check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md).
 
 ## Contributing to the vulnerability database
 
 You can search the [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project
 to find a vulnerability in the Gemnasium database.
-You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md).
\ No newline at end of file
+You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md).
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/application_security/img/create_issue_with_list_hover.png b/doc/user/application_security/img/create_issue_with_list_hover.png
index 7d70e8299f5..4c38862e68f 100644
--- a/doc/user/application_security/img/create_issue_with_list_hover.png
+++ b/doc/user/application_security/img/create_issue_with_list_hover.png
diff --git a/doc/user/application_security/img/dismissed_info.png b/doc/user/application_security/img/dismissed_info.png
index 64d5cf26ed2..b4470b664d2 100644
--- a/doc/user/application_security/img/dismissed_info.png
+++ b/doc/user/application_security/img/dismissed_info.png
diff --git a/doc/user/application_security/img/interactive_reports.png b/doc/user/application_security/img/interactive_reports.png
index 373b39104db..1b2ef0d3da9 100644
--- a/doc/user/application_security/img/interactive_reports.png
+++ b/doc/user/application_security/img/interactive_reports.png
diff --git a/doc/user/application_security/img/vulnerability_solution.png b/doc/user/application_security/img/vulnerability_solution.png
index 7443b9b6eea..d86b89a5f99 100644
--- a/doc/user/application_security/img/vulnerability_solution.png
+++ b/doc/user/application_security/img/vulnerability_solution.png
diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md
index 679847b76d7..83ea0ea3386 100644
--- a/doc/user/application_security/index.md
+++ b/doc/user/application_security/index.md
@@ -1,23 +1,59 @@
-# GitLab Secure **[ULTIMATE]**
+---
+type: reference, howto
+---
 
-Check your application for security vulnerabilities that may lead to unauthorized access,
-data leaks, and denial of services. GitLab will perform static and dynamic tests on the
-code of your application, looking for known flaws and report them in the merge request
-so you can fix them before merging. Security teams can use dashboards to get a
-high-level view on projects and groups, and start remediation processes when needed.
+# GitLab Secure **(ULTIMATE)**
+
+Check your application for security vulnerabilities that may lead to
+unauthorized access, data leaks, and denial of services.
+
+GitLab will perform static and dynamic tests on the code of your application,
+looking for known flaws and report them in the merge request so you can fix
+them before merging.
+
+Security teams can use dashboards to get a high-level view on projects and
+groups, and start remediation processes when needed.
+
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For an overview of application security with GitLab, see
+[Security Deep Dive](https://www.youtube.com/watch?v=k4vEJnGYy84).
 
 ## Security scanning tools
 
 GitLab can scan and report any vulnerabilities found in your project.
 
-| Secure scanning tools                                                        | Description                                                            |
+| Secure scanning tool                                                         | Description                                                            |
 |:-----------------------------------------------------------------------------|:-----------------------------------------------------------------------|
-| [Container Scanning](container_scanning/index.md) **[ULTIMATE]**             | Scan Docker containers for known vulnerabilities.                      |
-| [Dependency Scanning](dependency_scanning/index.md) **[ULTIMATE]**           | Analyze your dependencies for known vulnerabilities.                   |
-| [Dynamic Application Security Testing (DAST)](dast/index.md) **[ULTIMATE]**  | Analyze running web applications for known vulnerabilities.            |
-| [License Management](license_management/index.md) **[ULTIMATE]**             | Search your project's dependencies for their licenses.                 |
-| [Security Dashboard](security_dashboard/index.md) **[ULTIMATE]**             | View vulnerabilities in all your projects and groups.                  |
-| [Static Application Security Testing (SAST)](sast/index.md) **[ULTIMATE]**   | Analyze source code for known vulnerabilities.                         |
+| [Container Scanning](container_scanning/index.md) **(ULTIMATE)**             | Scan Docker containers for known vulnerabilities.                      |
+| [Dependency List](dependency_list/index.md) **(ULTIMATE)**                   | View your project's dependencies and their known vulnerabilities.      |
+| [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)**           | Analyze your dependencies for known vulnerabilities.                   |
+| [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)**  | Analyze running web applications for known vulnerabilities.            |
+| [License Management](license_management/index.md) **(ULTIMATE)**             | Search your project's dependencies for their licenses.                 |
+| [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)**             | View vulnerabilities in all your projects and groups.                  |
+| [Static Application Security Testing (SAST)](sast/index.md) **(ULTIMATE)**   | Analyze source code for known vulnerabilities.                         |
+
+## Maintenance and update of the vulnerabilities database
+
+The various scanning tools and the vulnerabilities database are updated regularly.
+
+| Secure scanning tool                                         | Vulnerabilities database updates          |
+|:-------------------------------------------------------------|-------------------------------------------|
+| [Container Scanning](container_scanning/index.md)            | Uses `clair` underneath and the latest `clair-db` version is used for each job run by running the [`latest` docker image tag](https://gitlab.com/gitlab-org/gitlab-ee/blob/438a0a56dc0882f22bdd82e700554525f552d91b/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L37). The `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). |
+| [Dependency Scanning](dependency_scanning/index.md)          | Relies on `bundler-audit` (for Rubygems), `retire.js` (for NPM packages) and `gemnasium` (GitLab's own tool for all libraries). `bundler-audit` and `retire.js` both fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. |
+| [Dynamic Application Security Testing (DAST)](dast/index.md) | Updated weekly on Sundays. The underlying tool, `zaproxy`, downloads fresh rules at startup. |
+| [Static Application Security Testing (SAST)](sast/index.md)  | Relies exclusively on [the tools GitLab is wrapping](sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. |
+
+You don't have to update GitLab to benefit from the latest vulnerabilities definitions,
+but you may have to in the future.
+
+The security tools are released as Docker images, and the vendored job definitions
+to enable them are using the `x-y-stable` image tags that get overridden each time a new
+release of the tools is pushed. The Docker images are updated to match the
+previous GitLab releases, so they automatically get the latest versions of the
+scanning tools without the user having to do anything.
+
+This workflow comes with some drawbacks and there's a
+[plan to change this](https://gitlab.com/gitlab-org/gitlab-ee/issues/9725).
 
 ## Interacting with the vulnerabilities
 
@@ -31,7 +67,7 @@ Each security vulnerability in the merge request report or the
 entry, a detailed information will pop up with different possible options:
 
 - [Dismiss vulnerability](#dismissing-a-vulnerability): Dismissing a vulnerability
-  will place a <s>strikethrough</s> styling on it.
+  will place a ~~strikethrough~~ styling on it.
 - [Create issue](#creating-an-issue-for-a-vulnerability): The new issue will
   have the title and description pre-populated with the information from the
   vulnerability report and will be created as [confidential](../project/issues/confidential_issues.md) by default.
@@ -92,16 +128,16 @@ generated by GitLab. To apply the fix:
 
 1. Click on the vulnerability.
 1. Download and review the patch file `remediation.patch`.
-2. Ensure your local project has the same commit checked out that was used to generate the patch.
-3. Run `git apply remediation.patch`.
-4. Verify and commit the changes to your branch.
+1. Ensure your local project has the same commit checked out that was used to generate the patch.
+1. Run `git apply remediation.patch`.
+1. Verify and commit the changes to your branch.
 
 ![Apply patch for dependency scanning](img/vulnerability_solution.png)
 
 #### Creating a merge request from a vulnerability
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9224) in
-  [GitLab Ultimate](https://about.gitlab.com/pricing) 11.9.
+> [GitLab Ultimate](https://about.gitlab.com/pricing) 11.9.
 
 In certain cases, GitLab will allow you to create a merge request that will
 automatically remediate the vulnerability. Any vulnerability that has a
@@ -112,3 +148,47 @@ If this action is available there will be a **Create merge request** button in t
 Clicking on this button will create a merge request to apply the solution onto the source branch.
 
 ![Create merge request from vulnerability](img/create_issue_with_list_hover.png)
+
+## Security approvals in merge requests **(ULTIMATE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing) 12.2.
+
+Merge Request Approvals can be configured to require approval from a member 
+of your security team when a vulnerability would be introduced by a merge request.
+
+This threshold is defined as `high`, `critical`, or `unknown`
+severity. When any vulnerabilities are present within a merge request, an
+approval will be required from the `Vulnerability-Check` approver group.
+
+### Enabling Security Approvals within a project
+
+To enable Security Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#multiple-approval-rules-premium)
+must be created with the case-sensitive name `Vulnerability-Check`. This approval
+group must be set with an "Approvals required" count greater than zero.
+
+Once this group has been added to your project, the approval rule will be enabled
+for all Merge Requests.
+
+Any code changes made will cause the count of approvals required to reset.
+
+An approval will be required when a security report:
+
+- Contains a new vulnerability of `high`, `critical`, or `unknown` severity.
+- Is not generated during pipeline execution.
+
+An approval will be optional when a security report:
+
+- Contains no new vulnerabilities.
+- Contains only new vulnerabilities of `low` or `medium` severity.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/application_security/license_management/img/license_management_add_license.png b/doc/user/application_security/license_management/img/license_management_add_license.png
new file mode 100644
index 00000000000..c9a5dc14c57
--- /dev/null
+++ b/doc/user/application_security/license_management/img/license_management_add_license.png
diff --git a/doc/user/application_security/license_management/img/license_management_decision.png b/doc/user/application_security/license_management/img/license_management_decision.png
index 0763130c375..fbf90bec7fd 100644
--- a/doc/user/application_security/license_management/img/license_management_decision.png
+++ b/doc/user/application_security/license_management/img/license_management_decision.png
diff --git a/doc/user/application_security/license_management/img/license_management_search.png b/doc/user/application_security/license_management/img/license_management_search.png
new file mode 100644
index 00000000000..b3ffd8d95a1
--- /dev/null
+++ b/doc/user/application_security/license_management/img/license_management_search.png
diff --git a/doc/user/application_security/license_management/img/license_management_settings.png b/doc/user/application_security/license_management/img/license_management_settings.png
index b5490e59074..2e3e8888e93 100644
--- a/doc/user/application_security/license_management/img/license_management_settings.png
+++ b/doc/user/application_security/license_management/img/license_management_settings.png
diff --git a/doc/user/application_security/license_management/index.md b/doc/user/application_security/license_management/index.md
index 7878dc77084..c324848c703 100644
--- a/doc/user/application_security/license_management/index.md
+++ b/doc/user/application_security/license_management/index.md
@@ -1,4 +1,8 @@
-# License Management **[ULTIMATE]**
+---
+type: reference, howto
+---
+
+# License Management **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5483)
 in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0.
@@ -8,7 +12,7 @@ in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0.
 If you are using [GitLab CI/CD](../../../ci/README.md), you can search your project dependencies for their licenses
 using License Management.
 
-You can take advantage of License Management by either [including the job](#configuring-license-management)
+You can take advantage of License Management by either [including the job](#configuration)
 in your existing `.gitlab-ci.yml` file or by implicitly using
 [Auto License Management](../../../topics/autodevops/index.md#auto-license-management-ultimate)
 that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
@@ -44,44 +48,37 @@ library whose license is incompatible with yours.
 
 The following languages and package managers are supported.
 
-| Language   | Package managers                                                  |
-|------------|-------------------------------------------------------------------|
-| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/)         |
-| Go         | [Godep](https://github.com/tools/godep), go get                   |
-| Java       | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) |
-| .NET       | [Nuget](https://www.nuget.org/)                                   |
-| Python     | [pip](https://pip.pypa.io/en/stable/)                             |
-| Ruby       | [gem](https://rubygems.org/)                                      |
+| Language   | Package managers                                                  | Scan Tool                                                |
+|------------|-------------------------------------------------------------------|----------------------------------------------------------|
+| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)|
+| Go         | [Godep](https://github.com/tools/godep), go get ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), gvt ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), glide ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), dep ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), trash ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))  and govendor ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), [go mod](https://github.com/golang/go/wiki/Modules) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))   |[License Finder](https://github.com/pivotal/LicenseFinder)|
+| Java       | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)|
+| .NET       | [Nuget](https://www.nuget.org/)                                   |[License Finder](https://github.com/pivotal/LicenseFinder)|
+| Python     | [pip](https://pip.pypa.io/en/stable/)                             |[License Finder](https://github.com/pivotal/LicenseFinder)|
+| Ruby       | [gem](https://rubygems.org/)                                      |[License Finder](https://github.com/pivotal/LicenseFinder)|
+| Erlang     | [rebar](https://www.rebar3.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)|
+| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) , [CocoaPods v0.39 and below](https://cocoapods.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))  |[License Finder](https://github.com/pivotal/LicenseFinder)|
+| Elixir     | [mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)|
+| C++/C      | [conan](https://conan.io/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)|
+| Scala      | [sbt](https://www.scala-sbt.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)|
+| Rust       | [cargo](https://crates.io/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)|
+| PHP        | [composer](https://getcomposer.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)|
 
 ## Requirements
 
 To run a License Management scanning job, you need GitLab Runner with the
 [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html).
 
-## Configuring License Management
-
-To enable License Management in your project, define a job in your `.gitlab-ci.yml`
-file that generates the [License Management report artifact](../../../ci/yaml/README.md#artifactsreportslicense_management-ultimate).
-
-This can be done in two ways:
-
-- For GitLab 11.9 and later, including the provided `License-Management.gitlab-ci.yml` template (recommended).
-- Manually specifying the job definition. Not recommended unless using GitLab
-  11.8 and earlier.
+## Configuration
 
-### Including the provided template
+For GitLab 11.9 and later, to enable License Management, you must
+[include](../../../ci/yaml/README.md#includetemplate) the
+[`License-Management.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml)
+that's provided as a part of your GitLab installation.
+For GitLab versions earlier than 11.9, you can copy and use the job as defined
+that template.
 
-NOTE: **Note:**
-The CI/CD License Management template is supported on GitLab 11.9 and later versions.
-For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later).
-
-A CI/CD [License Management template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml)
-with the default License Management job definition is provided as a part of your GitLab
-installation which you can [include](../../../ci/yaml/README.md#includetemplate)
-in your `.gitlab-ci.yml` file.
-
-To enable License Management using the provided template, add the following to
-your `.gitlab-ci.yml` file:
+Add the following to your `.gitlab-ci.yml` file:
 
 ```yaml
 include:
@@ -91,14 +88,17 @@ include:
 The included template will create a `license_management` job in your CI/CD pipeline
 and scan your dependencies to find their licenses.
 
-The report will be saved as a
+The results will be saved as a
 [License Management report artifact](../../../ci/yaml/README.md#artifactsreportslicense_management-ultimate)
 that you can later download and analyze. Due to implementation limitations, we
 always take the latest License Management artifact available. Behind the scenes, the
 [GitLab License Management Docker image](https://gitlab.com/gitlab-org/security-products/license-management)
 is used to detect the languages/frameworks and in turn analyzes the licenses.
 
-#### Installing custom dependencies
+The License Management settings can be changed through environment variables by using the
+[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. These variables are documented in the [License Management documentation](https://gitlab.com/gitlab-org/security-products/license-management#settings).
+
+### Installing custom dependencies
 
 > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4.
 
@@ -126,7 +126,7 @@ variables:
 In this example, `my-custom-install-script.sh` is a shell script at the root
 directory of your project.
 
-#### Overriding the template
+### Overriding the template
 
 If you want to override the job definition (for example, change properties like
 `variables` or `dependencies`), you need to declare a `license_management` job
@@ -141,7 +141,7 @@ license_management:
     CI_DEBUG_TRACE: "true"
 ```
 
-#### Configuring Maven projects
+### Configuring Maven projects
 
 The License Management tool provides a `MAVEN_CLI_OPTS` environment variable which can hold
 the command line arguments to pass to the `mvn install` command which is executed under the hood.
@@ -165,65 +165,21 @@ to explicitly add `-DskipTests` to your options.
 If you still need to run tests during `mvn install`, add `-DskipTests=false` to
 `MAVEN_CLI_OPTS`.
 
-### Manual job definition for GitLab 11.5 and later
+### Selecting the version of Python
 
-For GitLab 11.5 and GitLab Runner 11.5 and later, the following `license_management`
-job can be added:
+> [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/merge_requests/36) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0.
 
-```yaml
-license_management:
-  image:
-    name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable"
-    entrypoint: [""]
-  stage: test
-  allow_failure: true
-  script:
-    - /run.sh analyze .
-  artifacts:
-    reports:
-      license_management: gl-license-management-report.json
-```
-
-If you want to install custom project dependencies via the `SETUP_CMD` variable:
+License Management uses Python 2.7 and pip 10.0 by default.
+If your project requires Python 3, you can switch to Python 3.5 and pip 19.1
+by setting the `LM_PYTHON_VERSION` environment variable to `3`.
 
 ```yaml
-license_management:
-  image:
-    name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable"
-    entrypoint: [""]
-  stage: test
-  variables:
-    SETUP_CMD: ./my-custom-install-script.sh
-  allow_failure: true
-  script:
-    - /run.sh analyze .
-  artifacts:
-    reports:
-      license_management: gl-license-management-report.json
-```
-
-### Manual job definition for GitLab 11.4 and earlier (deprecated)
-
-CAUTION: **Caution:**
-Before GitLab 11.5, the License Management job and artifact had to be named specifically
-to automatically extract the report data and show it in the merge request widget.
-While these old job definitions are still maintained, they have been deprecated
-and may be removed in the next major release, GitLab 12.0. You are strongly advised
-to update your current `.gitlab-ci.yml` configuration to reflect that change.
-
-For GitLab 11.4 and earlier, the job should look like:
+include:
+  template: License-Management.gitlab-ci.yml
 
-```yaml
 license_management:
-  image:
-    name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable"
-    entrypoint: [""]
-  stage: test
-  allow_failure: true
-  script:
-    - /run.sh analyze .
-  artifacts:
-    paths: [gl-license-management-report.json]
+  variables:
+    LM_PYTHON_VERSION: 3
 ```
 
 ## Project policies for License Management
@@ -242,16 +198,29 @@ To approve or blacklist a license:
    navigate to the project's **Settings > CI/CD** and expand the
    **License Management** section.
 1. Click the **Add a license** button.
+
+   ![License Management Add License](img/license_management_add_license.png)
+
 1. In the **License name** dropdown, either:
-    - Select one of the available licenses. You can search for licenses in the field
-   at the top of the list.
-    - Enter arbitrary text in the field at the top of the list. This will cause the text to be
-    added as a license name to the list.
+   - Select one of the available licenses. You can search for licenses in the field
+     at the top of the list.
+   - Enter arbitrary text in the field at the top of the list. This will cause the text to be
+     added as a license name to the list.
 1. Select the **Approve** or **Blacklist** radio button to approve or blacklist respectively
    the selected license.
 
+To modify an existing license:
+
+1. In the **License Management** list, click the **Approved/Declined** dropdown to change it to the desired status.
+
    ![License Management Settings](img/license_management_settings.png)
 
+Searching for Licenses:
+
+1. Use the **Search** box to search for a specific license.
+
+   ![License Management Search](img/license_management_search.png)
+
 ## License Management report under pipelines
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5491)
@@ -262,3 +231,15 @@ pipeline ID that has a `license_management` job to see the Licenses tab with the
 licenses (if any).
 
 ![License Management Pipeline Tab](img/license_management_pipeline_tab.png)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md
new file mode 100644
index 00000000000..f730a25a9fc
--- /dev/null
+++ b/doc/user/application_security/sast/analyzers.md
@@ -0,0 +1,144 @@
+---
+table_display_block: true
+---
+
+# SAST Analyzers **(ULTIMATE)**
+
+SAST relies on underlying third party tools that are wrapped into what we call
+"Analyzers". An analyzer is a
+[dedicated project](https://gitlab.com/gitlab-org/security-products/analyzers)
+that wraps a particular tool to:
+
+- Expose its detection logic.
+- Handle its execution.
+- Convert its output to the common format.
+
+This is achieved by implementing the [common API](https://gitlab.com/gitlab-org/security-products/analyzers/common).
+
+SAST supports the following official analyzers:
+
+- [`bandit`](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) (Bandit)
+- [`brakeman`](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) (Brakeman)
+- [`eslint`](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) (ESLint (Javascript))
+- [`flawfinder`](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) (Flawfinder)
+- [`gosec`](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) (Gosec)
+- [`nodejs-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) (NodeJsScan)
+- [`phpcs-security-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) (PHP CS security-audit)
+- [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) (PMD (Apex only))
+- [`secrets`](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) (Secrets (Gitleaks, TruffleHog & Diffence secret detectors))
+- [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) (Security Code Scan (.NET))
+- [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) (Sobelow (Elixir Phoenix))
+- [`spotbugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) (SpotBugs with the Find Sec Bugs plugin (Ant, Gradle and wrapper, Grails, Maven and wrapper, SBT))
+- [`tslint`](https://gitlab.com/gitlab-org/security-products/analyzers/tslint) (TSLint (Typescript))
+
+The analyzers are published as Docker images that SAST will use to launch
+dedicated containers for each analysis.
+
+SAST is pre-configured with a set of **default images** that are maintained by
+GitLab, but users can also integrate their own **custom images**.
+
+## Official default analyzers
+
+Any custom change to the official analyzers can be achieved by using an
+[environment variable in your `.gitlab-ci.yml`](index.md#customizing-the-sast-settings).
+
+### Using a custom Docker mirror
+
+You can switch to a custom Docker registry that provides the official analyzer
+images under a different prefix. For instance, the following instructs
+SAST to pull `my-docker-registry/gl-images/bandit`
+instead of `registry.gitlab.com/gitlab-org/security-products/analyzers/bandit`.
+In `.gitlab-ci.yml` define:
+
+```yaml
+include:
+  template: SAST.gitlab-ci.yml
+
+variables:
+  SAST_ANALYZER_IMAGE_PREFIX: my-docker-registry/gl-images
+```
+
+This configuration requires that your custom registry provides images for all
+the official analyzers.
+
+### Selecting specific analyzers
+
+You can select the official analyzers you want to run. Here's how to enable
+`bandit` and `flawfinder` while disabling all the other default ones.
+In `.gitlab-ci.yml` define:
+
+```yaml
+include:
+  template: SAST.gitlab-ci.yml
+
+variables:
+  SAST_DEFAULT_ANALYZERS: "bandit,flawfinder"
+```
+
+`bandit` runs first. When merging the reports, SAST will
+remove the duplicates and will keep the `bandit` entries.
+
+### Disabling default analyzers
+
+Setting `SAST_DEFAULT_ANALYZERS` to an empty string will disable all the official
+default analyzers. In `.gitlab-ci.yml` define:
+
+```yaml
+include:
+  template: SAST.gitlab-ci.yml
+
+variables:
+  SAST_DEFAULT_ANALYZERS: ""
+```
+
+That's needed when one totally relies on [custom analyzers](#custom-analyzers).
+
+## Custom Analyzers
+
+You can provide your own analyzers as a comma separated list of Docker images.
+Here's how to add `analyzers/csharp` and `analyzers/perl` to the default images:
+In `.gitlab-ci.yml` define:
+
+```yaml
+include:
+  template: SAST.gitlab-ci.yml
+
+variables:
+  SAST_ANALYZER_IMAGES: "my-docker-registry/analyzers/csharp,amy-docker-registry/analyzers/perl"
+```
+
+The values must be the full path to the container registry images,
+like what you would feed to the `docker pull` command.
+
+NOTE: **Note:**
+This configuration doesn't benefit from the integrated detection step.
+SAST has to fetch and spawn each Docker image to establish whether the
+custom analyzer can scan the source code.
+
+## Analyzers Data
+
+| Property \ Tool                         | Apex                 | Bandit               | Brakeman             | ESLint security      | Find Sec Bugs        | Flawfinder           | Go AST Scanner       | NodeJsScan           | Php CS Security Audit   | Security code Scan (.NET)   | TSLint Security    | Sobelow            |
+| --------------------------------------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :---------------------: | :-------------------------: | :-------------:    | :----------------: |
+| Severity                                | ✓   | ✓   | 𐄂                  | 𐄂                  | ✓   | 𐄂                  | ✓   | 𐄂                  | ✓      | 𐄂                         | ✓ | 𐄂                |
+| Title                                   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓      | ✓          | ✓ | ✓ |
+| Description                             | ✓   | 𐄂                  | 𐄂                  | ✓   | ✓   | 𐄂                  | 𐄂                  | ✓   | 𐄂                     | 𐄂                         | ✓ | ✓ |
+| File                                    | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓      | ✓          | ✓ | ✓ |
+| Start line                              | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓      | ✓          | ✓ | ✓ |
+| End line                                | ✓   | ✓   | 𐄂                  | ✓   | ✓   | 𐄂                  | 𐄂                  | 𐄂                  | 𐄂                     | 𐄂                         | ✓ | 𐄂                |
+| Start column                            | ✓   | 𐄂                  | 𐄂                  | ✓   | ✓   | ✓   | ✓   | 𐄂                  | ✓      | ✓          | ✓ | 𐄂                |
+| End column                              | ✓   | 𐄂                  | 𐄂                  | ✓   | ✓   | 𐄂                  | 𐄂                  | 𐄂                  | 𐄂                     | 𐄂                         | ✓ | 𐄂                |
+| External id (e.g. CVE)                  | 𐄂   | 𐄂                  | ⚠            | 𐄂                  | ⚠            | ✓   | 𐄂                  | 𐄂                  | 𐄂                     | 𐄂                         | 𐄂                | 𐄂                |
+| URLs                                    | ✓   | 𐄂                  | ✓   | 𐄂                  | ⚠            | 𐄂                  | 𐄂                  | 𐄂                  | 𐄂                     | 𐄂                         | 𐄂                | 𐄂                |
+| Internal doc/explanation                | ✓   | ⚠            | ✓   | 𐄂                  | ✓   | 𐄂                  | 𐄂                  | 𐄂                  | 𐄂                     | 𐄂                         | 𐄂                | ✓ |
+| Solution                                | ✓   | 𐄂                  | 𐄂                  | 𐄂                  | ⚠            | ✓   | 𐄂                  | 𐄂                  | 𐄂                     | 𐄂                         | 𐄂                | 𐄂                |
+| Confidence                              | 𐄂   | ✓   | ✓   | 𐄂                  | ✓   | ✓   | ✓   | 𐄂                  | 𐄂                     | 𐄂                         | 𐄂                | ✓ |
+| Affected item (e.g. class or package)   | ✓   | 𐄂                  | ✓   | 𐄂                  | ✓   | ✓   | 𐄂                  | 𐄂                  | 𐄂                     | 𐄂                         | 𐄂                | 𐄂                |
+| Source code extract                     | 𐄂   | ✓   | ✓   | ✓   | 𐄂                  | ✓   | ✓   | 𐄂                  | 𐄂                     | 𐄂                         | 𐄂                | 𐄂                |
+| Internal ID                             | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | 𐄂                  | ✓      | ✓          | ✓ | ✓ |
+
+- ✓ => we have that data
+- ⚠ => we have that data but it's partially reliable, or we need to extract it from unstructured content
+- 𐄂 => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it.
+
+The values provided by these tools are heterogeneous so they are sometimes
+normalized into common values (e.g., `severity`, `confidence`, etc).
diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md
index 11361f8ad89..2f15d997b5b 100644
--- a/doc/user/application_security/sast/index.md
+++ b/doc/user/application_security/sast/index.md
@@ -1,4 +1,8 @@
-# Static Application Security Testing (SAST) **[ULTIMATE]**
+---
+type: reference, howto
+---
+
+# Static Application Security Testing (SAST) **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3775)
 in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3.
@@ -13,7 +17,7 @@ to learn how to protect your organization.
 If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known
 vulnerabilities using Static Application Security Testing (SAST).
 
-You can take advantage of SAST by either [including the CI job](#configuring-sast) in
+You can take advantage of SAST by either [including the CI job](#configuration) in
 your existing `.gitlab-ci.yml` file or by implicitly using
 [Auto SAST](../../../topics/autodevops/index.md#auto-sast-ultimate)
 that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
@@ -55,6 +59,7 @@ The following table shows which languages, package managers and frameworks are s
 |-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------|------------------------------|
 | .NET                                                                        | [Security Code Scan](https://security-code-scan.github.io)                             | 11.0                         |
 | Any                                                                         | [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) | 11.9 |
+| Apex (Salesforce)                                                           | [pmd](https://pmd.github.io/pmd/index.html)                                            | 12.1                         |
 | C/C++                                                                       | [Flawfinder](https://www.dwheeler.com/flawfinder/)                                     | 10.7                         |
 | Elixir (Phoenix)                                                            | [Sobelow](https://github.com/nccgroup/sobelow)                                         | 11.10                        |
 | Go                                                                          | [Gosec](https://github.com/securego/gosec)                                             | 10.7                         |
@@ -73,30 +78,16 @@ The Java analyzers can also be used for variants like the
 [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html),
 [Grails](https://grails.org/) and the [Maven wrapper](https://github.com/takari/maven-wrapper).
 
-## Configuring SAST
-
-To enable SAST in your project, define a job in your `.gitlab-ci.yml` file that generates the
-[SAST report artifact](../../../ci/yaml/README.md#artifactsreportssast-ultimate).
-
-This can be done in two ways:
-
-- For GitLab 11.9 and later, including the provided `SAST.gitlab-ci.yml` template (recommended).
-- Manually specifying the job definition. Not recommended unless using GitLab
-  11.8 and earlier.
-
-### Including the provided template
-
-NOTE: **Note:**
-The CI/CD SAST template is supported on GitLab 11.9 and later versions.
-For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later).
+## Configuration
 
-A CI/CD [SAST template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml)
-with the default SAST job definition is provided as a part of your GitLab
-installation which you can [include](../../../ci/yaml/README.md#includetemplate)
-in your `.gitlab-ci.yml` file.
+For GitLab 11.9 and later, to enable SAST, you must
+[include](../../../ci/yaml/README.md#includetemplate) the
+[`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml)
+that's provided as a part of your GitLab installation.
+For GitLab versions earlier than 11.9, you can copy and use the job as defined
+that template.
 
-To enable SAST using the provided template, add the following to your `.gitlab-ci.yml`
-file:
+Add the following to your `.gitlab-ci.yml` file:
 
 ```yaml
 include:
@@ -106,14 +97,14 @@ include:
 The included template will create a `sast` job in your CI/CD pipeline and scan
 your project's source code for possible vulnerabilities.
 
-The report will be saved as a
+The results will be saved as a
 [SAST report artifact](../../../ci/yaml/README.md#artifactsreportssast-ultimate)
 that you can later download and analyze. Due to implementation limitations, we
 always take the latest SAST artifact available. Behind the scenes, the
 [GitLab SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast)
 is used to detect the languages/frameworks and in turn runs the matching scan tools.
 
-#### Customizing the SAST settings
+### Customizing the SAST settings
 
 The SAST settings can be changed through environment variables by using the
 [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
@@ -134,7 +125,7 @@ variables:
 Because the template is [evaluated before](../../../ci/yaml/README.md#include)
 the pipeline configuration, the last mention of the variable will take precedence.
 
-#### Overriding the SAST template
+### Overriding the SAST template
 
 If you want to override the job definition (for example, change properties like
 `variables` or `dependencies`), you need to declare a `sast` job after the
@@ -149,84 +140,64 @@ sast:
     CI_DEBUG_TRACE: "true"
 ```
 
-### Manual job definition for GitLab 11.5 and later
+### Available variables
 
-For GitLab 11.5 and GitLab Runner 11.5 and later, the following `sast`
-job can be added:
+SAST can be [configured](#customizing-the-sast-settings) using environment variables.
 
-```yaml
-sast:
-  stage: test
-  image: docker:stable
-  variables:
-    DOCKER_DRIVER: overlay2
-  allow_failure: true
-  services:
-    - docker:stable-dind
-  script:
-    - export SAST_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')}
-    - |
-      docker run \
-        --env SAST_ANALYZER_IMAGES \
-        --env SAST_ANALYZER_IMAGE_PREFIX \
-        --env SAST_ANALYZER_IMAGE_TAG \
-        --env SAST_DEFAULT_ANALYZERS \
-        --env SAST_EXCLUDED_PATHS \
-        --env SAST_BANDIT_EXCLUDED_PATHS \
-        --env SAST_BRAKEMAN_LEVEL \
-        --env SAST_GOSEC_LEVEL \
-        --env SAST_FLAWFINDER_LEVEL \
-        --env SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \
-        --env SAST_PULL_ANALYZER_IMAGE_TIMEOUT \
-        --env SAST_RUN_ANALYZER_TIMEOUT \
-        --volume "$PWD:/code" \
-        --volume /var/run/docker.sock:/var/run/docker.sock \
-        "registry.gitlab.com/gitlab-org/security-products/sast:$SAST_VERSION" /app/bin/run /code
-  dependencies: []
-  artifacts:
-    reports:
-      sast: gl-sast-report.json
-```
+#### Docker images
 
-You can supply many other [settings variables](https://gitlab.com/gitlab-org/security-products/sast#settings)
-via `docker run --env` to customize your job execution.
+The following are Docker image-related variables.
 
-### Manual job definition for GitLab 11.4 and earlier (deprecated)
+| Environment variable          | Description                                                                    |
+|-------------------------------|--------------------------------------------------------------------------------|
+| `SAST_ANALYZER_IMAGES`        | Comma separated list of custom images. Default images are still enabled. Read more about [customizing analyzers](analyzers.md).       |
+| `SAST_ANALYZER_IMAGE_PREFIX`  | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). |
+| `SAST_ANALYZER_IMAGE_TAG`     | Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md).                                 |
+| `SAST_DEFAULT_ANALYZERS`      | Override the names of default images. Read more about [customizing analyzers](analyzers.md).                                          |
+| `SAST_PULL_ANALYZER_IMAGES`   | Pull the images from the Docker registry (set to 0 to disable). Read more about [customizing analyzers](analyzers.md).                 |
 
-CAUTION: **Deprecated:**
-Before GitLab 11.5, the SAST job and artifact had to be named specifically
-to automatically extract report data and show it in the merge request widget.
-While these old job definitions are still maintained, they have been deprecated
-and may be removed in the next major release, GitLab 12.0. You are strongly
-advised to update your current `.gitlab-ci.yml` configuration to reflect that change.
+### Vulnerability filters
 
-For GitLab 11.4 and earlier, the SAST job should look like:
+Some analyzers make it possible to filter out vulnerabilities under a given threshold.
 
-```yaml
-sast:
-  image: docker:stable
-  variables:
-    DOCKER_DRIVER: overlay2
-  allow_failure: true
-  services:
-    - docker:stable-dind
-  script:
-    - export SAST_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')}
-    - docker run
-        --env SAST_CONFIDENCE_LEVEL="${SAST_CONFIDENCE_LEVEL:-3}"
-        --volume "$PWD:/code"
-        --volume /var/run/docker.sock:/var/run/docker.sock
-        "registry.gitlab.com/gitlab-org/security-products/sast:$SAST_VERSION" /app/bin/run /code
-  artifacts:
-    paths: [gl-sast-report.json]
-```
+| `SAST_BANDIT_EXCLUDED_PATHS`  | -   | comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html) |
+| `SAST_BRAKEMAN_LEVEL`   |         1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. |
+| `SAST_FLAWFINDER_LEVEL` |         1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. |
+| `SAST_GITLEAKS_ENTROPY_LEVEL` | 8.0 | Minimum entropy for secret detection. Float, 0.0 = low, 8.0 = high. |
+| `SAST_GOSEC_LEVEL`      |         0 | Ignore gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. |
+| `SAST_EXCLUDED_PATHS`   |   -        | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, file or folder paths. Parent directories will also match patterns. |
+
+### Timeouts
+
+The following variables configure timeouts.
+
+| `SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` |      2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m". |
+| `SAST_PULL_ANALYZER_IMAGE_TIMEOUT`       |      5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m". |
+| `SAST_RUN_ANALYZER_TIMEOUT`              |     20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m".|
+
+### Analyzer settings
+
+Some analyzers can be customized with environment variables.
+
+| Environment variable    | Analyzer | Description |
+|-------------------------|----------|----------|
+| `ANT_HOME`              | spotbugs | The `ANT_HOME` environment variable. |
+| `ANT_PATH`              | spotbugs | Path to the `ant` executable. |
+| `GRADLE_PATH`           | spotbugs | Path to the `gradle` executable. |
+| `JAVA_OPTS`             | spotbugs | Additional arguments for the `java` executable. |
+| `JAVA_PATH`             | spotbugs | Path to the `java` executable. |
+| `MAVEN_CLI_OPTS`        | spotbugs | Additional arguments for the `mvn` or `mvnw` executable. |
+| `MAVEN_PATH`            | spotbugs | Path to the `mvn` executable. |
+| `MAVEN_REPO_PATH`       | spotbugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). |
+| `SBT_PATH`              | spotbugs | Path to the `sbt` executable. |
+| `FAIL_NEVER`            | spotbugs | Set to `1` to ignore compilation failure. |
 
 ## Reports JSON format
 
 CAUTION: **Caution:**
 The JSON report artifacts are not a public API of SAST and their format may change in the future.
 
-The SAST tool emits a JSON report report file. Here is an example of a structure for a report will all important parts of
+The SAST tool emits a JSON report report file. Here is an example of the report structure with all important parts of
 it highlighted:
 
 ```json-doc
@@ -269,10 +240,9 @@ it highlighted:
           "url": "https://cwe.mitre.org/data/definitions/330.html"
         }
       ]
-    },   
+    },
     {
       "category": "sast",
-      // "name" may be omitted because it could be not reported by a particular analyzer
       "message": "Probable insecure usage of temp file/directory.",
       "cve": "python/hardcoded/hardcoded-tmp.py:4ad6d4c40a8c263fc265f3384724014e0a4f8dd6200af83e51ff120420038031:B108",
       "severity": "Medium",
@@ -297,7 +267,7 @@ it highlighted:
           "url": "https://docs.openstack.org/bandit/latest/plugins/b108_hardcoded_tmp_directory.html"
         }
       ]
-    },    
+    },
   ],
   "remediations": []
 }
@@ -318,10 +288,10 @@ the report JSON unless stated otherwise. Presence of optional fields depends on
 | `vulnerabilities[].severity`            | How much the vulnerability impacts the software. Possible values: `Undefined` (an analyzer has not provided this info), `Info`, `Unknown`, `Low`, `Medium`, `High`, `Critical`. |
 | `vulnerabilities[].confidence`          | How reliable the vulnerability's assessment is. Possible values: `Undefined` (an analyzer has not provided this info), `Ignore`, `Unknown`, `Experimental`, `Low`, `Medium`, `High`, `Confirmed`. |
 | `vulnerabilities[].solution`            | Explanation of how to fix the vulnerability. Optional. |
-| `vulnerabilities[].scanner`             | A node that describes the analyzer used find this vulnerability. |
+| `vulnerabilities[].scanner`             | A node that describes the analyzer used to find this vulnerability. |
 | `vulnerabilities[].scanner.id`          | Id of the scanner as a snake_case string. |
 | `vulnerabilities[].scanner.name`        | Name of the scanner, for display purposes. |
-| `vulnerabilities[].location`            | A node that tells which class and/or method is affected by the vulnerability. | 
+| `vulnerabilities[].location`            | A node that tells where the vulnerability is located. |
 | `vulnerabilities[].location.file`       | Path to the file where the vulnerability is located. Optional. |
 | `vulnerabilities[].location.start_line` | The first line of the code affected by the vulnerability. Optional. |
 | `vulnerabilities[].location.end_line`   | The last line of the code affected by the vulnerability. Optional. |
@@ -331,7 +301,7 @@ the report JSON unless stated otherwise. Presence of optional fields depends on
 | `vulnerabilities[].identifiers[].type`  | Type of the identifier. Possible values: common identifier types (among `cve`, `cwe`, `osvdb`, and `usn`) or analyzer-dependent ones (e.g., `bandit_test_id` for [Bandit analyzer](https://wiki.openstack.org/wiki/Security/Projects/Bandit)). |
 | `vulnerabilities[].identifiers[].name`  | Name of the identifier for display purposes. |
 | `vulnerabilities[].identifiers[].value` | Value of the identifier for matching purposes. |
-| `vulnerabilities[].identifiers[].url`   | URL to identifier's documentation. Optional. | 
+| `vulnerabilities[].identifiers[].url`   | URL to identifier's documentation. Optional. |
 
 ## Secret detection
 
@@ -364,3 +334,20 @@ vulnerabilities in your groups and projects. Read more about the
 
 Once a vulnerability is found, you can interact with it. Read more on how to
 [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities).
+
+## Vulnerabilities database update
+
+For more information about the vulnerabilities database update, check the
+[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database).
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/application_security/security_dashboard/img/dashboard.png b/doc/user/application_security/security_dashboard/img/dashboard.png
deleted file mode 100644
index a75168b1ce4..00000000000
--- a/doc/user/application_security/security_dashboard/img/dashboard.png
+++ /dev/null
diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard.png
new file mode 100644
index 00000000000..85ab124f74c
--- /dev/null
+++ b/doc/user/application_security/security_dashboard/img/group_security_dashboard.png
diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard.png
index f0dad6c54d0..baa136fd885 100644
--- a/doc/user/application_security/security_dashboard/img/project_security_dashboard.png
+++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard.png
diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md
index 19eeb06a259..ac8c1ac0354 100644
--- a/doc/user/application_security/security_dashboard/index.md
+++ b/doc/user/application_security/security_dashboard/index.md
@@ -1,4 +1,8 @@
-# GitLab Security Dashboard **[ULTIMATE]**
+---
+type: reference, howto
+---
+
+# GitLab Security Dashboard **(ULTIMATE)**
 
 The Security Dashboard is a good place to get an overview of all the security
 vulnerabilities in your groups and projects.
@@ -16,9 +20,9 @@ To benefit from the Security Dashboard you must first configure one of the
 The Security Dashboard supports the following reports:
 
 - [Container Scanning](../container_scanning/index.md)
-- [DAST](../dast/index.md)
+- [Dynamic Application Security Testing](../dast/index.md)
 - [Dependency Scanning](../dependency_scanning/index.md)
-- [SAST](../sast/index.md)
+- [Static Application Security Testing](../sast/index.md)
 
 ## Requirements
 
@@ -26,8 +30,8 @@ To use the project or group security dashboard:
 
 1. At least one project inside a group must be configured with at least one of
    the [supported reports](#supported-reports).
-2. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/README.md#artifactsreports).
-3. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used.
+1. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/README.md#artifactsreports).
+1. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used.
    If you're using the shared Runners on GitLab.com, this is already the case.
 
 ## Project Security Dashboard
@@ -43,13 +47,13 @@ for your project. Use it to find and fix vulnerabilities affecting the
 ## Group Security Dashboard
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6709) in
-  [GitLab Ultimate](https://about.gitlab.com/pricing) 11.5.
+> [GitLab Ultimate](https://about.gitlab.com/pricing) 11.5.
 
 The group Security Dashboard gives an overview of the vulnerabilities of all the
 projects in a group and its subgroups.
 
 First, navigate to the Security Dashboard found under your group's
-**Overview > Security Dashboard**.
+**Security** tab.
 
 Once you're on the dashboard, at the top you should see a series of filters for:
 
@@ -58,7 +62,7 @@ Once you're on the dashboard, at the top you should see a series of filters for:
 - Report type
 - Project
 
-![dashboard with action buttons and metrics](img/dashboard.png)
+![dashboard with action buttons and metrics](img/group_security_dashboard.png)
 
 Selecting one or more filters will filter the results in this page.
 The first section is an overview of all the vulnerabilities, grouped by severity.
@@ -102,3 +106,15 @@ That way, reports are created even if no code change happens.
 When using [Auto DevOps](../../../topics/autodevops/index.md), use
 [special environment variables](../../../topics/autodevops/index.md#environment-variables)
 to configure daily security scans.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md
new file mode 100644
index 00000000000..862316b57da
--- /dev/null
+++ b/doc/user/asciidoc.md
@@ -0,0 +1,375 @@
+# AsciiDoc
+
+GitLab uses the [Asciidoctor](https://asciidoctor.org) gem to convert AsciiDoc content to HTML5.
+Consult the [Asciidoctor User Manual](https://asciidoctor.org/docs/user-manual/) for a complete Asciidoctor reference.
+
+## Syntax
+
+Here's a brief reference of the most commonly used AsciiDoc syntax.
+You can find the full documentation for the AsciiDoc syntax at <https://asciidoctor.org/docs>.
+
+### Paragraphs
+
+```asciidoc
+A normal paragraph.
+Line breaks are not preserved.
+```
+
+Line comments, which are lines that start with `//`, are skipped:
+
+```
+// this is a comment
+```
+
+A blank line separates paragraphs.
+
+A paragraph with the `[%hardbreaks]` option will preserve line breaks:
+
+```asciidoc
+[%hardbreaks]
+This paragraph carries the `hardbreaks` option.
+Notice how line breaks are now preserved.
+```
+
+An indented (literal) paragraph disables text formatting,
+preserves spaces and line breaks, and is displayed in a
+monospaced font:
+
+```asciidoc
+ This literal paragraph is indented with one space.
+ As a consequence, *text formatting*, spaces,
+ and lines breaks will be preserved.
+```
+
+An admonition paragraph grabs the reader's attention:
+
+```asciidoc
+NOTE: This is a brief reference, please read the full documentation at https://asciidoctor.org/docs.
+
+TIP: Lists can be indented. Leading whitespace is not significant.
+```
+
+### Text Formatting
+
+**Constrained (applied at word boundaries)**
+
+```asciidoc
+*strong importance* (aka bold)
+_stress emphasis_ (aka italic)
+`monospaced` (aka typewriter text)
+"`double`" and '`single`' typographic quotes
++passthrough text+ (substitutions disabled)
+`+literal text+` (monospaced with substitutions disabled)
+```
+
+**Unconstrained (applied anywhere)**
+
+```asciidoc
+**C**reate+**R**ead+**U**pdate+**D**elete
+fan__freakin__tastic
+``mono``culture
+```
+
+**Replacements**
+
+```asciidoc
+A long time ago in a galaxy far, far away...
+(C) 1976 Arty Artisan
+I believe I shall--no, actually I won't.
+```
+
+**Macros**
+
+```asciidoc
+// where c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements, etc.
+The European icon:flag[role=blue] is blue & contains pass:[************] arranged in a icon:circle-o[role=yellow].
+The pass:c[->] operator is often referred to as the stabby lambda.
+Since `pass:[++]` has strong priority in AsciiDoc, you can rewrite pass:c,a,r[C++ => C{pp}].
+// activate stem support by adding `:stem:` to the document header
+stem:[sqrt(4) = 2]
+```
+
+### Attributes
+
+```asciidoc
+// define attributes in the document header
+:name: value
+```
+
+```asciidoc
+:url-gem: https://rubygems.org/gems/asciidoctor
+
+You can download and install Asciidoctor {asciidoctor-version} from {url-gem}.
+C{pp} is not required, only Ruby.
+Use a leading backslash to output a word enclosed in curly braces, like \{name}.
+```
+
+### Links
+
+```asciidoc
+https://example.org/page[A webpage]
+link:../path/to/file.txt[A local file]
+xref:document.adoc[A sibling document]
+mailto:hello@example.org[Email to say hello!]
+```
+
+### Anchors
+
+```asciidoc
+[[idname,reference text]]
+// or written using normal block attributes as `[#idname,reftext=reference text]`
+A paragraph (or any block) with an anchor (aka ID) and reftext.
+
+See <<idname>> or <<idname,optional text of internal link>>.
+
+xref:document.adoc#idname[Jumps to anchor in another document].
+
+This paragraph has a footnote.footnote:[This is the text of the footnote.]
+```
+
+### Lists
+
+#### Unordered
+
+```asciidoc
+* level 1
+** level 2
+*** level 3
+**** level 4
+***** etc.
+* back at level 1
++
+Attach a block or paragraph to a list item using a list continuation (which you can enclose in an open block).
+
+.Some Authors
+[circle]
+- Edgar Allen Poe
+- Sheri S. Tepper
+- Bill Bryson
+```
+
+#### Ordered
+
+```asciidoc
+. Step 1
+. Step 2
+.. Step 2a
+.. Step 2b
+. Step 3
+
+.Remember your Roman numerals?
+[upperroman]
+. is one
+. is two
+. is three
+```
+
+#### Checklist
+
+```asciidoc
+* [x] checked
+* [ ] not checked
+```
+
+#### Callout
+
+```asciidoc
+// enable callout bubbles by adding `:icons: font` to the document header
+[,ruby]
+----
+puts 'Hello, World!' # <1>
+----
+<1> Prints `Hello, World!` to the console.
+```
+
+#### Description
+
+```asciidoc
+first term:: description of first term
+second term::
+description of second term
+```
+
+### Document Structure
+
+#### Header
+
+```asciidoc
+= Document Title
+Author Name <author@example.org>
+v1.0, 2019-01-01
+```
+
+#### Sections
+
+```asciidoc
+= Document Title (Level 0)
+== Level 1
+=== Level 2
+==== Level 3
+===== Level 4
+====== Level 5
+== Back at Level 1
+```
+
+#### Includes
+
+```asciidoc
+include::basics.adoc[]
+
+// define -a allow-uri-read to allow content to be read from URI
+include::https://example.org/installation.adoc[]
+```
+
+### Blocks
+
+```asciidoc
+--
+open - a general-purpose content wrapper; useful for enclosing content to attach to a list item
+--
+```
+
+```asciidoc
+// recognized types include CAUTION, IMPORTANT, NOTE, TIP, and WARNING
+// enable admonition icons by setting `:icons: font` in the document header
+[NOTE]
+====
+admonition - a notice for the reader, ranging in severity from a tip to an alert
+====
+```
+
+```asciidoc
+====
+example - a demonstration of the concept being documented
+====
+```
+
+```asciidoc
+.Toggle Me
+[%collapsible]
+====
+collapsible - these details are revealed by clicking the title
+====
+```
+
+```asciidoc
+****
+sidebar - auxiliary content that can be read independently of the main content
+****
+```
+
+```asciidoc
+....
+literal - an exhibit that features program output
+....
+```
+
+```asciidoc
+----
+listing - an exhibit that features program input, source code, or the contents of a file
+----
+```
+
+```asciidoc
+[,language]
+----
+source - a listing that is embellished with (colorized) syntax highlighting
+----
+```
+
+~~~asciidoc
+\```language
+fenced code - a shorthand syntax for the source block
+\```
+~~~
+
+```asciidoc
+[,attribution,citetitle]
+____
+quote - a quotation or excerpt; attribution with title of source are optional
+____
+```
+
+```asciidoc
+[verse,attribution,citetitle]
+____
+verse - a literary excerpt, often a poem; attribution with title of source are optional
+____
+```
+
+```asciidoc
+++++
+pass - content passed directly to the output document; often raw HTML
+++++
+```
+
+```asciidoc
+// activate stem support by adding `:stem:` to the document header
+[stem]
+++++
+x = y^2
+++++
+```
+
+```asciidoc
+////
+comment - content which is not included in the output document
+////
+```
+
+### Tables
+
+```asciidoc
+.Table Attributes
+[cols=>1h;2d,width=50%,frame=topbot]
+|===
+| Attribute Name | Values
+
+| options
+| header,footer,autowidth
+
+| cols
+| colspec[;colspec;...]
+
+| grid
+| all \| cols \| rows \| none
+
+| frame
+| all \| sides \| topbot \| none
+
+| stripes
+| all \| even \| odd \| none
+
+| width
+| (0%..100%)
+
+| format
+| psv {vbar} csv {vbar} dsv
+|===
+```
+
+### Multimedia
+
+```asciidoc
+image::screenshot.png[block image,800,450]
+
+Press image:reload.svg[reload,16,opts=interactive] to reload the page.
+
+video::movie.mp4[width=640,start=60,end=140,options=autoplay]
+
+video::aHjpOzsQ9YI[youtube]
+
+video::300817511[vimeo]
+```
+
+### Breaks
+
+```asciidoc
+// thematic break (aka horizontal rule)
+---
+```
+
+```asciidoc
+// page break
+<<<
+```
diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md
index e4fd08a582c..1b1d126b726 100644
--- a/doc/user/award_emojis.md
+++ b/doc/user/award_emojis.md
@@ -7,7 +7,7 @@
 
 When you're collaborating online, you get fewer opportunities for high-fives
 and thumbs-ups. Emoji can be awarded to [issues](project/issues/index.md), [merge requests](project/merge_requests/index.md),
-[snippets](snippets.md), and anywhere you can have a discussion.
+[snippets](snippets.md), and anywhere you can have a thread.
 
 ![Award emoji](img/award_emoji_select.png)
 
diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md
index b520c4fb579..096730f800c 100644
--- a/doc/user/clusters/applications.md
+++ b/doc/user/clusters/applications.md
@@ -1,15 +1,18 @@
 # GitLab Managed Apps
 
 GitLab provides **GitLab Managed Apps**, a one-click install for various applications which can
-be added directly to your configured cluster. These applications are
-needed for [Review Apps](../../ci/review_apps/index.md) and
-[deployments](../../ci/environments.md) when using [Auto DevOps](../../topics/autodevops/index.md).
+be added directly to your configured cluster.
+
+These applications are needed for [Review Apps](../../ci/review_apps/index.md)
+and [deployments](../../ci/environments.md) when using [Auto DevOps](../../topics/autodevops/index.md).
+
 You can install them after you
-[create a cluster](../project/clusters/index.md#adding-and-creating-a-new-gke-cluster-via-gitlab).
+[create a cluster](../project/clusters/index.md#adding-and-removing-clusters).
 
 ## Installing applications
 
 Applications managed by GitLab will be installed onto the `gitlab-managed-apps` namespace.
+
 This namespace:
 
 - Is different from the namespace used for project deployments.
@@ -19,8 +22,10 @@ This namespace:
 To see a list of available applications to install:
 
 1. For a:
-    - Project-level cluster, navigate to your project's **Operations > Kubernetes**.
-    - Group-level cluster, navigate to your group's **Kubernetes** page.
+   - [Project-level cluster](../project/clusters/index.md),
+     navigate to your project's **Operations > Kubernetes**.
+   - [Group-level cluster](../group/clusters/index.md),
+     navigate to your group's **Kubernetes** page.
 
 Install Helm first as it's used to install other applications.
 
@@ -94,7 +99,7 @@ CI/CD](../../ci/README.md), the open-source continuous integration
 service included with GitLab that coordinates the jobs. When installing
 the GitLab Runner via the applications, it will run in **privileged
 mode** by default. Make sure you read the [security
-implications](../project/clusters/index.md/#security-implications) before doing so.
+implications](../project/clusters/index.md#security-implications) before doing so.
 
 NOTE: **Note:**
 The
@@ -111,7 +116,7 @@ file.
 [Ingress](https://kubernetes.github.io/ingress-nginx/) can provide load
 balancing, SSL termination, and name-based virtual hosting. It acts as a
 web proxy for your applications and is useful if you want to use [Auto
-DevOps] or deploy your own web apps.
+DevOps](../../topics/autodevops/index.md) or deploy your own web apps.
 
 NOTE: **Note:**
 The
@@ -159,9 +164,9 @@ file.
 When installing JupyterHub onto your Kubernetes cluster, [JupyterLab's Git extension](https://github.com/jupyterlab/jupyterlab-git)
 is automatically provisioned and configured using the authenticated user's:
 
-- Name
-- Email
-- Newly created access token
+- Name.
+- Email.
+- Newly created access token.
 
 JupyterLab's Git extension enables full version control of your notebooks as well as issuance of Git commands within Jupyter.
 Git commands can be issued via the **Git** tab on the left panel or via Jupyter's command line prompt.
@@ -232,8 +237,10 @@ The applications below can be upgraded.
 To upgrade an application:
 
 1. For a:
-    - Project-level cluster, navigate to your project's **Operations > Kubernetes**.
-    - Group-level cluster, navigate to your group's **Kubernetes** page.
+   - [Project-level cluster](../project/clusters/index.md),
+     navigate to your project's **Operations > Kubernetes**.
+   - [Group-level cluster](../group/clusters/index.md),
+     navigate to your group's **Kubernetes** page.
 1. Select your cluster.
 1. If an upgrade is available, the **Upgrade** button is displayed. Click the button to upgrade.
 
@@ -251,13 +258,21 @@ The applications below can be uninstalled.
 
 | Application | GitLab version | Notes |
 | ----------- | -------------- | ----- |
+| Cert-Manager | 12.2+         | The associated private key will be deleted and cannot be restored. Deployed applications will continue to use HTTPS, but certificates will not be renewed. Before uninstalling, you may wish to [back up your configuration](https://docs.cert-manager.io/en/latest/tasks/backup-restore-crds.html) or [revoke your certificates](https://letsencrypt.org/docs/revoking/) |
+| GitLab Runner  | 12.2+         | Any running pipelines will be canceled. |
+| Helm  | 12.2+         | The associated Tiller pod will be deleted and cannot be restored. |
+| Ingress  | 12.1+         | The associated load balancer and IP will be deleted and cannot be restored. Furthermore, it can only be uninstalled if JupyterHub is not installed. |
+| JupyterHub  | 12.1+         | All data not committed to GitLab will be deleted and cannot be restored. |
+| Knative  | 12.1+         | The associated IP will be deleted and cannot be restored. |
 | Prometheus  | 11.11+         | All data will be deleted and cannot be restored. |
 
 To uninstall an application:
 
 1. For a:
-    - Project-level cluster, navigate to your project's **Operations > Kubernetes**.
-    - Group-level cluster, navigate to your group's **Kubernetes** page.
+   - [Project-level cluster](../project/clusters/index.md),
+     navigate to your project's **Operations > Kubernetes**.
+   - [Group-level cluster](../group/clusters/index.md),
+     navigate to your group's **Kubernetes** page.
 1. Select your cluster.
 1. Click the **Uninstall** button for the application.
 
@@ -287,4 +302,3 @@ To avoid installation errors:
   kubectl get secrets/tiller-secret -n gitlab-managed-apps -o "jsonpath={.data['ca\.crt']}" | base64 -d > b.pem
   diff a.pem b.pem
   ```
-
diff --git a/doc/user/clusters/img/jupyter-gitclone.png b/doc/user/clusters/img/jupyter-gitclone.png
index 41d467f806a..aff194dea43 100644
--- a/doc/user/clusters/img/jupyter-gitclone.png
+++ b/doc/user/clusters/img/jupyter-gitclone.png
diff --git a/doc/user/discussions/img/automatically_resolve_outdated_discussions.png b/doc/user/discussions/img/automatically_resolve_outdated_discussions.png
index ba129e7a618..a6fc4b0aef1 100644
--- a/doc/user/discussions/img/automatically_resolve_outdated_discussions.png
+++ b/doc/user/discussions/img/automatically_resolve_outdated_discussions.png
diff --git a/doc/user/discussions/img/btn_new_issue_for_all_discussions.png b/doc/user/discussions/img/btn_new_issue_for_all_discussions.png
deleted file mode 100644
index 3306bf2e60e..00000000000
--- a/doc/user/discussions/img/btn_new_issue_for_all_discussions.png
+++ /dev/null
diff --git a/doc/user/discussions/img/btn_new_issue_for_all_threads.png b/doc/user/discussions/img/btn_new_issue_for_all_threads.png
new file mode 100644
index 00000000000..5d86e0ca016
--- /dev/null
+++ b/doc/user/discussions/img/btn_new_issue_for_all_threads.png
diff --git a/doc/user/discussions/img/commit_comment_mr_context.png b/doc/user/discussions/img/commit_comment_mr_context.png
index b363e0035e8..68f58a57757 100644
--- a/doc/user/discussions/img/commit_comment_mr_context.png
+++ b/doc/user/discussions/img/commit_comment_mr_context.png
diff --git a/doc/user/discussions/img/commit_comment_mr_discussions_tab.png b/doc/user/discussions/img/commit_comment_mr_discussions_tab.png
index 2b06cdcc055..d88f08eae26 100644
--- a/doc/user/discussions/img/commit_comment_mr_discussions_tab.png
+++ b/doc/user/discussions/img/commit_comment_mr_discussions_tab.png
diff --git a/doc/user/discussions/img/discussion_comment.png b/doc/user/discussions/img/discussion_comment.png
index 206ddebf54b..3fec5962363 100644
--- a/doc/user/discussions/img/discussion_comment.png
+++ b/doc/user/discussions/img/discussion_comment.png
diff --git a/doc/user/discussions/img/discussion_view.png b/doc/user/discussions/img/discussion_view.png
deleted file mode 100644
index 3a2b766ed7e..00000000000
--- a/doc/user/discussions/img/discussion_view.png
+++ /dev/null
diff --git a/doc/user/discussions/img/image_resolved_discussion.png b/doc/user/discussions/img/image_resolved_discussion.png
index ed00b5c77fe..f6e5a3b66ae 100644
--- a/doc/user/discussions/img/image_resolved_discussion.png
+++ b/doc/user/discussions/img/image_resolved_discussion.png
diff --git a/doc/user/discussions/img/make_suggestion.png b/doc/user/discussions/img/make_suggestion.png
index 20acc1417da..a24e29770aa 100644
--- a/doc/user/discussions/img/make_suggestion.png
+++ b/doc/user/discussions/img/make_suggestion.png
diff --git a/doc/user/discussions/img/merge_request_commits_tab.png b/doc/user/discussions/img/merge_request_commits_tab.png
index 41a3648f390..267f3a720dc 100644
--- a/doc/user/discussions/img/merge_request_commits_tab.png
+++ b/doc/user/discussions/img/merge_request_commits_tab.png
diff --git a/doc/user/discussions/img/mr_review_resolve.png b/doc/user/discussions/img/mr_review_resolve.png
index 34176f3fa8e..ced33682459 100644
--- a/doc/user/discussions/img/mr_review_resolve.png
+++ b/doc/user/discussions/img/mr_review_resolve.png
diff --git a/doc/user/discussions/img/mr_review_resolve2.png b/doc/user/discussions/img/mr_review_resolve2.png
index e4adb5f2c2d..2f0be3b6d06 100644
--- a/doc/user/discussions/img/mr_review_resolve2.png
+++ b/doc/user/discussions/img/mr_review_resolve2.png
diff --git a/doc/user/discussions/img/mr_review_second_comment.png b/doc/user/discussions/img/mr_review_second_comment.png
index 920ea05ad66..f345c52e941 100644
--- a/doc/user/discussions/img/mr_review_second_comment.png
+++ b/doc/user/discussions/img/mr_review_second_comment.png
diff --git a/doc/user/discussions/img/mr_review_second_comment_added.png b/doc/user/discussions/img/mr_review_second_comment_added.png
index 1fb54348547..61b45431c9e 100644
--- a/doc/user/discussions/img/mr_review_second_comment_added.png
+++ b/doc/user/discussions/img/mr_review_second_comment_added.png
diff --git a/doc/user/discussions/img/mr_review_start.png b/doc/user/discussions/img/mr_review_start.png
index 38b44bda0d2..08b4c6bb82b 100644
--- a/doc/user/discussions/img/mr_review_start.png
+++ b/doc/user/discussions/img/mr_review_start.png
diff --git a/doc/user/discussions/img/mr_review_unresolve.png b/doc/user/discussions/img/mr_review_unresolve.png
index da895ceb89f..4bef38f7808 100644
--- a/doc/user/discussions/img/mr_review_unresolve.png
+++ b/doc/user/discussions/img/mr_review_unresolve.png
diff --git a/doc/user/discussions/img/mr_review_unresolve2.png b/doc/user/discussions/img/mr_review_unresolve2.png
index a824b806e4a..79da61bb556 100644
--- a/doc/user/discussions/img/mr_review_unresolve2.png
+++ b/doc/user/discussions/img/mr_review_unresolve2.png
diff --git a/doc/user/discussions/img/multi-line-suggestion-preview.png b/doc/user/discussions/img/multi-line-suggestion-preview.png
index 4288d0ba034..476c50b9098 100644
--- a/doc/user/discussions/img/multi-line-suggestion-preview.png
+++ b/doc/user/discussions/img/multi-line-suggestion-preview.png
diff --git a/doc/user/discussions/img/multi-line-suggestion-syntax.png b/doc/user/discussions/img/multi-line-suggestion-syntax.png
index df0c99b84ef..80424d1f056 100644
--- a/doc/user/discussions/img/multi-line-suggestion-syntax.png
+++ b/doc/user/discussions/img/multi-line-suggestion-syntax.png
diff --git a/doc/user/discussions/img/new_issue_for_thread.png b/doc/user/discussions/img/new_issue_for_thread.png
new file mode 100644
index 00000000000..28b76adf7fe
--- /dev/null
+++ b/doc/user/discussions/img/new_issue_for_thread.png
diff --git a/doc/user/discussions/img/onion_skin_view.png b/doc/user/discussions/img/onion_skin_view.png
index 91c3b396844..81bb4a2c85a 100644
--- a/doc/user/discussions/img/onion_skin_view.png
+++ b/doc/user/discussions/img/onion_skin_view.png
diff --git a/doc/user/discussions/img/only_allow_merge_if_all_threads_are_resolved.png b/doc/user/discussions/img/only_allow_merge_if_all_threads_are_resolved.png
new file mode 100644
index 00000000000..bd0aaca79b2
--- /dev/null
+++ b/doc/user/discussions/img/only_allow_merge_if_all_threads_are_resolved.png
diff --git a/doc/user/discussions/img/pending_review_comment.png b/doc/user/discussions/img/pending_review_comment.png
index 916ef5b7452..70a66b3f4f0 100644
--- a/doc/user/discussions/img/pending_review_comment.png
+++ b/doc/user/discussions/img/pending_review_comment.png
diff --git a/doc/user/discussions/img/preview_issue_for_thread.png b/doc/user/discussions/img/preview_issue_for_thread.png
new file mode 100644
index 00000000000..a9d7ab598be
--- /dev/null
+++ b/doc/user/discussions/img/preview_issue_for_thread.png
diff --git a/doc/user/discussions/img/preview_issue_for_threads.png b/doc/user/discussions/img/preview_issue_for_threads.png
new file mode 100644
index 00000000000..8757decb178
--- /dev/null
+++ b/doc/user/discussions/img/preview_issue_for_threads.png
diff --git a/doc/user/discussions/img/reply_to_comment_button.png b/doc/user/discussions/img/reply_to_comment_button.png
index d362b19785c..d327d1c3e27 100644
--- a/doc/user/discussions/img/reply_to_comment_button.png
+++ b/doc/user/discussions/img/reply_to_comment_button.png
diff --git a/doc/user/discussions/img/resolve_comment_button.png b/doc/user/discussions/img/resolve_comment_button.png
index 7c19fac31a2..0a3ed03a69c 100644
--- a/doc/user/discussions/img/resolve_comment_button.png
+++ b/doc/user/discussions/img/resolve_comment_button.png
diff --git a/doc/user/discussions/img/resolve_thread_button.png b/doc/user/discussions/img/resolve_thread_button.png
new file mode 100644
index 00000000000..ca0a3e50550
--- /dev/null
+++ b/doc/user/discussions/img/resolve_thread_button.png
diff --git a/doc/user/discussions/img/resolve_thread_issue_notice.png b/doc/user/discussions/img/resolve_thread_issue_notice.png
new file mode 100644
index 00000000000..30a65b8fbd4
--- /dev/null
+++ b/doc/user/discussions/img/resolve_thread_issue_notice.png
diff --git a/doc/user/discussions/img/resolve_thread_open_issue.png b/doc/user/discussions/img/resolve_thread_open_issue.png
new file mode 100644
index 00000000000..2dd4ea3cb1b
--- /dev/null
+++ b/doc/user/discussions/img/resolve_thread_open_issue.png
diff --git a/doc/user/discussions/img/review_comment_quickactions.png b/doc/user/discussions/img/review_comment_quickactions.png
index bd9880c329a..276def6381f 100644
--- a/doc/user/discussions/img/review_comment_quickactions.png
+++ b/doc/user/discussions/img/review_comment_quickactions.png
diff --git a/doc/user/discussions/img/review_preview.png b/doc/user/discussions/img/review_preview.png
index 4bf53a81b9c..e69a58dbb91 100644
--- a/doc/user/discussions/img/review_preview.png
+++ b/doc/user/discussions/img/review_preview.png
diff --git a/doc/user/discussions/img/suggestion.png b/doc/user/discussions/img/suggestion.png
index 68a67e6ae5e..f7962305a15 100644
--- a/doc/user/discussions/img/suggestion.png
+++ b/doc/user/discussions/img/suggestion.png
diff --git a/doc/user/discussions/img/swipe_view.png b/doc/user/discussions/img/swipe_view.png
index 82d6e52173c..e6f5e5053af 100644
--- a/doc/user/discussions/img/swipe_view.png
+++ b/doc/user/discussions/img/swipe_view.png
diff --git a/doc/user/discussions/img/thread_view.png b/doc/user/discussions/img/thread_view.png
new file mode 100644
index 00000000000..e2db44aa604
--- /dev/null
+++ b/doc/user/discussions/img/thread_view.png
diff --git a/doc/user/discussions/img/threads_resolved.png b/doc/user/discussions/img/threads_resolved.png
new file mode 100644
index 00000000000..ffb1233f2ee
--- /dev/null
+++ b/doc/user/discussions/img/threads_resolved.png
diff --git a/doc/user/discussions/img/two_up_view.png b/doc/user/discussions/img/two_up_view.png
index d9e90708e87..3b6ddfbe1be 100644
--- a/doc/user/discussions/img/two_up_view.png
+++ b/doc/user/discussions/img/two_up_view.png
diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md
index 20eabdada79..6891682141c 100644
--- a/doc/user/discussions/index.md
+++ b/doc/user/discussions/index.md
@@ -1,18 +1,18 @@
-# Discussions
+# Threads
 
 The ability to contribute conversationally is offered throughout GitLab.
 
 You can leave a comment in the following places:
 
 - issues
-- epics **[ULTIMATE]**
+- epics **(ULTIMATE)**
 - merge requests
 - snippets
 - commits
 - commit diffs
 
 There are standard comments, and you also have the option to create a comment
-in the form of a threaded discussion. A comment can also be [turned into a discussion](#start-a-discussion-by-replying-to-a-standard-comment)
+in the form of a thread. A comment can also be [turned into a thread](#start-a-thread-by-replying-to-a-standard-comment)
 when it receives a reply.
 
 The comment area supports [Markdown] and [quick actions]. You can edit your own
@@ -21,187 +21,190 @@ higher can also edit a comment made by someone else.
 
 You can also reply to a comment notification email to reply to the comment if
 [Reply by email] is configured for your GitLab instance. Replying to a standard comment
-creates another standard comment. Replying to a discussion comment creates a reply in the
-discussion thread. Email replies support [Markdown] and [quick actions], just as if you replied from the web.
+creates another standard comment. Replying to a threaded comment creates a reply in the thread. Email replies support
+[Markdown] and [quick actions], just as if you replied from the web.
 
-## Resolvable comments and discussions
+## Resolvable comments and threads
 
 > **Notes:**
 >
 > - The main feature was [introduced][ce-5022] in GitLab 8.11.
-> - Resolvable discussions can be added only to merge request diffs.
+> - Resolvable threads can be added only to merge request diffs.
 
-Discussion resolution helps keep track of progress during planning or code review.
+Thread resolution helps keep track of progress during planning or code review.
 
-Every standard comment or discussion thread in merge requests, commits, commit diffs, and
+Every standard comment or thread in merge requests, commits, commit diffs, and
 snippets is initially displayed as unresolved. They can then be individually resolved by anyone
 with at least Developer access to the project or by the author of the change being reviewed.
 
-The need to resolve all standard comments or discussions prevents you from forgetting
-to address feedback and lets you hide discussions that are no longer relevant.
+The need to resolve all standard comments or threads prevents you from forgetting
+to address feedback and lets you hide threads that are no longer relevant.
 
-!["A discussion between two people on a piece of code"][discussion-view]
+!["A thread between two people on a piece of code"](img/thread_view.png)
 
-### Commit discussions in the context of a merge request
+### Commit threads in the context of a merge request
 
 > [Introduced][ce-31847] in GitLab 10.3.
 
-For reviewers with commit-based workflow, it may be useful to add discussions to
-specific commit diffs in the context of a merge request. These discussions will
+For reviewers with commit-based workflow, it may be useful to add threads to
+specific commit diffs in the context of a merge request. These threads will
 persist through a commit ID change when:
 
 - force-pushing after a rebase
 - amending a commit
 
-This functionality is also demonstrated in the video [How to use Merge Request Commit Discussions](https://www.youtube.com/watch?v=TviJH6oRboo).
-
-To create a commit diff discussion:
+To create a commit diff thread:
 
 1. Navigate to the merge request **Commits** tab. A list of commits that
    constitute the merge request will be shown.
 
-    ![Merge request commits tab](img/merge_request_commits_tab.png)
+   ![Merge request commits tab](img/merge_request_commits_tab.png)
 
 1. Navigate to a specific commit, click on the **Changes** tab (where you
    will only be presented diffs from the selected commit), and leave a comment.
 
-    ![Commit diff discussion in merge request context](img/commit_comment_mr_context.png)
+   ![Commit diff discussion in merge request context](img/commit_comment_mr_context.png)
 
-1. Any discussions created this way will be shown in the merge request's
+1. Any threads created this way will be shown in the merge request's
    **Discussions** tab and are resolvable.
 
-    ![Merge request Discussions tab](img/commit_comment_mr_discussions_tab.png)
+   ![Merge request Discussions tab](img/commit_comment_mr_discussions_tab.png)
 
-Discussions created this way will only appear in the original merge request
+Threads created this way will only appear in the original merge request
 and not when navigating to that commit under your project's
 **Repository > Commits** page.
 
 TIP: **Tip:**
-When a link of a commit reference is found in a discussion inside a merge
+When a link of a commit reference is found in a thread inside a merge
 request, it will be automatically converted to a link in the context of the
 current merge request.
 
-### Jumping between unresolved discussions
+### Jumping between unresolved threads
 
 When a merge request has a large number of comments it can be difficult to track
-what remains unresolved. You can jump between unresolved discussions with the
-Jump button next to the Reply field on a discussion.
+what remains unresolved. You can jump between unresolved threads with the
+Jump button next to the Reply field on a thread.
+
+You can also jump to the first unresolved thread from the button next to the
+resolved threads tracker.
 
-You can also jump to the first unresolved discussion from the button next to the
-resolved discussions tracker.
+You can also use keyboard shortcuts to navigate among threads:
 
-!["3/4 discussions resolved"][discussions-resolved]
+- Use <kbd>n</kbd> to jump to the next unresolved thread.
+- Use <kbd>p</kbd> to jump to the previous unresolved thread.
 
-### Marking a comment or discussion as resolved
+!["8/9 threads resolved"](img/threads_resolved.png)
 
-You can mark a discussion as resolved by clicking the **Resolve discussion**
-button at the bottom of the discussion.
+### Marking a comment or thread as resolved
 
-!["Resolve discussion" button][resolve-discussion-button]
+You can mark a thread as resolved by clicking the **Resolve thread**
+button at the bottom of the thread.
+
+!["Resolve thread" button](img/resolve_thread_button.png)
 
 Alternatively, you can mark each comment as resolved individually.
 
-!["Resolve comment" button][resolve-comment-button]
+!["Resolve comment" button](img/resolve_comment_button.png)
 
-### Move all unresolved discussions in a merge request to an issue
+### Move all unresolved threads in a merge request to an issue
 
 > [Introduced][ce-8266] in GitLab 9.1
 
-To continue all open discussions from a merge request in a new issue, click the
-**Resolve all discussions in new issue** button.
+To continue all open threads from a merge request in a new issue, click the
+**Resolve all threads in new issue** button.
 
-![Open new issue for all unresolved discussions](img/btn_new_issue_for_all_discussions.png)
+![Open new issue for all unresolved threads](img/btn_new_issue_for_all_threads.png)
 
-Alternatively, when your project only accepts merge requests [when all discussions
-are resolved](#only-allow-merge-requests-to-be-merged-if-all-discussions-are-resolved),
+Alternatively, when your project only accepts merge requests [when all threads
+are resolved](#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved),
 there will be an **open an issue to resolve them later** link in the merge
 request widget.
 
-![Link in merge request widget](img/resolve_discussion_open_issue.png)
+![Link in merge request widget](img/resolve_thread_open_issue.png)
 
 This will prepare an issue with its content referring to the merge request and
-the unresolved discussions.
+the unresolved threads.
 
-![Issue mentioning discussions in a merge request](img/preview_issue_for_discussions.png)
+![Issue mentioning threads in a merge request](img/preview_issue_for_threads.png)
 
-Hitting **Submit issue** will cause all discussions to be marked as resolved and
+Hitting **Submit issue** will cause all threads to be marked as resolved and
 add a note referring to the newly created issue.
 
-![Mark discussions as resolved notice](img/resolve_discussion_issue_notice.png)
+![Mark threads as resolved notice](img/resolve_thread_issue_notice.png)
 
 You can now proceed to merge the merge request from the UI.
 
-### Moving a single discussion to a new issue
+### Moving a single thread to a new issue
 
 > [Introduced][ce-8266] in GitLab 9.1
 
-To create a new issue for a single discussion, you can use the **Resolve this
-discussion in a new issue** button.
+To create a new issue for a single thread, you can use the **Resolve this
+thread in a new issue** button.
 
-![Create issue for discussion](img/new_issue_for_discussion.png)
+![Create issue for thread](img/new_issue_for_thread.png)
 
 This will direct you to a new issue prefilled with the content of the
-discussion, similar to the issues created for delegating multiple
-discussions at once. Saving the issue will mark the discussion as resolved and
-add a note to the merge request discussion referencing the new issue.
+thread, similar to the issues created for delegating multiple
+threads at once. Saving the issue will mark the thread as resolved and
+add a note to the merge request thread referencing the new issue.
 
-![New issue for a single discussion](img/preview_issue_for_discussion.png)
+![New issue for a single thread](img/preview_issue_for_thread.png)
 
-### Only allow merge requests to be merged if all discussions are resolved
+### Only allow merge requests to be merged if all threads are resolved
 
 > [Introduced][ce-7125] in GitLab 8.14.
 
-You can prevent merge requests from being merged until all discussions are
+You can prevent merge requests from being merged until all threads are
 resolved.
 
 Navigate to your project's settings page, select the
-**Only allow merge requests to be merged if all discussions are resolved** check
+**Only allow merge requests to be merged if all threads are resolved** check
 box and hit **Save** for the changes to take effect.
 
-![Only allow merge if all the discussions are resolved settings](img/only_allow_merge_if_all_discussions_are_resolved.png)
+![Only allow merge if all the threads are resolved settings](img/only_allow_merge_if_all_threads_are_resolved.png)
 
-From now on, you will not be able to merge from the UI until all discussions
+From now on, you will not be able to merge from the UI until all threads
 are resolved.
 
-![Only allow merge if all the discussions are resolved message](img/only_allow_merge_if_all_discussions_are_resolved_msg.png)
+![Only allow merge if all the threads are resolved message](img/resolve_thread_open_issue.png)
 
-### Automatically resolve merge request diff discussions when they become outdated
+### Automatically resolve merge request diff threads when they become outdated
 
 > [Introduced][ce-14053] in GitLab 10.0.
 
-You can automatically resolve merge request diff discussions on lines modified
+You can automatically resolve merge request diff threads on lines modified
 with a new push.
 
 Navigate to your project's settings page, select the **Automatically resolve
-merge request diffs discussions on lines changed with a push** check box and hit
+merge request diffs threads on lines changed with a push** check box and hit
 **Save** for the changes to take effect.
 
-![Automatically resolve merge request diff discussions when they become outdated](img/automatically_resolve_outdated_discussions.png)
+![Automatically resolve merge request diff threads when they become outdated](img/automatically_resolve_outdated_discussions.png)
 
-From now on, any discussions on a diff will be resolved by default if a push
-makes that diff section outdated. Discussions on lines that don't change and
-top-level resolvable discussions are not automatically resolved.
+From now on, any threads on a diff will be resolved by default if a push
+makes that diff section outdated. Threads on lines that don't change and
+top-level resolvable threads are not automatically resolved.
 
-## Commit discussions
+## Commit threads
 
-You can add comments and discussion threads to a particular commit under your
+You can add comments and threads to a particular commit under your
 project's **Repository > Commits**.
 
 CAUTION: **Attention:**
-Discussions created this way will be lost if the commit ID changes after a
+Threads created this way will be lost if the commit ID changes after a
 force push.
 
 ## Threaded discussions
 
 > [Introduced][ce-7527] in GitLab 9.1.
 
-While resolvable discussions are only available to merge request diffs,
-discussions can also be added without a diff. You can start a specific
-discussion which will look like a thread, on issues, commits, snippets, and
+While resolvable threads are only available to merge request diffs,
+threads can also be added without a diff. You can start a specific
+thread which will look like a thread, on issues, commits, snippets, and
 merge requests.
 
 To start a threaded discussion, click on the **Comment** button toggle dropdown,
-select **Start discussion** and click **Start discussion** when you're ready to
+select **Start thread** and click **Start thread** when you're ready to
 post the comment.
 
 ![Comment type toggle](img/comment_type_toggle.gif)
@@ -209,56 +212,57 @@ post the comment.
 This will post a comment with a single thread to allow you to discuss specific
 comments in greater detail.
 
-![Discussion comment](img/discussion_comment.png)
+![Thread comment](img/discussion_comment.png)
 
-## Image discussions
+## Image threads
 
 > [Introduced][ce-14061] in GitLab 10.1.
 
-Sometimes a discussion is revolved around an image. With image discussions,
-you can easily target a specific coordinate of an image and start a discussion
-around it. Image discussions are available in merge requests and commit detail views.
+Sometimes a thread is revolved around an image. With image threads,
+you can easily target a specific coordinate of an image and start a thread
+around it. Image threads are available in merge requests and commit detail views.
 
-To start an image discussion, hover your mouse over the image. Your mouse pointer
+To start an image thread, hover your mouse over the image. Your mouse pointer
 should convert into an icon, indicating that the image is available for commenting.
-Simply click anywhere on the image to create a new discussion.
+Simply click anywhere on the image to create a new thread.
 
-![Start image discussion](img/start_image_discussion.gif)
+![Start image thread](img/start_image_discussion.gif)
 
 After you click on the image, a comment form will be displayed that would be the start
-of your discussion. Once you save your comment, you will see a new badge displayed on
-top of your image. This badge represents your discussion.
+of your thread. Once you save your comment, you will see a new badge displayed on
+top of your image. This badge represents your thread.
 
 >**Note:**
-This discussion badge is typically associated with a number that is only used as a visual
-reference for each discussion. In the merge request discussion tab,
-this badge will be indicated with a comment icon since each discussion will render a new
+This thread badge is typically associated with a number that is only used as a visual
+reference for each thread. In the merge request thread tab,
+this badge will be indicated with a comment icon since each thread will render a new
 image section.
 
-Image discussions also work on diffs that replace an existing image. In this diff view
-mode, you can toggle the different view modes and still see the discussion point badges.
+Image threads also work on diffs that replace an existing image. In this diff view
+mode, you can toggle the different view modes and still see the thread point badges.
 
 | 2-up | Swipe | Onion Skin |
 | :-----------: | :----------: | :----------: |
 | ![2-up view](img/two_up_view.png) | ![swipe view](img/swipe_view.png) | ![onion skin view](img/onion_skin_view.png) |
 
-Image discussions also work well with resolvable discussions. Resolved discussions
+Image threads also work well with resolvable threads. Resolved threads
 on diffs (not on the merge request discussion tab) will appear collapsed on page
 load and will have a corresponding badge counter to match the counter on the image.
 
-![Image resolved discussion](img/image_resolved_discussion.png)
+![Image resolved thread](img/image_resolved_discussion.png)
 
 ## Lock discussions
 
 > [Introduced][ce-14531] in GitLab 10.1.
 
-For large projects with many contributors, it may be useful to stop discussions
+For large projects with many contributors, it may be useful to stop threads
 in issues or merge requests in these scenarios:
 
-- The project maintainer has already resolved the discussion and it is not helpful
-  for continued feedback. The project maintainer has already directed new conversation
+- The project maintainer has already resolved the thread and it is not helpful
+  for continued feedback.
+- The project maintainer has already directed new conversation
   to newer issues or merge requests.
-- The people participating in the discussion are trolling, abusive, or otherwise
+- The people participating in the thread are trolling, abusive, or otherwise
   being unproductive.
 
 In these cases, a user with Developer permissions or higher in the project can lock (and unlock)
@@ -282,7 +286,7 @@ edit existing comments. Non-team members are restricted from adding or editing c
 
 Additionally, locked issues and merge requests can not be reopened.
 
-## Merge Request Reviews **[PREMIUM]**
+## Merge Request Reviews **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4213) in GitLab 11.4.
 
@@ -300,7 +304,7 @@ in an MR and click on the **Start a review** button.
 Once a review is started, you will see any comments that are part of this review marked `Pending`.
 All comments that are part of a review show two buttons:
 
-- **Submit review**: Submits all comments that are part of the review, making them visible to other users.
+- **Finish review**: Submits all comments that are part of the review, making them visible to other users.
 - **Add comment now**: Submits the specific comment as a regular comment instead of as part of the review.
 
 ![A comment that is part of a review](img/pending_review_comment.png)
@@ -317,20 +321,20 @@ This will add the comment to the review.
 
 ![Second review comment](img/mr_review_second_comment_added.png)
 
-### Resolving/Unresolving discussions
+### Resolving/Unresolving threads
 
-Review comments can also resolve/unresolve [resolvable discussions](#resolvable-comments-and-discussions).
+Review comments can also resolve/unresolve [resolvable threads](#resolvable-comments-and-threads).
 When replying to a comment, you will see a checkbox that you can click in order to resolve or unresolve
-the discussion once published.
+the thread once published.
 
 ![Resolve checkbox](img/mr_review_resolve.png)
-![Unresolve checkbox](img/mr_review_unresolve.png)
 
-If a particular pending comment will resolve or unresolve the discussion, this will be shown on the pending
+If a particular pending comment will resolve or unresolve the thread, this will be shown on the pending
 comment itself.
 
 ![Resolve status](img/mr_review_resolve2.png)
-![Unresolve status](img/mr_review_unresolve2.png)
+
+![Unresolve status](img/mr_review_unresolve.png)
 
 ### Submitting a review
 
@@ -339,8 +343,8 @@ bottom of the screen with two buttons:
 
 - **Discard**: Discards all comments that have not been submitted.
 - **Finish review**: Opens a list of comments ready to be submitted for review.
-   Clicking **Submit review** will publish all comments. Any quick actions
-   submitted are performed at this time.
+  Clicking **Submit review** will publish all comments. Any quick actions
+  submitted are performed at this time.
 
 Alternatively, every pending comment has a button to finish the entire review.
 
@@ -356,7 +360,7 @@ Replying to this email will, consequentially, create a new comment on the associ
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/26723) in GitLab 11.5.
 
 For issues with many comments like activity notes and user comments, sometimes
-finding useful information can be hard. There is a way to filter comments from single notes and discussions for merge requests and issues.
+finding useful information can be hard. There is a way to filter comments from single notes and threads for merge requests and issues.
 
 From a merge request's **Discussion** tab, or from an epic/issue overview, find the filter's dropdown menu on the right side of the page, from which you can choose one of the following options:
 
@@ -376,7 +380,7 @@ from any device you're logged into.
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6.
 
 As a reviewer, you're able to suggest code changes with a simple
-markdown syntax in Merge Request Diff discussions. Then, the
+markdown syntax in Merge Request Diff threads. Then, the
 Merge Request author (or other users with appropriate
 [permission](../permissions.md)) is able to apply these
 suggestions with a click, which will generate a commit in
@@ -385,21 +389,21 @@ the Merge Request authored by the user that applied them.
 1. Choose a line of code to be changed, add a new comment, then click
    on the **Insert suggestion** icon in the toolbar:
 
-    ![Add a new comment](img/insert_suggestion.png)
+   ![Add a new comment](img/insert_suggestion.png)
 
 1. In the comment, add your suggestion to the pre-populated code block:
 
-    ![Add a suggestion into a code block tagged properly](img/make_suggestion.png)
+   ![Add a suggestion into a code block tagged properly](img/make_suggestion.png)
 
 1. Click **Comment**.
 
-    The suggestions in the comment can be applied by the merge request author
-    directly from the merge request:
+   The suggestions in the comment can be applied by the merge request author
+   directly from the merge request:
 
-    ![Apply suggestions](img/suggestion.png)
+   ![Apply suggestions](img/suggestion.png)
 
 Once the author applies a suggestion, it will be marked with the **Applied** label,
-the discussion will be automatically resolved, and GitLab will create a new commit
+the thread will be automatically resolved, and GitLab will create a new commit
 with the message `Apply suggestion to <file-name>` and push the suggested change
 directly into the codebase in the merge request's branch.
 [Developer permission](../permissions.md) is required to do so.
@@ -413,8 +417,8 @@ Custom commit messages will be introduced by
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/53310) in GitLab 11.10.
 
 Reviewers can also suggest changes to multiple lines with a single suggestion
-within Merge Request diff discussions by adjusting the range offsets. The
-offsets are relative to the position of the diff discussion, and specify the
+within Merge Request diff threads by adjusting the range offsets. The
+offsets are relative to the position of the diff thread, and specify the
 range to be replaced by the suggestion when it is applied.
 
 ![Multi-line suggestion syntax](img/multi-line-suggestion-syntax.png)
@@ -430,25 +434,26 @@ Suggestions covering multiple lines are limited to 100 lines _above_ and 100
 lines _below_ the commented diff line, allowing up to 200 changed lines per
 suggestion.
 
-## Start a discussion by replying to a standard comment
+## Start a thread by replying to a standard comment
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30299) in GitLab 11.9
 
-To reply to a standard (non-discussion) comment, you can use the **Reply to comment** button.
+To reply to a standard (non-thread) comment, you can use the **Reply to comment** button.
 
 ![Reply to comment button](img/reply_to_comment_button.png)
 
-The **Reply to comment** button is only displayed if you have permissions to reply to an existing discussion, or start a discussion from a standard comment.
+The **Reply to comment** button is only displayed if you have permissions to reply to an existing thread, or start a thread from a standard comment.
 
 Clicking on the **Reply to comment** button will bring the reply area into focus and you can type your reply.
 
 ![Reply to comment feature](img/reply_to_comment.gif)
 
-Relying to a non-discussion comment will convert the non-discussion comment to a
-threaded discussion once the reply is submitted. This conversion is considered an edit
+Replying to a non-thread comment will convert the non-thread comment to a
+thread once the reply is submitted. This conversion is considered an edit
 to the original comment, so a note about when it was last edited will appear underneath it.
 
-This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff discussions are not supported yet.
+This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff threads are 
+not supported yet.
 
 [ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022
 [ce-7125]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7125
diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md
index 2fb6cec55fa..d21a325d401 100644
--- a/doc/user/gitlab_com/index.md
+++ b/doc/user/gitlab_com/index.md
@@ -1,7 +1,7 @@
 # GitLab.com settings
 
 In this page you will find information about the settings that are used on
-[GitLab.com](https://about.gitlab.com/pricing).
+[GitLab.com](https://about.gitlab.com/pricing/).
 
 ## SSH host keys fingerprints
 
@@ -73,21 +73,20 @@ or over the size limit, you can [reduce your repository size with Git](../projec
 
 ## IP range
 
-GitLab.com, CI/CD, and related services are deployed into Google Cloud Platform (GCP). Any 
-IP based firewall can be configured by looking up all 
-[IP address ranges or CIDR blocks for GCP](https://cloud.google.com/compute/docs/faq#where_can_i_find_product_name_short_ip_ranges). 
+GitLab.com, CI/CD, and related services are deployed into Google Cloud Platform (GCP). Any
+IP based firewall can be configured by looking up all
+[IP address ranges or CIDR blocks for GCP](https://cloud.google.com/compute/docs/faq#where_can_i_find_product_name_short_ip_ranges).
 
 [Static endpoints](https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/5071) are being considered.
 
 ## Shared Runners
 
-Shared Runners on GitLab.com run in [autoscale mode] and powered by
-Google Cloud Platform. Autoscaling means reduced
-waiting times to spin up CI/CD jobs, and isolated VMs for each project,
-thus maximizing security.
-They're free to use for public open source projects and limited to 2000 CI
-minutes per month per group for private projects. Read about all
-[GitLab.com plans](https://about.gitlab.com/pricing/).
+Shared Runners on GitLab.com run in [autoscale mode] and powered by Google Cloud Platform.
+Autoscaling means reduced waiting times to spin up CI/CD jobs, and isolated VMs for each project,
+thus maximizing security. They're free to use for public open source projects and limited
+to 2000 CI minutes per month per group for private projects. More minutes
+[can be purchased](../../subscriptions/index.md#extra-shared-runners-pipeline-minutes), if
+needed. Read about all [GitLab.com plans](https://about.gitlab.com/pricing/).
 
 All your CI/CD jobs run on [n1-standard-1 instances](https://cloud.google.com/compute/docs/machine-types) with 3.75GB of RAM, CoreOS and the latest Docker Engine
 installed. Instances provide 1 vCPU and 25GB of HDD disk space. The default
@@ -113,57 +112,6 @@ Below are the shared Runners settings.
 
 The full contents of our `config.toml` are:
 
-**DigitalOcean**
-
-```toml
-concurrent = X
-check_interval = 1
-metrics_server = "X"
-sentry_dsn = "X"
-
-[[runners]]
-  name = "docker-auto-scale"
-  request_concurrency = X
-  url = "https://gitlab.com/"
-  token = "SHARED_RUNNER_TOKEN"
-  executor = "docker+machine"
-  environment = [
-    "DOCKER_DRIVER=overlay2"
-  ]
-  limit = X
-  [runners.docker]
-    image = "ruby:2.5"
-    privileged = true
-  [runners.machine]
-    IdleCount = 20
-    IdleTime = 1800
-    OffPeakPeriods = ["* * * * * sat,sun *"]
-    OffPeakTimezone = "UTC"
-    OffPeakIdleCount = 5
-    OffPeakIdleTime = 1800
-    MaxBuilds = 1
-    MachineName = "srm-%s"
-    MachineDriver = "digitalocean"
-    MachineOptions = [
-      "digitalocean-image=X",
-      "digitalocean-ssh-user=core",
-      "digitalocean-region=nyc1",
-      "digitalocean-size=s-2vcpu-2gb",
-      "digitalocean-private-networking",
-      "digitalocean-tags=shared_runners,gitlab_com",
-      "engine-registry-mirror=http://INTERNAL_IP_OF_OUR_REGISTRY_MIRROR",
-      "digitalocean-access-token=DIGITAL_OCEAN_ACCESS_TOKEN",
-    ]
-  [runners.cache]
-    Type = "s3"
-    BucketName = "runner"
-    Insecure = true
-    Shared = true
-    ServerAddress = "INTERNAL_IP_OF_OUR_CACHE_SERVER"
-    AccessKey = "ACCESS_KEY"
-    SecretKey = "ACCESS_SECRET_KEY"
-```
-
 **Google Cloud Platform**
 
 ```toml
@@ -179,20 +127,25 @@ sentry_dsn = "X"
   token = "SHARED_RUNNER_TOKEN"
   executor = "docker+machine"
   environment = [
-    "DOCKER_DRIVER=overlay2"
+    "DOCKER_DRIVER=overlay2",
+    "DOCKER_TLS_CERTDIR="
   ]
   limit = X
   [runners.docker]
     image = "ruby:2.5"
     privileged = true
+    volumes = [
+      "/certs/client",
+      "/dummy-sys-class-dmi-id:/sys/class/dmi/id:ro" # Make kaniko builds work on GCP.
+    ]
   [runners.machine]
-    IdleCount = 20
-    IdleTime = 1800
+    IdleCount = 50
+    IdleTime = 3600
     OffPeakPeriods = ["* * * * * sat,sun *"]
     OffPeakTimezone = "UTC"
-    OffPeakIdleCount = 5
-    OffPeakIdleTime = 1800
-    MaxBuilds = 1
+    OffPeakIdleCount = 15
+    OffPeakIdleTime = 3600
+    MaxBuilds = 1 # For security reasons we delete the VM after job has finished so it's not reused.
     MachineName = "srm-%s"
     MachineDriver = "google"
     MachineOptions = [
@@ -203,17 +156,18 @@ sentry_dsn = "X"
       "google-tags=gitlab-com,srm",
       "google-use-internal-ip",
       "google-zone=us-east1-d",
+      "engine-opt=mtu=1460", # Set MTU for container interface, for more information check https://gitlab.com/gitlab-org/gitlab-runner/issues/3214#note_82892928
       "google-machine-image=PROJECT/global/images/IMAGE",
-      "engine-registry-mirror=http://INTERNAL_IP_OF_OUR_REGISTRY_MIRROR"
+      "engine-opt=ipv6", # This will create IPv6 interfaces in the containers.
+      "engine-opt=fixed-cidr-v6=fc00::/7",
+      "google-operation-backoff-initial-interval=2" # Custom flag from forked docker-machine, for more information check https://github.com/docker/machine/pull/4600
     ]
   [runners.cache]
-    Type = "s3"
-    BucketName = "runner"
-    Insecure = true
+    Type = "gcs"
     Shared = true
-    ServerAddress = "INTERNAL_IP_OF_OUR_CACHE_SERVER"
-    AccessKey = "ACCESS_KEY"
-    SecretKey = "ACCESS_SECRET_KEY"
+    [runners.cache.gcs]
+      CredentialsFile = "/path/to/file"
+      BucketName = "bucket-name"
 ```
 
 ## Sidekiq
@@ -223,7 +177,7 @@ and the following environment variables:
 
 | Setting                                 | GitLab.com | Default   |
 |--------                                 |----------- |--------   |
-| `SIDEKIQ_MEMORY_KILLER_MAX_RSS`         | `1000000`  | `1000000` |
+| `SIDEKIQ_MEMORY_KILLER_MAX_RSS`         | `1000000`  | `2000000` |
 | `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_SIGNAL` | `SIGKILL`  | -         |
 | `SIDEKIQ_LOG_ARGUMENTS`                 | `1`        | -         |
 
@@ -260,7 +214,7 @@ The list of GitLab.com specific settings (and their defaults) is as follows:
 | hot_standby_feedback                | on                                                                  | off                                   |
 | log_autovacuum_min_duration         | 0                                                                   | -1                                    |
 | log_checkpoints                     | on                                                                  | off                                   |
-| log_line_prefix                     | `%t [%p]: [%l-1] `                                                  | empty                                 |
+| log_line_prefix                     | `%t [%p]: [%l-1]`                                                   | empty                                 |
 | log_min_duration_statement          | 1000                                                                | -1                                    |
 | log_temp_files                      | 0                                                                   | -1                                    |
 | maintenance_work_mem                | 2048MB                                                              | 16 MB                                 |
@@ -298,6 +252,82 @@ Web front-ends:
 - `memory_limit_min` = 1024MiB
 - `memory_limit_max` = 1280MiB
 
+## GitLab.com-specific rate limits
+
+NOTE: **Note:**
+See [Rate limits](../../security/rate_limits.md) for administrator
+documentation.
+
+IP blocks usually happen when GitLab.com receives unusual traffic from a single
+IP address that the system views as potentially malicious based on rate limit
+settings. After the unusual traffic ceases, the IP address will be automatically
+released depending on the type of block, as described below.
+
+If you receive a `403 Forbidden` error for all requests to GitLab.com, please
+check for any automated processes that may be triggering a block. For
+assistance, contact [GitLab Support](https://support.gitlab.com)
+with details, such as the affected IP address.
+
+### HAProxy API throttle
+
+GitLab.com responds with HTTP status code `429` to API requests that exceed 10
+requests
+per second per IP address.
+
+The following example headers are included for all API requests:
+
+```
+RateLimit-Limit: 600
+RateLimit-Observed: 6
+RateLimit-Remaining: 594
+RateLimit-Reset: 1563325137
+RateLimit-ResetTime: Wed, 17 Jul 2019 00:58:57 GMT
+```
+
+Source:
+
+- Search for `rate_limit_http_rate_per_minute` and `rate_limit_sessions_per_second` in [GitLab.com's current HAProxy settings](https://gitlab.com/gitlab-cookbooks/gitlab-haproxy/blob/master/attributes/default.rb).
+
+### Rack Attack initializer
+
+Details of rate limits enforced by [Rack Attack](../../security/rack_attack.md).
+
+#### Protected paths throttle
+
+GitLab.com responds with HTTP status code `429` to POST requests at protected
+paths that exceed 10 requests per **minute** per IP address.
+
+See the source below for which paths are protected. This includes user creation,
+user confirmation, user sign in, and password reset.
+
+This header is included in responses to blocked requests:
+
+```
+Retry-After: 60
+```
+
+Source:
+
+- Search for `rate_limit_requests_per_period`, `rate_limit_period`, and `rack_attack_protected_paths` in [GitLab.com's current Rails app settings](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/attributes/default.rb).
+
+#### Git and container registry failed authentication ban
+
+GitLab.com responds with HTTP status code 403 for 1 hour, if 30 failed
+authentication requests were received in a 3-minute period from a single IP address.
+
+This applies only to Git requests and container registry (`/jwt/auth`) requests
+(combined).
+
+This limit is reset by requests that authenticate successfully. For example, 29
+failed authentication requests followed by 1 successful request, followed by 29
+more failed authentication requests would not trigger a ban.
+
+No response headers are provided.
+
+### Admin Area settings
+
+GitLab.com does not currently use these settings.
+
 ## GitLab.com at scale
 
 In addition to the GitLab Enterprise Edition Omnibus install, GitLab.com uses
@@ -352,3 +382,11 @@ High Performance TCP/HTTP Load Balancer:
 [unicorn-worker-killer]: https://rubygems.org/gems/unicorn-worker-killer "unicorn-worker-killer"
 [4010]: https://gitlab.com/gitlab-com/infrastructure/issues/4010 "Find a good value for maximum timeout for Shared Runners"
 [4070]: https://gitlab.com/gitlab-com/infrastructure/issues/4070 "Configure per-runner timeout for shared-runners-manager-X on GitLab.com"
+
+## Group and project settings
+
+On GitLab.com, projects, groups, and snippets created
+after July 2019 have the `Internal` visibility setting disabled.
+
+You can read more about the change in the
+[relevant issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/12388).
diff --git a/doc/user/group/bulk_editing/img/bulk-editing.png b/doc/user/group/bulk_editing/img/bulk-editing.png
new file mode 100644
index 00000000000..ca1662a781b
--- /dev/null
+++ b/doc/user/group/bulk_editing/img/bulk-editing.png
diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md
new file mode 100644
index 00000000000..ea48b0b9fef
--- /dev/null
+++ b/doc/user/group/bulk_editing/index.md
@@ -0,0 +1,31 @@
+# Bulk editing issues, merge requests, and epics at the group level **(PREMIUM)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7249) for issues in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12719) for merge requests in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7250) for epics in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2.
+
+## Editing milestones and labels
+
+> **Notes:**
+>
+> - A permission level of `Reporter` or higher is required in order to manage issues.
+> - A permission level of `Developer` or higher is required in order to manage merge requests.
+> - A permission level of `Reporter` or higher is required in order to manage epics.
+
+By using the bulk editing feature:
+
+- Milestones can be updated simultaneously across multiple issues or merge requests.
+- Labels can be updated simultaneously across multiple issues, merge requests, or epics.
+
+![Bulk editing](img/bulk-editing.png)
+
+To bulk update group issues, merge requests, or epics:
+
+1. Navigate to the issues, merge requests, or epics list.
+1. Click **Edit issues**, **Edit merge requests**, or **Edit epics**.
+    - This will open a sidebar on the right-hand side where editable fields
+      for milestones and labels will be displayed.
+    - Checkboxes will also appear beside each issue, merge request, or epic.
+1. Check the checkbox beside each issue, merge request, or epic to be edited.
+1. Select the desired new values from the sidebar.
+1. Click **Update all**.
diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md
index 3c5e820c1ca..d41f44f85cc 100644
--- a/doc/user/group/clusters/index.md
+++ b/doc/user/group/clusters/index.md
@@ -5,7 +5,6 @@ type: reference
 # Group-level Kubernetes clusters
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) in GitLab 11.6.
-> Group Cluster integration is currently in [Beta](https://about.gitlab.com/handbook/product/#alpha-beta-ga).
 
 ## Overview
 
@@ -42,7 +41,7 @@ to the group containing the project if the project's cluster is available and no
 In the case of sub-groups, GitLab will use the cluster of the closest ancestor group
 to the project, provided the cluster is not disabled.
 
-## Multiple Kubernetes clusters **[PREMIUM]**
+## Multiple Kubernetes clusters **(PREMIUM)**
 
 With GitLab Premium, you can associate more than one Kubernetes clusters to your
 group. That way you can have different clusters for different environments,
@@ -57,10 +56,6 @@ differentiate the new cluster from the rest.
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22011) in GitLab 11.5.
 > Became [optional](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/26565) in GitLab 11.11.
 
-NOTE: **Note:**
-Only available when creating clusters. Existing clusters not managed by GitLab
-cannot become GitLab-managed later.
-
 You can choose to allow GitLab to manage your cluster for you. If your cluster is
 managed by GitLab, resources for your projects will be automatically created. See the
 [Access controls](../../project/clusters/index.md#access-controls) section for details on which resources will
@@ -86,12 +81,12 @@ the [Auto DevOps](../../../topics/autodevops/index.md) stages.
 
 The domain should have a wildcard DNS configured to the Ingress IP address.
 
-## Environment scopes **[PREMIUM]**
+## Environment scopes **(PREMIUM)**
 
 When adding more than one Kubernetes cluster to your project, you need to differentiate
 them with an environment scope. The environment scope associates clusters with
 [environments](../../../ci/environments.md) similar to how the
-[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables-premium)
+[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables)
 work.
 
 While evaluating which environment matches the environment scope of a
@@ -142,13 +137,12 @@ The result will then be:
 - The Staging cluster will be used for the `deploy to staging` job.
 - The Production cluster will be used for the `deploy to production` job.
 
-## Unavailable features
-
-The following features are not currently available for group-level clusters:
+## Security of Runners
 
-1. Terminals (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55487)).
-1. Pod logs (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55488)).
-1. Deployment boards (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55489)).
+For important information about securely configuring GitLab Runners, see
+[Security of
+Runners](../../project/clusters/index.md#security-of-gitlab-runners)
+documentation for project-level clusters.
 
 <!-- ## Troubleshooting
 
diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md
index 7e6cb24a51e..a0dd5cd497d 100644
--- a/doc/user/group/contribution_analytics/index.md
+++ b/doc/user/group/contribution_analytics/index.md
@@ -2,9 +2,10 @@
 type: reference
 ---
 
-# Contribution Analytics **[STARTER]**
+# Contribution Analytics **(STARTER)**
 
-> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3.
+> - Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3090) for subgroups in GitLab 12.2.
 
 ## Overview
 
@@ -21,9 +22,9 @@ page.
 ## Use cases
 
 - Analyze your team's contributions over a period of time, and offer a bonus for the top
-contributors.
+  contributors.
 - Identify opportunities for improvement with group members who may benefit from additional
-support.
+  support.
 
 ## Using Contribution Analytics
 
@@ -54,13 +55,13 @@ Select the desired period from the calendar dropdown.
 
 Contributions per group member are also presented in tabular format. Click a column header to sort the table by that column:
 
-* Member name
-* Number of pushed events
-* Number of opened issues
-* Number of closed issues
-* Number of opened MRs
-* Number of accepted MRs
-* Number of total contributions
+- Member name
+- Number of pushed events
+- Number of opened issues
+- Number of closed issues
+- Number of opened MRs
+- Number of accepted MRs
+- Number of total contributions
 
 ![Contribution analytics contributions table](img/group_stats_table.png)
 
diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md
index aa088d2fcdb..7cdba8cf2b5 100644
--- a/doc/user/group/custom_project_templates.md
+++ b/doc/user/group/custom_project_templates.md
@@ -2,9 +2,9 @@
 type: reference
 ---
 
-# Custom group-level project templates **[PREMIUM]**
+# Custom group-level project templates **(PREMIUM)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing) 11.6.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.6.
 
 When you create a new [project](../project/index.md), creating it based on custom project templates is
 a convenient bootstrap option.
@@ -24,7 +24,7 @@ project in the group will be available to every logged in user.
 However, private projects will be available only if the user is a member of the project.
 
 NOTE: **Note:**
-Projects of nested subgroups of a selected template source cannot be used.
+Only direct subgroups can be set as the template source. Projects of nested subgroups of a selected template source cannot be used.
 
 Repository and database information that are copied over to each new project are
 identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md).
diff --git a/doc/user/group/dependency_proxy/index.md b/doc/user/group/dependency_proxy/index.md
index 4fc2d8e9509..771468fbba8 100644
--- a/doc/user/group/dependency_proxy/index.md
+++ b/doc/user/group/dependency_proxy/index.md
@@ -1,4 +1,4 @@
-# Dependency Proxy **[PREMIUM]**
+# Dependency Proxy **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11.
 
diff --git a/doc/user/group/epics/img/bulk_editing.png b/doc/user/group/epics/img/bulk_editing.png
new file mode 100644
index 00000000000..85610bef83e
--- /dev/null
+++ b/doc/user/group/epics/img/bulk_editing.png
diff --git a/doc/user/group/epics/img/button_reopen_epic.png b/doc/user/group/epics/img/button_reopen_epic.png
index 7a953189270..9d1be88549d 100644
--- a/doc/user/group/epics/img/button_reopen_epic.png
+++ b/doc/user/group/epics/img/button_reopen_epic.png
diff --git a/doc/user/group/epics/img/containing_epic.png b/doc/user/group/epics/img/containing_epic.png
index 5ed693e6d6a..dc13d55e2bc 100644
--- a/doc/user/group/epics/img/containing_epic.png
+++ b/doc/user/group/epics/img/containing_epic.png
diff --git a/doc/user/group/epics/img/epic_view.png b/doc/user/group/epics/img/epic_view.png
index dbda98e4351..c55d302ec29 100644
--- a/doc/user/group/epics/img/epic_view.png
+++ b/doc/user/group/epics/img/epic_view.png
diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md
index 2e4106f55e5..5968b91c9b7 100644
--- a/doc/user/group/epics/index.md
+++ b/doc/user/group/epics/index.md
@@ -2,7 +2,7 @@
 type: reference, howto
 ---
 
-# Epics **[ULTIMATE]**
+# Epics **(ULTIMATE)**
 
 > Introduced in [GitLab Ultimate][ee] 10.2.
 
@@ -97,6 +97,22 @@ have a [start or due date](#start-date-and-due-date), then you can see a
 
 Drag and drop to reorder issues and child epics. New issues and child epics added to an epic appear at the top of the list.
 
+## Updating epics
+
+### Using bulk editing
+
+To apply labels across multiple epics:
+
+1. Go to the Epics list.
+1. Click **Edit epics**.
+    - Checkboxes will appear beside each epic.
+    - A sidebar on the right-hand side will appear, with an editable field for labels.
+1. Check the checkbox beside each epic to be edited.
+1. Select the desired labels.
+1. Click **Update all**.
+
+![bulk editing](img/bulk_editing.png)
+
 ## Deleting an epic
 
 NOTE: **Note:**
@@ -202,21 +218,21 @@ You may also consult the [group permissions table][permissions].
 ## Thread
 
 - Comments: collaborate on that epic by posting comments in its thread.
-These text fields also fully support
-[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm).
+  These text fields also fully support
+  [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm).
 
-## Comment, or start a discussion
+## Comment, or start a thread
 
 Once you wrote your comment, you can either:
 
 - Click "Comment" and your comment will be published.
-- Click "Start discussion": start a thread within that epic's thread to discuss specific points.
+- Click "Start thread": start a thread within that epic's discussion to discuss specific points.
 
 ## Award emoji
 
 - You can [award an emoji](../../award_emojis.md) to that epic or its comments.
 
-## Notifications            
+## Notifications
 
 - [Receive notifications](../../../workflow/notifications.md) for epic events.
 
diff --git a/doc/user/group/img/group_file_template_dropdown.png b/doc/user/group/img/group_file_template_dropdown.png
index d9caae1a223..f0586772218 100644
--- a/doc/user/group/img/group_file_template_dropdown.png
+++ b/doc/user/group/img/group_file_template_dropdown.png
diff --git a/doc/user/group/img/group_file_template_settings.png b/doc/user/group/img/group_file_template_settings.png
index ca42f7726db..5e07974bc86 100644
--- a/doc/user/group/img/group_file_template_settings.png
+++ b/doc/user/group/img/group_file_template_settings.png
diff --git a/doc/user/group/img/group_storage_usage_quota.png b/doc/user/group/img/group_storage_usage_quota.png
new file mode 100644
index 00000000000..c5d81ad7a8b
--- /dev/null
+++ b/doc/user/group/img/group_storage_usage_quota.png
diff --git a/doc/user/group/index.md b/doc/user/group/index.md
index 97d309caf7c..d1d4f3740b0 100644
--- a/doc/user/group/index.md
+++ b/doc/user/group/index.md
@@ -41,12 +41,13 @@ You can create groups for numerous reasons. To name a couple:
 - Make it easier to `@mention` all of your team at once in issues and merge requests by creating a group and including the appropriate members.
 
 For example, you could create a group for your company members, and create a [subgroup](subgroups/index.md) for each individual team. Let's say you create a group called `company-team`, and you create subgroups in this group for the individual teams `backend-team`, `frontend-team`, and `production-team`.
-    - When you start a new implementation from an issue, you add a comment:
-        _"`@company-team`, let's do it! `@company-team/backend-team` you're good to go!"_
-    - When your backend team needs help from frontend, they add a comment:
-        _"`@company-team/frontend-team` could you help us here please?"_
-    - When the frontend team completes their implementation, they comment:
-        _"`@company-team/backend-team`, it's done! Let's ship it `@company-team/production-team`!"_
+
+- When you start a new implementation from an issue, you add a comment:
+  _"`@company-team`, let's do it! `@company-team/backend-team` you're good to go!"_
+- When your backend team needs help from frontend, they add a comment:
+  _"`@company-team/frontend-team` could you help us here please?"_
+- When the frontend team completes their implementation, they comment:
+  _"`@company-team/backend-team`, it's done! Let's ship it `@company-team/production-team`!"_
 
 ## Namespaces
 
@@ -77,6 +78,10 @@ Issues and merge requests are part of projects. For a given group, you can view
 [issues](../project/issues/index.md#issues-list) and [merge requests](../project/merge_requests/index.md#merge-requests-per-group) across all projects in that group,
 together in a single list view.
 
+### Bulk editing issues and merge requests
+
+For details, see [bulk editing issues and merge requests](../group/bulk_editing/index.md).
+
 ## Create a new group
 
 > For a list of words that are not allowed to be used as group names see the
@@ -86,11 +91,11 @@ To create a new Group, either:
 
 - In the top menu, click **Groups** and then **Your Groups**, and click the green button **New group**.
 
-    ![new group from groups page](img/new_group_from_groups.png)
+  ![new group from groups page](img/new_group_from_groups.png)
 
 - Or, in the top menu, expand the `plus` sign and choose **New group**.
 
-    ![new group from elsewhere](img/new_group_from_other_pages.png)
+  ![new group from elsewhere](img/new_group_from_other_pages.png)
 
 Add the following information:
 
@@ -99,15 +104,15 @@ Add the following information:
 1. The **Group name** will automatically populate the URL. Optionally, you can change it.
    This is the name that displays in group views.
    The name can contain only:
-     - Alphanumeric characters
-     - Underscores
-     - Dashes and dots
-     - Spaces
+   - Alphanumeric characters
+   - Underscores
+   - Dashes and dots
+   - Spaces
 1. The **Group URL** is the namespace under which your projects will be hosted.
    The URL can contain only:
-     - Alphanumeric characters
-     - Underscores
-     - Dashes and dots (it cannot start with dashes or end in a dot)
+   - Alphanumeric characters
+   - Underscores
+   - Dashes and dots (it cannot start with dashes or end in a dot)
 1. Optionally, you can add a brief description to tell others
    what this group is about.
 1. Optionally, choose an avatar for your group.
@@ -161,12 +166,12 @@ There are two different ways to add a new project to a group:
 
 - Select a group, and then click **New project**. You can then continue [creating your project](../../gitlab-basics/create-project.md).
 
-    ![New project](img/create_new_project_from_group.png)
+  ![New project](img/create_new_project_from_group.png)
 
 - While you are creating a project, select a group namespace
   you've already created from the dropdown menu.
 
-    ![Select group](img/select_group_dropdown.png)
+  ![Select group](img/select_group_dropdown.png)
 
 ### Default project-creation level
 
@@ -199,7 +204,7 @@ Alternatively, you can [lock the sharing with group feature](#share-with-group-l
 In GitLab Enterprise Edition, it is possible to manage GitLab group memberships using LDAP groups.
 See [the GitLab Enterprise Edition documentation](../../integration/ldap.md) for more information.
 
-## Epics **[ULTIMATE]**
+## Epics **(ULTIMATE)**
 
 > Introduced in [GitLab Ultimate][ee] 10.2.
 
@@ -209,13 +214,15 @@ milestones.
 
 [Learn more about Epics.](epics/index.md)
 
-## Group Security Dashboard **[ULTIMATE]**
+## Group Security Dashboard **(ULTIMATE)**
 
 Get an overview of the vulnerabilities of all the projects in a group and its subgroups.
 
 [Learn more about the Group Security Dashboard.](security_dashboard/index.md)
 
-## Insights **[ULTIMATE]**
+## Insights **(ULTIMATE)**
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0.
 
 Configure the Insights that matter for your groups or projects, allowing users
 to explore data such as:
@@ -268,9 +275,10 @@ be unique.
 
 To change your group path:
 
-1. Navigate to your group's **Settings > General**.
-1. Enter a new name under **Group path**.
-1. Click **Save group**.
+1. Navigate to your group's **Settings > General** page.
+1. Expand the **Path, transfer, remove** section.
+1. Enter a new name under **Change group path**.
+1. Click **Change group path**.
 
 CAUTION: **Caution:**
 It is currently not possible to rename a namespace if it contains a
@@ -303,7 +311,7 @@ To enable this feature, navigate to the group settings page. Select
 
 ![Checkbox for share with group lock](img/share_with_group_lock.png)
 
-#### Member Lock **[STARTER]**
+#### Member Lock **(STARTER)**
 
 Member lock lets a group owner prevent any new project membership to all of the
 projects within a group, allowing tighter control over project membership.
@@ -323,7 +331,58 @@ This will disable the option for all users who previously had permissions to
 operate project memberships, so no new users can be added. Furthermore, any
 request to add a new user to a project through API will not be possible.
 
-#### Group file templates **[PREMIUM]**
+#### IP access restriction **(ULTIMATE ONLY)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1985) in
+[GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0.
+
+To make sure only people from within your organization can access particular
+resources, you have the option to restrict access to groups and their
+underlying projects, issues, etc, by IP address. This can help ensure that
+particular content doesn't leave the premises, while not blocking off access to
+the entire instance.
+
+Add whitelisted IP subnet using CIDR notation to the group settings and anyone
+coming from a different IP address won't be able to access the restricted
+content.
+
+Restriction currently applies to UI, API access is not restricted.
+To avoid accidental lock-out, admins and group owners are are able to access
+the group regardless of the IP restriction.
+
+#### Allowed domain restriction **(PREMIUM ONLY)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7297) in
+[GitLab Premium](https://about.gitlab.com/pricing/) 12.2.
+
+You can restrict access to groups and their underlying projects by
+allowing only users with email addresses in particular domains to be added to the group.
+
+Add email domains you want to whitelist and users with emails from different 
+domains won't be allowed to be added to this group.
+
+Some domains cannot be restricted. These are the most popular public email domains, such as:
+
+- `gmail.com`
+- `yahoo.com`
+- `hotmail.com`
+- `aol.com`
+- `msn.com`
+- `hotmail.co.uk`
+- `hotmail.fr`
+- `live.com`
+- `outlook.com`
+- `icloud.com`
+
+To enable this feature:
+
+1. Navigate to the group's **Settings > General** page.
+1. Expand the **Permissions, LFS, 2FA** section, and enter domain name into **Restrict membership by email** field.
+1. Click **Save changes**.
+
+This will enable the domain-checking for all new users added to the group from this moment on.
+
+#### Group file templates **(PREMIUM)**
 
 Group file templates allow you to share a set of templates for common file
 types with every project in a group. It is analogous to the
@@ -347,11 +406,22 @@ To enable this feature, navigate to the group settings page, expand the
 
 ![Group file template settings](img/group_file_template_settings.png)
 
-#### Group-level project templates **[PREMIUM]**
+#### Group-level project templates **(PREMIUM)**
 
 Define project templates at a group level by setting a group as the template source.
 [Learn more about group-level project templates](custom_project_templates.md).
 
+#### Disabling email notifications
+
+You can disable all email notifications related to the group, which also includes
+it's subgroups and projects.
+
+To enable this feature:
+ 
+1. Navigate to the group's **Settings > General** page.
+1. Expand the **Permissions, LFS, 2FA** section, and select **Disable email notifications**.
+1. Click **Save changes**.
+
 ### Advanced settings
 
 - **Projects**: View all projects within that group, add members to each project,
@@ -359,20 +429,28 @@ Define project templates at a group level by setting a group as the template sou
 - **Webhooks**: Configure [webhooks](../project/integrations/webhooks.md) for your group.
 - **Kubernetes cluster integration**: Connect your GitLab group with [Kubernetes clusters](clusters/index.md).
 - **Audit Events**: View [Audit Events](../../administration/audit_events.md)
-  for the group. **[STARTER ONLY]**
+  for the group. **(STARTER ONLY)**
 - **Pipelines quota**: Keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group.
 
-## User contribution analysis **[STARTER]**
+#### Storage usage quota **(STARTER)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/13294) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0.
+
+A group owner can check the aggregated storage usage for all the project in a group, sub-groups included, in the **Storage** tab of the **Usage Quotas** page available to the group page settings list.
+
+![Group storage usage quota](img/group_storage_usage_quota.png)
+
+## User contribution analysis **(STARTER)**
 
 With [GitLab Contribution Analytics](contribution_analytics/index.md),
 you have an overview of the contributions (pushes, merge requests,
 and issues) performed by your group members.
 
-## Issues analytics **[PREMIUM]**
+## Issues analytics **(PREMIUM)**
 
 With [GitLab Issues Analytics](issues_analytics/index.md), you can see a bar chart of the number of issues created each month in your groups.
 
-## Dependency Proxy **[PREMIUM]**
+## Dependency Proxy **(PREMIUM)**
 
 Use GitLab as a [dependency proxy](dependency_proxy/index.md) for upstream Docker images.
 
diff --git a/doc/user/group/insights/img/insights_example_stacked_bar_chart.png b/doc/user/group/insights/img/insights_example_stacked_bar_chart.png
index 791d0e4bcdf..0e338b99e4c 100644
--- a/doc/user/group/insights/img/insights_example_stacked_bar_chart.png
+++ b/doc/user/group/insights/img/insights_example_stacked_bar_chart.png
diff --git a/doc/user/group/insights/img/insights_group_configuration.png b/doc/user/group/insights/img/insights_group_configuration.png
index 0af0073e448..d181a1e94c3 100644
--- a/doc/user/group/insights/img/insights_group_configuration.png
+++ b/doc/user/group/insights/img/insights_group_configuration.png
diff --git a/doc/user/group/insights/img/insights_sidebar_link.png b/doc/user/group/insights/img/insights_sidebar_link.png
index 64bbd1fc4d3..f7b0c2daae3 100644
--- a/doc/user/group/insights/img/insights_sidebar_link.png
+++ b/doc/user/group/insights/img/insights_sidebar_link.png
diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md
index 1aba5d0986b..f0e7f7239c1 100644
--- a/doc/user/group/insights/index.md
+++ b/doc/user/group/insights/index.md
@@ -2,10 +2,9 @@
 type: reference, howto
 ---
 
-# Insights **[ULTIMATE]**
+# Insights **(ULTIMATE)**
 
-> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9 behind the `insights` feature flag.
-> **Generally Available** (GA) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0.
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0.
 
 Configure the Insights that matter for your groups to explore data such as
 triage hygiene, issues created/closed per a given period, average time for merge
diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md
index 46d5c1e2e09..dc4b057789f 100644
--- a/doc/user/group/issues_analytics/index.md
+++ b/doc/user/group/issues_analytics/index.md
@@ -2,7 +2,7 @@
 type: reference
 ---
 
-# Issues Analytics **[PREMIUM]**
+# Issues Analytics **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5.
 
diff --git a/doc/user/group/roadmap/img/roadmap_view.png b/doc/user/group/roadmap/img/roadmap_view.png
index ff41a2e0441..2be3849ba1b 100644
--- a/doc/user/group/roadmap/img/roadmap_view.png
+++ b/doc/user/group/roadmap/img/roadmap_view.png
diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md
index 683c715c8d5..a72cd990706 100644
--- a/doc/user/group/roadmap/index.md
+++ b/doc/user/group/roadmap/index.md
@@ -2,9 +2,9 @@
 type: reference
 ---
 
-# Roadmap **[ULTIMATE]**
+# Roadmap **(ULTIMATE)**
 
-> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 10.5.
+> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.5.
 
 An Epic within a group containing **Start date** and/or **Due date**
 can be visualized in a form of a timeline (e.g. a Gantt chart). The Epics Roadmap page
@@ -30,7 +30,7 @@ Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-ep
 
 ## Timeline duration
 
-> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.0.
+> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0.
 
 Roadmap supports the following date ranges:
 
diff --git a/doc/user/group/saml_sso/img/group_saml_configuration_information.png b/doc/user/group/saml_sso/img/group_saml_configuration_information.png
index 98b83d0cb0f..e03c50ceb01 100644
--- a/doc/user/group/saml_sso/img/group_saml_configuration_information.png
+++ b/doc/user/group/saml_sso/img/group_saml_configuration_information.png
diff --git a/doc/user/group/saml_sso/img/group_saml_settings.png b/doc/user/group/saml_sso/img/group_saml_settings.png
index d95acb5075f..487be4faeba 100644
--- a/doc/user/group/saml_sso/img/group_saml_settings.png
+++ b/doc/user/group/saml_sso/img/group_saml_settings.png
diff --git a/doc/user/group/saml_sso/img/scim_advanced.png b/doc/user/group/saml_sso/img/scim_advanced.png
index 3b70e3fbe83..c9e095dc89a 100644
--- a/doc/user/group/saml_sso/img/scim_advanced.png
+++ b/doc/user/group/saml_sso/img/scim_advanced.png
diff --git a/doc/user/group/saml_sso/img/scim_attribute_mapping.png b/doc/user/group/saml_sso/img/scim_attribute_mapping.png
index c9f6b71f5b0..933d8fb6f36 100644
--- a/doc/user/group/saml_sso/img/scim_attribute_mapping.png
+++ b/doc/user/group/saml_sso/img/scim_attribute_mapping.png
diff --git a/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png b/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png
new file mode 100644
index 00000000000..f9c63970f16
--- /dev/null
+++ b/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png
diff --git a/doc/user/group/saml_sso/img/scim_provisioning_status.png b/doc/user/group/saml_sso/img/scim_provisioning_status.png
new file mode 100644
index 00000000000..41466ec9276
--- /dev/null
+++ b/doc/user/group/saml_sso/img/scim_provisioning_status.png
diff --git a/doc/user/group/saml_sso/img/scim_token.png b/doc/user/group/saml_sso/img/scim_token.png
index 7eb52bf6ea2..bf9347716e9 100644
--- a/doc/user/group/saml_sso/img/scim_token.png
+++ b/doc/user/group/saml_sso/img/scim_token.png
diff --git a/doc/user/group/saml_sso/img/unlink_group_saml.png b/doc/user/group/saml_sso/img/unlink_group_saml.png
index 0561443b5f4..9d53a9bf407 100644
--- a/doc/user/group/saml_sso/img/unlink_group_saml.png
+++ b/doc/user/group/saml_sso/img/unlink_group_saml.png
diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md
index fcfd638f185..e3f657af564 100644
--- a/doc/user/group/saml_sso/index.md
+++ b/doc/user/group/saml_sso/index.md
@@ -2,7 +2,7 @@
 type: reference, howto
 ---
 
-# SAML SSO for GitLab.com Groups **[SILVER ONLY]**
+# SAML SSO for GitLab.com Groups **(SILVER ONLY)**
 
 > Introduced in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.0.
 
@@ -35,6 +35,8 @@ SSO enforcement was:
 
 With this option enabled, users must use your group's GitLab single sign on URL to be added to the group or be added via SCIM. Users cannot be added manually, and may only access project/group resources via the UI by signing in through the SSO URL.
 
+However, users will not be prompted to log via SSO on each visit. GitLab will check whether a user has authenticated through the SSO link, and will only prompt the user to login via SSO if it has been longer than 7 days.
+
 We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab-ee/issues/9152) in the future.
 
 ### NameID
@@ -69,7 +71,7 @@ Once you've set up your identity provider to work with GitLab, you'll need to co
 1. Navigate to the group's **Settings > SAML SSO**.
 1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign on URL** field.
 1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field.
-1. Check the **Enable SAML authentication for this group** checkbox.
+1. Click the **Enable SAML authentication for this group** toggle switch.
 1. Click the **Save changes** button.
 
 ![Group SAML Settings for GitLab.com](img/group_saml_settings.png)
diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md
index 96cc523f4ec..5d136ad62da 100644
--- a/doc/user/group/saml_sso/scim_setup.md
+++ b/doc/user/group/saml_sso/scim_setup.md
@@ -2,7 +2,7 @@
 type: howto, reference
 ---
 
-# SCIM provisioning using SAML SSO for Groups **[SILVER ONLY]**
+# SCIM provisioning using SAML SSO for Groups **(SILVER ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10.
 
@@ -24,28 +24,28 @@ The following identity providers are supported:
 
 ## Requirements
 
-- [Group SSO](index.md) needs to be configured. 
+- [Group SSO](index.md) needs to be configured.
 - The `scim_group` feature flag must be enabled:
 
-    Run the following commands in a Rails console:
-    
-    ```sh
-    # Omnibus GitLab
-    gitlab-rails console
-    
-    # Installation from source
-    cd /home/git/gitlab
-    sudo -u git -H bin/rails console RAILS_ENV=production
-    ```
-    
-    To enable SCIM for a group named `group_name`:
-    
-    ```ruby
-    group = Group.find_by_full_path('group_name')
-    Feature.enable(:group_scim, group)
-    ```
-    
-### GitLab configuration
+  Run the following commands in a Rails console:
+
+  ```sh
+  # Omnibus GitLab
+  gitlab-rails console
+
+  # Installation from source
+  cd /home/git/gitlab
+  sudo -u git -H bin/rails console RAILS_ENV=production
+  ```
+
+  To enable SCIM for a group named `group_name`:
+
+  ```ruby
+  group = Group.find_by_full_path('group_name')
+  Feature.enable(:group_scim, group)
+  ```
+
+## GitLab configuration
 
 Once [Single sign-on](index.md) has been configured, we can:
 
@@ -53,70 +53,86 @@ Once [Single sign-on](index.md) has been configured, we can:
 1. Click on the **Generate a SCIM token** button.
 1. Save the token and URL so they can be used in the next step.
 
-![SCIM token configuration](img/scim_token.png)    
+![SCIM token configuration](img/scim_token.png)
 
-## SCIM IdP configuration
+## Identity Provider configuration
 
-### Configuration on Azure
+### Azure
 
-In the [Single sign-on](index.md) configuration for the group, make sure
-that the **Name identifier value** (NameID) points to a unique identifier, such
-as the `user.objectid`. This will match the `extern_uid`  used on GitLab.
+The SAML application that was created during [Single sign-on](index.md) setup now needs to be set up for SCIM.
 
-The GitLab app in Azure needs to be configured following 
-[Azure's SCIM setup](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#getting-started).
+1. Check the configuration for your GitLab SAML app and ensure that **Name identifier value** (NameID) points to `user.objectid` or another unique identifier. This will match the `extern_uid` used on GitLab.
 
-Note the following:
+   ![Name identifier value mapping](img/scim_name_identifier_mapping.png)
+
+1. Set up automatic provisioning and administrative credentials by following the
+   [Provisioning users and groups to applications that support SCIM](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim) section in Azure's SCIM setup documentation.
+
+During this configuration, note the following:
 
 - The `Tenant URL` and `secret token` are the ones retrieved in the
-[previous step](#gitlab-configuration).
+  [previous step](#gitlab-configuration).
 - Should there be any problems with the availability of GitLab or similar
-errors, the notification email set will get those.
+  errors, the notification email set will get those.
+- It is recommended to set a notification email and check the **Send an email notification when a failure occurs** checkbox.
 - For mappings, we will only leave `Synchronize Azure Active Directory Users to AppName` enabled.
 
-You can then test the connection clicking on `Test Connection`.
+You can then test the connection by clicking on **Test Connection**. If the connection is successful, be sure to save your configuration before moving on. See below for [troubleshooting](#troubleshooting).
+
+#### Configure attribute mapping
+
+1. Click on `Synchronize Azure Active Directory Users to AppName`, to configure the attribute mapping.
+1. Click **Delete** next to the `mail` mapping.
+1. Map `userPrincipalName` to `emails[type eq "work"].value` and change it's **Matching precedence** to `2`.
+1. Map `mailNickname` to `userName`.
+1. Create a new mapping by clicking **Add New Mapping** then set **Source attribute** to `objectId`, **Target attribute** to `id`, **Match objects using this attribute** to `Yes`, and **Matching precedence** to `1`.
+1. Create a new mapping by clicking **Add New Mapping** then set **Source attribute** to `objectId`, and **Target attribute** to `externalId`.
+1. Click the `userPrincipalName` mapping and change **Match objects using this attribute** to `No`.
 
-### Synchronize Azure Active Directory users
+   Save your changes and you should have the following configuration:
 
-1. Click on `Synchronize Azure Active Directory Users to AppName`, to configure
-the attribute mapping.
-1. Select the unique identifier (in the example `objectId`) as the `id` and `externalId`,
-and enable the `Create`, `Update`, and `Delete` actions.
-1. Map the `userPricipalName` to `emails[type eq "work"].value` and `mailNickname` to
-`userName`.
+   ![Azure's attribute mapping configuration](img/scim_attribute_mapping.png)
 
-    Example configuration:
-    
-    ![Azure's attribute mapping configuration](img/scim_attribute_mapping.png)
+   NOTE: **Note:** If you used a unique identifier **other than** `objectId`, be sure to map it instead to both `id` and `externalId`.
+
+1. Below the mapping list click on **Show advanced options > Edit attribute list for AppName**.
 
-1. Click on **Show advanced options > Edit attribute list for AppName**.
 1. Leave the `id` as the primary and only required field.
 
-    NOTE: **Note:**
-    `username` should neither be primary nor required as we don't support
-    that field on GitLab SCIM yet.
-    
-    ![Azure's attribute advanced configuration](img/scim_advanced.png)
+   NOTE: **Note:**
+   `username` should neither be primary nor required as we don't support
+   that field on GitLab SCIM yet.
+
+   ![Azure's attribute advanced configuration](img/scim_advanced.png)
 
 1. Save all the screens and, in the **Provisioning** step, set
-the `Provisioning Status` to `ON`.
+   the `Provisioning Status` to `On`.
 
-    NOTE: **Note:**
-    You can control what is actually synced by selecting the `Scope`. For example,
-    `Sync only assigned users and groups` will only sync the users assigned to
-    the application (`Users and groups`), otherwise it will sync the whole Active Directory.
+   ![Provisioning status toggle switch](img/scim_provisioning_status.png)
+
+   NOTE: **Note:**
+   You can control what is actually synced by selecting the `Scope`. For example,
+   `Sync only assigned users and groups` will only sync the users assigned to
+   the application (`Users and groups`), otherwise, it will sync the whole Active Directory.
 
 Once enabled, the synchronization details and any errors will appear on the
 bottom of the **Provisioning** screen, together with a link to the audit logs.
 
-<!-- ## Troubleshooting
+## Troubleshooting
+
+### Testing Azure connection: invalid credentials
+
+When testing the connection, you may encounter an error: **You appear to have entered invalid credentials. Please confirm you are using the correct information for an administrative account**. If `Tenant URL` and `secret token` are correct, check whether your group path contains characters that may be considered invalid JSON primitives (such as `.`). Removing such characters from the group path typically resolves the error.
+
+### Azure: (Field) can't be blank sync error
+
+When checking the Audit Logs for the Provisioning, you can sometimes see the
+error `Namespace can't be blank, Name can't be blank, and User can't be blank.`
+
+This is likely caused because not all required fields (such as first name and last name) are present for all users being mapped.
 
-Include any troubleshooting steps that you can foresee. If you know beforehand what issues
-one might have when setting this up, or when something is changed, or on upgrading, it's
-important to describe those, too. Think of things that may go wrong and include them here.
-This is important to minimize requests for support, and to avoid doc comments with
-questions that you know someone might ask.
+As a workaround, try an alternate mapping:
 
-Each scenario can be a third-level heading, e.g. `### Getting error message X`.
-If you have none to add when creating a doc, leave this section in place
-but commented out to help encourage others to add to it in the future. -->
+1. Follow the Azure mapping instructions from above.
+1. Delete the `name.formatted` target attribute entry.
+1. Change the `displayName` source attribute to have `name.formatted` target attribute.
diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md
index 79ae94dd9ef..2eb3fae1a85 100644
--- a/doc/user/group/subgroups/index.md
+++ b/doc/user/group/subgroups/index.md
@@ -5,8 +5,7 @@ type: reference, howto, concepts
 # Subgroups
 
 NOTE: **Note:**
-[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2772) in GitLab 9.0. Not available when using MySQL as external
-database (support removed in GitLab 9.3 [due to performance reasons](https://gitlab.com/gitlab-org/gitlab-ce/issues/30472#note_27747600)).
+[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2772) in GitLab 9.0.
 
 Subgroups, also known as nested groups or hierarchical groups, allow you to have up to 20
 levels of groups.
@@ -21,16 +20,6 @@ By using subgroups you can do the following:
 - **Make it easier to manage people and control visibility.** Give people
   different [permissions](../../permissions.md#group-members-permissions) depending on their group [membership](#membership).
 
-## Database Requirements
-
-Subgroups are only supported when you use PostgreSQL. Supporting subgroups on MySQL in an
-efficient way is not possible due to MySQL's limitations.
-
-See the following links for more information:
-
-- <https://gitlab.com/gitlab-org/gitlab-ce/issues/30472>
-- <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10885>
-
 ## Overview
 
 A group can have many subgroups inside it, and at the same time a group can have
@@ -39,39 +28,39 @@ only 1 parent group. It resembles a directory behavior or a nested items list:
 - Group 1
   - Group 1.1
   - Group 1.2
-      - Group 1.2.1
-      - Group 1.2.2
-          - Group 1.2.2.1
+    - Group 1.2.1
+    - Group 1.2.2
+      - Group 1.2.2.1
 
 In a real world example, imagine maintaining a GNU/Linux distribution with the
 first group being the name of the distribution, and subsequent groups split as follows:
 
 - Organization Group - GNU/Linux distro
   - Category Subgroup - Packages
-      - (project) Package01
-      - (project) Package02
+    - (project) Package01
+    - (project) Package02
   - Category Subgroup - Software
-      - (project) Core
-      - (project) CLI
-      - (project) Android app
-      - (project) iOS app
+    - (project) Core
+    - (project) CLI
+    - (project) Android app
+    - (project) iOS app
   - Category Subgroup - Infra tools
-      - (project) Ansible playbooks
+    - (project) Ansible playbooks
 
 Another example of GitLab as a company would be the following:
 
 - Organization Group - GitLab
   - Category Subgroup - Marketing
-      - (project) Design
-      - (project) General
+    - (project) Design
+    - (project) General
   - Category Subgroup - Software
-      - (project) GitLab CE
-      - (project) GitLab EE
-      - (project) Omnibus GitLab
-      - (project) GitLab Runner
-      - (project) GitLab Pages daemon
+    - (project) GitLab CE
+    - (project) GitLab EE
+    - (project) Omnibus GitLab
+    - (project) GitLab Runner
+    - (project) GitLab Pages daemon
   - Category Subgroup - Infra tools
-      - (project) Chef cookbooks
+    - (project) Chef cookbooks
   - Category Subgroup - Executive team
 
 ---
@@ -85,27 +74,37 @@ structure.
 
 ## Creating a subgroup
 
-NOTE: **Note:**
-You must be an Owner of a group to create a subgroup. For
-more information check the [permissions table](../../permissions.md#group-members-permissions).
-For a list of words that are not allowed to be used as group names see the
+To create a subgroup you must either be an Owner or a Maintainer of the
+group, depending on the group's setting.
+
+By default, groups created in:
+
+- GitLab 12.2 or later allow both Owners and Maintainers to create subgroups.
+- GitLab 12.1 or earlier only allow Owners to create subgroups.
+
+This setting can be for any group by an Owner or Administrator.
+
+For more information check the
+[permissions table](../../permissions.md#group-members-permissions). For a list
+of words that are not allowed to be used as group names see the
 [reserved names](../../reserved_names.md).
-Users can always create subgroups if they are explicitly added as an Owner to
-a parent group, even if group creation is disabled by an administrator in their
-settings.
+
+Users can always create subgroups if they are explicitly added as an Owner (or
+Maintainer, if that setting is enabled) to a parent group, even if group
+creation is disabled by an administrator in their settings.
 
 To create a subgroup:
 
 1. In the group's dashboard expand the **New project** split button, select
    **New subgroup** and click the **New subgroup** button.
 
-    ![Subgroups page](img/create_subgroup_button.png)
+   ![Subgroups page](img/create_subgroup_button.png)
 
 1. Create a new group like you would normally do. Notice that the parent group
    namespace is fixed under **Group path**. The visibility level can differ from
    the parent group.
 
-    ![Subgroups page](img/create_new_group.png)
+   ![Subgroups page](img/create_new_group.png)
 
 1. Click the **Create group** button and you will be taken to the new group's
    dashboard page.
diff --git a/doc/user/img/color_inline_colorchip_render_gfm.png b/doc/user/img/color_inline_colorchip_render_gfm.png
deleted file mode 100644
index 6f93dbeeb10..00000000000
--- a/doc/user/img/color_inline_colorchip_render_gfm.png
+++ /dev/null
diff --git a/doc/user/img/markdown_inline_diffs_tags_rendered.png b/doc/user/img/markdown_inline_diffs_tags_rendered.png
deleted file mode 100644
index 4279a20b5a0..00000000000
--- a/doc/user/img/markdown_inline_diffs_tags_rendered.png
+++ /dev/null
diff --git a/doc/user/img/math_inline_sup_render_gfm.png b/doc/user/img/math_inline_sup_render_gfm.png
deleted file mode 100644
index 3ee2abb14df..00000000000
--- a/doc/user/img/math_inline_sup_render_gfm.png
+++ /dev/null
diff --git a/doc/user/img/task_list_ordered_render_gfm.png b/doc/user/img/task_list_ordered_render_gfm.png
deleted file mode 100644
index 98ec791e958..00000000000
--- a/doc/user/img/task_list_ordered_render_gfm.png
+++ /dev/null
diff --git a/doc/user/index.md b/doc/user/index.md
index 1fc4e4c43cf..c93f64cd528 100644
--- a/doc/user/index.md
+++ b/doc/user/index.md
@@ -2,7 +2,7 @@
 description: 'Read through the GitLab User documentation to learn how to use, configure, and customize GitLab and GitLab.com to your own needs.'
 ---
 
-# User documentation
+# User Docs
 
 Welcome to GitLab! We're glad to have you here!
 
@@ -66,7 +66,7 @@ With GitLab Enterprise Edition, you can also:
 - Leverage continuous delivery method with [Canary Deployments](project/canary_deployments.md).
 - Scan your code for vulnerabilities and [display them in merge requests](application_security/sast/index.md).
 
-You can also [integrate](project/integrations/project_services.md) GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, HipChat, Trello, Slack, Bamboo CI, JIRA, and a lot more.
+You can also [integrate](project/integrations/project_services.md) GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, HipChat, Trello, Slack, Bamboo CI, Jira, and a lot more.
 
 ## Projects
 
@@ -124,12 +124,12 @@ merge requests, code snippets, and commits.
 
 When performing inline reviews to implementations
 to your codebase through merge requests you can
-gather feedback through [resolvable discussions](discussions/index.md#resolvable-comments-and-discussions).
+gather feedback through [resolvable threads](discussions/index.md#resolvable-comments-and-threads).
 
 ### GitLab Flavored Markdown (GFM)
 
 Read through the [GFM documentation](markdown.md) to learn how to apply
-the best of GitLab Flavored Markdown in your discussions, comments,
+the best of GitLab Flavored Markdown in your threads, comments,
 issues and merge requests descriptions, and everywhere else GMF is
 supported.
 
@@ -148,12 +148,12 @@ requests you're assigned to.
 
 [Snippets](snippets.md) are code blocks that you want to store in GitLab, from which
 you have quick access to. You can also gather feedback on them through
-[discussions](#discussions).
+[Discussions](#Discussions).
 
 ## Integrations
 
 [Integrate GitLab](../integration/README.md) with your preferred tool,
-such as Trello, JIRA, etc.
+such as Trello, Jira, etc.
 
 ## Webhooks
 
@@ -173,7 +173,7 @@ Learn what is [Git](../topics/git/index.md) and its best practices.
 
 See [various statistics](instance_statistics/index.md) of your GitLab instance.
 
-## Operations Dashboard **[PREMIUM]**
+## Operations Dashboard **(PREMIUM)**
 
 See [Operations Dashboard](operations_dashboard/index.md) for a summary of each
 project's operational health.
diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md
index 894f83d3c75..f557dcf4b3c 100644
--- a/doc/user/instance/clusters/index.md
+++ b/doc/user/instance/clusters/index.md
@@ -1,7 +1,6 @@
 # Instance-level Kubernetes clusters
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/39840) in GitLab 11.11.
-> Instance-level cluster integration is currently in [Beta](https://about.gitlab.com/handbook/product/#alpha-beta-ga).
 
 ## Overview
 
diff --git a/doc/user/markdown.md b/doc/user/markdown.md
index 31c8093ced7..6cfc8b6429b 100644
--- a/doc/user/markdown.md
+++ b/doc/user/markdown.md
@@ -1,15 +1,20 @@
 # GitLab Markdown
 
-This markdown guide is **valid for GitLab's system markdown entries and files**.
-It is not valid for the [GitLab documentation website](https://docs.gitlab.com)
-nor [GitLab's main website](https://about.gitlab.com), as they both use
-[Kramdown](https://kramdown.gettalong.org) as their markdown engine.
-The documentation website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown).
-Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) for a complete Kramdown reference.
+This markdown guide is **valid only for GitLab's internal markdown rendering system for entries and files**.
+It is **not** valid for the [GitLab documentation website](https://docs.gitlab.com)
+or [GitLab's main website](https://about.gitlab.com), as they both use
+[Kramdown](https://kramdown.gettalong.org) as their markdown engine. The documentation
+website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown).
+Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/)
+for a complete Kramdown reference.
+
+NOTE: **Note:** We encourage you to view this document as [rendered by GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md).
 
 ## GitLab Flavored Markdown (GFM)
 
-GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification][commonmark-spec] (which is based on standard Markdown) in a few significant ways to add additional useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/).
+GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification](https://spec.commonmark.org/current/)
+(which is based on standard Markdown) in several ways to add additional useful functionality.
+It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/).
 
 You can use GFM in the following areas:
 
@@ -20,37 +25,31 @@ You can use GFM in the following areas:
 - Snippets (the snippet must be named with a `.md` extension)
 - Wiki pages
 - Markdown documents inside repositories
-- Epics **[ULTIMATE]**
-
-You can also use other rich text files in GitLab. You might have to install a
-dependency to do so. Please see the [`github-markup` gem readme](https://github.com/gitlabhq/markup#markups) for more information.
-
-> **Notes:**
->
-> We encourage you to view this document as [rendered by GitLab itself](markdown.md).
->
-> As of 11.1, GitLab uses the [CommonMark Ruby Library][commonmarker] for Markdown
-processing of all new issues, merge requests, comments, and other Markdown content
-in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the
-repositories are also processed with CommonMark. As of 11.8, the [Redcarpet
-Ruby library][redcarpet] has been removed and all issues/comments, including
-those from pre-11.1, are now processed using [CommonMark Ruby
-Library][commonmarker].
->
-> The documentation website had its [markdown engine migrated from Redcarpet to Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108)
-in October 2018.
->
-> _Where there are significant differences, we will try to call them out in this document._
+- Epics **(ULTIMATE)**
+
+You can also use other rich text files in GitLab. You might have to install a dependency
+to do so. Please see the [`gitlab-markup` gem project](https://gitlab.com/gitlab-org/gitlab-markup)
+for more information.
 
-### Transitioning to CommonMark
+### Transition from Redcarpet to CommonMark
+
+Since 11.1, GitLab uses the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker)
+for Markdown processing of all new issues, merge requests, comments, and other Markdown
+content in the GitLab system. Since 11.3, wiki pages and Markdown files (`*.md`) in
+repositories are also processed with CommonMark. As of 11.8, the [Redcarpet Ruby library](https://github.com/vmg/redcarpet)
+has been removed and all issues and comments, including those from pre-11.1, are now processed
+using the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker).
+
+The documentation website had its [markdown engine migrated from Redcarpet to Kramdown](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/108)
+in October 2018.
 
-You may have older issues/merge requests or Markdown documents in your
-repository that were written using some of the nuances of RedCarpet's version
+You may have older issues, merge requests, or Markdown documents in your
+repository that were written using some of the nuances of GitLab's RedCarpet version
 of Markdown. Since CommonMark uses a slightly stricter syntax, these documents
-may now display a little strangely since we've transitioned to CommonMark.
-Numbered lists with nested lists in particular can be displayed incorrectly.
+may now display a little differently since we've transitioned to CommonMark.
 
-It is usually quite easy to fix.  In the case of a nested list such as this:
+It is usually quite easy to fix. For example, numbered lists with nested lists may
+render incorrectly:
 
 ```markdown
 1. Chocolate
@@ -58,7 +57,14 @@ It is usually quite easy to fix.  In the case of a nested list such as this:
   - milk
 ```
 
-simply add a space to each nested item:
+1. Chocolate
+  - dark
+  - milk
+
+---
+
+Simply add a space to each nested item to align the `-` with the first character of
+the top list item (`C` in this case):
 
 ```markdown
 1. Chocolate
@@ -66,776 +72,925 @@ simply add a space to each nested item:
    - milk
 ```
 
-In the documentation below, we try to highlight some of the differences.
+1. Chocolate
+   - dark
+   - milk
+
+NOTE: **Note:** We will flag any significant differences between Redcarpet and CommonMark
+  markdown in this document.
 
 If you have a large volume of Markdown files, it can be tedious to determine
-if they will be displayed correctly or not. You can use the
+if they will display correctly or not. You can use the
 [diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark)
-tool (not an officially supported product) to generate a list of files and
+tool (not an officially supported product) to generate a list of files, and the
 differences between how RedCarpet and CommonMark render the files. It can give
-you a great idea if anything needs to be changed - many times nothing will need
-to changed.
+an indication if anything needs to be changed - often nothing will need
+to change.
+
+### GFM extends standard markdown
+
+GitLab makes full use of the standard (CommonMark) formatting, but also includes additional
+functionality useful for GitLab users.
+
+It makes use of [new markdown features](#new-GFM-markdown-extensions),
+not found in standard markdown:
+
+- [Color "chips" written in HEX, RGB or HSL](#colors)
+- [Diagrams and flowcharts using Mermaid](#diagrams-and-flowcharts-using-mermaid)
+- [Emoji](#emoji)
+- [Front matter](#front-matter)
+- [Inline diffs](#inline-diff)
+- [Math equations and symbols written in LaTeX](#math)
+- [Special GitLab references](#special-gitlab-references)
+- [Task Lists](#task-lists)
+- [Wiki specific markdown](#wiki-specific-markdown)
+
+It also has [extended markdown features](#standard-markdown-and-extensions-in-gitlab), without
+changing how standard markdown is used:
+
+| Standard markdown                     | Extended markdown in GitLab |
+| ------------------------------------- | ------------------------- |
+| [blockquotes](#blockquotes)           | [multiline blockquotes](#multiline-blockquote) |
+| [code blocks](#code-spans-and-blocks) | [colored code and syntax highlighting](#colored-code-and-syntax-highlighting) |
+| [emphasis](#emphasis)                 | [multiple underscores in words](#multiple-underscores-in-words-and-mid-word-emphasis)
+| [headers](#headers)                   | [linkable Header IDs](#header-ids-and-links) |
+| [images](#images)                     | [embedded videos](#videos) |
+| [linebreaks](#line-breaks)            | [more linebreak control](#newlines) |
+| [links](#links)                       | [automatically linking URLs](#url-auto-linking) |
+
+## New GFM markdown extensions
 
-### Newlines
+### Colors
 
-> If this is not rendered correctly, see
-https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newlines
+> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#colors).
 
-GFM honors the markdown specification in how [paragraphs and line breaks are handled][commonmark-spec].
+It is possible to have color written in HEX, RGB or HSL format rendered with a color
+indicator.
 
-A paragraph is simply one or more consecutive lines of text, separated by one or
-more blank lines.
-Line-breaks, or soft returns, are rendered if you end a line with two or more spaces:
+Supported formats (named colors are not supported):
 
-<!-- (Do *NOT* remove the two ending whitespaces in the following line.) -->
-<!-- (They are needed for the Markdown text to render correctly.) -->
-    Roses are red [followed by two or more spaces]  
-    Violets are blue
+- HEX: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` ``
+- RGB: `` `RGB[A](R, G, B[, A])` ``
+- HSL: `` `HSL[A](H, S, L[, A])` ``
 
-    Sugar is sweet
+Color written inside backticks will be followed by a color "chip":
 
-<!-- (Do *NOT* remove the two ending whitespaces in the following line.) -->
-<!-- (They are needed for the Markdown text to render correctly.) -->
-Roses are red  
-Violets are blue
+```markdown
+`#F00`  
+`#F00A`  
+`#FF0000`  
+`#FF0000AA`  
+`RGB(0,255,0)`  
+`RGB(0%,100%,0%)`  
+`RGBA(0,255,0,0.3)`  
+`HSL(540,70%,50%)`  
+`HSLA(540,70%,50%,0.3)`  
+```
 
-Sugar is sweet
+`#F00`  
+`#F00A`  
+`#FF0000`  
+`#FF0000AA`  
+`RGB(0,255,0)`  
+`RGB(0%,100%,0%)`  
+`RGBA(0,255,0,0.3)`  
+`HSL(540,70%,50%)`  
+`HSLA(540,70%,50%,0.3)`  
 
-### Multiple underscores in words
+### Diagrams and flowcharts using Mermaid
 
-> If this is not rendered correctly, see
-https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15107) in
+GitLab 10.3.
 
-It is not reasonable to italicize just _part_ of a word, especially when you're
-dealing with code and names that often appear with multiple underscores.
-Therefore, GFM ignores multiple underscores in words:
+It is possible to generate diagrams and flowcharts from text using [Mermaid](https://mermaidjs.github.io/).
+Visit the official page for more details.
 
-    perform_complicated_task
+In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block:
 
-    do_this_and_do_that_and_another_thing
+~~~
+```mermaid
+graph TD;
+  A-->B;
+  A-->C;
+  B-->D;
+  C-->D;
+```
+~~~
 
-perform_complicated_task
+```mermaid
+graph TD;
+  A-->B;
+  A-->C;
+  B-->D;
+  C-->D;
+```
 
-do_this_and_do_that_and_another_thing
+#### Subgraphs
+
+NOTE: **Note:** GitLab 12.1 and up now [requires quotes around subgraph
+titles that contain multiple words](https://github.com/knsv/mermaid/pull/845).
+
+Subgraphs can also be included:
 
-### URL auto-linking
+~~~
+```mermaid
+graph TB
+
+  SubGraph1 --> SubGraph1Flow
+  subgraph "SubGraph 1 Flow"
+  SubGraph1Flow(SubNode 1)
+  SubGraph1Flow -- Choice1 --> DoChoice1
+  SubGraph1Flow -- Choice2 --> DoChoice2
+  end
+
+  subgraph "Main Graph"
+  Node1[Node 1] --> Node2[Node 2]
+  Node2 --> SubGraph1[Jump to SubGraph1]
+  SubGraph1 --> FinalThing[Final Thing]
+end
+```
+~~~
 
-> If this is not rendered correctly, see
-https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#url-auto-linking
+```mermaid
+graph TB
+
+  SubGraph1 --> SubGraph1Flow
+  subgraph "SubGraph 1 Flow"
+  SubGraph1Flow(SubNode 1)
+  SubGraph1Flow -- Choice1 --> DoChoice1
+  SubGraph1Flow -- Choice2 --> DoChoice2
+  end
+
+  subgraph "Main Graph"
+  Node1[Node 1] --> Node2[Node 2]
+  Node2 --> SubGraph1[Jump to SubGraph1]
+  SubGraph1 --> FinalThing[Final Thing]
+end
+```
 
-GFM will autolink almost any URL you copy and paste into your text:
+### Emoji
 
-    * https://www.google.com
-    * https://google.com/
-    * ftp://ftp.us.debian.org/debian/
-    * smb://foo/bar/baz
-    * irc://irc.freenode.net/gitlab
-    * http://localhost:3000
+> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#emoji).
 
-* https://www.google.com
-* https://google.com/
-* ftp://ftp.us.debian.org/debian/
-* <a href="smb://foo/bar/baz">smb://foo/bar/baz</a>
-* <a href="irc://irc.freenode.net/gitlab">irc://irc.freenode.net/gitlab</a>
-* http://localhost:3000
+```md
+Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you:
 
-### Multiline blockquote
+:zap: You can use emoji anywhere GFM is supported. :v:
 
-> If this is not rendered correctly, see
-https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiline-blockquote
+You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that.
 
-On top of standard Markdown [blockquotes](#blockquotes), which require prepending `>` to quoted lines,
-GFM supports multiline blockquotes fenced by <code>>>></code>:
+If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes.
 
+Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup:
 ```
->>>
-If you paste a message from somewhere else
 
-that
+Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px" style="display:inline;margin:0"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px" style="display:inline;margin:0"> to your <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0">. Well we have a gift for you:
 
-spans
+<img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px" style="display:inline;margin:0">You can use emoji anywhere GFM is supported. <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px" style="display:inline;margin:0">
 
-multiple lines,
+You can use it to point out a <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/bug.png" width="20px" height="20px" style="display:inline;margin:0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0"> patches. And if someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/snail.png" width="20px" height="20px" style="display:inline;margin:0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/birthday.png" width="20px" height="20px" style="display:inline;margin:0">. People will <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0"> you for that.
 
-you can quote that without having to manually prepend `>` to every line!
->>>
-```
+If you are new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0">. You can easily join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0">. All you need to do is to look up one of the supported codes.
 
-<blockquote dir="auto">
-<p>If you paste a message from somewhere else</p>
-<p>that</p>
-<p>spans</p>
-<p>multiple lines,</p>
-<p>you can quote that without having to manually prepend <code>&gt;</code> to every line!</p>
-</blockquote>
+Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0">
 
-### Code and syntax highlighting
+> **Note:** The emoji example above uses hard-coded images for this documentation. The emoji,
+when rendered within GitLab, may appear different depending on the OS and browser used.
 
-> If this is not rendered correctly, see
-https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting
+Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support.
 
-_GitLab uses the [Rouge Ruby library][rouge] for syntax highlighting. For a
-list of supported languages visit the Rouge website._
+NOTE: **Note:** On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/)
+to get full native emoji support. Ubuntu 18.04 (like many modern Linux distros) has
+this font installed by default.
 
-Blocks of code are either fenced by lines with three back-ticks <code>```</code>,
-or are indented with four spaces. Only the fenced code blocks support syntax
-highlighting:
+### Front matter
 
-```
-Inline `code` has `back-ticks around` it.
-```
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23331)
+  in GitLab 11.6.
 
-Inline `code` has `back-ticks around` it.
+Front matter is metadata included at the beginning of a markdown document, preceding
+its content. This data can be used by static site generators such as [Jekyll](https://jekyllrb.com/docs/front-matter/),
+[Hugo](https://gohugo.io/content-management/front-matter/), and many other applications.
 
-Example:
+When you view a Markdown file rendered by GitLab, any front matter is displayed as-is,
+in a box at the top of the document, before the rendered HTML content. To view an example,
+you can toggle between the source and rendered version of a [GitLab documentation file](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/README.md).
 
-    ```javascript
-    var s = "JavaScript syntax highlighting";
-    alert(s);
-    ```
+In GitLab, front matter is only used in Markdown files and wiki pages, not the other
+places where Markdown formatting is supported. It must be at the very top of the document,
+and must be between delimiters, as explained below.
 
-    ```python
-    def function():
-        #indenting works just fine in the fenced code block
-        s = "Python syntax highlighting"
-        print s
-    ```
+The following delimeters are supported:
 
-    ```ruby
-    require 'redcarpet'
-    markdown = Redcarpet.new("Hello World!")
-    puts markdown.to_html
-    ```
+- YAML (`---`):
 
-    ```
-    No language indicated, so no syntax highlighting.
-    s = "There is no highlighting for this."
-    But let's throw in a <b>tag</b>.
-    ```
+  ~~~yaml
+  ---
+  title: About Front Matter
+  example:
+  language: yaml
+  ---
+  ~~~
 
-becomes:
+- TOML (`+++`):
 
-```javascript
-var s = "JavaScript syntax highlighting";
-alert(s);
-```
+  ~~~toml
+  +++
+  title = "About Front Matter"
+  [example]
+  language = "toml"
+  +++
+  ~~~
 
-```python
-def function():
-    #indenting works just fine in the fenced code block
-    s = "Python syntax highlighting"
-    print s
-```
+- JSON (`;;;`):
 
-```ruby
-require 'redcarpet'
-markdown = Redcarpet.new("Hello World!")
-puts markdown.to_html
-```
+  ~~~json
+  ;;;
+  {
+    "title": "About Front Matter"
+    "example": {
+      "language": "json"
+    }
+  }
+  ;;;
+  ~~~
 
-```
-No language indicated, so no syntax highlighting.
-s = "There is no highlighting for this."
-But let's throw in a <b>tag</b>.
+Other languages are supported by adding a specifier to any of the existing
+delimiters. For example:
+
+```php
+---php
+$title = "About Front Matter";
+$example = array(
+  'language' => "php",
+);
+---
 ```
 
 ### Inline diff
 
-> If this is not rendered correctly, see
-https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff
+> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff).
 
-With inline diffs tags you can display {+ additions +} or [- deletions -].
+With inline diff tags you can display `{+ additions +}` or `[- deletions -]`.
 
-The wrapping tags can be either curly braces or square brackets.
-
-Examples:
+The wrapping tags can be either curly braces or square brackets:
 
-```
-- {+ additions +}
-- [+ additions +]
-- {- deletions -}
-- [- deletions -]
+```markdown
+- {+ addition 1 +}
+- [+ addition 2 +]
+- {- deletion 3 -}
+- [- deletion 4 -]
 ```
 
-becomes:
+- {+ addition 1 +}
+- [+ addition 2 +]
+- {- deletion 3 -}
+- [- deletion 4 -]
 
-![inline diffs tags rendered](img/markdown_inline_diffs_tags_rendered.png)
+---
 
-However the wrapping tags cannot be mixed as such:
+However the wrapping tags cannot be mixed:
 
-```
-- {+ additions +]
-- [+ additions +}
-- {- deletions -]
-- [- deletions -}
+```markdown
+- {+ addition +]
+- [+ addition +}
+- {- deletion -]
+- [- deletion -}
 ```
 
-### Emoji
-
-```md
-Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you:
-
-:zap: You can use emoji anywhere GFM is supported. :v:
+### Math
 
-You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that.
+> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#math).
 
-If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes.
+It is possible to have math written with LaTeX syntax rendered using [KaTeX](https://github.com/Khan/KaTeX).
 
-Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup:
+Math written between dollar signs `$` will be rendered inline with the text. Math written
+inside a [code block](#code-spans-and-blocks) with the language declared as `math`, will be rendered
+on a separate line:
 
-Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support.
+~~~
+This math is inline $`a^2+b^2=c^2`$.
 
-On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support.
+This is on a separate line
 
-Ubuntu 18.04 (like many modern Linux distros) has this font installed by default.
+```math
+a^2+b^2=c^2
 ```
+~~~
 
-Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px" style="display:inline;margin:0"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px" style="display:inline;margin:0"> to your <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0">. Well we have a gift for you:
+This math is inline $`a^2+b^2=c^2`$.
 
-<img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px" style="display:inline;margin:0">You can use emoji anywhere GFM is supported. <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px" style="display:inline;margin:0">
-
-You can use it to point out a <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/bug.png" width="20px" height="20px" style="display:inline;margin:0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0"> patches. And if someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/snail.png" width="20px" height="20px" style="display:inline;margin:0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/birthday.png" width="20px" height="20px" style="display:inline;margin:0">. People will <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0"> you for that.
-
-If you are new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0">. You can easily join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0">. All you need to do is to look up one of the supported codes.
-
-Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0">
+This is on a separate line
 
-Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support.
+```math
+a^2+b^2=c^2
+```
 
-On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support.
+_Be advised that KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX._
 
-Ubuntu 18.04 (like many modern Linux distros) has this font installed by default.
+NOTE: **Note:** This also works for the asciidoctor `:stem: latexmath`. For details see
+the [asciidoctor user manual](http://asciidoctor.org/docs/user-manual/#activating-stem-support).
 
 ### Special GitLab references
 
-GFM recognizes special references.
-
-You can easily reference e.g. an issue, a commit, a team member or even the whole team within a project.
+GFM recognizes special GitLab related references. For example, you can easily reference
+an issue, a commit, a team member or even the whole team within a project. GFM will turn
+that reference into a link so you can navigate between them easily.
 
-GFM will turn that reference into a link so you can navigate between them easily.
+Additionally, GFM recognizes certain cross-project references, and also has a shorthand
+version to reference other projects from the same namespace.
 
 GFM will recognize the following:
 
-| input                      | references                      |
-|:---------------------------|:--------------------------------|
-| `@user_name`               | specific user                   |
-| `@group_name`              | specific group                  |
-| `@all`                     | entire team                     |
-| `namespace/project>`       | project                         |
-| `#12345`                   | issue                           |
-| `!123`                     | merge request                   |
-| `$123`                     | snippet                         |
-| `&123`                     | epic **[ULTIMATE]**             |
-| `~123`                     | label by ID                     |
-| `~bug`                     | one-word label by name          |
-| `~"feature request"`       | multi-word label by name        |
-| `%123`                     | project milestone by ID         |
-| `%v1.23`                   | one-word milestone by name      |
-| `%"release candidate"`     | multi-word milestone by name    |
-| `9ba12248`                 | specific commit                 |
-| `9ba12248...b19a04f5`      | commit range comparison         |
-| `[README](doc/README)`     | repository file references      |
-| `[README](doc/README#L13)` | repository file line references |
-
-GFM also recognizes certain cross-project references:
-
-| input                                   | references              |
-|:----------------------------------------|:------------------------|
-| `namespace/project#123`                 | issue                   |
-| `namespace/project!123`                 | merge request           |
-| `namespace/project%123`                 | project milestone       |
-| `namespace/project$123`                 | snippet                 |
-| `namespace/project@9ba12248`            | specific commit         |
-| `group1/subgroup&123`                   | epic **[ULTIMATE]**     |
-| `namespace/project@9ba12248...b19a04f5` | commit range comparison |
-| `namespace/project~"Some label"`        | issues with given label |
-
-It also has a shorthand version to reference other projects from the same namespace:
-
-| input                         | references              |
-|:------------------------------|:------------------------|
-| `project#123`                 | issue                   |
-| `project!123`                 | merge request           |
-| `project%123`                 | project milestone       |
-| `project$123`                 | snippet                 |
-| `project@9ba12248`            | specific commit         |
-| `project@9ba12248...b19a04f5` | commit range comparison |
-| `project~"Some label"`        | issues with given label |
+| references                      | input                      | cross-project reference                 | shortcut within same namespace |
+| :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- |
+| specific user                   | `@user_name`               |                                         |                                |
+| specific group                  | `@group_name`              |                                         |                                |
+| entire team                     | `@all`                     |                                         |                                |
+| project                         | `namespace/project>`       |                                         |                                |
+| issue                           | ``#123``                   | `namespace/project#123`                 | `project#123`                  |
+| merge request                   | `!123`                     | `namespace/project!123`                 | `project!123`                  |
+| snippet                         | `$123`                     | `namespace/project$123`                 | `project$123`                  |
+| epic **(ULTIMATE)**             | `&123`                     | `group1/subgroup&123`                   |                                |
+| label by ID                     | `~123`                     | `namespace/project~123`                 | `project~123`                  |
+| one-word label by name          | `~bug`                     | `namespace/project~bug`                 | `project~bug`                  |
+| multi-word label by name        | `~"feature request"`       | `namespace/project~"feature request"`   | `project~"feature request"`    |
+| project milestone by ID         | `%123`                     | `namespace/project%123`                 | `project%123`                  |
+| one-word milestone by name      | `%v1.23`                   | `namespace/project%v1.23`               | `project%v1.23`                |
+| multi-word milestone by name    | `%"release candidate"`     | `namespace/project%"release candidate"` | `project%"release candidate"`  |
+| specific commit                 | `9ba12248`                 | `namespace/project@9ba12248`            | `project@9ba12248`             |
+| commit range comparison         | `9ba12248...b19a04f5`      | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5`  |
+| repository file references      | `[README](doc/README)`     |                                         |                                |
+| repository file line references | `[README](doc/README#L13)` |                                         |                                |
 
 ### Task lists
 
-> If this is not rendered correctly, see
-https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-lists
+> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-lists).
 
-You can add task lists to issues, merge requests and comments. To create a task list, add a specially-formatted Markdown list, like so:
+You can add task lists anywhere markdown is supported, but you can only "click" to
+toggle the boxes if they are in issues, merge requests, or comments. In other places
+you must edit the markdown manually to change the status by adding or removing the `x`.
 
-```
+To create a task list, add a specially-formatted Markdown list. You can use either
+unordered or ordered lists:
+
+```markdown
 - [x] Completed task
 - [ ] Incomplete task
-    - [ ] Sub-task 1
-    - [x] Sub-task 2
-    - [ ] Sub-task 3
-```
+  - [ ] Sub-task 1
+  - [x] Sub-task 2
+  - [ ] Sub-task 3
 
-![alt unordered-check-list-render-gfm](img/unordered_check_list_render_gfm.png)
+1. [x] Completed task
+1. [ ] Incomplete task
+   1. [ ] Sub-task 1
+   1. [x] Sub-task 2
+```
 
-Tasks formatted as ordered lists are supported as well:
+- [x] Completed task
+- [ ] Incomplete task
+  - [ ] Sub-task 1
+  - [x] Sub-task 2
+  - [ ] Sub-task 3
 
-```
 1. [x] Completed task
 1. [ ] Incomplete task
-    1. [ ] Sub-task 1
-    1. [x] Sub-task 2
-```
+   1. [ ] Sub-task 1
+   1. [x] Sub-task 2
 
-![alt task-list-ordered-render-gfm](img/task_list_ordered_render_gfm.png)
+### Wiki-specific Markdown
 
-Task lists can only be created in descriptions, not in titles. Task item state can be managed by editing the description's Markdown or by toggling the rendered check boxes.
+The following examples show how links inside wikis behave.
 
-### Videos
+#### Wiki - Direct page link
 
-> If this is not rendered correctly, see
-https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#videos
+A link which just includes the slug for a page will point to that page,
+_at the base level of the wiki_.
 
-Image tags with a video extension are automatically converted to a video player.
+This snippet would link to a `documentation` page at the root of your wiki:
 
-The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`.
+```markdown
+[Link to Documentation](documentation)
+```
 
-    Here's a sample video:
+#### Wiki - Direct file link
 
-    ![Sample Video](img/markdown_video.mp4)
+Links with a file extension point to that file, _relative to the current page_.
 
-Here's a sample video:
+If the snippet below was placed on a page at `<your_wiki>/documentation/related`,
+it would link to `<your_wiki>/documentation/file.md`:
 
-<div class="video-container">
-   <video src="img/markdown_video.mp4" width="400" controls="true" data-setup="{}" data-title="Sample Video"></video>
-   <p><a href="img/markdown_video.mp4" target="_blank" rel="noopener noreferrer" title="Download 'Sample Video'">Sample Video</a></p>
-</div>
+```markdown
+[Link to File](file.md)
+```
 
-### Math
+#### Wiki - Hierarchical link
 
-> If this is not rendered correctly, see
-https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#math
+A link can be constructed relative to the current wiki page using `./<page>`,
+`../<page>`, etc.
 
-It is possible to have math written with the LaTeX syntax rendered using [KaTeX][katex].
+If this snippet was placed on a page at `<your_wiki>/documentation/main`,
+it would link to `<your_wiki>/documentation/related`:
 
-Math written inside ```$``$``` will be rendered inline with the text.
+```markdown
+[Link to Related Page](./related)
+```
 
-Math written inside triple back quotes, with the language declared as `math`, will be rendered on a separate line.
+If this snippet was placed on a page at `<your_wiki>/documentation/related/content`,
+it would link to `<your_wiki>/documentation/main`:
 
-Example:
+```markdown
+[Link to Related Page](../main)
+```
 
-    This math is inline $`a^2+b^2=c^2`$.
+If this snippet was placed on a page at `<your_wiki>/documentation/main`,
+it would link to `<your_wiki>/documentation/related.md`:
 
-    This is on a separate line
-    ```math
-    a^2+b^2=c^2
-    ```
+```markdown
+[Link to Related Page](./related.md)
+```
 
-Becomes:
+If this snippet was placed on a page at `<your_wiki>/documentation/related/content`,
+it would link to `<your_wiki>/documentation/main.md`:
 
-This math is inline ![alt text](img/math_inline_sup_render_gfm.png).
+```markdown
+[Link to Related Page](../main.md)
+```
 
-This is on a separate line
+#### Wiki - Root link
 
-<img src="./img/math_inline_sup_render_gfm.png" >
+A link starting with a `/` is relative to the wiki root.
 
-_Be advised that KaTeX only supports a [subset][katex-subset] of LaTeX._
+This snippet links to `<wiki_root>/documentation`:
 
->**Note:**
-This also works for the asciidoctor `:stem: latexmath`. For details see the [asciidoctor user manual][asciidoctor-manual].
+```markdown
+[Link to Related Page](/documentation)
+```
 
-### Colors
+This snippet links to `<wiki_root>/miscellaneous.md`:
 
-> If this is not rendered correctly, see
-https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#colors
+```markdown
+[Link to Related Page](/miscellaneous.md)
+```
 
-It is possible to have color written in HEX, RGB or HSL format rendered with a color indicator.
+### Embedding metrics in GitLab Flavored Markdown
 
-Color written inside backticks will be followed by a color "chip".
+Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab flavored Markdown](../user/project/integrations/prometheus.md#embedding-metric-charts-within-gitlab-flavored-markdown) for more details.
 
-Examples:
+## Standard markdown and extensions in GitLab
 
-    `#F00`
-    `#F00A`
-    `#FF0000`
-    `#FF0000AA`
-    `RGB(0,255,0)`
-    `RGB(0%,100%,0%)`
-    `RGBA(0,255,0,0.7)`
-    `HSL(540,70%,50%)`
-    `HSLA(540,70%,50%,0.7)`
+All standard markdown formatting should work as expected within GitLab. Some standard
+functionality is extended with additional features, without affecting the standard usage.
+If a functionality is extended, the new option will be listed as a sub-section.
 
-Becomes:
+### Blockquotes
 
-![alt color-inline-colorchip-render-gfm](img/color_inline_colorchip_render_gfm.png)
+Blockquotes are an easy way to highlight information, such as a side-note. It is generated
+by starting the lines of the blockquote with `>`:
 
-#### Supported formats:
+```markdown
+> Blockquotes are very handy to emulate reply text.
+> This line is part of the same quote.
 
-* HEX: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` ``
-* RGB: `` `RGB[A](R, G, B[, A])` ``
-* HSL: `` `HSL[A](H, S, L[, A])` ``
+Quote break.
 
-### Mermaid
+> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.
+```
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15107) in
-GitLab 10.3.
->
-> If this is not rendered correctly, see
-https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#mermaid
+> Blockquotes are very handy to emulate reply text.
+> This line is part of the same quote.
 
-It is possible to generate diagrams and flowcharts from text using [Mermaid](https://mermaidjs.github.io/).
+Quote break.
 
-In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block.
+> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.
 
-Example:
+#### Multiline blockquote
 
-    ```mermaid
-    graph TD;
-      A-->B;
-      A-->C;
-      B-->D;
-      C-->D;
-    ```
+> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiline-blockquote).
 
-Becomes:
+GFM extends the standard markdown standard by also supporting multiline blockquotes
+fenced by `>>>`:
 
-```mermaid
-graph TD;
-  A-->B;
-  A-->C;
-  B-->D;
-  C-->D;
 ```
+>>>
+If you paste a message from somewhere else
 
-For details see the [Mermaid official page](https://mermaidjs.github.io/).
-
-### Front matter
+that spans multiple lines,
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23331)
-  in GitLab 11.6.
+you can quote that without having to manually prepend `>` to every line!
+>>>
+```
 
-Front matter is metadata included at the beginning of a markdown document, preceding
-its content. This data can be used by static site generators such as [Jekyll](https://jekyllrb.com/docs/front-matter/) and [Hugo](https://gohugo.io/content-management/front-matter/),
-and many other applications.
+>>>
+If you paste a message from somewhere else
 
-In GitLab, front matter is only used in Markdown files and wiki pages, not the other places where Markdown formatting is supported.
-When you view a Markdown file rendered by GitLab, any front matter is displayed as-is, in a box at the top of the document, before the rendered HTML content.
-To view an example, you can toggle between the source and rendered version of a [GitLab documentation file](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/README.md).
+that spans multiple lines,
 
-The following delimeters are supported:
+you can quote that without having to manually prepend `>` to every line!
+>>>
 
-- YAML (`---`):
+### Code spans and blocks
 
-  ```
-  ---
-  title: About Front Matter
-  example:
-    language: yaml
-  ---
-  ```
+You can easily highlight anything that should be viewed as code and not simple text.
 
-- TOML (`+++`):
+Simple inline code is easily highlighted with single backticks `` ` ``:
 
-  ```
-  +++
-  title = "About Front Matter"
-  [example]
-  language = "toml"
-  +++
-  ```
+```markdown
+Inline `code` has `back-ticks around` it.
+```
 
-- JSON (`;;;`):
+Inline `code` has `back-ticks around` it.
 
-  ```
-  ;;;
-  {
-    "title": "About Front Matter"
-    "example": {
-      "language": "json"
-    }
-  }
-  ;;;
-  ```
+---
 
-Other languages are supported by adding a specifier to any of the existing
-delimiters. For example:
+Similarly, a whole block of code can be fenced with triple backticks ```` ``` ````,
+triple tildes (`~~~`), or indended 4 or more spaces to achieve a similar effect for
+a larger body of code.
 
+~~~
 ```
----php
-$title = "About Front Matter";
-$example = array(
-  'language' => "php",
-);
----
+def function():
+    #indenting works just fine in the fenced code block
+    s = "Python code"
+    print s
 ```
 
-## Standard Markdown
-
-### Headers
+    Using 4 spaces
+    is like using
+    3-backtick fences.
+~~~
 
 ```
-# H1
-## H2
-### H3
-#### H4
-##### H5
-###### H6
+~~~
+Tildes are OK too.
+~~~
+```
 
-Alternatively, for H1 and H2, an underline-ish style:
+The three examples above render as:
 
-Alt-H1
-======
+```
+def function():
+    #indenting works just fine in the fenced code block
+    s = "Python code"
+    print s
+```
 
-Alt-H2
-------
+```
+Using 4 spaces
+is like using
+3-backtick fences.
 ```
 
-#### Header IDs and links
+~~~
+Tildes are OK too.
+~~~
 
-All Markdown-rendered headers automatically get IDs, which can be linked to, except in comments.
+#### Colored code and syntax highlighting
 
-On hover, a link to those IDs becomes visible to make it easier to copy the link to the header to use it somewhere else.
+> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting).
 
-The IDs are generated from the content of the header according to the following rules:
+GitLab uses the [Rouge Ruby library](http://rouge.jneen.net/) for more colorful syntax
+highlighting in code blocks. For a list of supported languages visit the
+[Rouge project wiki](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers).
+Syntax highlighting is only supported in code blocks, it is not possible to highlight
+code when it is inline.
 
-1. All text is converted to lowercase.
-1. All non-word text (e.g., punctuation, HTML) is removed.
-1. All spaces are converted to hyphens.
-1. Two or more hyphens in a row are converted to one.
-1. If a header with the same ID has already been generated, a unique
-   incrementing number is appended, starting at 1.
+Blocks of code are fenced by lines with three back-ticks ```` ``` ```` or three tildes `~~~`, and have
+the language identified at the end of the first fence:
 
-For example:
+~~~
+```javascript
+var s = "JavaScript syntax highlighting";
+alert(s);
+```
 
+```python
+def function():
+    #indenting works just fine in the fenced code block
+    s = "Python syntax highlighting"
+    print s
 ```
-# This header has spaces in it
-## This header has a :thumbsup: in it
-# This header has Unicode in it: 한글
-## This header has spaces in it
-### This header has spaces in it
-## This header has 3.5 in it (and parentheses)
+
+```ruby
+require 'redcarpet'
+markdown = Redcarpet.new("Hello World!")
+puts markdown.to_html
 ```
 
-Would generate the following link IDs:
+```
+No language indicated, so no syntax highlighting.
+s = "There is no highlighting for this."
+But let's throw in a <b>tag</b>.
+```
+~~~
 
-1. `this-header-has-spaces-in-it`
-1. `this-header-has-a-in-it`
-1. `this-header-has-unicode-in-it-한글`
-1. `this-header-has-spaces-in-it-1`
-1. `this-header-has-spaces-in-it-2`
-1. `this-header-has-3-5-in-it-and-parentheses`
+The four examples above render as:
+
+```javascript
+var s = "JavaScript syntax highlighting";
+alert(s);
+```
 
-Note that the Emoji processing happens before the header IDs are generated, so the Emoji is converted to an image which then gets removed from the ID.
+```python
+def function():
+    #indenting works just fine in the fenced code block
+    s = "Python syntax highlighting"
+    print s
+```
+
+```ruby
+require 'redcarpet'
+markdown = Redcarpet.new("Hello World!")
+puts markdown.to_html
+```
+
+```
+No language indicated, so no syntax highlighting.
+s = "There is no highlighting for this."
+But let's throw in a <b>tag</b>.
+```
 
 ### Emphasis
 
+There are multiple ways to emphasize text in markdown. You can italicize, bold, strikethrough,
+as well as combine these emphasis styles together.
+
 Examples:
 
-```
+```markdown
 Emphasis, aka italics, with *asterisks* or _underscores_.
 
-Strong emphasis, aka bold, with **asterisks** or __underscores__.
+Strong emphasis, aka bold, with double **asterisks** or __underscores__.
 
 Combined emphasis with **asterisks and _underscores_**.
 
 Strikethrough uses two tildes. ~~Scratch this.~~
 ```
 
-Becomes:
-
 Emphasis, aka italics, with *asterisks* or _underscores_.
 
-Strong emphasis, aka bold, with **asterisks** or __underscores__.
+Strong emphasis, aka bold, with double **asterisks** or __underscores__.
 
 Combined emphasis with **asterisks and _underscores_**.
 
 Strikethrough uses two tildes. ~~Scratch this.~~
 
-### Lists
+NOTE: **Note:** Strikethrough is not part of the core Markdown standard, but is part of GFM.
 
-Examples:
+#### Multiple underscores in words and mid-word emphasis
 
-```
-1. First ordered list item
-2. Another item
-   * Unordered sub-list.
-1. Actual numbers don't matter, just that it's a number
-   1. Ordered sub-list
-4. And another item.
+> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words).
 
-* Unordered list can use asterisks
-- Or minuses
-+ Or pluses
+It is not usually useful to italicize just _part_ of a word, especially when you're
+dealing with code and names that often appear with multiple underscores. As a result,
+GFM extends the standard markdown standard by ignoring multiple underlines in words,
+to allow better rendering of markdown documents discussing code:
+
+```md
+perform_complicated_task
+
+do_this_and_do_that_and_another_thing
+
+but_emphasis is_desired _here_
 ```
 
-Becomes:
+perform_complicated_task
 
-1. First ordered list item
-2. Another item
-   * Unordered sub-list.
-1. Actual numbers don't matter, just that it's a number
-   1. Ordered sub-list
-4. And another item.
+do_this_and_do_that_and_another_thing
 
-* Unordered list can use asterisks
-- Or minuses
-+ Or pluses
+but_emphasis is_desired _here_
 
-If a list item contains multiple paragraphs,
-each subsequent paragraph should be indented to the same level as the start of the list item text
+---
 
-Example:
+If you wish to emphasize only a part of a word, it can still be done with asterisks:
+
+```md
+perform*complicated*task
 
+do*this*and*do*that*and*another thing
 ```
-1. First ordered list item
 
-   Second paragraph of first item.
+perform*complicated*task
 
-2. Another item
+do*this*and*do*that*and*another thing
+
+### Footnotes
+
+Footnotes add a link to a note rendered at the end of a markdown file:
+
+```markdown
+You can add footnotes to your text as follows.[^1]
+
+[^1]: This is my awesome footnote (later in file).
 ```
 
-Becomes:
+You can add footnotes to your text as follows.[^1]
 
-1.  First ordered list item
+[^1]: This is my awesome footnote (later in file).
 
-    Paragraph of first item.
+### Headers
 
-2.  Another item
+```markdown
+# H1
+## H2
+### H3
+#### H4
+##### H5
+###### H6
 
-If the paragraph of the first item is not indented with the proper number of spaces,
-the paragraph will appear outside the list, instead of properly indented under the list item.
+Alternatively, for H1 and H2, an underline-ish style:
 
-Example:
+Alt-H1
+======
 
+Alt-H2
+------
 ```
-1. First ordered list item
 
-  Paragraph of first item.
+#### Header IDs and links
 
-2. Another item
-```
+GFM extends the standard markdown standard so that all Markdown-rendered headers automatically
+get IDs, which can be linked to, except in comments.
 
-Becomes:
+On hover, a link to those IDs becomes visible to make it easier to copy the link to
+the header to use it somewhere else.
 
-1. First ordered list item
+The IDs are generated from the content of the header according to the following rules:
 
-  Paragraph of first item.
+1. All text is converted to lowercase.
+1. All non-word text (e.g., punctuation, HTML) is removed.
+1. All spaces are converted to hyphens.
+1. Two or more hyphens in a row are converted to one.
+1. If a header with the same ID has already been generated, a unique
+   incrementing number is appended, starting at 1.
 
-2. Another item
+Example:
 
-### Links
+```
+# This header has spaces in it
+## This header has a :thumbsup: in it
+# This header has Unicode in it: 한글
+## This header has spaces in it
+### This header has spaces in it
+## This header has 3.5 in it (and parentheses)
+```
+
+Would generate the following link IDs:
+
+1. `this-header-has-spaces-in-it`
+1. `this-header-has-a-in-it`
+1. `this-header-has-unicode-in-it-한글`
+1. `this-header-has-spaces-in-it-1`
+1. `this-header-has-spaces-in-it-2`
+1. `this-header-has-3-5-in-it-and-parentheses`
+
+Note that the Emoji processing happens before the header IDs are generated, so the
+Emoji is converted to an image which is then removed from the ID.
 
-There are two ways to create links, inline-style and reference-style.
+### Horizontal Rule
+
+It's very simple to create a horizontal rule, by using three or more hyphens, asterisks,
+or underscores:
 
 ```markdown
-[I'm an inline-style link](https://www.google.com)
-[I'm a link to a repository file in the same directory](index.md)
-[I am an absolute reference within the repository](/doc/user/index.md)
-[I'm a relative link to the Milestones page](../README.md)
+Three or more hyphens,
 
-[I link to a section on a different markdown page, using a header ID](index.md#overview)
-[I link to a different section on the same page, using the header ID](#header-ids-and-links)
+---
 
-[I'm a reference-style link][Arbitrary case-insensitive reference text]
-[You can use numbers for reference-style link definitions][1]
-Or leave it empty and use the [link text itself][]
+asterisks,
 
-Some text to show that the reference links can follow later.
+***
 
-[arbitrary case-insensitive reference text]: https://www.mozilla.org
-[1]: http://slashdot.org
-[link text itself]: https://www.reddit.com
+or underscores
+
+___
 ```
 
->**Note:**
-Relative links do not allow referencing project files in a wiki page or wiki
-page in a project file. The reason for this is that, in GitLab, wiki is always
-a separate Git repository. For example, `[I'm a reference-style link](style)`
-will point the link to `wikis/style` when the link is inside of a wiki markdown file.
+Three or more hyphens,
+
+---
+
+asterisks,
+
+***
+
+or underscores
+
+___
 
 ### Images
 
 Examples:
 
-    Here's our logo (hover to see the title text):
-
-    Inline-style:
-    ![alt text](img/markdown_logo.png)
+```markdown
+Inline-style (hover to see title text):
 
-    Reference-style:
-    ![alt text1][logo]
+![alt text](img/markdown_logo.png "Title Text")
 
-    [logo]: img/markdown_logo.png
+Reference-style (hover to see title text):
 
-Becomes:
+![alt text1][logo]
 
-Here's our logo:
+[logo]: img/markdown_logo.png "Title Text"
+```
 
-Inline-style:
+Inline-style (hover to see title text):
 
-![alt text](img/markdown_logo.png)
+![alt text](img/markdown_logo.png "Title Text")
 
-Reference-style:
+Reference-style (hover to see title text):
 
 ![alt text][logo]
 
-[logo]: img/markdown_logo.png
+[logo]: img/markdown_logo.png "Title Text"
 
-### Blockquotes
+#### Videos
 
-Examples:
+> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#videos).
 
-```
-> Blockquotes are very handy in email to emulate reply text.
-> This line is part of the same quote.
+Image tags that link to files with a video extension are automatically converted to
+a video player. The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`:
 
-Quote break.
+```md
+Here's a sample video:
 
-> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.
+![Sample Video](img/markdown_video.mp4)
 ```
 
-Becomes:
-
-> Blockquotes are very handy in email to emulate reply text.
-> This line is part of the same quote.
-
-Quote break.
+Here's a sample video:
 
-> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.
+![Sample Video](img/markdown_video.mp4)
 
 ### Inline HTML
 
-You can also use raw HTML in your Markdown, and it'll mostly work pretty well.
+> To see the markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-html).
 
-See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubydoc.info/gems/html-pipeline/1.11.0/HTML/Pipeline/SanitizationFilter#WHITELIST-constant) class for the list of allowed HTML tags and attributes.  In addition to the default `SanitizationFilter` whitelist, GitLab allows `span`, `abbr`, `details` and `summary` elements.
+You can also use raw HTML in your Markdown, and it'll usually work pretty well.
 
-Examples:
+See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubydoc.info/gems/html-pipeline/1.11.0/HTML/Pipeline/SanitizationFilter#WHITELIST-constant)
+class for the list of allowed HTML tags and attributes.  In addition to the default
+`SanitizationFilter` whitelist, GitLab allows `span`, `abbr`, `details` and `summary` elements.
 
-```
+```html
 <dl>
   <dt>Definition list</dt>
   <dd>Is something people use sometimes.</dd>
 
   <dt>Markdown in HTML</dt>
-  <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
+  <dd>Does *not* work **very** well. HTML <em>tags</em> will <b>always</b> work.</dd>
 </dl>
 ```
 
-Becomes:
-
 <dl>
   <dt>Definition list</dt>
   <dd>Is something people use sometimes.</dd>
 
   <dt>Markdown in HTML</dt>
-  <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
+  <dd>Does *not* work **very** well. HTML <em>tags</em> will <b>always</b> work.</dd>
+</dl>
+
+---
+
+It is still possible to use markdown inside HTML tags, but only if the lines containing markdown
+are separated into their own lines:
+
+```html
+<dl>
+  <dt>Markdown in HTML</dt>
+  <dd>Does *not* work **very** well. HTML tags will always work.</dd>
+
+  <dt>Markdown in HTML</dt>
+  <dd>
+
+  Does *not* work **very** well. HTML tags will always work.
+
+  </dd>
+</dl>
+```
+
+<!-- Note: The example below uses HTML to force correct rendering on docs.gitlab.com, markdown will be fine in GitLab -->
+
+<dl>
+  <dt>Markdown in HTML</dt>
+  <dd>Does *not* work **very** well. HTML tags will always work.</dd>
+
+  <dt>Markdown in HTML</dt>
+  <dd>
+
+  Does <em>not</em> work <b>very</b> well. HTML tags will always work.
+
+  </dd>
 </dl>
 
 #### Details and Summary
 
-Content can be collapsed using HTML's [`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) and [`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) tags. This is especially useful for collapsing long logs so they take up less screen space.
+> To see the markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#details-and-summary).
+
+Content can be collapsed using HTML's [`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details)
+and [`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary)
+tags. This is especially useful for collapsing long logs so they take up less screen space.
 
+```html
 <p>
 <details>
 <summary>Click me to collapse/fold.</summary>
@@ -846,8 +1001,23 @@ These details <em>will</em> remain <strong>hidden</strong> until expanded.
 
 </details>
 </p>
+```
+
+<p>
+<details>
+<summary>Click me to collapse/fold.</summary>
 
-**Note:** Markdown inside these tags is supported, as long as you have a blank line after the `</summary>` tag and before the `</details>` tag, as shown in the example.
+These details <em>will</em> remain <strong>hidden</strong> until expanded.
+
+<pre><code>PASTE LOGS HERE</code></pre>
+
+</details>
+</p>
+
+---
+
+Markdown inside these tags is supported as well, as long as you have a blank line
+after the `</summary>` tag and before the `</details>` tag, as shown in the example:
 
 ```html
 <details>
@@ -855,237 +1025,313 @@ These details <em>will</em> remain <strong>hidden</strong> until expanded.
 
 These details _will_ remain **hidden** until expanded.
 
-    PASTE LOGS HERE
+PASTE LOGS HERE
 
 </details>
 ```
 
-### Horizontal Rule
+<!-- Note: The example below uses HTML to force correct rendering on docs.gitlab.com, markdown will be fine in GitLab -->
 
-Examples:
+<details>
+<summary>Click me to collapse/fold.</summary>
 
-```
-Three or more...
+These details <em>will</em> remain <b>hidden</b> until expanded.
 
----
+PASTE LOGS HERE
 
-Hyphens
+</details>
 
-***
+### Line Breaks
 
-Asterisks
+A line break will be inserted (a new paragraph will start) if the previous text is
+ended with two newlines, i.e. you hit <kbd>Enter</kbd> twice in a row. If you only
+use one newline (hit <kbd>Enter</kbd> once), the next sentence will be part of the
+same paragraph. This is useful if you want to keep long lines from wrapping, and keep
+them easily editable:
 
-___
+```markdown
+Here's a line for us to start with.
+
+This longer line is separated from the one above by two newlines, so it will be a *separate paragraph*.
 
-Underscores
+This line is also a separate paragraph, but...
+These lines are only separated by single newlines,
+so they *do not break* and just follow the previous lines
+in the *same paragraph*.
 ```
 
-Becomes:
+Here's a line for us to start with.
 
-Three or more...
+This longer line is separated from the one above by two newlines, so it will be a *separate paragraph*.
 
----
+This line is also a separate paragraph, but...
+These lines are only separated by single newlines,
+so they *do not break* and just follow the previous lines
+in the *same paragraph*.
 
-Hyphens
+#### Newlines
 
-***
+GFM adheres to the markdown specification in how [paragraphs and line breaks are handled](https://spec.commonmark.org/current/).
 
-Asterisks
+A paragraph is simply one or more consecutive lines of text, separated by one or
+more blank lines (i.e. two newlines at the end of the first paragraph), as [explained above](#line-breaks).
 
-___
+If you need more control over line-breaks or soft returns, you can add a single line-break
+by ending a line with a backslash, or two or more spaces. Two newlines in a row will create a new
+paragraph, with a blank line in between:
 
-Underscores
+```markdown
+First paragraph.
+Another line in the same paragraph.
+A third line in the same paragraph, but this time ending with two spaces.{space}{space}
+A new line directly under the first paragraph.
+
+Second paragraph.
+Another line, this time ending with a backslash.\
+A new line due to the previous backslash.
+```
 
-### Line Breaks
+<!-- (Do *NOT* remove the two ending whitespaces in the third line) -->
+<!-- (They are needed for the Markdown text to render correctly) -->
 
-A good way to learn how line breaks work is to experiment and discover -- hit <kbd>Enter</kbd> once (i.e., insert one newline), then hit it twice (i.e., insert two newlines), see what happens. You'll soon learn to get what you want. The "Preview" tab is your friend.
+First paragraph.
+Another line in the same paragraph.
+A third line in the same paragraph, but this time ending with two spaces.  
+A new line directly under the first paragraph.
 
-Here are some things to try out:
+<!-- (Do *NOT* remove the two ending whitespaces in the second line) -->
+<!-- (They are needed for the Markdown text to render correctly on docs.gitlab.com, the backslash works fine inside GitLab itself) -->
 
-Examples:
+Second paragraph.
+Another line, this time ending with a backslash.  
+A new line due to the previous backslash.
 
-```
-Here's a line for us to start with.
+### Links
 
-This line is separated from the one above by two newlines, so it will be a *separate paragraph*.
+There are two ways to create links, inline-style and reference-style:
 
-This line is also a separate paragraph, but...
-This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*.
+```md
+- This is an [inline-style link](https://www.google.com)
+- This is a [link to a repository file in the same directory](index.md)
+- This is a [relative link to a readme one directory higher](../README.md)
+- This is a [link that also has title text](https://www.google.com "This link takes you to Google!")
 
-This line is also a separate paragraph, and...  
-This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*)
+Using header ID anchors:
+
+- This links to [a section on a different markdown page, using a "#" and the header ID](index.md#overview)
+- This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links)
+
+Using references:
+
+- This is a [reference-style link, see below][Arbitrary case-insensitive reference text]
+- You can [use numbers for reference-style link definitions, see below][1]
+- Or leave it empty and use the [link text itself][], see below.
+
+Some text to show that the reference links can follow later.
 
-spaces.
+[arbitrary case-insensitive reference text]: https://www.mozilla.org
+[1]: http://slashdot.org
+[link text itself]: https://www.reddit.com
 ```
 
-Becomes:
+- This is an [inline-style link](https://www.google.com)
+- This is a [link to a repository file in the same directory](index.md)
+- This is a [relative link to a readme one directory higher](../README.md)
+- This is a [link that also has title text](https://www.google.com "This link takes you to Google!")
 
-Here's a line for us to start with.
+Using header ID anchors:
 
-This line is separated from the one above by two newlines, so it will be a *separate paragraph*.
+- This links to [a section on a different markdown page, using a "#" and the header ID](index.md#overview)
+- This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links)
 
-This line is also a separate paragraph, but...
-This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*.
+Using references:
 
-This line is also a separate paragraph, and...  
-This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*)
+- This is a [reference-style link, see below][Arbitrary case-insensitive reference text]
+- You can [use numbers for reference-style link definitions, see below][1]
+- Or leave it empty and use the [link text itself][], see below.
 
-spaces.
+Some text to show that the reference links can follow later.
 
-### Tables
+[arbitrary case-insensitive reference text]: https://www.mozilla.org
+[1]: http://slashdot.org
+[link text itself]: https://www.reddit.com
 
-Tables aren't part of the core Markdown spec, but they are part of GFM.
+NOTE: **Note:** Relative links do not allow the referencing of project files in a wiki
+page, or a wiki page in a project file. The reason for this is that a wiki is always
+in a separate Git repository in GitLab. For example, `[I'm a reference-style link](style)`
+will point the link to `wikis/style` only when the link is inside of a wiki markdown file.
 
-Example:
+#### URL auto-linking
 
-```
-| header 1 | header 2 |
-| -------- | -------- |
-| cell 1   | cell 2   |
-| cell 3   | cell 4   |
+GFM will autolink almost any URL you put into your text:
+
+```markdown
+- https://www.google.com
+- https://google.com/
+- ftp://ftp.us.debian.org/debian/
+- smb://foo/bar/baz
+- irc://irc.freenode.net/gitlab
+- http://localhost:3000
 ```
 
-Becomes:
+- <https://www.google.com>
+- <https://google.com/>
+- <ftp://ftp.us.debian.org/debian/>
+- <smb://foo/bar/baz>
+- <irc://irc.freenode.net/gitlab>
+- <http://localhost:3000>
 
-| header 1 | header 2 |
-| -------- | -------- |
-| cell 1   | cell 2   |
-| cell 3   | cell 4   |
+### Lists
 
-**Note:** The row of dashes between the table header and body must have at least three dashes in each column.
+Ordered and unordered lists can be easily created. Add the number you want the list
+to start with, like `1.`, followed by a space, at the start of each line for ordered lists.
+After the first number, it does not matter what number you use, ordered lists will be
+numbered automatically by vertical order, so repeating `1.` for all items in the
+same list is common. If you start with a number other than `1.`, it will use that as the first
+number, and count up from there.
 
-By including colons in the header row, you can align the text within that column.
+Add a `*`, `-` or `+`, followed by a space, at the start of each line for unordered lists, but
+you should not use a mix of them.
 
-Example:
+Examples:
 
-```
-| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned |
-| :----------- | :------: | ------------: | :----------- | :------: | ------------: |
-| Cell 1       | Cell 2   | Cell 3        | Cell 4       | Cell 5   | Cell 6        |
-| Cell 7       | Cell 8   | Cell 9        | Cell 10      | Cell 11  | Cell 12       |
+```md
+1. First ordered list item
+2. Another item
+   - Unordered sub-list.
+1. Actual numbers don't matter, just that it's a number
+   1. Ordered sub-list
+   1. Next ordered sub-list item
+4. And another item.
+
+* Unordered lists can use asterisks
+
+- Or minuses
+
++ Or pluses
 ```
 
-Becomes:
+<!-- The "2." and "4." in the example above are changed to "1." below, only to match the standards on docs.gitlab.com -->
 
-| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned |
-| :----------- | :------: | ------------: | :----------- | :------: | ------------: |
-| Cell 1       | Cell 2   | Cell 3        | Cell 4       | Cell 5   | Cell 6        |
-| Cell 7       | Cell 8   | Cell 9        | Cell 10      | Cell 11  | Cell 12       |
+1. First ordered list item
+1. Another item
+   - Unordered sub-list.
+1. Actual numbers don't matter, just that it's a number
+   1. Ordered sub-list
+   1. Next ordered sub-list item
+1. And another item.
 
-### Footnotes
+- Unordered lists can use asterisks
 
-Example:
+- Or minuses
 
-```
-You can add footnotes to your text as follows.[^2]
-[^2]: This is my awesome footnote.
-```
+- Or pluses
 
-Becomes:
+---
 
-You can add footnotes to your text as follows.[^2]
+If a list item contains multiple paragraphs, each subsequent paragraph should be indented
+to the same level as the start of the list item text.
 
-### Superscripts / Subscripts
+Example:
 
-CommonMark and GFM currently do not support the superscript syntax ( `x^2` ) that Redcarpet does.  You can use the standard HTML syntax for superscripts and subscripts.
+```markdown
+1. First ordered list item
 
-```
-The formula for water is H<sub>2</sub>O
-while the equation for the theory of relativity is E = mc<sup>2</sup>.
+   Second paragraph of first item.
+
+1. Another item
 ```
 
-The formula for water is H<sub>2</sub>O while the equation for the theory of relativity is E = mc<sup>2</sup>.
+1. First ordered list item
 
-## Wiki-specific Markdown
+   Second paragraph of first item.
 
-The following examples show how links inside wikis behave.
+1. Another item
 
-### Wiki - Direct page link
+---
 
-A link which just includes the slug for a page will point to that page,
-_at the base level of the wiki_.
+If the paragraph of the first item is not indented with the proper number of spaces,
+the paragraph will appear outside the list, instead of properly indented under the list item.
 
-This snippet would link to a `documentation` page at the root of your wiki:
+Example:
 
-```markdown
-[Link to Documentation](documentation)
 ```
+1. First ordered list item
 
-### Wiki - Direct file link
-
-Links with a file extension point to that file, _relative to the current page_.
-
-If this snippet was placed on a page at `<your_wiki>/documentation/related`,
-it would link to `<your_wiki>/documentation/file.md`:
+  Paragraph of first item.
 
-```markdown
-[Link to File](file.md)
+1. Another item
 ```
 
-### Wiki - Hierarchical link
+1. First ordered list item
 
-A link can be constructed relative to the current wiki page using `./<page>`,
-`../<page>`, etc.
+  Paragraph of first item.
 
-- If this snippet was placed on a page at `<your_wiki>/documentation/main`,
-  it would link to `<your_wiki>/documentation/related`:
+1. Another item
 
-    ```markdown
-    [Link to Related Page](related)
-    ```
+### Superscripts / Subscripts
 
-- If this snippet was placed on a page at `<your_wiki>/documentation/related/content`,
-  it would link to `<your_wiki>/documentation/main`:
+CommonMark and GFM currently do not support the superscript syntax ( `x^2` ) that
+Redcarpet does. You can use the standard HTML syntax for superscripts and subscripts:
+
+```html
+The formula for water is H<sub>2</sub>O
+while the equation for the theory of relativity is E = mc<sup>2</sup>.
+```
 
-    ```markdown
-    [Link to Related Page](../main)
-    ```
+The formula for water is H<sub>2</sub>O
+while the equation for the theory of relativity is E = mc<sup>2</sup>.
 
-- If this snippet was placed on a page at `<your_wiki>/documentation/main`,
-  it would link to `<your_wiki>/documentation/related.md`:
+### Tables
 
-    ```markdown
-    [Link to Related Page](related.md)
-    ```
+Tables aren't part of the core Markdown spec, but they are part of GFM.
 
-- If this snippet was placed on a page at `<your_wiki>/documentation/related/content`,
-  it would link to `<your_wiki>/documentation/main.md`:
+1. The first line contains the headers, separated by "pipes" (`|`).
+1. The second line separates the headers from the cells, and must contain three or more dashes.
+1. The third, and any following lines, contain the cell values.
+   - You **can't** have cells separated over many lines in the markdown, they must be kept to single lines,
+     but they can be very long. You can also include HTML `<br>` tags to force newlines if needed.
+   - The cell sizes **don't** have to match each other. They are flexible, but must be separated
+     by pipes (`|`).
+   - You **can** have blank cells.
 
-    ```markdown
-    [Link to Related Page](../main.md)
-    ```
+Example:
 
-### Wiki - Root link
+```markdown
+| header 1 | header 2 | header 3 |
+| ---      |  ------  |----------|
+| cell 1   | cell 2   | cell 3   |
+| cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It will eventually wrap the text when the cell is too large for the display size. |
+| cell 7   |          | cell <br> 9 |
+```
 
-A link starting with a `/` is relative to the wiki root.
+| header 1 | header 2 | header 3 |
+| ---      |  ------  |---------:|
+| cell 1   | cell 2   | cell 3   |
+| cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It will eventually wrap the text when the cell is too large for the display size. |
+| cell 7   |          | cell <br> 9 |
 
-- This snippet links to `<wiki_root>/documentation`:
+Additionally, you can choose the alignment of text within columns by adding colons (`:`)
+to the sides of the "dash" lines in the second row. This will affect every cell in the column.
 
-    ```markdown
-    [Link to Related Page](/documentation)
-    ```
+> Note that the headers are always right aligned [within GitLab itself itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#tables).
 
-- This snippet links to `<wiki_root>/miscellaneous.md`:
+```markdown
+| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned |
+| :---         | :---:    | ---:          | :----------- | :------: | ------------: |
+| Cell 1       | Cell 2   | Cell 3        | Cell 4       | Cell 5   | Cell 6        |
+| Cell 7       | Cell 8   | Cell 9        | Cell 10      | Cell 11  | Cell 12       |
+```
 
-    ```markdown
-    [Link to Related Page](/miscellaneous.md)
-    ```
+| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned |
+| :---         | :---:    | ---:          | :----------- | :------: | ------------: |
+| Cell 1       | Cell 2   | Cell 3        | Cell 4       | Cell 5   | Cell 6        |
+| Cell 7       | Cell 8   | Cell 9        | Cell 10      | Cell 11  | Cell 12       |
 
 ## References
 
 - This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
-- The original [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown.
-- The detailed specification for CommonMark can be found in the [CommonMark Spec][commonmark-spec]
+- The original [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax)
+  at Daring Fireball is an excellent resource for a detailed explanation of standard markdown.
+- The detailed specification for CommonMark can be found in the [CommonMark Spec](https://spec.commonmark.org/current/)
 - The [CommonMark Dingus](http://try.commonmark.org) is a handy tool for testing CommonMark syntax.
-
-[^1]: This link will be broken if you see this document from the Help page or docs.gitlab.com
-[^2]: This is my awesome footnote.
-
-[markdown.md]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md
-[rouge]: http://rouge.jneen.net/ "Rouge website"
-[redcarpet]: https://github.com/vmg/redcarpet "Redcarpet website"
-[katex]: https://github.com/Khan/KaTeX "KaTeX website"
-[katex-subset]: https://katex.org/docs/supported.html "Macros supported by KaTeX"
-[asciidoctor-manual]: http://asciidoctor.org/docs/user-manual/#activating-stem-support "Asciidoctor user manual"
-[commonmarker]: https://github.com/gjtorikian/commonmarker
-[commonmark-spec]: https://spec.commonmark.org/current/
diff --git a/doc/user/operations_dashboard/img/index_operations_dashboard_top_bar_icon.png b/doc/user/operations_dashboard/img/index_operations_dashboard_top_bar_icon.png
index 9d6a509ea72..d4db5e88672 100644
--- a/doc/user/operations_dashboard/img/index_operations_dashboard_top_bar_icon.png
+++ b/doc/user/operations_dashboard/img/index_operations_dashboard_top_bar_icon.png
diff --git a/doc/user/operations_dashboard/img/index_operations_dashboard_with_projects.png b/doc/user/operations_dashboard/img/index_operations_dashboard_with_projects.png
index ee33eee8134..7dbec81c18a 100644
--- a/doc/user/operations_dashboard/img/index_operations_dashboard_with_projects.png
+++ b/doc/user/operations_dashboard/img/index_operations_dashboard_with_projects.png
diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md
index 66362f27299..8c4d387190a 100644
--- a/doc/user/operations_dashboard/index.md
+++ b/doc/user/operations_dashboard/index.md
@@ -1,9 +1,6 @@
-# Operations Dashboard **[PREMIUM]**
+# Operations Dashboard **(PREMIUM)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5781)
-in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5.
-[Moved](https://gitlab.com/gitlab-org/gitlab-ee/issues/9218) to
-[GitLab Premium](https://about.gitlab.com/pricing/) in 11.10.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5781) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. [Moved](https://gitlab.com/gitlab-org/gitlab-ee/issues/9218) to [GitLab Premium](https://about.gitlab.com/pricing/) in 11.10.
 
 The Operations Dashboard provides a summary of each project's operational health,
 including pipeline and alert status.
@@ -16,9 +13,9 @@ dashboard icon:
 ## Adding a project to the dashboard
 
 NOTE: **Note:**
-For GitLab.com, the Operations Dashboard is available for free for public projects.
-If your project is private, the group it belongs to must have a
-[Gold](https://about.gitlab.com/pricing/) plan.
+For GitLab.com, you can add your project to the Operations Dashboard for free if
+your project is public. If your project is private, the group it belongs to must
+have a [Silver](https://about.gitlab.com/pricing/) plan.
 
 To add a project to the dashboard:
 
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index 5b348b1ac60..9ecc8a80b3a 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -17,7 +17,10 @@ will be unassigned automatically.
 GitLab [administrators](../administration/index.md) receive all permissions.
 
 To add or import a user, you can follow the
-[project members documentation](../user/project/members/index.md).
+[project members documentation](project/members/index.md).
+
+For information on eligible approvers for Merge Requests, see
+[Eligible approvers](project/merge_requests/merge_request_approvals.md#eligible-approvers).
 
 ## Principles behind permissions
 
@@ -40,10 +43,12 @@ The following table depicts the various user permission levels in a project.
 |---------------------------------------------------|---------|------------|-------------|----------|--------|
 | Download project                                  | ✓ (*1*) | ✓          | ✓           | ✓        | ✓      |
 | Leave comments                                    | ✓ (*1*) | ✓          | ✓           | ✓        | ✓      |
-| View Insights charts **[ULTIMATE]**               | ✓       | ✓          | ✓           | ✓        | ✓      |
-| View approved/blacklisted licenses **[ULTIMATE]** | ✓       | ✓          | ✓           | ✓        | ✓      |
-| View license management reports **[ULTIMATE]**    | ✓ (*1*) | ✓          | ✓           | ✓        | ✓      |
-| View Security reports **[ULTIMATE]**              | ✓ (*1*) | ✓          | ✓           | ✓        | ✓      |
+| View Insights charts **(ULTIMATE)**               | ✓       | ✓          | ✓           | ✓        | ✓      |
+| View approved/blacklisted licenses **(ULTIMATE)** | ✓       | ✓          | ✓           | ✓        | ✓      |
+| View license management reports **(ULTIMATE)**    | ✓ (*1*) | ✓          | ✓           | ✓        | ✓      |
+| View Security reports **(ULTIMATE)**              | ✓ (*1*) | ✓          | ✓           | ✓        | ✓      |
+| View Dependency list **(ULTIMATE)**               | ✓ (*1*) | ✓          | ✓           | ✓        | ✓      |
+| View [Design Management](project/issues/design_management.md) pages **(PREMIUM)** | ✓ (*1*) | ✓          | ✓           | ✓        | ✓      |
 | View project code                                 | ✓ (*1*) | ✓          | ✓           | ✓        | ✓      |
 | Pull project code                                 | ✓ (*1*) | ✓          | ✓           | ✓        | ✓      |
 | View GitLab Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control-core-only) | ✓       | ✓          | ✓           | ✓        | ✓      |
@@ -57,10 +62,9 @@ The following table depicts the various user permission levels in a project.
 | View confidential issues                          | (*2*)   | ✓          | ✓           | ✓        | ✓      |
 | Assign issues                                     |         | ✓          | ✓           | ✓        | ✓      |
 | Label issues                                      |         | ✓          | ✓           | ✓        | ✓      |
-| Lock issue discussions                            |         | ✓          | ✓           | ✓        | ✓      |
+| Lock issue threads                                |         | ✓          | ✓           | ✓        | ✓      |
 | Manage issue tracker                              |         | ✓          | ✓           | ✓        | ✓      |
-| Manage related issues **[STARTER]**               |         | ✓          | ✓           | ✓        | ✓      |
-| Create issue from vulnerability **[ULTIMATE]**    |         | ✓          | ✓           | ✓        | ✓      |
+| Manage related issues **(STARTER)**               |         | ✓          | ✓           | ✓        | ✓      |
 | Manage labels                                     |         | ✓          | ✓           | ✓        | ✓      |
 | Create code snippets                              |         | ✓          | ✓           | ✓        | ✓      |
 | See a commit status                               |         | ✓          | ✓           | ✓        | ✓      |
@@ -69,8 +73,9 @@ The following table depicts the various user permission levels in a project.
 | See a list of merge requests                      |         | ✓          | ✓           | ✓        | ✓      |
 | View project statistics                           |         | ✓          | ✓           | ✓        | ✓      |
 | View Error Tracking list                          |         | ✓          | ✓           | ✓        | ✓      |
-| Pull from [Maven repository](project/packages/maven_repository.md) or [NPM registry](project/packages/npm_registry.md) **[PREMIUM]** |         | ✓          | ✓           | ✓        | ✓      |
-| Publish to [Maven repository](project/packages/maven_repository.md) or [NPM registry](project/packages/npm_registry.md) **[PREMIUM]** |         |            | ✓           | ✓        | ✓      ||
+| Pull from [Maven repository](project/packages/maven_repository.md) or [NPM registry](project/packages/npm_registry.md) **(PREMIUM)** |         | ✓          | ✓           | ✓        | ✓      |
+| Publish to [Maven repository](project/packages/maven_repository.md) or [NPM registry](project/packages/npm_registry.md) **(PREMIUM)** |         |            | ✓           | ✓        | ✓      ||
+| Upload [Design Management](project/issues/design_management.md) files **(PREMIUM)** |         |            | ✓           | ✓        | ✓      |
 | Create new branches                               |         |            | ✓           | ✓        | ✓      |
 | Push to non-protected branches                    |         |            | ✓           | ✓        | ✓      |
 | Force push to non-protected branches              |         |            | ✓           | ✓        | ✓      |
@@ -78,7 +83,7 @@ The following table depicts the various user permission levels in a project.
 | Create new merge request                          |         |            | ✓           | ✓        | ✓      |
 | Assign merge requests                             |         |            | ✓           | ✓        | ✓      |
 | Label merge requests                              |         |            | ✓           | ✓        | ✓      |
-| Lock merge request discussions                    |         |            | ✓           | ✓        | ✓      |
+| Lock merge request threads                        |         |            | ✓           | ✓        | ✓      |
 | Manage/Accept merge requests                      |         |            | ✓           | ✓        | ✓      |
 | Create new environments                           |         |            | ✓           | ✓        | ✓      |
 | Stop environments                                 |         |            | ✓           | ✓        | ✓      |
@@ -88,18 +93,20 @@ The following table depicts the various user permission levels in a project.
 | Update a container registry                       |         |            | ✓           | ✓        | ✓      |
 | Remove a container registry image                 |         |            | ✓           | ✓        | ✓      |
 | Create/edit/delete project milestones             |         |            | ✓           | ✓        | ✓      |
-| Use security dashboard **[ULTIMATE]**             |         |            | ✓           | ✓        | ✓      |
-| Dismiss vulnerability **[ULTIMATE]**              |         |            | ✓           | ✓        | ✓      |
+| Use security dashboard **(ULTIMATE)**             |         |            | ✓           | ✓        | ✓      |
+| View vulnerabilities in Dependency list **(ULTIMATE)** |    |            | ✓           | ✓        | ✓      |
+| Create issue from vulnerability **(ULTIMATE)**    |         |            | ✓           | ✓        | ✓      |
+| Dismiss vulnerability **(ULTIMATE)**              |         |            | ✓           | ✓        | ✓      |
 | Apply code change suggestions                     |         |            | ✓           | ✓        | ✓      |
 | Create and edit wiki pages                        |         |            | ✓           | ✓        | ✓      |
+| Rewrite/remove Git tags                           |         |            | ✓           | ✓        | ✓      |
 | Use environment terminals                         |         |            |             | ✓        | ✓      |
-| Run Web IDE's Interactive Web Terminals **[ULTIMATE ONLY]** |     |      |             | ✓        | ✓      |
+| Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** |     |      |             | ✓        | ✓      |
 | Add new team members                              |         |            |             | ✓        | ✓      |
 | Enable/disable branch protection                  |         |            |             | ✓        | ✓      |
 | Push to protected branches                        |         |            |             | ✓        | ✓      |
 | Turn on/off protected branch push for devs        |         |            |             | ✓        | ✓      |
 | Enable/disable tag protections                    |         |            |             | ✓        | ✓      |
-| Rewrite/remove Git tags                           |         |            |             | ✓        | ✓      |
 | Edit project                                      |         |            |             | ✓        | ✓      |
 | Add deploy keys to project                        |         |            |             | ✓        | ✓      |
 | Configure project hooks                           |         |            |             | ✓        | ✓      |
@@ -110,7 +117,7 @@ The following table depicts the various user permission levels in a project.
 | Manage GitLab Pages domains and certificates      |         |            |             | ✓        | ✓      |
 | Remove GitLab Pages                               |         |            |             | ✓        | ✓      |
 | Manage clusters                                   |         |            |             | ✓        | ✓      |
-| Manage license policy **[ULTIMATE]**              |         |            |             | ✓        | ✓      |
+| Manage license policy **(ULTIMATE)**              |         |            |             | ✓        | ✓      |
 | Edit comments (posted by any user)                |         |            |             | ✓        | ✓      |
 | Manage Error Tracking                             |         |            |             | ✓        | ✓      |
 | Delete wiki pages                                 |         |            |             | ✓        | ✓      |
@@ -119,8 +126,9 @@ The following table depicts the various user permission levels in a project.
 | Transfer project to another namespace             |         |            |             |          | ✓      |
 | Remove project                                    |         |            |             |          | ✓      |
 | Delete issues                                     |         |            |             |          | ✓      |
-| Force push to protected branches [^4]             |         |            |             |          |        |
-| Remove protected branches [^4]                    |         |            |             |          |        |
+| Disable notification emails                       |         |            |             |          | ✓      |
+| Force push to protected branches (*4*)            |         |            |             |          |        |
+| Remove protected branches (*4*)                   |         |            |             |          |        |
 
 - (*1*): All users are able to perform this action on public and internal projects, but not private projects.
 - (*2*): Guest users can only view the confidential issues they created themselves
@@ -154,7 +162,7 @@ to learn more.
 ### Cycle Analytics permissions
 
 Find the current permissions on the Cycle Analytics dashboard on
-the [documentation on Cycle Analytics permissions](project/cycle_analytics.md#permissions).
+the [documentation on Cycle Analytics permissions](analytics/cycle_analytics.md#permissions).
 
 ### Issue Board permissions
 
@@ -164,7 +172,7 @@ and drag issues around. Read though the
 [documentation on Issue Boards permissions](project/issue_board.md#permissions)
 to learn more.
 
-### File Locking permissions **[PREMIUM]**
+### File Locking permissions **(PREMIUM)**
 
 The user that locks a file or directory is the only one that can edit and push their changes back to the repository where the locked objects are located.
 
@@ -199,19 +207,24 @@ group.
 | Action                                          | Guest | Reporter | Developer | Maintainer | Owner |
 |-------------------------------------------------|-------|----------|-----------|------------|-------|
 | Browse group                                    | ✓     | ✓        | ✓         | ✓          | ✓     |
-| View Insights charts **[ULTIMATE]**             | ✓     | ✓        | ✓         | ✓          | ✓     |
-| View group epic **[ULTIMATE]**                  | ✓     | ✓        | ✓         | ✓          | ✓     |
-| Create/edit group epic **[ULTIMATE]**           |       | ✓        | ✓         | ✓          | ✓     |
+| View Insights charts **(ULTIMATE)**             | ✓     | ✓        | ✓         | ✓          | ✓     |
+| View group epic **(ULTIMATE)**                  | ✓     | ✓        | ✓         | ✓          | ✓     |
+| Create/edit group epic **(ULTIMATE)**           |       | ✓        | ✓         | ✓          | ✓     |
 | Manage group labels                             |       | ✓        | ✓         | ✓          | ✓     |
 | Create project in group                         |       |          | ✓         | ✓          | ✓     |
 | Create/edit/delete group milestones             |       |          | ✓         | ✓          | ✓     |
-| Enable/disable a dependency proxy **[PREMIUM]** |       |          | ✓         | ✓          | ✓     |
+| Enable/disable a dependency proxy **(PREMIUM)** |       |          | ✓         | ✓          | ✓     |
+| Use security dashboard **(ULTIMATE)**           |       |          | ✓         | ✓          | ✓     |
+| Create subgroup                                 |       |          |           | ✓ (1)      | ✓     |
 | Edit group                                      |       |          |           |            | ✓     |
-| Create subgroup                                 |       |          |           |            | ✓     |
 | Manage group members                            |       |          |           |            | ✓     |
 | Remove group                                    |       |          |           |            | ✓     |
-| Delete group epic **[ULTIMATE]**                |       |          |           |            | ✓     |
+| Delete group epic **(ULTIMATE)**                |       |          |           |            | ✓     |
 | View group Audit Events                         |       |          |           |            | ✓     |
+| Disable notification emails                     |       |          |           |            | ✓     |
+
+- (1): Groups can be set to [allow either Owners or Owners and
+  Maintainers to create subgroups](group/subgroups/index.md#creating-a-subgroup)
 
 ### Subgroup permissions
 
@@ -222,6 +235,19 @@ nested groups if you have membership in one of its parents.
 To learn more, read through the documentation on
 [subgroups memberships](group/subgroups/index.md#membership).
 
+## Guest User
+
+When a user is given `Guest` permissions on a project and/or group, and holds no
+higher permission level on any other project or group on the instance, the user
+is considered a guest user by GitLab and will not consume a license seat.
+There is no other specific "guest" designation for newly created users.
+
+If the user is assigned a higher role on any projects or groups, the user will
+take a license seat. If a user creates a project, the user becomes a `Maintainer`
+on the project, resulting in the use of a license seat. To prevent a guest user
+from creating projects, you can edit the user profile to mark the user as
+[External](#external-users-permissions).
+
 ## External users permissions
 
 In cases where it is desired that a user has access only to some internal or
@@ -261,7 +287,7 @@ Here are some examples:
 
 Please be aware that this regex could lead to a DOS attack, [see](https://en.wikipedia.org/wiki/ReDoS?) ReDos on Wikipedia.
 
-## Auditor users **[PREMIUM ONLY]**
+## Auditor users **(PREMIUM ONLY)**
 
 >[Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/998) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.17.
 
@@ -362,3 +388,8 @@ for details about the pipelines security model.
 
 Since GitLab 8.15, LDAP user permissions can now be manually overridden by an admin user.
 Read through the documentation on [LDAP users permissions](../administration/auth/how_to_configure_ldap_gitlab_ee/index.html) to learn more.
+
+## Project aliases
+
+Project aliases can only be read, created and deleted by a GitLab administrator.
+Read through the documentation on [Project aliases](../user/project/index.md#project-aliases-premium-only) to learn more.
diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md
index 304a7984191..5b0954195f8 100644
--- a/doc/user/profile/account/delete_account.md
+++ b/doc/user/profile/account/delete_account.md
@@ -1,37 +1,87 @@
-# Deleting a User Account
+---
+type: howto
+---
+
+# Deleting a User account
+
+Users can be deleted from a GitLab instance, either by:
+
+- The user themselves.
+- An administrator.
 
 NOTE: **Note:**
 Deleting a user will delete all projects in that user namespace.
 
-- As a user, you can delete your own account by navigating to **Settings** > **Account** and selecting **Delete account**
-- As an admin, you can delete a user account by navigating to the **Admin Area**, selecting the **Users** tab, selecting a user, and clicking on **Delete user**
+## As a user
+
+As a user, you can delete your own account by:
+
+1. Clicking on your avatar.
+1. Navigating to **Settings > Account**.
+1. Selecting **Delete account**.
+
+## As an administrator
+
+As an administrator, you can delete a user account by:
+
+1. Navigating to **Admin Area > Overview > Users**.
+1. Selecting a user.
+1. Under the **Account** tab, clicking:
+   - **Delete user** to delete only the user but maintaining their
+     [associated records](#associated-records).
+   - **Delete user and contributions** to delete the user and
+     their associated records.
+
+### Blocking a user
+
+In addition to blocking a user
+[via an abuse report](../../admin_area/abuse_reports.md#blocking-users),
+a user can be blocked directly from the Admin area. To do this:
+
+1. Navigate to  **Admin Area > Overview > Users**.
+1. Selecting a user.
+1. Under the **Account** tab, click **Block user**.
 
 ## Associated Records
 
-> Introduced for issues in [GitLab 9.0][ce-7393], and for merge requests, award
-  emoji, notes, and abuse reports in [GitLab 9.1][ce-10467].
-  Hard deletion from abuse reports and spam logs was introduced in
-  [GitLab 9.1][ce-10273], and from the API in [GitLab 9.3][ce-11853].
+> - Introduced for issues in
+>   [GitLab 9.0](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7393).
+> - Introduced for merge requests, award emoji, notes, and abuse reports in
+>   [GitLab 9.1](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10467).
+> - Hard deletion from abuse reports and spam logs was introduced in
+>   [GitLab 9.1](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10273),
+>   and from the API in
+>   [GitLab 9.3](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11853).
 
 When a user account is deleted, not all associated records are deleted with it.
 Here's a list of things that will **not** be deleted:
 
-- Issues that the user created
-- Merge requests that the user created
-- Notes that the user created
-- Abuse reports that the user reported
-- Award emoji that the user created
+- Issues that the user created.
+- Merge requests that the user created.
+- Notes that the user created.
+- Abuse reports that the user reported.
+- Award emoji that the user created.
 
 Instead of being deleted, these records will be moved to a system-wide
-user with the username "Ghost User", whose sole purpose is to act as a container for such records. Any commits made by a deleted user will still display the username of the original user.
+user with the username "Ghost User", whose sole purpose is to act as a container
+for such records. Any commits made by a deleted user will still display the
+username of the original user.
 
-When a user is deleted from an [abuse report](../../admin_area/abuse_reports.md) or spam log, these associated
+When a user is deleted from an [abuse report](../../admin_area/abuse_reports.md)
+or spam log, these associated
 records are not ghosted and will be removed, along with any groups the user
-is a sole owner of. Administrators can also request this behaviour when
+is a sole owner of. Administrators can also request this behavior when
 deleting users from the [API](../../../api/users.md#user-deletion) or the
-admin area.
+Admin Area.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
 
-[ce-7393]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7393
-[ce-10273]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10273
-[ce-10467]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10467
-[ce-11853]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11853
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/profile/account/img/2fa.png b/doc/user/profile/account/img/2fa.png
deleted file mode 100644
index bb464efa685..00000000000
--- a/doc/user/profile/account/img/2fa.png
+++ /dev/null
diff --git a/doc/user/profile/account/img/2fa_auth.png b/doc/user/profile/account/img/2fa_auth.png
deleted file mode 100644
index 0caaed10805..00000000000
--- a/doc/user/profile/account/img/2fa_auth.png
+++ /dev/null
diff --git a/doc/user/profile/account/img/2fa_u2f_authenticate.png b/doc/user/profile/account/img/2fa_u2f_authenticate.png
deleted file mode 100644
index ff2e936764d..00000000000
--- a/doc/user/profile/account/img/2fa_u2f_authenticate.png
+++ /dev/null
diff --git a/doc/user/profile/account/img/2fa_u2f_register.png b/doc/user/profile/account/img/2fa_u2f_register.png
deleted file mode 100644
index 1cc142aa851..00000000000
--- a/doc/user/profile/account/img/2fa_u2f_register.png
+++ /dev/null
diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md
index df413a11af0..e2b1a20a605 100644
--- a/doc/user/profile/account/two_factor_authentication.md
+++ b/doc/user/profile/account/two_factor_authentication.md
@@ -1,3 +1,7 @@
+---
+type: howto
+---
+
 # Two-Factor Authentication
 
 Two-factor Authentication (2FA) provides an additional level of security to your
@@ -10,17 +14,18 @@ is to know your username and password *and* have access to your one time passwor
 
 ## Overview
 
-> **Note:**
-When you enable 2FA, don't forget to back up your recovery codes.
-
-In addition to one time authenticators (TOTP), GitLab supports U2F (universal 2nd factor) devices as
-the second factor of authentication. Once enabled, in addition to supplying your username and
-password to login, you'll be prompted to activate your U2F device (usually by pressing
-a button on it), and it will perform secure authentication on your behalf.
+TIP: **Tip:**
+When you enable 2FA, don't forget to back up your [recovery codes](#recovery-codes)!
 
-The U2F workflow is [supported by](https://caniuse.com/#search=U2F) Google Chrome, Opera, and Firefox.
+In addition to time-based one time passwords (TOTP), GitLab supports U2F
+(universal 2nd factor) devices as the second factor of authentication. Once
+enabled, in addition to supplying your username and password to log in, you'll
+be prompted to activate your U2F device (usually by pressing a button on it),
+and it will perform secure authentication on your behalf.
 
-We recommend that you set up 2FA with both a [one-time password authenticator](#enable-2fa-via-one-time-password-authenticator) and a [U2F device](#enable-2fa-via-u2f-device), so you can still access your account
+It is highly recommended that you set up 2FA with both a
+[one-time password authenticator](#enable-2fa-via-one-time-password-authenticator)
+and a [U2F device](#enable-2fa-via-u2f-device), so you can still access your account
 if you lose your U2F device.
 
 ## Enabling 2FA
@@ -30,41 +35,52 @@ or a U2F device.
 
 ### Enable 2FA via one time password authenticator
 
-**In GitLab:**
-
-1. Log in to your GitLab account.
-1. Go to your **Profile Settings**.
-1. Go to **Account**.
-1. Click **Enable Two-factor Authentication**.
-
-![Two-factor setup](img/2fa.png)
-
-**On your phone:**
-
-1. Install a compatible application. We recommend [Google Authenticator]
-   \(proprietary\) or [FreeOTP] \(open source\).
-1. In the application, add a new entry in one of two ways:
-    - Scan the code with your phone's camera to add the entry automatically.
-    - Enter the details provided to add the entry manually.
-
-**In GitLab:**
-
-1. Enter the six-digit pin number from the entry on your phone into the **Pin
-   code** field.
-1. Click **Submit**.
+To enable 2FA:
+
+1. **In GitLab:**
+   1. Log in to your GitLab account.
+   1. Go to your **Profile Settings**.
+   1. Go to **Account**.
+   1. Click **Enable Two-factor Authentication**.
+1. **On your device (usually your phone):**
+   1. Install a compatible application, like:
+      - [Authenticator](https://mattrubin.me/authenticator/): open source app for iOS devices.
+      - [andOTP](https://github.com/andOTP/andOTP): feature rich open source app for Android which supports PGP encrypted backups.
+      - [FreeOTP](https://freeotp.github.io/): open source app for Android.
+      - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en): proprietary app for iOS and Android.
+   1. In the application, add a new entry in one of two ways:
+      - Scan the code presented in GitLab with your device's camera to add the
+        entry automatically.
+      - Enter the details provided to add the entry manually.
+1. **In GitLab:**
+   1. Enter the six-digit pin number from the entry on your device into the **Pin
+      code** field.
+   1. Click **Submit**.
 
 If the pin you entered was correct, you'll see a message indicating that
 Two-Factor Authentication has been enabled, and you'll be presented with a list
-of recovery codes.
+of [recovery codes](#recovery-codes). Make sure you download them and keep them
+in a safe place.
 
 ### Enable 2FA via U2F device
 
-> **Notes:**
->
-> - GitLab officially only supports [Yubikey] U2F devices.
-> - Support for U2F devices was added in GitLab 8.8.
+GitLab officially only supports [YubiKey](https://www.yubico.com/products/yubikey-hardware/)
+U2F devices, but users have successfully used [SoloKeys](https://solokeys.com/).
+
+The U2F workflow is [supported by](https://caniuse.com/#search=U2F) the
+following desktop browsers:
+
+- Chrome
+- Edge
+- Firefox (disabled by default)
+- Opera
 
-**In GitLab:**
+NOTE: **Note:**
+For Firefox, you can enable the FIDO U2F API in
+[about:config](https://support.mozilla.org/en-US/kb/about-config-editor-firefox).
+Search for `security.webauth.u2f` and double click on it to toggle to `true`.
+
+To set up 2FA with a U2F device:
 
 1. Log in to your GitLab account.
 1. Go to your **Profile Settings**.
@@ -77,20 +93,21 @@ of recovery codes.
 You will see a message indicating that your device was successfully set up.
 Click on **Register U2F Device** to complete the process.
 
-![Two-Factor U2F Setup](img/2fa_u2f_register.png)
-
-## Recovery Codes
+## Recovery codes
 
-> **Note:**
+NOTE: **Note:**
 Recovery codes are not generated for U2F devices.
 
-Should you ever lose access to your one time password authenticator, you can use one of the ten provided
-backup codes to login to your account. We suggest copying them, printing them, or downloading them using
-the **Download codes** button for storage in a safe place.
-
 CAUTION: **Caution:**
 Each code can be used only once to log in to your account.
 
+Immediately after successfully enabling two-factor authentication, you'll be
+prompted to download a set of set recovery codes. Should you ever lose access
+to your one time password authenticator, you can use one of them to log in to
+your account. We suggest copying them, printing them, or downloading them using
+the **Download codes** button for storage in a safe place. If you choose to
+download them, the file will be called **gitlab-recovery-codes.txt**.
+
 If you lose the recovery codes or just want to generate new ones, you can do so
 [using SSH](#generate-new-recovery-codes-using-ssh).
 
@@ -100,24 +117,26 @@ Logging in with 2FA enabled is only slightly different than a normal login.
 Enter your username and password credentials as you normally would, and you'll
 be presented with a second prompt, depending on which type of 2FA you've enabled.
 
-### Log in via mobile application
+### Log in via a one-time password
 
-Enter the pin from your one time password authenticator's application or a recovery code to log in.
-
-![Two-Factor Authentication on sign in via OTP](img/2fa_auth.png)
+When asked, enter the pin from your one time password authenticator's application or a
+recovery code to log in.
 
 ### Log in via U2F device
 
-1. Click **Login via U2F Device**.
-1. A light will start blinking on your device. Activate it by pressing its button.
+To log in via a U2F device:
 
-You will see a message indicating that your device responded to the authentication request.
-Click on **Authenticate via U2F Device** to complete the process.
+1. Click **Login via U2F Device**.
+1. A light will start blinking on your device. Activate it by touching/pressing
+   its button.
 
-![Two-Factor Authentication on sign in via U2F device](img/2fa_u2f_authenticate.png)
+You will see a message indicating that your device responded to the authentication
+request and you will be automatically logged in.
 
 ## Disabling 2FA
 
+If you ever need to disable 2FA:
+
 1. Log in to your GitLab account.
 1. Go to your **Profile Settings**.
 1. Go to **Account**.
@@ -130,7 +149,8 @@ applications and U2F devices.
 
 When 2FA is enabled, you can no longer use your normal account password to
 authenticate with Git over HTTPS on the command line or when using
-[GitLab's API][api], you must use a [personal access token][pat] instead.
+[GitLab's API](../../../api/README.md). You must use a
+[personal access token](../personal_access_tokens.md) instead.
 
 ## Recovery options
 
@@ -149,7 +169,6 @@ codes. If you saved these codes, you can use one of them to sign in.
 To use a recovery code, enter your username/email and password on the GitLab
 sign-in page. When prompted for a two-factor code, enter the recovery code.
 
-> **Note:**
 Once you use a recovery code, you cannot re-use it. You can still use the other
 recovery codes you saved.
 
@@ -157,41 +176,45 @@ recovery codes you saved.
 
 Users often forget to save their recovery codes when enabling two-factor
 authentication. If an SSH key is added to your GitLab account, you can generate
-a new set of recovery codes with SSH.
+a new set of recovery codes with SSH:
+
+1. Run:
 
-1. Run `ssh git@gitlab.example.com 2fa_recovery_codes`.
-1. You are prompted to confirm that you want to generate new codes. Continuing this process invalidates previously saved codes.
+   ```sh
+   ssh git@gitlab.example.com 2fa_recovery_codes
+   ```
 
-    ```sh
-    $ ssh git@gitlab.example.com 2fa_recovery_codes
-    Are you sure you want to generate new two-factor recovery codes?
-    Any existing recovery codes you saved will be invalidated. (yes/no)
+1. You will then be prompted to confirm that you want to generate new codes.
+   Continuing this process invalidates previously saved codes:
 
-    yes
+   ```sh
+   Are you sure you want to generate new two-factor recovery codes?
+   Any existing recovery codes you saved will be invalidated. (yes/no)
 
-    Your two-factor authentication recovery codes are:
+   yes
 
-    119135e5a3ebce8e
-    11f6v2a498810dcd
-    3924c7ab2089c902
-    e79a3398bfe4f224
-    34bd7b74adbc8861
-    f061691d5107df1a
-    169bf32a18e63e7f
-    b510e7422e81c947
-    20dbed24c5e74663
-    df9d3b9403b9c9f0
+   Your two-factor authentication recovery codes are:
 
-    During sign in, use one of the codes above when prompted for your
-    two-factor code. Then, visit your Profile Settings and add a new device
-    so you do not lose access to your account again.
-    ```
+   119135e5a3ebce8e
+   11f6v2a498810dcd
+   3924c7ab2089c902
+   e79a3398bfe4f224
+   34bd7b74adbc8861
+   f061691d5107df1a
+   169bf32a18e63e7f
+   b510e7422e81c947
+   20dbed24c5e74663
+   df9d3b9403b9c9f0
+
+   During sign in, use one of the codes above when prompted for your
+   two-factor code. Then, visit your Profile Settings and add a new device
+   so you do not lose access to your account again.
+   ```
 
 1. Go to the GitLab sign-in page and enter your username/email and password.
    When prompted for a two-factor code, enter one of the recovery codes obtained
    from the command-line output.
 
-> **Note:**
 After signing in, visit your **Profile settings > Account**  immediately to set
 up two-factor authentication with a new device.
 
@@ -220,8 +243,14 @@ Sign in and re-enable two-factor authentication as soon as possible.
   - The user logs out and attempts to log in via `second.host.xyz` - U2F authentication fails, because
     the U2F key has only been registered on `first.host.xyz`.
 
-[Google Authenticator]: https://support.google.com/accounts/answer/1066447?hl=en
-[FreeOTP]: https://freeotp.github.io/
-[YubiKey]: https://www.yubico.com/products/yubikey-hardware/
-[api]: ../../../api/README.md
-[pat]: ../personal_access_tokens.md
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md
index 28e3f4904a9..2d7bd25fc27 100644
--- a/doc/user/profile/active_sessions.md
+++ b/doc/user/profile/active_sessions.md
@@ -1,14 +1,31 @@
+---
+type: howto
+---
+
 # Active Sessions
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17867)
 >   in GitLab 10.8.
 
 GitLab lists all devices that have logged into your account. This allows you to
-review the sessions.
+review the sessions, and revoke any you don't recognize.
 
 ## Listing all active sessions
 
-1. On the upper right corner, click on your avatar and go to your **Settings**.
-1. Navigate to the **Active Sessions** tab.
+1. Click your avatar.
+1. Select **Settings**.
+1. Click **Active Sessions** in the sidebar.
 
 ![Active sessions list](img/active_sessions_list.png)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/profile/img/active_sessions_list.png b/doc/user/profile/img/active_sessions_list.png
index 1e242ac4710..41173c7eee5 100644
--- a/doc/user/profile/img/active_sessions_list.png
+++ b/doc/user/profile/img/active_sessions_list.png
diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md
index 61a30a775b0..e5ccc8ee758 100644
--- a/doc/user/profile/index.md
+++ b/doc/user/profile/index.md
@@ -1,7 +1,12 @@
+---
+type: index, howto
+---
+
 # User account
 
-When signed into their GitLab account, users can customize their
-experience according to the best approach to their cases.
+Each GitLab account has a user profile, and settings. Your [profile](#user-profile)
+contains information about you, and your GitLab activity. Your [settings](#profile-settings)
+allow you to customize some aspects of GitLab to suit yourself.
 
 ## Signing in
 
@@ -10,8 +15,10 @@ See the [authentication topic](../../topics/authentication/index.md) for more de
 
 ## User profile
 
-Your profile is available from the up-right corner menu bar (user's avatar) > **Profile**,
-or from `https://example.gitlab.com/username`.
+To access your profile:
+
+1. Click on your avatar.
+1. Select **Profile**.
 
 On your profile page, you will see the following information:
 
@@ -20,12 +27,15 @@ On your profile page, you will see the following information:
 - Groups: [groups](../group/index.md) you're a member of
 - Contributed projects: [projects](../project/index.md) you contributed to
 - Personal projects: your personal projects (respecting the project's visibility level)
+- Starred projects: projects you starred
 - Snippets: your personal code [snippets](../snippets.md#personal-snippets)
 
 ## Profile settings
 
-You can edit your account settings by navigating from the up-right corner menu bar
-(user's avatar) > **Settings**, or visiting `https://example.gitlab.com/profile`.
+To access your profile settings:
+
+1. Click on your avatar.
+1. Select **Settings**.
 
 From there, you can:
 
@@ -56,8 +66,8 @@ before proceeding.
 To change your `username`:
 
 1. Navigate to your [profile's](#profile-settings) **Settings > Account**.
-1. Enter a new username under "Change username".
-1. Hit **Update username**.
+1. Enter a new username under **Change username**.
+1. Click **Update username**.
 
 CAUTION: **Caution:**
 It is currently not possible to change your username if it contains a
@@ -82,16 +92,20 @@ The following information will be hidden from the user profile page (`https://gi
 - Groups tab
 - Contributed projects tab
 - Personal projects tab
+- Starred projects tab
 - Snippets tab
 
 To enable private profile:
 
-1. Navigate to your personal [profile settings](#profile-settings).
-1. Check the "Private profile" option.
-1. Hit **Update profile settings**.
+1. Click your avatar.
+1. Select **Profile**.
+1. Click **Edit profile** (pencil icon).
+1. Check the **Private profile** option in the **Main settings** section.
+1. Click **Update profile settings**.
 
 NOTE: **Note:**
-You and GitLab admins can see your the abovementioned information on your profile even if it is private.
+All your profile information can be seen by yourself, and GitLab admins, even if
+the **Private profile** option is enabled.
 
 ## Add details of external accounts
 
@@ -99,9 +113,15 @@ GitLab allows you to add links to certain other external accounts you might have
 
 To add links to other accounts:
 
-1. Navigate to your **User Settings > Profile**.
-1. In the **Main settings** section, locate and fill out fields for links to external accounts like Skype and Twitter.
-1. Click the **Update profile settings** button.
+1. Click your avatar.
+1. Select **Profile**.
+1. Click **Edit profile** (pencil icon).
+1. Complete the desired fields for external accounts, in the **Main settings**
+   section:
+   - Skype
+   - Twitter
+   - LinkedIn
+1. Click **Update profile settings**.
 
 ## Private contributions
 
@@ -111,9 +131,11 @@ Enabling private contributions will include contributions to private projects, i
 
 To enable private contributions:
 
-1. Navigate to your personal [profile settings](#profile-settings).
-1. Check the "Private contributions" option.
-1. Hit **Update profile settings**.
+1. Click on your avatar.
+1. Select **Profile**.
+1. Click **Edit profile** (pencil icon).
+1. Check the **Private contributions** option.
+1. Click **Update profile settings**.
 
 ## Current status
 
@@ -124,22 +146,24 @@ This may be helpful when you are out of office or otherwise not available.
 Other users can then take your status into consideration when responding to your issues or assigning work to you.
 Please be aware that your status is publicly visible even if your [profile is private](#private-profile).
 
+Status messages are restricted to 100 characters of plain text.
+They may however contain emoji codes such as `I'm on vacation :palm_tree:`.
+
 To set your current status:
 
-1. Open the user menu in the top-right corner of the navigation bar.
-1. Hit **Set status**, or **Edit status** if you have already set a status.
-1. Set the emoji and/or status message to your liking.
-1. Hit **Set status**. Alternatively, you can also hit **Remove status** to remove your user status entirely.
+1. Click your avatar.
+1. Click **Set status**, or **Edit status** if you have already set a status.
+1. Set the desired emoji and/or status message.
+1. Click **Set status**. Alternatively, you can click **Remove status** to remove your user status entirely.
 
 or
 
-1. Navigate to your personal [profile settings](#profile-settings).
-1. In the text field below `Your status`, enter your status message.
-1. Select an emoji from the dropdown if you like.
-1. Hit **Update profile settings**.
-
-Status messages are restricted to 100 characters of plain text.
-They may however contain emoji codes such as `I'm on vacation :palm_tree:`.
+1. Click your avatar.
+1. Select **Profile**.
+1. Click **Edit profile** (pencil icon).
+1. Enter your status message in the **Your status** text field.
+1. Click **Add status emoji** (smiley face), and select the desired emoji.
+1. Click **Update profile settings**.
 
 You can also set your current status [using the API](../../api/users.md#user-status).
 
@@ -147,39 +171,42 @@ You can also set your current status [using the API](../../api/users.md#user-sta
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21598) in GitLab 11.4.
 
-A commit email, is the email that will be displayed in every Git-related action done through the
-GitLab interface.
+A commit email is an email address displayed in every Git-related action carried out through the GitLab interface.
 
-You are able to select from the list of your own verified emails which email you want to use as the commit email.
+Any of your own verified email addresses can be used as the commit email.
 
-To change it:
+To change your commit email:
 
-1. Open the user menu in the top-right corner of the navigation bar.
-1. Hit **Commit email** selection box.
+1. Click your avatar.
+1. Select **Profile**.
+1. Click **Edit profile** (pencil icon).
+1. Click **Commit email** dropdown.
 1. Select any of the verified emails.
-1. Hit **Update profile settings**.
+1. Click **Update profile settings**.
 
 ### Private commit email
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22560) in GitLab 11.5.
 
 GitLab provides the user with an automatically generated private commit email option,
-which allows the user to not make their email information public.
+which allows the user to keep their email information private.
 
 To enable this option:
 
-1. Open the user menu in the top-right corner of the navigation bar.
-1. Hit **Commit email** selection box.
+1. Click your avatar.
+1. Select **Profile**.
+1. Click **Edit profile** (pencil icon).
+1. Click **Commit email** dropdown.
 1. Select **Use a private email** option.
-1. Hit **Update profile settings**.
+1. Click **Update profile settings**.
 
 Once this option is enabled, every Git-related action will be performed using the private commit email.
 
-In order to stay fully annonymous, you can also copy this private commit email
+To stay fully anonymous, you can also copy this private commit email
 and configure it on your local machine using the following command:
 
-```
-git config --global user.email "YOUR_PRIVATE_COMMIT_EMAIL"
+```sh
+git config --global user.email <your email address>
 ```
 
 ## Troubleshooting
@@ -202,3 +229,15 @@ to get you a new `_gitlab_session` and keep you signed in through browser restar
 
 After your `remember_user_token` expires and your `_gitlab_session` is cleared/expired,
 you will be asked to sign in again to verify your identity (which is for security reasons).
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md
index 0b224fc7e01..d556daa3460 100644
--- a/doc/user/profile/personal_access_tokens.md
+++ b/doc/user/profile/personal_access_tokens.md
@@ -1,3 +1,7 @@
+---
+type: concepts, howto
+---
+
 # Personal access tokens
 
 > [Introduced][ce-3749] in GitLab 8.8.
@@ -40,7 +44,7 @@ the following table.
 | Scope              | Introduced in | Description |
 | ------------------ | ------------- | ----------- |
 | `read_user`        | [GitLab 8.15](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951)   | Allows access to the read-only endpoints under `/users`. Essentially, any of the `GET` requests in the [Users API][users] are allowed. |
-| `api`              | [GitLab 8.15](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951)   | Grants complete access to the API and Container Registry (read/write). |
+| `api`              | [GitLab 8.15](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951)   | Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry. |
 | `read_registry`    | [GitLab 9.3](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845)   | Allows to read (pull) [container registry] images if a project is private and authorization is required. |
 | `sudo`             | [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14838)  | Allows performing API actions as any user in the system (if the authenticated user is an admin). |
 | `read_repository`  | [GitLab 10.7](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17894)  | Allows read-only access (pull) to the repository through git clone. |
@@ -52,3 +56,15 @@ the following table.
 [container registry]: ../project/container_registry.md
 [users]: ../../api/users.md
 [usage]: ../../api/README.md#personal-access-tokens
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md
index b61216b7b67..82a6d2b3703 100644
--- a/doc/user/profile/preferences.md
+++ b/doc/user/profile/preferences.md
@@ -1,11 +1,17 @@
+---
+type: concepts, howto
+---
+
 # Profile preferences
 
 A user's profile preferences page allows the user to customize various aspects
 of GitLab to their liking.
 
-To navigate to your profile's preferences, click your avatar icon in the top
-right corner, select **Settings** and then choose **Preferences** from the
-left sidebar.
+To navigate to your profile's preferences:
+
+1. Click your avatar.
+1. Select **Settings**.
+1. Click **Preferences** in the sidebar.
 
 ## Navigation theme
 
@@ -15,7 +21,7 @@ and left side navigation.
 Using individual color themes might help you differentiate between your different
 GitLab instances.
 
-The default palette is Indigo. You can choose between 10 different themes:
+The default theme is Indigo. You can choose between 10 themes:
 
 - Indigo
 - Light Indigo
@@ -39,7 +45,7 @@ for syntax highlighting. For a list of supported languages visit the rouge websi
 Changing this setting allows you to customize the color theme when viewing any
 syntax highlighted code on GitLab.
 
-The default syntax theme is White, and you can choose among 5 different colors:
+The default syntax theme is White, and you can choose among 5 different themes:
 
 - White
 - Dark
@@ -79,7 +85,17 @@ You have 8 options here that you can use for your default dashboard view:
 - Your [Todos](../../workflow/todos.md)
 - Assigned Issues
 - Assigned Merge Requests
-- Operations Dashboard **[PREMIUM]**
+- Operations Dashboard **(PREMIUM)**
+
+### Group overview content
+
+The **Group overview content** dropdown allows you to choose what information is
+displayed on a group’s home page.
+
+You can choose between 2 options:
+
+- Details (default)
+- [Security dashboard](../application_security/security_dashboard/index.md) **(ULTIMATE)**
 
 ### Project overview content
 
@@ -102,7 +118,7 @@ Select your preferred language from a list of supported languages.
 
 ### First day of the week
 
-The first day of the week can be customised for calendar views and date pickers.
+The first day of the week can be customized for calendar views and date pickers.
 
 You can choose one of the following options as the first day of the week:
 
@@ -111,3 +127,15 @@ You can choose one of the following options as the first day of the week:
 - Monday
 
 If you select **System Default**, the system-wide default setting will be used.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md
new file mode 100644
index 00000000000..9ebf7f821a1
--- /dev/null
+++ b/doc/user/project/autocomplete_characters.md
@@ -0,0 +1,48 @@
+# Autocomplete characters
+
+The autocomplete characters provide a quick way of entering field values into
+Markdown fields. When you start typing a word in a Markdown field with one of
+the following characters, GitLab progressively autocompletes against a set of
+matching values. The string matching is not case sensitive.
+
+| Character | Autocompletes |
+| :-------- | :------------ |
+| `~`       | Labels |
+| `%`       | Milestones |
+| `@`       | Users and groups |
+| `#`       | Issues |
+| `!`       | Merge requests |
+| `&`       | Epics |
+| `$`       | Snippets |
+| `:`       | Emoji |
+| `/`       | Quick Actions |
+
+Up to 5 of the most relevant matches are displayed in a popup list. When you
+select an item from the list, the value is entered in the field. The more
+characters you enter, the more precise the matches are.
+
+Autocomplete characters are useful when combined with [Quick Actions](quick_actions.md).
+
+## Example
+
+Assume your GitLab instance includes the following users:
+
+| Username        | Name |
+| :-------------- | :--- |
+| alessandra      | Rosy Grant |
+| lawrence.white  | Kelsey Kerluke |
+| leanna          | Rosemarie Rogahn |
+| logan_gutkowski | Lee Wuckert |
+| shelba          | Josefine Haley |
+
+In an Issue comment, entering `@l` results in the following popup list
+appearing. Note that user `shelba` is not included, because the list includes
+only the 5 users most relevant to the Issue.
+
+![Popup list which includes users whose username or name contains the letter `l`](img/autocomplete_characters_example1_v12_0.png)
+
+If you continue to type, `@le`, the popup list changes to the following. The
+popup now only includes users where `le` appears in their username, or a word in
+their name.
+
+![Popup list which includes users whose username or name contains the string `le`](img/autocomplete_characters_example2_v12_0.png)
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md
index 8849dd2d684..cd3e5f5a63c 100644
--- a/doc/user/project/badges.md
+++ b/doc/user/project/badges.md
@@ -17,10 +17,10 @@ If you find that you have to add the same badges to several projects, you may wa
 
 To add a new badge to a project:
 
-1.  Navigate to your project's **Settings > General > Badges**.
-1.  Under "Link", enter the URL that the badges should point to and under
-    "Badge image URL" the URL of the image that should be displayed.
-1.  Submit the badge by clicking the **Add badge** button.
+1. Navigate to your project's **Settings > General > Badges**.
+1. Under "Link", enter the URL that the badges should point to and under
+   "Badge image URL" the URL of the image that should be displayed.
+1. Submit the badge by clicking the **Add badge** button.
 
 After adding a badge to a project, you can see it in the list below the form.
 You can edit it by clicking on the pen icon next to it or to delete it by
@@ -39,10 +39,10 @@ project, consider adding them on the [project level](#project-badges) or use
 
 To add a new badge to a group:
 
-1.  Navigate to your group's **Settings > General > Badges**.
-1.  Under "Link", enter the URL that the badges should point to and under
-    "Badge image URL" the URL of the image that should be displayed.
-1.  Submit the badge by clicking the **Add badge** button.
+1. Navigate to your group's **Settings > General > Badges**.
+1. Under "Link", enter the URL that the badges should point to and under
+   "Badge image URL" the URL of the image that should be displayed.
+1. Submit the badge by clicking the **Add badge** button.
 
 After adding a badge to a group, you can see it in the list below the form.
 You can edit the badge by clicking on the pen icon next to it or to delete it
diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md
index d0c7daf4692..f4733620640 100644
--- a/doc/user/project/bulk_editing.md
+++ b/doc/user/project/bulk_editing.md
@@ -13,13 +13,20 @@ by using the bulk editing feature.
 ![Bulk editing](img/bulk-editing.png)
 
 NOTE: **Note:**
-Bulk editing of issues and merge requests is only available at the project level.
+Bulk editing issues and merge requests is also available at the group level.
+For more details, see [bulk editing group issues and merge requests](../group/bulk_editing/index.md).
 
-To update multiple project issues or merge requests at the same time, navigate to
-their respective lists and click **Edit issues** or **Edit merge requests** available
-in the tab bar. This will open a sidebar on the right-hand side of your screen
-where editable fields will be displayed. Checkboxes will also appear to the left-hand
-side of eachissue or merge request for you to select the items you want to update.
+To update multiple project issues or merge requests at the same time:
 
-Once you have selected all relevant items, choose the appropriate fields and their
-values from the sidebar and click **Update all** to apply your changes.
+1. Navigate to their respective list.
+
+1. Click **Edit issues** or **Edit merge requests**.
+
+    - This will open a sidebar on the right-hand side of your screen
+    where editable fields will be displayed.
+
+    - Checkboxes will also appear beside each issue or merge request.
+
+1. Check the checkboxes of each items to be edited.
+1. Choose the appropriate fields and their values from the sidebar.
+1. Click **Update all**.
diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md
index cce862b0911..5068d2757be 100644
--- a/doc/user/project/canary_deployments.md
+++ b/doc/user/project/canary_deployments.md
@@ -1,4 +1,4 @@
-# Canary Deployments **[PREMIUM]**
+# Canary Deployments **(PREMIUM)**
 
 > [Introduced][ee-1659] in [GitLab Premium][eep] 9.1.
 
@@ -44,7 +44,7 @@ Canary deployments require that you properly configure Deploy Boards:
 
 1. Follow the steps to [enable Deploy Boards](deploy_boards.md#enabling-deploy-boards).
 1. To track canary deployments you need to label your Kubernetes deployments and
-   pods with `track: canary`. To get started quickly, you can use the [Auto Deploy]
+   pods with `track: canary`. To get started quickly, you can use the [Auto Deploy](../../ci/autodeploy/index.md)
    template for canary deployments that GitLab provides.
 
 Depending on the deploy, the label should be either `stable` or `canary`.
@@ -62,7 +62,6 @@ can easily notice them.
 
 ![Canary deployments on Deploy Board](img/deploy_boards_canary_deployments.png)
 
-[autodeploy]: ../../ci/autodeploy/index.md "GitLab Autodeploy"
 [eep]: https://about.gitlab.com/pricing/
 [ee-1659]: https://gitlab.com/gitlab-org/gitlab-ee/issues/1659
 [kube-canary]: https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments
diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md
index ea09f9f1547..28f3420de35 100644
--- a/doc/user/project/clusters/eks_and_gitlab/index.md
+++ b/doc/user/project/clusters/eks_and_gitlab/index.md
@@ -40,97 +40,97 @@ then click **Add an existing Kubernetes cluster**.
 
 A few details from the EKS cluster will be required to connect it to GitLab:
 
-1.  **Retrieve the certificate**: A valid Kubernetes certificate is needed to
-    authenticate to the EKS cluster. We will use the certificate created by default.
-    Open a shell and use `kubectl` to retrieve it:
+1. **Retrieve the certificate**: A valid Kubernetes certificate is needed to
+   authenticate to the EKS cluster. We will use the certificate created by default.
+   Open a shell and use `kubectl` to retrieve it:
 
-    -  List the secrets with `kubectl get secrets`, and one should named similar to
-       `default-token-xxxxx`. Copy that token name for use below.
-    -  Get the certificate with:
+   - List the secrets with `kubectl get secrets`, and one should named similar to
+     `default-token-xxxxx`. Copy that token name for use below.
+   - Get the certificate with:
 
-       ```sh
-       kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode
-       ```
+     ```sh
+     kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode
+     ```
 
-1.  **Create admin token**: A `cluster-admin` token is required to install and
-    manage Helm Tiller. GitLab establishes mutual SSL auth with Helm Tiller
-    and creates limited service accounts for each application. To create the
-    token we will create an admin service account as follows:
+1. **Create admin token**: A `cluster-admin` token is required to install and
+   manage Helm Tiller. GitLab establishes mutual SSL auth with Helm Tiller
+   and creates limited service accounts for each application. To create the
+   token we will create an admin service account as follows:
 
-    2.1. Create a file called `eks-admin-service-account.yaml` with contents:
+   2.1. Create a file called `eks-admin-service-account.yaml` with contents:
 
-    ```yaml
-    apiVersion: v1
-    kind: ServiceAccount
-    metadata:
-      name: eks-admin
-      namespace: kube-system
-    ```
+   ```yaml
+   apiVersion: v1
+   kind: ServiceAccount
+   metadata:
+     name: eks-admin
+     namespace: kube-system
+   ```
 
-    2.2. Apply the service account to your cluster:
+   2.2. Apply the service account to your cluster:
 
-     ```bash
-    kubectl apply -f eks-admin-service-account.yaml
-     ```
+   ```bash
+   kubectl apply -f eks-admin-service-account.yaml
+   ```
 
-    Output:
+   Output:
 
-    ```bash
-    serviceaccount "eks-admin" created
-    ```
+   ```bash
+   serviceaccount "eks-admin" created
+   ```
 
-    2.3. Create a file called `eks-admin-cluster-role-binding.yaml` with contents:
+   2.3. Create a file called `eks-admin-cluster-role-binding.yaml` with contents:
 
-    ```yaml
-    apiVersion: rbac.authorization.k8s.io/v1beta1
-    kind: ClusterRoleBinding
-    metadata:
-      name: eks-admin
-    roleRef:
-      apiGroup: rbac.authorization.k8s.io
-      kind: ClusterRole
-      name: cluster-admin
-    subjects:
-    - kind: ServiceAccount
-      name: eks-admin
-      namespace: kube-system
-    ```
+   ```yaml
+   apiVersion: rbac.authorization.k8s.io/v1beta1
+   kind: ClusterRoleBinding
+   metadata:
+     name: eks-admin
+   roleRef:
+     apiGroup: rbac.authorization.k8s.io
+     kind: ClusterRole
+     name: cluster-admin
+   subjects:
+   - kind: ServiceAccount
+     name: eks-admin
+     namespace: kube-system
+   ```
 
-    2.4. Apply the cluster role binding to your cluster:
+   2.4. Apply the cluster role binding to your cluster:
 
-    ```bash
-    kubectl apply -f eks-admin-cluster-role-binding.yaml
-    ```
+   ```bash
+   kubectl apply -f eks-admin-cluster-role-binding.yaml
+   ```
 
-    Output:
+   Output:
 
-    ```bash
-    clusterrolebinding "eks-admin" created
-    ```
+   ```bash
+   clusterrolebinding "eks-admin" created
+   ```
 
-    2.5. Retrieve the token for the `eks-admin` service account:
+   2.5. Retrieve the token for the `eks-admin` service account:
 
-    ```bash
-    kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}')
-    ```
+   ```bash
+   kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}')
+   ```
 
-    Copy the `<authentication_token>` value from the output:
+   Copy the `<authentication_token>` value from the output:
 
-    ```yaml
-    Name:         eks-admin-token-b5zv4
-    Namespace:    kube-system
-    Labels:       <none>
-    Annotations:  kubernetes.io/service-account.name=eks-admin
-                  kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8
+   ```yaml
+   Name:         eks-admin-token-b5zv4
+   Namespace:    kube-system
+   Labels:       <none>
+   Annotations:  kubernetes.io/service-account.name=eks-admin
+                 kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8
 
-    Type:  kubernetes.io/service-account-token
+   Type:  kubernetes.io/service-account-token
 
-    Data
-    ====
-    ca.crt:     1025 bytes
-    namespace:  11 bytes
-    token:      <authentication_token>
-    ```
+   Data
+   ====
+   ca.crt:     1025 bytes
+   namespace:  11 bytes
+   token:      <authentication_token>
+   ```
 
 1. The API server endpoint is also required, so GitLab can connect to the cluster.
    This is displayed on the AWS EKS console, when viewing the EKS cluster details.
@@ -253,7 +253,7 @@ With RBAC disabled and services deployed,
 [Auto DevOps](../../../../topics/autodevops/index.md) can now be leveraged
 to build, test, and deploy the app.
 
-[Enable Auto DevOps](../../../../topics/autodevops/index.md#enablingdisabling-auto-devops-at-the-project-level)
+[Enable Auto DevOps](../../../../topics/autodevops/index.md#at-the-project-level)
 if not already enabled. If a wildcard DNS entry was created resolving to the
 Load Balancer, enter it in the `domain` field under the Auto DevOps settings.
 Otherwise, the deployed app will not be externally available outside of the cluster.
diff --git a/doc/user/project/clusters/img/k8s_cluster_monitoring.png b/doc/user/project/clusters/img/k8s_cluster_monitoring.png
index e449893a606..0a8c5043c65 100644
--- a/doc/user/project/clusters/img/k8s_cluster_monitoring.png
+++ b/doc/user/project/clusters/img/k8s_cluster_monitoring.png
diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md
index dc21db603d6..cf3a3fef79f 100644
--- a/doc/user/project/clusters/index.md
+++ b/doc/user/project/clusters/index.md
@@ -1,30 +1,113 @@
-# Connecting GitLab with a Kubernetes cluster
+# Kubernetes clusters
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/35954) in GitLab 10.1.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/35954) in GitLab 10.1 for projects.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) in
+>   GitLab 11.6 for [groups](../../group/clusters/index.md).
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/39840) in
+>   GitLab 11.11 for [instances](../../instance/clusters/index.md).
 
-Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes
-cluster in a few steps.
+GitLab provides many features with a Kubernetes integration. Kubernetes can be
+integrated with projects, but also:
+
+- [Groups](../../group/clusters/index.md).
+- [Instances](../../instance/clusters/index.md).
+
+NOTE: **Scalable app deployment with GitLab and Google Cloud Platform**
+[Watch the webcast](https://about.gitlab.com/webcast/scalable-app-deploy/) and learn how to spin up a Kubernetes cluster managed by Google Cloud Platform (GCP) in a few clicks.
 
 ## Overview
 
-With one or more Kubernetes clusters associated to your project, you can use
-[Review Apps](../../../ci/review_apps/index.md), deploy your applications, run
-your pipelines, use it with [Auto DevOps](../../../topics/autodevops/index.md),
-and much more, all from within GitLab.
+Using the GitLab project Kubernetes integration, you can:
+
+- Use [Review Apps](../../../ci/review_apps/index.md).
+- Run [pipelines](../../../ci/pipelines.md).
+- [Deploy](#deploying-to-a-kubernetes-cluster) your applications.
+- Detect and [monitor Kubernetes](#kubernetes-monitoring).
+- Use it with [Auto DevOps](#auto-devops).
+- Use [Web terminals](#web-terminals).
+- Use [Deploy Boards](#deploy-boards-premium). **(PREMIUM)**
+- Use [Canary Deployments](#canary-deployments-premium). **(PREMIUM)**
+- View [Pod logs](#pod-logs-ultimate). **(ULTIMATE)**
+
+You can also:
+
+- Connect and deploy to an [Amazon EKS cluster](eks_and_gitlab/index.html).
+- Run serverless workloads on [Kubernetes with Knative](serverless/index.md).
+
+### Deploy Boards **(PREMIUM)**
+
+GitLab's Deploy Boards offer a consolidated view of the current health and
+status of each CI [environment](../../../ci/environments.md) running on Kubernetes,
+displaying the status of the pods in the deployment. Developers and other
+teammates can view the progress and status of a rollout, pod by pod, in the
+workflow they already use without any need to access Kubernetes.
+
+[Read more about Deploy Boards](../deploy_boards.md)
+
+### Canary Deployments **(PREMIUM)**
+
+Leverage [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments)
+and visualize your canary deployments right inside the Deploy Board, without
+the need to leave GitLab.
+
+[Read more about Canary Deployments](../canary_deployments.md)
+
+### Pod logs **(ULTIMATE)**
+
+GitLab makes it easy to view the logs of running pods in connected Kubernetes clusters. By displaying the logs directly in GitLab, developers can avoid having to manage console tools or jump to a different interface.
+
+[Read more about Kubernetes pod logs](kubernetes_pod_logs.md)
+
+### Kubernetes monitoring
 
-There are two options when adding a new cluster to your project; either associate
-your account with Google Kubernetes Engine (GKE) so that you can [create new
-clusters](#adding-and-creating-a-new-gke-cluster-via-gitlab) from within GitLab,
-or provide the credentials to an [existing Kubernetes cluster](#adding-an-existing-kubernetes-cluster).
+Automatically detect and monitor Kubernetes metrics. Automatic monitoring of
+[NGINX ingress](../integrations/prometheus_library/nginx.md) is also supported.
+
+[Read more about Kubernetes monitoring](../integrations/prometheus_library/kubernetes.md)
+
+### Auto DevOps
+
+Auto DevOps automatically detects, builds, tests, deploys, and monitors your
+applications.
+
+To make full use of Auto DevOps(Auto Deploy, Auto Review Apps, and Auto Monitoring)
+you will need the Kubernetes project integration enabled.
+
+[Read more about Auto DevOps](../../../topics/autodevops/index.md)
+
+NOTE: **Note**
+Kubernetes clusters can be used without Auto DevOps.
+
+### Web terminals
 
 NOTE: **Note:**
-From [GitLab 11.6](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) you
-can also associate a Kubernetes cluster to your groups and from
-[GitLab 11.11](https://gitlab.com/gitlab-org/gitlab-ce/issues/39840),
-to the GitLab instance. Learn more about [group-level](../../group/clusters/index.md)
-and [instance-level](../../instance/clusters/index.md) Kubernetes clusters.
+Introduced in GitLab 8.15. You must be the project owner or have `maintainer` permissions
+to use terminals. Support is limited to the first container in the
+first pod of your environment.
+
+When enabled, the Kubernetes service adds [web terminal](../../../ci/environments.md#web-terminals)
+support to your [environments](../../../ci/environments.md). This is based on the `exec` functionality found in
+Docker and Kubernetes, so you get a new shell session within your existing
+containers. To use this integration, you should deploy to Kubernetes using
+the deployment variables above, ensuring any deployments, replica sets, and
+pods are annotated with:
+
+- `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG`
+- `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG`
 
-## Adding and creating a new GKE cluster via GitLab
+`$CI_ENVIRONMENT_SLUG` and `$CI_PROJECT_PATH_SLUG` are the values of
+the CI variables.
+
+## Adding and removing clusters
+
+There are two options when adding a new cluster to your project:
+
+- Associate your account with Google Kubernetes Engine (GKE) to
+  [create new clusters](#add-new-gke-cluster) from within GitLab.
+- Provide credentials to an
+  [existing Kubernetes cluster](#add-existing-kubernetes-cluster).
+
+### Add new GKE cluster
 
 TIP: **Tip:**
 Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](https://console.cloud.google.com/freetrial),
@@ -36,7 +119,7 @@ The [Google authentication integration](../../../integration/google.md) must
 be enabled in GitLab at the instance level. If that's not the case, ask your
 GitLab administrator to enable it. On GitLab.com, this is enabled.
 
-### Requirements
+#### Requirements
 
 Before creating your first cluster on Google Kubernetes Engine with GitLab's
 integration, make sure the following requirements are met:
@@ -46,15 +129,15 @@ integration, make sure the following requirements are met:
 - The Kubernetes Engine API and related service are enabled. It should work immediately but may take up to 10 minutes after you create a project. For more information see the
   ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin).
 
-### Creating the cluster
+#### Creating the cluster
 
 If all of the above requirements are met, you can proceed to create and add a
 new Kubernetes cluster to your project:
 
 1. Navigate to your project's **Operations > Kubernetes** page.
 
-    NOTE: **Note:**
-    You need Maintainer [permissions] and above to access the Kubernetes page.
+   NOTE: **Note:**
+   You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page.
 
 1. Click **Add Kubernetes cluster**.
 1. Click **Create with Google Kubernetes Engine**.
@@ -71,7 +154,6 @@ new Kubernetes cluster to your project:
    - **Number of nodes** - Enter the number of nodes you wish the cluster to have.
    - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types)
      of the Virtual Machine instance that the cluster will be based on.
-   - **RBAC-enabled cluster** - Leave this checked if using default GKE creation options, see the [RBAC section](#rbac-cluster-resources) for more information.
    - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](#gitlab-managed-clusters) for more information.
 1. Finally, click the **Create Kubernetes cluster** button.
 
@@ -86,130 +168,167 @@ account](#access-controls). Starting from [GitLab
 creation process will explicitly request that basic authentication and
 client certificate is enabled.
 
-## Adding an existing Kubernetes cluster
+NOTE: **Note:**
+Starting from [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ce/issues/55902), all GKE clusters created by GitLab are RBAC enabled. Take a look at the [RBAC section](#rbac-cluster-resources) for more information.
+
+### Add existing Kubernetes cluster
+
+NOTE: **Note:**
+Kubernetes integration is not supported for arm64 clusters. See the issue [Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab-ce/issues/64044) for details.
 
 To add an existing Kubernetes cluster to your project:
 
 1. Navigate to your project's **Operations > Kubernetes** page.
 
-    NOTE: **Note:**
-    You need Maintainer [permissions] and above to access the Kubernetes page.
+   NOTE: **Note:**
+   You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page.
 
 1. Click **Add Kubernetes cluster**.
 1. Click **Add an existing Kubernetes cluster** and fill in the details:
-    - **Kubernetes cluster name** (required) - The name you wish to give the cluster.
-    - **Environment scope** (required) - The
-      [associated environment](#setting-the-environment-scope-premium) to this cluster.
-    - **API URL** (required) -
-      It's the URL that GitLab uses to access the Kubernetes API. Kubernetes
-      exposes several APIs, we want the "base" URL that is common to all of them,
-      e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`.
-
-      Get the API URL by running this command:
-
-      ```sh
-      kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}'
-      ```
-    - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the EKS cluster. We will use the certificate created by default.
-      - List the secrets with `kubectl get secrets`, and one should named similar to
-       `default-token-xxxxx`. Copy that token name for use below.
-      - Get the certificate by running this command:
-
-      ```sh
-      kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode
-      ```
-    - **Token** -
-      GitLab authenticates against Kubernetes using service tokens, which are
-      scoped to a particular `namespace`.
-      **The token used should belong to a service account with
-      [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
-      privileges.** To create this service account:
-
-      1. Create a file called `gitlab-admin-service-account.yaml` with contents:
-
-         ```yaml
-         apiVersion: v1
-         kind: ServiceAccount
-         metadata:
-           name: gitlab-admin
-           namespace: kube-system
-         ---
-         apiVersion: rbac.authorization.k8s.io/v1beta1
-         kind: ClusterRoleBinding
-         metadata:
-           name: gitlab-admin
-         roleRef:
-           apiGroup: rbac.authorization.k8s.io
-           kind: ClusterRole
-           name: cluster-admin
-         subjects:
-         - kind: ServiceAccount
-           name: gitlab-admin
-           namespace: kube-system
-         ```
-
-      1. Apply the service account and cluster role binding to your cluster:
-
-          ```bash
-          kubectl apply -f gitlab-admin-service-account.yaml
-          ```
-
-          Output:
-
-          ```bash
-          serviceaccount "gitlab-admin" created
-          clusterrolebinding "gitlab-admin" created
-          ```
-
-      1. Retrieve the token for the `gitlab-admin` service account:
-
-          ```bash
-          kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}')
-          ```
-
-         Copy the `<authentication_token>` value from the output:
-
-         ```yaml
-         Name:         gitlab-admin-token-b5zv4
-         Namespace:    kube-system
-         Labels:       <none>
-         Annotations:  kubernetes.io/service-account.name=gitlab-admin
-                       kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8
-
-         Type:  kubernetes.io/service-account-token
-
-         Data
-         ====
-         ca.crt:     1025 bytes
-         namespace:  11 bytes
-         token:      <authentication_token>
-         ```
-
-      NOTE: **Note:**
-      For GKE clusters, you will need the
-      `container.clusterRoleBindings.create` permission to create a cluster
-      role binding. You can follow the [Google Cloud
-      documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access)
-      to grant access.
-
-    - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](#gitlab-managed-clusters) for more information.
-
-    - **Project namespace** (optional) - You don't have to fill it in; by leaving
-      it blank, GitLab will create one for you. Also:
-       - Each project should have a unique namespace.
-       - The project namespace is not necessarily the namespace of the secret, if
-         you're using a secret with broader permissions, like the secret from `default`.
-       - You should **not** use `default` as the project namespace.
-       - If you or someone created a secret specifically for the project, usually
-         with limited permissions, the secret's namespace and project namespace may
-         be the same.
+   - **Kubernetes cluster name** (required) - The name you wish to give the cluster.
+   - **Environment scope** (required) - The
+     [associated environment](#setting-the-environment-scope-premium) to this cluster.
+   - **API URL** (required) -
+     It's the URL that GitLab uses to access the Kubernetes API. Kubernetes
+     exposes several APIs, we want the "base" URL that is common to all of them,
+     e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`.
+
+     Get the API URL by running this command:
+
+     ```sh
+     kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}'
+     ```
+
+   - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the EKS cluster. We will use the certificate created by default.
+     - List the secrets with `kubectl get secrets`, and one should named similar to
+      `default-token-xxxxx`. Copy that token name for use below.
+     - Get the certificate by running this command:
+
+     ```sh
+     kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode
+     ```
+
+   - **Token** -
+     GitLab authenticates against Kubernetes using service tokens, which are
+     scoped to a particular `namespace`.
+     **The token used should belong to a service account with
+     [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
+     privileges.** To create this service account:
+
+     1. Create a file called `gitlab-admin-service-account.yaml` with contents:
+
+        ```yaml
+        apiVersion: v1
+        kind: ServiceAccount
+        metadata:
+          name: gitlab-admin
+          namespace: kube-system
+        ---
+        apiVersion: rbac.authorization.k8s.io/v1beta1
+        kind: ClusterRoleBinding
+        metadata:
+          name: gitlab-admin
+        roleRef:
+          apiGroup: rbac.authorization.k8s.io
+          kind: ClusterRole
+          name: cluster-admin
+        subjects:
+        - kind: ServiceAccount
+          name: gitlab-admin
+          namespace: kube-system
+        ```
+
+     1. Apply the service account and cluster role binding to your cluster:
+
+        ```bash
+        kubectl apply -f gitlab-admin-service-account.yaml
+        ```
+
+        Output:
+
+        ```bash
+        serviceaccount "gitlab-admin" created
+        clusterrolebinding "gitlab-admin" created
+        ```
+
+     1. Retrieve the token for the `gitlab-admin` service account:
+
+        ```bash
+        kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}')
+        ```
+
+        Copy the `<authentication_token>` value from the output:
+
+        ```yaml
+        Name:         gitlab-admin-token-b5zv4
+        Namespace:    kube-system
+        Labels:       <none>
+        Annotations:  kubernetes.io/service-account.name=gitlab-admin
+                      kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8
+
+        Type:  kubernetes.io/service-account-token
+
+        Data
+        ====
+        ca.crt:     1025 bytes
+        namespace:  11 bytes
+        token:      <authentication_token>
+        ```
+
+     NOTE: **Note:**
+     For GKE clusters, you will need the
+     `container.clusterRoleBindings.create` permission to create a cluster
+     role binding. You can follow the [Google Cloud
+     documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access)
+     to grant access.
+
+   - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](#gitlab-managed-clusters) for more information.
+
+   - **Project namespace** (optional) - You don't have to fill it in; by leaving
+     it blank, GitLab will create one for you. Also:
+     - Each project should have a unique namespace.
+     - The project namespace is not necessarily the namespace of the secret, if
+       you're using a secret with broader permissions, like the secret from `default`.
+     - You should **not** use `default` as the project namespace.
+     - If you or someone created a secret specifically for the project, usually
+       with limited permissions, the secret's namespace and project namespace may
+       be the same.
 
 1. Finally, click the **Create Kubernetes cluster** button.
 
 After a couple of minutes, your cluster will be ready to go. You can now proceed
 to install some [pre-defined applications](#installing-applications).
 
-## Security implications
+### Enabling or disabling integration
+
+After you have successfully added your cluster information, you can enable the
+Kubernetes cluster integration:
+
+1. Click the **Enabled/Disabled** switch
+1. Hit **Save** for the changes to take effect
+
+To disable the Kubernetes cluster integration, follow the same procedure.
+
+### Removing integration
+
+NOTE: **Note:**
+You need Maintainer [permissions](../../permissions.md) and above to remove a Kubernetes cluster integration.
+
+NOTE: **Note:**
+When you remove a cluster, you only remove its relation to GitLab, not the
+cluster itself. To remove the cluster, you can do so by visiting the GKE
+dashboard or using `kubectl`.
+
+To remove the Kubernetes cluster integration from your project, simply click the
+**Remove integration** button. You will then be able to follow the procedure
+and add a Kubernetes cluster again.
+
+## Cluster configuration
+
+This section covers important considerations for configuring Kubernetes
+clusters with GitLab.
+
+### Security implications
 
 CAUTION: **Important:**
 The whole cluster security is based on a model where [developers](../../permissions.md)
@@ -220,15 +339,11 @@ functionalities needed to successfully build and deploy a containerized
 application. Bear in mind that the same credentials are used for all the
 applications running on the cluster.
 
-## Gitlab-managed clusters
+### GitLab-managed clusters
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22011) in GitLab 11.5.
 > Became [optional](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/26565) in GitLab 11.11.
 
-NOTE: **Note:**
-Only available when creating clusters. Existing clusters not managed by GitLab
-cannot become GitLab-managed later.
-
 You can choose to allow GitLab to manage your cluster for you. If your cluster is
 managed by GitLab, resources for your projects will be automatically created. See the
 [Access controls](#access-controls) section for details on which resources will
@@ -243,7 +358,7 @@ NOTE: **Note:**
 If you [install applications](#installing-applications) on your cluster, GitLab will create
 the resources required to run these even if you have chosen to manage your own cluster.
 
-## Base domain
+### Base domain
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24580) in GitLab 11.8.
 
@@ -261,7 +376,7 @@ you can either:
 - Create an `A` record that points to the Ingress IP address with your domain provider.
 - Enter a wildcard DNS address using a service such as nip.io or xip.io. For example, `192.168.1.1.xip.io`.
 
-## Access controls
+### Access controls
 
 When creating a cluster in GitLab, you will be asked if you would like to create either:
 
@@ -272,13 +387,9 @@ NOTE: **Note:**
 [RBAC](#rbac-cluster-resources) is recommended and the GitLab default.
 
 GitLab creates the necessary service accounts and privileges to install and run
-[GitLab managed applications](#installing-applications). When GitLab creates the cluster:
-
-- A `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace
-  to manage the newly created cluster.
-- A project service account with [`edit`
-  privileges](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
-  is created in the GitLab-created project namespace for [deployment jobs](#deployment-variables).
+[GitLab managed applications](#installing-applications). When GitLab creates the cluster,
+a `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace
+to manage the newly created cluster.
 
   NOTE: **Note:**
   Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/51716) in GitLab 11.5.
@@ -291,47 +402,53 @@ Helm will also create additional service accounts and other resources for each
 installed application. Consult the documentation of the Helm charts for each application
 for details.
 
-If you are [adding an existing Kubernetes cluster](#adding-an-existing-kubernetes-cluster),
+If you are [adding an existing Kubernetes cluster](#add-existing-kubernetes-cluster),
 ensure the token of the account has administrator privileges for the cluster.
 
 The resources created by GitLab differ depending on the type of cluster.
 
-### ABAC cluster resources
+#### ABAC cluster resources
 
 GitLab creates the following resources for ABAC clusters.
 
-| Name              | Type                 | Details                           | Created when               |
-|:------------------|:---------------------|:----------------------------------|:---------------------------|
-| `gitlab`          | `ServiceAccount`     | `default` namespace               | Creating a new GKE Cluster |
-| `gitlab-token`    | `Secret`             | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster |
-| `tiller`          | `ServiceAccount`     | `gitlab-managed-apps` namespace   | Installing Helm Tiller     |
-| `tiller-admin`    | `ClusterRoleBinding` | `cluster-admin` roleRef           | Installing Helm Tiller     |
-| Project namespace | `ServiceAccount`     | Uses namespace of Project         | Deploying to a cluster     |
-| Project namespace | `Secret`             | Token for project ServiceAccount  | Deploying to a cluster     |
+| Name                  | Type                 | Details                              | Created when               |
+|:----------------------|:---------------------|:-------------------------------------|:---------------------------|
+| `gitlab`              | `ServiceAccount`     | `default` namespace                         | Creating a new GKE Cluster |
+| `gitlab-token`        | `Secret`             | Token for `gitlab` ServiceAccount           | Creating a new GKE Cluster |
+| `tiller`              | `ServiceAccount`     | `gitlab-managed-apps` namespace             | Installing Helm Tiller     |
+| `tiller-admin`        | `ClusterRoleBinding` | `cluster-admin` roleRef                     | Installing Helm Tiller     |
+| Environment namespace | `Namespace`          | Contains all environment-specific resources | Deploying to a cluster     |
+| Environment namespace | `ServiceAccount`     | Uses namespace of environment               | Deploying to a cluster     |
+| Environment namespace | `Secret`             | Token for environment ServiceAccount        | Deploying to a cluster     |
 
-### RBAC cluster resources
+#### RBAC cluster resources
 
 GitLab creates the following resources for RBAC clusters.
 
-| Name              | Type                 | Details                                                                                                    | Created when               |
-|:------------------|:---------------------|:-----------------------------------------------------------------------------------------------------------|:---------------------------|
-| `gitlab`          | `ServiceAccount`     | `default` namespace                                                                                        | Creating a new GKE Cluster |
-| `gitlab-admin`    | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new GKE Cluster |
-| `gitlab-token`    | `Secret`             | Token for `gitlab` ServiceAccount                                                                          | Creating a new GKE Cluster |
-| `tiller`          | `ServiceAccount`     | `gitlab-managed-apps` namespace                                                                            | Installing Helm Tiller     |
-| `tiller-admin`    | `ClusterRoleBinding` | `cluster-admin` roleRef                                                                                    | Installing Helm Tiller     |
-| Project namespace | `ServiceAccount`     | Uses namespace of Project                                                                                  | Deploying to a cluster     |
-| Project namespace | `Secret`             | Token for project ServiceAccount                                                                           | Deploying to a cluster     |
-| Project namespace | `RoleBinding`        | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef          | Deploying to a cluster     |
+| Name                  | Type                 | Details                                                                                                    | Created when               |
+|:----------------------|:---------------------|:-----------------------------------------------------------------------------------------------------------|:---------------------------|
+| `gitlab`              | `ServiceAccount`     | `default` namespace                                                                                        | Creating a new GKE Cluster |
+| `gitlab-admin`        | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new GKE Cluster |
+| `gitlab-token`        | `Secret`             | Token for `gitlab` ServiceAccount                                                                          | Creating a new GKE Cluster |
+| `tiller`              | `ServiceAccount`     | `gitlab-managed-apps` namespace                                                                            | Installing Helm Tiller     |
+| `tiller-admin`        | `ClusterRoleBinding` | `cluster-admin` roleRef                                                                                    | Installing Helm Tiller     |
+| Environment namespace | `Namespace`          | Contains all environment-specific resources                                                                | Deploying to a cluster     |
+| Environment namespace | `ServiceAccount`     | Uses namespace of environment                                                                              | Deploying to a cluster     |
+| Environment namespace | `Secret`             | Token for environment ServiceAccount                                                                       | Deploying to a cluster     |
+| Environment namespace | `RoleBinding`        | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef          | Deploying to a cluster     |
 
 NOTE: **Note:**
-Project-specific resources are only created if your cluster is [managed by GitLab](#gitlab-managed-clusters).
+Environment-specific resources are only created if your cluster is [managed by GitLab](#gitlab-managed-clusters).
 
-### Security of GitLab Runners
+NOTE: **Note:**
+If your cluster was created before GitLab 12.2, it will use a single namespace for all project environments.
+
+#### Security of GitLab Runners
 
 GitLab Runners have the [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#the-privileged-mode)
 enabled by default, which allows them to execute special commands and running
-Docker in Docker. This functionality is needed to run some of the [Auto DevOps]
+Docker in Docker. This functionality is needed to run some of the
+[Auto DevOps](../../../topics/autodevops/index.md)
 jobs. This implies the containers are running in privileged mode and you should,
 therefore, be aware of some important details.
 
@@ -340,10 +457,81 @@ turn can do almost everything that the host can do. Be aware of the
 inherent security risk associated with performing `docker run` operations on
 arbitrary images as they effectively have root access.
 
-If you don't want to use GitLab Runner in privileged mode, first make sure that
-you don't have it installed via the applications, and then use the
-[Runner's Helm chart](../../../install/kubernetes/gitlab_runner_chart.md) to
-install it manually.
+If you don't want to use GitLab Runner in privileged mode, either:
+
+- Use shared Runners on GitLab.com. They don't have this security issue.
+- Set up your own Runners using configuration described at
+  [Shared Runners](../../gitlab_com/index.md#shared-runners). This involves:
+  1. Making sure that you don't have it installed via
+     [the applications](#installing-applications).
+  1. Installing a Runner
+     [using `docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html).
+
+### Setting the environment scope **(PREMIUM)**
+
+When adding more than one Kubernetes cluster to your project, you need to differentiate
+them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments.md) similar to how the
+[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables) work.
+
+The default environment scope is `*`, which means all jobs, regardless of their
+environment, will use that cluster. Each scope can only be used by a single
+cluster in a project, and a validation error will occur if otherwise.
+Also, jobs that don't have an environment keyword set will not be able to access any cluster.
+
+For example, let's say the following Kubernetes clusters exist in a project:
+
+| Cluster     | Environment scope |
+| ----------- | ----------------- |
+| Development | `*`               |
+| Production  | `production`      |
+
+And the following environments are set in
+[`.gitlab-ci.yml`](../../../ci/yaml/README.md):
+
+```yaml
+stages:
+- test
+- deploy
+
+test:
+  stage: test
+  script: sh test
+
+deploy to staging:
+  stage: deploy
+  script: make deploy
+  environment:
+    name: staging
+    url: https://staging.example.com/
+
+deploy to production:
+  stage: deploy
+  script: make deploy
+  environment:
+    name: production
+    url: https://example.com/
+```
+
+The result will then be:
+
+- The Development cluster details will be available in the `deploy to staging`
+  job.
+- The production cluster details will be available in the `deploy to production`
+  job.
+- No cluster details will be available in the `test` job because it doesn't
+  define any environment.
+
+### Multiple Kubernetes clusters **(PREMIUM)**
+
+> Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3.
+
+With GitLab Premium, you can associate more than one Kubernetes cluster to your
+project. That way you can have different clusters for different environments,
+like dev, staging, production, etc.
+
+Simply add another cluster, like you did the first time, and make sure to
+[set an environment scope](#setting-the-environment-scope-premium) that will
+differentiate the new cluster with the rest.
 
 ## Installing applications
 
@@ -352,7 +540,7 @@ cluster. For more information on installing, upgrading, uninstalling,
 and troubleshooting applications for your project cluster, see
 [Gitlab Managed Apps](../../clusters/applications.md).
 
-## Getting the external endpoint
+### Getting the external endpoint
 
 NOTE: **Note:**
 With the following procedure, a load balancer must be installed in your cluster
@@ -363,7 +551,7 @@ to obtain the endpoint. You can use either
 In order to publish your web application, you first need to find the endpoint which will be either an IP
 address or a hostname associated with your load balancer.
 
-### Automatically determining the external endpoint
+#### Automatically determining the external endpoint
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17052) in GitLab 10.6.
 
@@ -378,7 +566,7 @@ and your cluster runs on Google Kubernetes Engine:
 If GitLab is still unable to determine the endpoint of your Ingress or Knative application, you can
 manually determine it by following the steps below.
 
-### Manually determining the external endpoint
+#### Manually determining the external endpoint
 
 If the cluster is on GKE, click the **Google Kubernetes Engine** link in the
 **Advanced settings**, or go directly to the
@@ -417,7 +605,7 @@ Otherwise, you can list the IP addresses of all load balancers:
 kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} '
 ```
 
-### Using a static IP
+#### Using a static IP
 
 By default, an ephemeral external IP address is associated to the cluster's load
 balancer. If you associate the ephemeral IP with your DNS and the IP changes,
@@ -427,79 +615,27 @@ reserved IP.
 
 Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip).
 
-### Pointing your DNS at the external endpoint
+#### Pointing your DNS at the external endpoint
 
 Once you've set up the external endpoint, you should associate it with a [wildcard DNS
 record](https://en.wikipedia.org/wiki/Wildcard_DNS_record) such as `*.example.com.`
 in order to be able to reach your apps. If your external endpoint is an IP address,
 use an A record. If your external endpoint is a hostname, use a CNAME record.
 
-## Multiple Kubernetes clusters **[PREMIUM]**
-
-> Introduced in [GitLab Premium][ee] 10.3.
-
-With GitLab Premium, you can associate more than one Kubernetes clusters to your
-project. That way you can have different clusters for different environments,
-like dev, staging, production, etc.
-
-Simply add another cluster, like you did the first time, and make sure to
-[set an environment scope](#setting-the-environment-scope-premium) that will
-differentiate the new cluster with the rest.
-
-## Setting the environment scope **[PREMIUM]**
-
-When adding more than one Kubernetes cluster to your project, you need to differentiate
-them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments.md) similar to how the
-[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables-premium) work.
-
-The default environment scope is `*`, which means all jobs, regardless of their
-environment, will use that cluster. Each scope can only be used by a single
-cluster in a project, and a validation error will occur if otherwise.
-Also, jobs that don't have an environment keyword set will not be able to access any cluster.
+## Deploying to a Kubernetes cluster
 
----
-
-For example, let's say the following Kubernetes clusters exist in a project:
-
-| Cluster     | Environment scope |
-| ----------- | ----------------- |
-| Development | `*`               |
-| Staging     | `staging`         |
-| Production  | `production`      |
+A Kubernetes cluster can be the destination for a deployment job. If
 
-And the following environments are set in [`.gitlab-ci.yml`](../../../ci/yaml/README.md):
+- The cluster is integrated with GitLab, special
+  [deployment variables](#deployment-variables) are made available to your job
+  and configuration is not required. You can immediately begin interacting with
+  the cluster from your jobs using tools such as `kubectl` or `helm`.
+- You don't use GitLab's cluster integration you can still deploy to your
+  cluster. However, you will need configure Kubernetes tools yourself
+  using [environment variables](../../../ci/variables/README.md#creating-a-custom-environment-variable)
+  before you can interact with the cluster from your jobs.
 
-```yaml
-stages:
-- test
-- deploy
-
-test:
-  stage: test
-  script: sh test
-
-deploy to staging:
-  stage: deploy
-  script: make deploy
-  environment:
-    name: staging
-    url: https://staging.example.com/
-
-deploy to production:
-  stage: deploy
-  script: make deploy
-  environment:
-    name: production
-    url: https://example.com/
-```
-
-The result will then be:
-
-- The development cluster will be used for the "test" job.
-- The staging cluster will be used for the "deploy to staging" job.
-- The production cluster will be used for the "deploy to production" job.
-
-## Deployment variables
+### Deployment variables
 
 The Kubernetes cluster integration exposes the following
 [deployment variables](../../../ci/variables/README.md#deployment-environment-variables) in the
@@ -508,8 +644,8 @@ GitLab CI/CD build environment.
 | Variable | Description |
 | -------- | ----------- |
 | `KUBE_URL` | Equal to the API URL. |
-| `KUBE_TOKEN` | The Kubernetes token of the [project service account](#access-controls). |
-| `KUBE_NAMESPACE` | The Kubernetes namespace is auto-generated if not specified. The default value is `<project_name>-<project_id>`. You can overwrite it to use different one if needed, otherwise the `KUBE_NAMESPACE` variable will receive the default value. |
+| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](#access-controls). |
+| `KUBE_NAMESPACE` | The Kubernetes namespace is auto-generated if not specified. The default value is `<project_name>-<project_id>-<environment>`. You can overwrite it to use different one if needed, otherwise the `KUBE_NAMESPACE` variable will receive the default value. |
 | `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. |
 | `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. |
 | `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This config also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. |
@@ -519,12 +655,16 @@ NOTE: **NOTE:**
 Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main
 service account of the cluster integration.
 
-### Troubleshooting failed deployment jobs
+NOTE: **Note:**
+If your cluster was created before GitLab 12.2, default `KUBE_NAMESPACE` will be set to `<project_name>-<project_id>`.
+
+### Troubleshooting
 
-GitLab will create a namespace and service account specifically for your
-deployment jobs. On project level clusters, this happens when the cluster
-is created. On group level clusters, resources are created immediately
-before the deployment job starts.
+Before the deployment jobs starts, GitLab creates the following specifically for
+the deployment job:
+
+- A namespace.
+- A service account.
 
 However, sometimes GitLab can not create them. In such instances, your job will fail with the message:
 
@@ -534,115 +674,24 @@ This job failed because the necessary resources were not successfully created.
 
 To find the cause of this error when creating a namespace and service account, check the [logs](../../../administration/logs.md#kuberneteslog).
 
-Common reasons for failure include:
+Reasons for failure include:
 
-- The token you gave GitLab did not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
+- The token you gave GitLab does not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
   privileges required by GitLab.
 - Missing `KUBECONFIG` or `KUBE_TOKEN` variables. To be passed to your job, they must have a matching
   [`environment:name`](../../../ci/environments.md#defining-environments). If your job has no
   `environment:name` set, it will not be passed the Kubernetes credentials.
 
-## Monitoring your Kubernetes cluster **[ULTIMATE]**
+NOTE: **NOTE:**
+Project-level clusters upgraded from GitLab 12.0 or older may be configured
+in a way that causes this error. Ensure you deselect the
+[GitLab-managed cluster](#gitlab-managed-clusters) option if you want to manage
+namespaces and service accounts yourself.
+
+## Monitoring your Kubernetes cluster **(ULTIMATE)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4701) in [GitLab Ultimate][ee] 10.6.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6.
 
 When [Prometheus is deployed](#installing-applications), GitLab will automatically monitor the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start.
 
 ![Cluster Monitoring](img/k8s_cluster_monitoring.png)
-
-## Enabling or disabling the Kubernetes cluster integration
-
-After you have successfully added your cluster information, you can enable the
-Kubernetes cluster integration:
-
-1. Click the **Enabled/Disabled** switch
-1. Hit **Save** for the changes to take effect
-
-You can now start using your Kubernetes cluster for your deployments.
-
-To disable the Kubernetes cluster integration, follow the same procedure.
-
-## Removing the Kubernetes cluster integration
-
-NOTE: **Note:**
-You need Maintainer [permissions] and above to remove a Kubernetes cluster integration.
-
-NOTE: **Note:**
-When you remove a cluster, you only remove its relation to GitLab, not the
-cluster itself. To remove the cluster, you can do so by visiting the GKE
-dashboard or using `kubectl`.
-
-To remove the Kubernetes cluster integration from your project, simply click the
-**Remove integration** button. You will then be able to follow the procedure
-and add a Kubernetes cluster again.
-
-## What you can get with the Kubernetes integration
-
-Here's what you can do with GitLab if you enable the Kubernetes integration.
-
-### Deploy Boards **[PREMIUM]**
-
-GitLab's Deploy Boards offer a consolidated view of the current health and
-status of each CI [environment](../../../ci/environments.md) running on Kubernetes,
-displaying the status of the pods in the deployment. Developers and other
-teammates can view the progress and status of a rollout, pod by pod, in the
-workflow they already use without any need to access Kubernetes.
-
-[Read more about Deploy Boards](../deploy_boards.md)
-
-### Canary Deployments **[PREMIUM]**
-
-Leverage [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments)
-and visualize your canary deployments right inside the Deploy Board, without
-the need to leave GitLab.
-
-[Read more about Canary Deployments](../canary_deployments.md)
-
-### Pod logs **[ULTIMATE]**
-
-GitLab makes it easy to view the logs of running pods in connected Kubernetes clusters. By displaying the logs directly in GitLab, developers can avoid having to manage console tools or jump to a different interface.
-
-[Read more about Kubernetes pod logs](kubernetes_pod_logs.md)
-
-### Kubernetes monitoring
-
-Automatically detect and monitor Kubernetes metrics. Automatic monitoring of
-[NGINX ingress](../integrations/prometheus_library/nginx.md) is also supported.
-
-[Read more about Kubernetes monitoring](../integrations/prometheus_library/kubernetes.md)
-
-### Auto DevOps
-
-Auto DevOps automatically detects, builds, tests, deploys, and monitors your
-applications.
-
-To make full use of Auto DevOps(Auto Deploy, Auto Review Apps, and Auto Monitoring)
-you will need the Kubernetes project integration enabled.
-
-[Read more about Auto DevOps](../../../topics/autodevops/index.md)
-
-### Web terminals
-
-NOTE: **Note:**
-Introduced in GitLab 8.15. You must be the project owner or have `maintainer` permissions
-to use terminals. Support is limited to the first container in the
-first pod of your environment.
-
-When enabled, the Kubernetes service adds [web terminal](../../../ci/environments.md#web-terminals)
-support to your [environments](../../../ci/environments.md). This is based on the `exec` functionality found in
-Docker and Kubernetes, so you get a new shell session within your existing
-containers. To use this integration, you should deploy to Kubernetes using
-the deployment variables above, ensuring any pods you create are labelled with
-`app=$CI_ENVIRONMENT_SLUG`. GitLab will do the rest!
-
-### Integrating Amazon EKS cluster with GitLab
-
-- Learn how to [connect and deploy to an Amazon EKS cluster](eks_and_gitlab/index.md).
-
-### Serverless
-
-- [Run serverless workloads on Kubernetes with Knative.](serverless/index.md)
-
-[permissions]: ../../permissions.md
-[ee]: https://about.gitlab.com/pricing/
-[Auto DevOps]: ../../../topics/autodevops/index.md
diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md
index 368031070c1..163f3befeee 100644
--- a/doc/user/project/clusters/kubernetes_pod_logs.md
+++ b/doc/user/project/clusters/kubernetes_pod_logs.md
@@ -1,10 +1,14 @@
-# Kubernetes Pod Logs **[ULTIMATE]**
+# Kubernetes Pod Logs **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0.
 
 GitLab makes it easy to view the logs of running pods in [connected Kubernetes clusters](index.md).
 By displaying the logs directly in GitLab, developers can avoid having to manage console tools or jump to a different interface.
 
+NOTE: **Kubernetes + GitLab**
+Everything you need to build, test, deploy, and run your app at scale.
+[Learn more](https://about.gitlab.com/solutions/kubernetes/).
+
 ## Overview
 
 [Kubernetes](https://kubernetes.io) pod logs can be viewed directly within GitLab. Logs can be displayed by clicking on a specific pod from [Deploy Boards](../deploy_boards.md):
@@ -12,9 +16,9 @@ By displaying the logs directly in GitLab, developers can avoid having to manage
 1. Go to **Operations > Environments** and find the environment which contains the desired pod, like `production`.
 1. On the **Environments** page, you should see the status of the environment's pods with [Deploy Boards](../deploy_boards.md).
 1. When mousing over the list of pods, a tooltip will appear with the exact pod name and status.
-![Deploy Boards pod list](img/pod_logs_deploy_board.png)
+   ![Deploy Boards pod list](img/pod_logs_deploy_board.png)
 1. Click on the desired pod to bring up the logs view, which will contain the last 500 lines for that pod. Support for pods with multiple containers is coming [in a future release](https://gitlab.com/gitlab-org/gitlab-ee/issues/6502).
-![Deploy Boards pod list](img/kubernetes_pod_logs.png)
+   ![Deploy Boards pod list](img/kubernetes_pod_logs.png)
 
 ## Requirements
 
diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md
index c67b12fb91a..8df27976662 100644
--- a/doc/user/project/clusters/runbooks/index.md
+++ b/doc/user/project/clusters/runbooks/index.md
@@ -1,28 +1,27 @@
 # Runbooks
 
-Runbooks are a collection of documented procedures that explain how to 
-carry out a particular process, be it starting, stopping, debugging, 
+Runbooks are a collection of documented procedures that explain how to
+carry out a particular process, be it starting, stopping, debugging,
 or troubleshooting a particular system.
 
 Using [Jupyter Notebooks](https://jupyter.org/) and the [Rubix library](https://github.com/Nurtch/rubix),
 users can get started writing their own executable runbooks.
 
-
 ## Overview
 
-Historically, runbooks took the form of a decision tree or a detailed 
-step-by-step guide depending on the condition or system. 
+Historically, runbooks took the form of a decision tree or a detailed
+step-by-step guide depending on the condition or system.
 
-Modern implementations have introduced the concept of an "executable 
-runbooks", where, along with a well-defined process, operators can execute 
+Modern implementations have introduced the concept of an "executable
+runbooks", where, along with a well-defined process, operators can execute
 pre-written code blocks or database queries against a given environment.
 
 ## Executable Runbooks
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/45912) in GitLab 11.4.
 
-The JupyterHub app offered via GitLab’s Kubernetes integration now ships 
-with Nurtch’s Rubix library, providing a simple way to create DevOps 
+The JupyterHub app offered via GitLab’s Kubernetes integration now ships
+with Nurtch’s Rubix library, providing a simple way to create DevOps
 runbooks. A sample runbook is provided, showcasing common operations. While Rubix makes it
 simple to create common Kubernetes and AWS workflows, you can also create them manually without
 Rubix.
@@ -35,33 +34,33 @@ for an overview of how this is accomplished in GitLab!**
 
 To create an executable runbook, you will need:
 
-1. **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. 
-    The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab).
-1. **Helm Tiller** - Helm is a package manager for Kubernetes and is required to install 
-    all the other applications. It is installed in its own pod inside the cluster which 
+1. **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications.
+    The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#add-new-gke-cluster).
+1. **Helm Tiller** - Helm is a package manager for Kubernetes and is required to install
+    all the other applications. It is installed in its own pod inside the cluster which
     can run the helm CLI in a safe environment.
-1. **Ingress** - Ingress can provide load balancing, SSL termination, and name-based 
+1. **Ingress** - Ingress can provide load balancing, SSL termination, and name-based
     virtual hosting. It acts as a web proxy for your applications.
-1. **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user service for managing notebooks across 
-    a team. Jupyter Notebooks provide a web-based interactive programming environment 
+1. **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user service for managing notebooks across
+    a team. Jupyter Notebooks provide a web-based interactive programming environment
     used for data analysis, visualization, and machine learning.
 
 ## Nurtch
 
-Nurtch is the company behind the [Rubix library](https://github.com/Nurtch/rubix). Rubix is 
-an open-source python library that makes it easy to perform common DevOps tasks inside Jupyter Notebooks. 
-Tasks such as plotting Cloudwatch metrics and rolling your ECS/Kubernetes app are simplified 
-down to a couple of lines of code. See the [Nurtch Documentation](http://docs.nurtch.com/en/latest) 
+Nurtch is the company behind the [Rubix library](https://github.com/Nurtch/rubix). Rubix is
+an open-source python library that makes it easy to perform common DevOps tasks inside Jupyter Notebooks.
+Tasks such as plotting Cloudwatch metrics and rolling your ECS/Kubernetes app are simplified
+down to a couple of lines of code. See the [Nurtch Documentation](http://docs.nurtch.com/en/latest)
 for more information.
 
 ## Configure an executable runbook with GitLab
 
-Follow this step-by-step guide to configure an executable runbook in GitLab using 
+Follow this step-by-step guide to configure an executable runbook in GitLab using
 the components outlined above and the preloaded demo runbook.
 
 ### 1. Add a Kubernetes cluster
 
-Follow the steps outlined in [Adding and creating a new GKE cluster via GitLab](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) 
+Follow the steps outlined in [Add new GKE cluster](../index.md#add-new-gke-cluster)
 to add a Kubernetes cluster to your project.
 
 ### 2. Install Helm Tiller, Ingress, and JupyterHub
@@ -80,13 +79,13 @@ Once Ingress has been installed successfully, click the **Install** button next
 
 ### 3. Login to JupyterHub and start the server
 
-Once JupyterHub has been installed successfully, navigate to the displayed **Jupyter Hostname** URL and click 
-**Sign in with GitLab**. Authentication is automatically enabled for any user of the GitLab instance via OAuth2. This 
+Once JupyterHub has been installed successfully, navigate to the displayed **Jupyter Hostname** URL and click
+**Sign in with GitLab**. Authentication is automatically enabled for any user of the GitLab instance via OAuth2. This
 will redirect to GitLab in order to authorize JupyterHub to use your GitLab account. Click **Authorize**.
 
 ![authorize jupyter](img/authorize-jupyter.png)
 
-Once the application has been authorized you will taken back to the JupyterHub application. Click **Start My Server**. 
+Once the application has been authorized you will taken back to the JupyterHub application. Click **Start My Server**.
 The server will take a couple of seconds to start.
 
 ### 4. Configure access
@@ -103,7 +102,7 @@ Double-click the "Nurtch-DevOps-Demo.ipynb" runbook.
 
 ![sample runbook](img/sample-runbook.png)
 
-The contents on the runbook will be displayed on the right side of the screen. Under the "Setup" section, you will find 
+The contents on the runbook will be displayed on the right side of the screen. Under the "Setup" section, you will find
 entries for both your `PRIVATE_TOKEN` and your `PROJECT_ID`. Enter both these values, conserving the single quotes as follows:
 
 ```sql
@@ -111,7 +110,7 @@ PRIVATE_TOKEN = 'n671WNGecHugsdEDPsyo'
 PROJECT_ID = '1234567'
 ```
 
-Update the `VARIABLE_NAME` on the last line of this section to match the name of the variable you are using for your 
+Update the `VARIABLE_NAME` on the last line of this section to match the name of the variable you are using for your
 access token. In this example our variable name is `PRIVATE_TOKEN`.
 
 ```sql
@@ -120,8 +119,8 @@ VARIABLE_VALUE = project.variables.get('PRIVATE_TOKEN').value
 
 ### 5. Configure an operation
 
-For this example we'll use the "**Run SQL queries in Notebook**" section in the sample runbook to query 
-a postgres database. The first 4 lines of the section define the variables that are required for this query to function. 
+For this example we'll use the "**Run SQL queries in Notebook**" section in the sample runbook to query
+a postgres database. The first 4 lines of the section define the variables that are required for this query to function.
 
 ```sql
 %env DB_USER={project.variables.get('DB_USER').value}
@@ -134,10 +133,10 @@ Create the matching variables in your project's **Settings >> CI/CD >> Variables
 
 ![gitlab variables](img/gitlab-variables.png)
 
-Back in Jupyter, click the "Run SQL queries in Notebook" heading and the click *Run*. The results will be 
+Back in Jupyter, click the "Run SQL queries in Notebook" heading and the click *Run*. The results will be
 displayed in-line as follows:
 
 ![postgres query](img/postgres-query.png)
 
-You can try other operations such as running shell scripts or interacting with a Kubernetes cluster. Visit the 
-[Nurtch Documentation](http://docs.nurtch.com/) for more information.
\ No newline at end of file
+You can try other operations such as running shell scripts or interacting with a Kubernetes cluster. Visit the
+[Nurtch Documentation](http://docs.nurtch.com/) for more information.
diff --git a/doc/user/project/clusters/serverless/img/dns-entry.png b/doc/user/project/clusters/serverless/img/dns-entry.png
index 351e40b77d5..7b5d6497f0e 100644
--- a/doc/user/project/clusters/serverless/img/dns-entry.png
+++ b/doc/user/project/clusters/serverless/img/dns-entry.png
diff --git a/doc/user/project/clusters/serverless/img/function-details-loaded.png b/doc/user/project/clusters/serverless/img/function-details-loaded.png
index 34465c5c087..2f0d61f8032 100644
--- a/doc/user/project/clusters/serverless/img/function-details-loaded.png
+++ b/doc/user/project/clusters/serverless/img/function-details-loaded.png
diff --git a/doc/user/project/clusters/serverless/img/function-endpoint.png b/doc/user/project/clusters/serverless/img/function-endpoint.png
new file mode 100644
index 00000000000..a38fe2cb6c2
--- /dev/null
+++ b/doc/user/project/clusters/serverless/img/function-endpoint.png
diff --git a/doc/user/project/clusters/serverless/img/function-execution.png b/doc/user/project/clusters/serverless/img/function-execution.png
index 93b0b6d802d..f60dd277081 100644
--- a/doc/user/project/clusters/serverless/img/function-execution.png
+++ b/doc/user/project/clusters/serverless/img/function-execution.png
diff --git a/doc/user/project/clusters/serverless/img/install-knative.png b/doc/user/project/clusters/serverless/img/install-knative.png
index ecc2f8fb481..1dc830848f2 100644
--- a/doc/user/project/clusters/serverless/img/install-knative.png
+++ b/doc/user/project/clusters/serverless/img/install-knative.png
diff --git a/doc/user/project/clusters/serverless/img/serverless-page.png b/doc/user/project/clusters/serverless/img/serverless-page.png
index a872fda7740..8dce3cb1f70 100644
--- a/doc/user/project/clusters/serverless/img/serverless-page.png
+++ b/doc/user/project/clusters/serverless/img/serverless-page.png
diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md
index 2cda850f24e..bcf9a677a40 100644
--- a/doc/user/project/clusters/serverless/index.md
+++ b/doc/user/project/clusters/serverless/index.md
@@ -24,34 +24,33 @@ To run Knative on Gitlab, you will need:
 
 1. **Existing GitLab project:** You will need a GitLab project to associate all resources. The simplest way to get started:
 
-    - If you are planning on deploying functions, clone the [functions example project](https://gitlab.com/knative-examples/functions) to get started.
-    - If you are planning on deploying a serverless application, clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started.
+   - If you are planning on deploying functions, clone the [functions example project](https://gitlab.com/knative-examples/functions) to get started.
+   - If you are planning on deploying a serverless application, clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started.
 
 1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative.
-    The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab).
-    The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory.
+   The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#add-new-gke-cluster).
+   The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory.
 1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install
-    Knative.
+   Knative.
 1. **GitLab Runner:** A runner is required to run the CI jobs that will deploy serverless
-    applications or functions onto your cluster. You can install the GitLab Runner
-    onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information.
+   applications or functions onto your cluster. You can install the GitLab Runner
+   onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information.
 1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an
-    external IP address or hostname for all the applications served by Knative. You will be prompted to enter a
-    wildcard domain where your applications will be served. Configure your DNS server to use the
-    external IP address or hostname for that domain.
+   external IP address or hostname for all the applications served by Knative. You will be prompted to enter a
+   wildcard domain where your applications will be served. Configure your DNS server to use the
+   external IP address or hostname for that domain.
 1. **`.gitlab-ci.yml`:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko)
-    to build the application. We also use [gitlabktl](https://gitlab.com/gitlab-org/gitlabktl)
-    and [TriggerMesh CLI](https://github.com/triggermesh/tm) CLIs to simplify the
-    deployment of services and functions to Knative.
+   to build the application. We also use [gitlabktl](https://gitlab.com/gitlab-org/gitlabktl)
+   CLI to simplify the deployment of services and functions to Knative.
 1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file
-    will contain the information for all the functions being hosted in the repository as well as a reference to the
-    runtime being used.
+   will contain the information for all the functions being hosted in the repository as well as a reference to the
+   runtime being used.
 1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications): Knative requires a
-    `Dockerfile` in order to build your applications. It should be included at the root of your
-    project's repo and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions
-    using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes).
+   `Dockerfile` in order to build your applications. It should be included at the root of your
+   project's repo and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions
+   using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes).
 1. **Prometheus** (optional): Installing Prometheus allows you to monitor the scale and traffic of your serverless function/application.
-    See [Installing Applications](../index.md#installing-applications) for more information.
+   See [Installing Applications](../index.md#installing-applications) for more information.
 
 ## Installing Knative via GitLab's Kubernetes integration
 
@@ -60,9 +59,9 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.
 
 1. [Add a Kubernetes cluster](../index.md) and [install Helm](../index.md#installing-applications).
 1. Once Helm has been successfully installed, scroll down to the Knative app section. Enter the domain to be used with
-    your application/functions (e.g. `example.com`) and click **Install**.
+   your application/functions (e.g. `example.com`) and click **Install**.
 
-    ![install-knative](img/install-knative.png)
+   ![install-knative](img/install-knative.png)
 
 1. After the Knative installation has finished, you can wait for the IP address or hostname to be displayed in the
    **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../#manually-determining-the-external-endpoint).
@@ -77,19 +76,90 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.
    if your Knative base domain is `knative.info` then you need to create an A record or CNAME record with domain `*.knative.info`
    pointing the ip address or hostname of the ingress.
 
-    ![dns entry](img/dns-entry.png)
+   ![dns entry](img/dns-entry.png)
 
 NOTE: **Note:**
 You can deploy either [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications)
 on a given project but not both. The current implementation makes use of a `serverless.yml` file to signal a FaaS project.
 
+## Using an existing installation of Knative
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/58941) in GitLab 12.0.
+
+NOTE: **Note:**
+The "invocations" monitoring feature of GitLab serverless will not work when
+adding an existing installation of Knative.
+
+It is also possible to use GitLab Serverless with an existing Kubernetes
+cluster which already has Knative installed.
+
+You must do the following:
+
+1. Follow the steps to
+   [add an existing Kubernetes
+   cluster](../index.md#add-existing-kubernetes-cluster).
+
+1. Ensure GitLab can manage Knative:
+   - For a non-GitLab managed cluster, ensure that the service account for the token
+     provided can manage resources in the `serving.knative.dev` API group.
+   - For a GitLab managed cluster, if you added the cluster in [GitLab 12.1 or later](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30235),
+     then GitLab will already have the required access and you can proceed to the next step.
+
+     Otherwise, you need to manually grant GitLab's service account the ability to manage
+     resources in the `serving.knative.dev` API group. Since every GitLab service account
+     has the `edit` cluster role, the simplest way to do this is with an
+     [aggregated ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles)
+     adding rules to the default `edit` cluster role: First, save the following YAML as
+     `knative-serving-only-role.yaml`:
+
+     ```yaml
+     apiVersion: rbac.authorization.k8s.io/v1
+     kind: ClusterRole
+     metadata:
+       name: knative-serving-only-role
+       labels:
+         rbac.authorization.k8s.io/aggregate-to-edit: "true"
+     rules:
+     - apiGroups:
+       - serving.knative.dev
+       resources:
+       - configurations
+       - configurationgenerations
+       - routes
+       - revisions
+       - revisionuids
+       - autoscalers
+       - services
+       verbs:
+       - get
+       - list
+       - create
+       - update
+       - delete
+       - patch
+       - watch
+     ```
+
+     Then run the following command:
+
+     ```bash
+     kubectl apply -f knative-serving-only-role.yaml
+     ```
+
+     If you would rather grant permissions on a per service account basis, you can do this
+     using a `Role` and `RoleBinding` specific to the service account and namespace.
+
+1. Follow the steps to deploy [functions](#deploying-functions)
+   or [serverless applications](#deploying-serverless-applications) onto your
+   cluster.
+
 ## Deploying functions
 
 > Introduced in GitLab 11.6.
 
-Using functions is useful for dealing with independent
-events without needing to maintain a complex unified infrastructure. This allows
-you to focus on a single task that can be executed/scaled automatically and independently.
+Using functions is useful for dealing with independent events without needing
+to maintain a complex unified infrastructure. This allows you to focus on a
+single task that can be executed/scaled automatically and independently.
 
 Currently the following [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes) are offered:
 
@@ -97,15 +167,21 @@ Currently the following [runtimes](https://gitlab.com/gitlab-org/serverless/runt
 - node.js
 - Dockerfile
 
-You can find and import all the files referenced in this doc in the **[functions example project](https://gitlab.com/knative-examples/functions)**.
+`Dockerfile` presence is assumed when a runtime is not specified.
 
-Follow these steps to deploy a function using the Node.js runtime to your Knative instance (you can skip these steps if you've cloned the example project):
+You can find and import all the files referenced in this doc in the
+**[functions example project](https://gitlab.com/knative-examples/functions)**.
 
-1. Create a directory that will house the function. In this example we will create a directory called `echo` at the root of the project.
+Follow these steps to deploy a function using the Node.js runtime to your
+Knative instance (you can skip these steps if you've cloned the example
+project):
+
+1. Create a directory that will house the function. In this example we will
+   create a directory called `echo` at the root of the project.
 
 1. Create the file that will contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is:
-    - Public, continue to the next step.
-    - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope.
+   - Public, continue to the next step.
+   - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope.
 
 1. `.gitlab-ci.yml`: this defines a pipeline used to deploy your functions.
    It must be included at the root of your repository:
@@ -123,16 +199,16 @@ Follow these steps to deploy a function using the Node.js runtime to your Knativ
      environment: production
    ```
 
-    This `.gitlab-ci.yml` creates jobs that invoke some predefined commands to
-    build and deploy your functions to your cluster.
+   This `.gitlab-ci.yml` creates jobs that invoke some predefined commands to
+   build and deploy your functions to your cluster.
 
-    `Serverless.gitlab-ci.yml` is a template that allows customization.
-    You can either import it with `include` parameter and use `extends` to
-    customize your jobs, or you can inline the entire template by choosing it
-    from **Apply a template** dropdown when editing the `.gitlab-ci.yml` file through
-    the user interface.
+   `Serverless.gitlab-ci.yml` is a template that allows customization.
+   You can either import it with `include` parameter and use `extends` to
+   customize your jobs, or you can inline the entire template by choosing it
+   from **Apply a template** dropdown when editing the `.gitlab-ci.yml` file through
+   the user interface.
 
-2. `serverless.yml`: this file contains the metadata for your functions,
+1. `serverless.yml`: this file contains the metadata for your functions,
    such as name, runtime, and environment.
 
    It must be included at the root of your repository.
@@ -173,26 +249,27 @@ Explanation of the fields used above:
 
 | Parameter | Description |
 |-----------|-------------|
-| `name` | Indicates which provider is used to execute the `serverless.yml` file. In this case, the TriggerMesh `tm` CLI. |
+| `name` | Indicates which provider is used to execute the `serverless.yml` file. In this case, the TriggerMesh middleware. |
 | `environment` | Includes the environment variables to be passed as part of function execution for **all** functions in the file, where `FOO` is the variable name and `BAR` are he variable contents. You may replace this with you own variables. |
 
 ### `functions`
 
-In the `serverless.yml` example above, the function name is `echo` and the subsequent lines contain the function attributes.
+In the `serverless.yml` example above, the function name is `echo` and the
+subsequent lines contain the function attributes.
 
 | Parameter | Description |
 |-----------|-------------|
 | `handler` | The function's name. |
 | `source` | Directory with sources of a functions. |
-| `runtime` | The runtime to be used to execute the function. |
+| `runtime` (optional)| The runtime to be used to execute the function. When the runtime is not specified, we assume that `Dockerfile` is present in the function directory specified by `source`. |
 | `description` | A short description of the function. |
 | `environment` | Sets an environment variable for the specific function only. |
 
-After the `gitlab-ci.yml` template has been added and the `serverless.yml` file has been
-created, pushing a commit to your project will result in a
-CI pipeline being executed which will deploy each function as a Knative service.
-Once the deploy stage has finished, additional details for the function will
-appear under **Operations > Serverless**.
+After the `gitlab-ci.yml` template has been added and the `serverless.yml` file
+has been created, pushing a commit to your project will result in a CI pipeline
+being executed which will deploy each function as a Knative service.  Once the
+deploy stage has finished, additional details for the function will appear
+under **Operations > Serverless**.
 
 ![serverless page](img/serverless-page.png)
 
@@ -211,16 +288,17 @@ The sample function can now be triggered from any HTTP client using a simple `PO
 
   1. Using curl (replace the URL on the last line with the URL of your application):
 
-      ```bash
-      curl \
-      --header "Content-Type: application/json" \
-      --request POST \
-      --data '{"GitLab":"FaaS"}' \
-      http://functions-echo.functions-1.functions.example.com/
-      ```
-  2. Using a web-based tool (ie. postman, restlet, etc)
+     ```bash
+     curl \
+     --header "Content-Type: application/json" \
+     --request POST \
+     --data '{"GitLab":"FaaS"}' \
+     http://functions-echo.functions-1.functions.example.com/
+     ```
+
+  1. Using a web-based tool (ie. postman, restlet, etc)
 
-      ![function execution](img/function-execution.png)
+     ![function execution](img/function-execution.png)
 
 ## Deploying Serverless applications
 
@@ -249,6 +327,8 @@ customize your jobs, or you can inline the entire template by choosing it
 from **Apply a template** dropdown when editing the `.gitlab-ci.yml` file through
 the user interface.
 
+A `serverless.yml` file is not required when deploying serverless applications.
+
 ### Deploy the application with Knative
 
 With all the pieces in place, the next time a CI pipeline runs, the Knative application will be deployed. Navigate to
@@ -263,27 +343,23 @@ Go to the **CI/CD > Pipelines** and click on the pipeline that deployed your app
 The output will look like this:
 
 ```bash
-Running with gitlab-runner 11.5.0~beta.844.g96d88322 (96d88322)
-  on docker-auto-scale 72989761
-Using Docker executor with image gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ...
-Pulling docker image gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ...
-Using docker image sha256:6b3f6590a9b30bd7aafb9573f047d930c70066e43955b4beb18a1eee175f6de1 for gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ...
-Running on runner-72989761-project-4342902-concurrent-0 via runner-72989761-stg-srm-1541795796-27929c96...
-Cloning repository...
-Cloning into '/builds/danielgruesso/knative'...
-Checking out 8671ad20 as master...
-Skipping Git submodules setup
-$ echo "$CI_REGISTRY_IMAGE"
-registry.staging.gitlab.com/danielgruesso/knative
-$ tm -n "$KUBE_NAMESPACE" --config "$KUBECONFIG" deploy service "$CI_PROJECT_NAME" --from-image "$CI_REGISTRY_IMAGE" --wait
-Deployment started. Run "tm -n knative-4342902 describe service knative" to see the details
-Waiting for ready state.......
-Service domain: knative.knative-4342902.example.com
+Running with gitlab-runner 12.1.0-rc1 (6da35412)
+  on prm-com-gitlab-org ae3bfce3
+Using Docker executor with image registry.gitlab.com/gitlab-org/gitlabktl:latest ...
+Running on runner-ae3bfc-concurrent-0 via runner-ae3bfc ...
+Fetching changes...
+Authenticating with credentials from job payload (GitLab Registry)
+$ /usr/bin/gitlabktl application deploy
+Welcome to gitlabktl tool
+time="2019-07-15T10:51:07Z" level=info msg="deploying registry credentials"
+Creating app-hello function
+Waiting for app-hello ready state
+Service app-hello URL: http://app-hello.serverless.example.com
 Job succeeded
 ```
 
-The second to last line, labeled **Service domain** contains the URL for the deployment. Copy and paste the domain into your
-browser to see the app live.
+The second to last line, labeled **Service domain** contains the URL for the
+deployment. Copy and paste the domain into your browser to see the app live.
 
 ![knative app](img/knative-app.png)
 
@@ -306,3 +382,274 @@ loading or is not available at this time._  It will appear upon the first access
 page, but should go away after a few seconds. If the message does not disappear, then it
 is possible that GitLab is unable to connect to the Prometheus instance running on the
 cluster.
+
+## Enabling TLS for Knative services
+
+By default, a GitLab serverless deployment will be served over `http`. In order to serve over `https` you
+must manually obtain and install TLS certificates.
+
+The simplest way to accomplish this is to
+use [Certbot to manually obtain Let's Encrypt certificates](https://knative.dev/docs/serving/using-a-tls-cert/#using-certbot-to-manually-obtain-let-s-encrypt-certificates). Certbot is a free, open source software tool for automatically using Let’s Encrypt certificates on manually-administrated websites to enable HTTPS.
+
+NOTE: **Note:**
+The instructions below relate to installing and running Certbot on a Linux server and may not work on other operating systems.
+
+1. Install Certbot by running the
+   [`certbot-auto` wrapper script](https://certbot.eff.org/docs/install.html#certbot-auto).
+   On the command line of your server, run the following commands:
+
+   ```sh
+   wget https://dl.eff.org/certbot-auto
+   sudo mv certbot-auto /usr/local/bin/certbot-auto
+   sudo chown root /usr/local/bin/certbot-auto
+   chmod 0755 /usr/local/bin/certbot-auto
+   /usr/local/bin/certbot-auto --help
+   ```
+
+   To check the integrity of the `certbot-auto` script, run:
+
+   ```sh
+   wget -N https://dl.eff.org/certbot-auto.asc
+   gpg2 --keyserver ipv4.pool.sks-keyservers.net --recv-key A2CFB51FA275A7286234E7B24D17C995CD9775F2
+   gpg2 --trusted-key 4D17C995CD9775F2 --verify certbot-auto.asc /usr/local/bin/certbot-auto
+   ```
+
+   The output of the last command should look something like:
+
+   ```sh
+   gpg: Signature made Mon 10 Jun 2019 06:24:40 PM EDT
+   gpg:                using RSA key A2CFB51FA275A7286234E7B24D17C995CD9775F2
+   gpg: key 4D17C995CD9775F2 marked as ultimately trusted
+   gpg: checking the trustdb
+   gpg: marginals needed: 3  completes needed: 1  trust model: pgp
+   gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
+   gpg: next trustdb check due at 2027-11-22
+   gpg: Good signature from "Let's Encrypt Client Team <letsencrypt-client@eff.org>" [ultimate]
+   ```
+
+1. Run the following command to use Certbot to request a certificate
+   using DNS challenge during authorization:
+
+   ```sh
+   ./certbot-auto certonly --manual --preferred-challenges dns -d '*.<namespace>.example.com'
+   ```
+
+   Where `<namespace>` is the namespace created by GitLab for your serverless project (composed of `<project_name>-<project_id>-<environment>`) and
+   `example.com` is the domain being used for your project. If you are unsure what the namespace of your project is, navigate
+   to the **Operations > Serverless** page of your project and inspect
+   the endpoint provided for your function/app.
+
+   ![function_endpoint](img/function-endpoint.png)
+
+   In the above image, the namespace for the project is `node-function-11909507` and the domain is `knative.info`, thus
+   certificate request line would look like this:
+
+   ```sh
+   ./certbot-auto certonly --manual --preferred-challenges dns -d '*.node-function-11909507.knative.info'
+   ```
+
+   The Certbot tool walks you through the steps of validating that you own each domain that you specify by creating TXT records in those domains.
+   After this process is complete, the output should look something like this:
+
+   ```sh
+   IMPORTANT NOTES:
+   - Congratulations! Your certificate and chain have been saved at:
+     /etc/letsencrypt/live/namespace.example.com/fullchain.pem
+     Your key file has been saved at:
+     /etc/letsencrypt/live/namespace.example/privkey.pem
+     Your cert will expire on 2019-09-19. To obtain a new or tweaked
+     version of this certificate in the future, simply run certbot-auto
+     again. To non-interactively renew *all* of your certificates, run
+     "certbot-auto renew"
+   -----BEGIN PRIVATE KEY-----
+   - Your account credentials have been saved in your Certbot
+     configuration directory at /etc/letsencrypt. You should make a
+     secure backup of this folder now. This configuration directory will
+     also contain certificates and private keys obtained by Certbot so
+     making regular backups of this folder is ideal.
+   ```
+
+1. Create certificate and private key files. Using the contents of the files
+   returned by Certbot, we'll create two files in order to create the
+   Kubernetes secret:
+
+   Run the following command to see the contents of `fullchain.pem`:
+
+   ```sh
+   sudo cat /etc/letsencrypt/live/node-function-11909507.knative.info/fullchain.pem
+   ```
+
+   Output should look like this:
+
+   ```sh
+   -----BEGIN CERTIFICATE-----
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b4ag==
+   -----END CERTIFICATE-----
+   -----BEGIN CERTIFICATE-----
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   K2fcb195768c39e9a94cec2c2e30Qg==
+   -----END CERTIFICATE-----
+   ```
+
+   Create a file with the name `cert.pem` with the contents of the entire output.
+
+   Once `cert.pem` is created, run the following command to see the contents of `privkey.pem`:
+
+   ```sh
+   sudo cat /etc/letsencrypt/live/namespace.example/privkey.pem
+   ```
+
+   Output should look like this:
+
+   ```sh
+   -----BEGIN PRIVATE KEY-----
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+   -----BEGIN CERTIFICATE-----
+   fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+   4f294d1eaca42b8692017b4262==
+   -----END PRIVATE KEY-----
+   ```
+
+   Create a new file with the name `cert.pk` with the contents of the entire output.
+
+1. Create a Kubernetes secret to hold your TLS certificate, `cert.pem`, and
+   the private key `cert.pk`:
+
+   NOTE: **Note:**
+   Running `kubectl` commands on your cluster requires setting up access to the cluster first.
+   For clusters created on GKE, see
+   [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl).
+   For other platforms, [install `kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
+
+   ```sh
+   kubectl create --namespace istio-system secret tls istio-ingressgateway-certs \
+   --key cert.pk \
+   --cert cert.pem
+   ```
+
+   Where `cert.pem` and `cert.pk` are your certificate and private key files. Note that the `istio-ingressgateway-certs` secret name is required.
+
+1. Configure Knative to use the new secret that you created for HTTPS
+   connections. Run the
+   following command to open the Knative shared `gateway` in edit mode:
+
+   ```sh
+   kubectl edit gateway knative-ingress-gateway --namespace knative-serving
+   ```
+
+   Update the gateway to include the following tls: section and configuration:
+
+   ```sh
+   tls:
+     mode: SIMPLE
+     privateKey: /etc/istio/ingressgateway-certs/tls.key
+     serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
+   ```
+
+   Example:
+
+   ```sh
+   apiVersion: networking.istio.io/v1alpha3
+   kind: Gateway
+   metadata:
+     # ... skipped ...
+   spec:
+     selector:
+       istio: ingressgateway
+     servers:
+       - hosts:
+           - "*"
+         port:
+           name: http
+           number: 80
+           protocol: HTTP
+       - hosts:
+           - "*"
+         port:
+           name: https
+           number: 443
+           protocol: HTTPS
+         tls:
+           mode: SIMPLE
+           privateKey: /etc/istio/ingressgateway-certs/tls.key
+           serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
+   ```
+
+   After your changes are running on your Knative cluster, you can begin using the HTTPS protocol for secure access your deployed Knative services.
+   In the event a mistake is made during this process and you need to update the cert, you will need to edit the gateway `knative-ingress-gateway`
+   to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway will use the new certificates.
diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md
index ae04616943f..96c4f16fe04 100644
--- a/doc/user/project/code_owners.md
+++ b/doc/user/project/code_owners.md
@@ -1,10 +1,12 @@
-# Code Owners **[STARTER]**
+# Code Owners **(STARTER)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6916)
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6916)
 in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.
+> - [Support for group namespaces](https://gitlab.com/gitlab-org/gitlab-ce/issues/53182) added in GitLab Starter 12.1.
 
-You can use a `CODEOWNERS` file to specify users that are responsible
-for certain files in a repository.
+You can use a `CODEOWNERS` file to specify users or
+[shared groups](members/share_project_with_groups.md)
+that are responsible for certain files in a repository.
 
 You can choose and add the `CODEOWNERS` file in three places:
 
@@ -25,7 +27,8 @@ the given file.
 
 Files can be specified using the same kind of patterns you would use
 in the `.gitignore` file followed by the `@username` or email of one
-or more users that should be owners of the file.
+or more users or by the `@name` of one or more groups that should
+be owners of the file.
 
 The order in which the paths are defined is significant: the last
 pattern that matches a given path will be used to find the code
@@ -54,8 +57,8 @@ Example `CODEOWNERS` file:
 # Files with a `#` can still be accesssed by escaping the pound sign
 \#file_with_pound.rb @owner-file-with-pound
 
-# Multiple codeowners can be specified, separated by whitespace
-CODEOWNERS @multiple @owners	@tab-separated
+# Multiple codeowners can be specified, separated by spaces or tabs
+CODEOWNERS @multiple @code @owners 
 
 # Both usernames or email addresses can be used to match
 # users. Everything else will be ignored. For example this will
@@ -63,6 +66,10 @@ CODEOWNERS @multiple @owners	@tab-separated
 # owner for the LICENSE file
 LICENSE @legal this_does_not_match janedoe@gitlab.com
 
+# Group names can be used to match groups and nested groups to specify
+# them as owners for a file
+README @group @group/with-nested/subgroup
+
 # Ending a path in a `/` will specify the code owners for every file
 # nested in that directory, on any level
 /docs/ @all-docs
diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md
index 58b7fe33906..c9eb81b990c 100644
--- a/doc/user/project/container_registry.md
+++ b/doc/user/project/container_registry.md
@@ -1,13 +1,8 @@
 # GitLab Container Registry
 
-> **Notes:**
->
 > - [Introduced][ce-4040] in GitLab 8.8.
 > - Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker
 >   versions earlier than 1.10.
-> - This document is about the user guide. To learn how to enable GitLab Container
->   Registry across your GitLab instance, visit the
->   [administrator documentation](../../administration/container_registry.md).
 > - Starting from GitLab 8.12, if you have 2FA enabled in your account, you need
 >   to pass a [personal access token][pat] instead of your password in order to
 >   login to GitLab's Container Registry.
@@ -16,28 +11,33 @@
 With the Docker Container Registry integrated into GitLab, every project can
 have its own space to store its Docker images.
 
+This document is the user guide. To learn how to enable GitLab Container
+Registry across your GitLab instance, visit the
+[administrator documentation](../../administration/container_registry.md).
+
 You can read more about Docker Registry at <https://docs.docker.com/registry/introduction/>.
 
 ## Enable the Container Registry for your project
 
-NOTE: **Note:**
-If you cannot find the Container Registry entry under your project's settings,
-that means that it is not enabled in your GitLab instance. Ask your administrator
-to enable it.
-
-1. First, ask your system administrator to enable GitLab Container Registry
-   following the [administration documentation](../../administration/container_registry.md).
-   If you are using GitLab.com, this is enabled by default so you can start using
-   the Registry immediately. Currently there is a soft (10GB) size restriction for
-   registry on GitLab.com, as part of the [repository size limit](repository/index.html#repository-size).
-1. Go to your [project's General settings](settings/index.md#sharing-and-permissions)
+If you cannot find the **Packages > Container Registry** entry under your
+project's sidebar, it is not enabled in your GitLab instance. Ask your
+administrator to enable GitLab Container Registry following the
+[administration documentation](../../administration/container_registry.md).
+
+If you are using GitLab.com, this is enabled by default so you can start using
+the Registry immediately. Currently there is a soft (10GB) size restriction for
+registry on GitLab.com, as part of the [repository size limit](repository/index.md).
+
+Once enabled for your GitLab instance, to enable Container Registry for your
+project:
+
+1. Go to your project's **Settings > General** page.
+1. Expand the **Visibility, project features, permissions** section
    and enable the **Container Registry** feature on your project. For new
    projects this might be enabled by default. For existing projects
    (prior GitLab 8.8), you will have to explicitly enable it.
-1. Hit **Save changes** for the changes to take effect. You should now be able
-   to see the **Registry** link in the sidebar.
-
-![Container Registry](img/container_registry.png)
+1. Press **Save changes** for the changes to take effect. You should now be able
+   to see the **Packages > Container Registry**  link in the sidebar.
 
 ## Build and push images
 
@@ -49,14 +49,14 @@ to enable it.
 > - To move or rename a repository with a container registry you will have to
 >   delete all existing images.
 
-If you visit the **Registry** link under your project's menu, you can see the
-explicit instructions to login to the Container Registry using your GitLab
-credentials.
+If you visit the **Packages > Container Registry** link under your project's
+menu, you can see the explicit instructions to login to the Container Registry
+using your GitLab credentials.
 
 For example if the Registry's URL is `registry.example.com`, then you should be
 able to login with:
 
-```
+```sh
 docker login registry.example.com
 ```
 
@@ -64,14 +64,14 @@ Building and publishing images should be a straightforward process. Just make
 sure that you are using the Registry URL with the namespace and project name
 that is hosted on GitLab:
 
-```
+```sh
 docker build -t registry.example.com/group/project/image .
 docker push registry.example.com/group/project/image
 ```
 
 Your image will be named after the following scheme:
 
-```
+```text
 <registry URL>/<namespace>/<project>/<image>
 ```
 
@@ -79,7 +79,7 @@ GitLab supports up to three levels of image repository names.
 
 Following examples of image tags are valid:
 
-```
+```text
 registry.example.com/group/project:some-tag
 registry.example.com/group/project/image:latest
 registry.example.com/group/project/my/image:rc1
@@ -90,7 +90,7 @@ registry.example.com/group/project/my/image:rc1
 To download and run a container from images hosted in GitLab Container Registry,
 use `docker run`:
 
-```
+```sh
 docker run [options] registry.example.com/group/project/image [arguments]
 ```
 
@@ -100,7 +100,7 @@ For more information on running Docker containers, visit the
 ## Control Container Registry from within GitLab
 
 GitLab offers a simple Container Registry management panel. Go to your project
-and click **Registry** in the project menu.
+and click **Packages > Container Registry** in the project menu.
 
 This view will show you all tags in your project and will easily allow you to
 delete them.
@@ -113,6 +113,7 @@ This feature requires GitLab 8.8 and GitLab Runner 1.2.
 Make sure that your GitLab Runner is configured to allow building Docker images by
 following the [Using Docker Build](../../ci/docker/using_docker_build.md)
 and [Using the GitLab Container Registry documentation](../../ci/docker/using_docker_build.md#using-the-gitlab-container-registry).
+Alternatively, you can [build images with Kaniko](../../ci/docker/using_kaniko.md) if the Docker builds are not an option for you.
 
 ## Using with private projects
 
@@ -167,9 +168,23 @@ curl localhost:5001/debug/health
 curl localhost:5001/debug/vars
 ```
 
+#### Docker connection error
+
+A Docker connection error can occur when there are special characters in either the group,
+project or branch name. Special characters can include:
+
+- Leading underscore
+- Trailing hyphen/dash
+- Double hyphen/dash
+
+To get around this, you can [change the group path](../group/index.md#changing-a-groups-path),
+[change the project path](../project/settings/index.md#renaming-a-repository) or chanage the branch
+name.
+
 ### Advanced Troubleshooting
 
->**NOTE:** The following section is only recommended for experts.
+NOTE: **Note:**
+The following section is only recommended for experts.
 
 Sometimes it's not obvious what is wrong, and you may need to dive deeper into
 the communication between the Docker client and the Registry to find out
@@ -181,7 +196,7 @@ diagnose a problem with the S3 setup.
 A user attempted to enable an S3-backed Registry. The `docker login` step went
 fine. However, when pushing an image, the output showed:
 
-```
+```text
 The push refers to a repository [s3-testing.myregistry.com:4567/root/docker-test/docker-image]
 dc5e59c14160: Pushing [==================================================>] 14.85 kB
 03c20c1a019a: Pushing [==================================================>] 2.048 kB
@@ -204,7 +219,7 @@ at the communication between the client and the Registry.
 The REST API between the Docker client and Registry is [described
 here](https://docs.docker.com/registry/spec/api/). Normally, one would just
 use Wireshark or tcpdump to capture the traffic and see where things went
-wrong.  However, since all communications between Docker clients and servers
+wrong. However, since all communications between Docker clients and servers
 are done over HTTPS, it's a bit difficult to decrypt the traffic quickly even
 if you know the private key. What can we do instead?
 
@@ -227,10 +242,10 @@ The following installation instructions assume you are running Ubuntu:
    Enter <kbd>CTRL</kbd>-<kbd>C</kbd> to quit.
 1. Install the certificate from `~/.mitmproxy` to your system:
 
-    ```sh
-    sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt
-    sudo update-ca-certificates
-    ```
+   ```sh
+   sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt
+   sudo update-ca-certificates
+   ```
 
 If successful, the output should indicate that a certificate was added:
 
diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md
index dc97a44fd68..87577c9ec88 100644
--- a/doc/user/project/cycle_analytics.md
+++ b/doc/user/project/cycle_analytics.md
@@ -1,161 +1,5 @@
-# Cycle Analytics
-
-Cycle Analytics measures the time spent to go from an [idea to production] - also known
-as cycle time - for each of your projects. Cycle Analytics displays the median time for an idea to
-reach production, along with the time typically spent in each DevOps stage along the way.
-
-Cycle Analytics is useful in order to quickly determine the velocity of a given
-project. It points to bottlenecks in the development process, enabling management
-to uncover, triage, and root-cause slowdowns in the software development life cycle.
-
-Cycle Analytics is tightly coupled with the [GitLab flow] and
-calculates a separate median for each stage.
-
-## Overview
-
-You can find the Cycle Analytics page under your project's **Project ➔ Cycle
-Analytics** tab.
-
-![Cycle Analytics landing page](img/cycle_analytics_landing_page.png)
-
-There are seven stages that are tracked as part of the Cycle Analytics calculations.
-
-- **Issue** (Tracker)
-    - Time to schedule an issue (by milestone or by adding it to an issue board)
-- **Plan** (Board)
-    - Time to first commit
-- **Code** (IDE)
-    - Time to create a merge request
-- **Test** (CI)
-    - Time it takes GitLab CI/CD to test your code
-- **Review** (Merge Request/MR)
-    - Time spent on code review
-- **Staging** (Continuous Deployment)
-    - Time between merging and deploying to production
-- **Production** (Total)
-    - Total lifecycle time; i.e. the velocity of the project or team
-
-## How the data is measured
-
-Cycle Analytics records cycle time and data based on the project issues with the
-exception of the staging and production stages, where only data deployed to
-production are measured.
-
-Specifically, if your CI is not set up and you have not defined a `production`
-or `production/*` [environment], then you will not have any data for those stages.
-
-Below you can see in more detail what the various stages of Cycle Analytics mean.
-
-| **Stage** | **Description** |
-| --------- | --------------- |
-| Issue     | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label will be tracked only if it already has an [Issue Board list][board] created for it. |
-| Plan      | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (e.g., `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. |
-| Code      | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern] to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the issue closing pattern is not present in the merge request description, the MR is not considered to the measurement time of the stage. |
-| Test      | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. |
-| Review    | Measures the median time taken to review the merge request that has closing issue pattern, between its creation and until it's merged. |
-| Staging   | Measures the median time between merging the merge request with closing issue pattern until the very first deployment to production. It's tracked by the [environment] set to `production` or matching `production/*` (case-sensitive, `Production` won't work) in your GitLab CI configuration. If there isn't a production environment, this is not tracked. |
-| Production| The sum of all time (medians) taken to run the entire process, from issue creation to deploying the code to production. |
-
+---
+redirect_to: '../analytics/cycle_analytics.md'
 ---
 
-Here's a little explanation of how this works behind the scenes:
-
-1. Issues and merge requests are grouped together in pairs, such that for each
-   `<issue, merge request>` pair, the merge request has the [issue closing pattern]
-   for the corresponding issue. All other issues and merge requests are **not**
-   considered.
-1. Then the `<issue, merge request>` pairs are filtered out by last XX days (specified
-   by the UI - default is 90 days). So it prohibits these pairs from being considered.
-1. For the remaining `<issue, merge request>` pairs, we check the information that
-   we need for the stages, like issue creation date, merge request merge time,
-   etc.
-
-To sum up, anything that doesn't follow the [GitLab flow] won't be tracked at all.
-So, the Cycle Analytics dashboard won't present any data:
-
-- For merge requests that do not close an issue.
-- For issues not labeled with a label present in the Issue Board or for issues not assigned a milestone.
-- For staging and production stages, if the project has no `production` or `production/*`
-  environment.
-
-## Example workflow
-
-Below is a simple fictional workflow of a single cycle that happens in a
-single day passing through all seven stages. Note that if a stage does not have
-a start and a stop mark, it is not measured and hence not calculated in the median
-time. It is assumed that milestones are created and CI for testing and setting
-environments is configured.
-
-1. Issue is created at 09:00 (start of **Issue** stage).
-1. Issue is added to a milestone at 11:00 (stop of **Issue** stage / start of
-   **Plan** stage).
-1. Start working on the issue, create a branch locally and make one commit at
-   12:00.
-1. Make a second commit to the branch which mentions the issue number at 12.30
-   (stop of **Plan** stage / start of **Code** stage).
-1. Push branch and create a merge request that contains the [issue closing pattern]
-   in its description at 14:00 (stop of **Code** stage / start of **Test** and
-   **Review** stages).
-1. The CI starts running your scripts defined in [`.gitlab-ci.yml`][yml] and
-   takes 5min (stop of **Test** stage).
-1. Review merge request, ensure that everything is OK and merge the merge
-   request at 19:00. (stop of **Review** stage / start of **Staging** stage).
-1. Now that the merge request is merged, a deployment to the `production`
-   environment starts and finishes at 19:30 (stop of **Staging** stage).
-1. The cycle completes and the sum of the median times of the previous stages
-   is recorded to the **Production** stage. That is the time between creating an
-   issue and deploying its relevant merge request to production.
-
-From the above example you can conclude the time it took each stage to complete
-as long as their total time:
-
-- **Issue**:  2h (11:00 - 09:00)
-- **Plan**:   1h (12:00 - 11:00)
-- **Code**:   2h (14:00 - 12:00)
-- **Test**:   5min
-- **Review**: 5h (19:00 - 14:00)
-- **Staging**:  30min (19:30 - 19:00)
-- **Production**: Since this stage measures the sum of median time off all
-  previous stages, we cannot calculate it if we don't know the status of the
-  stages before. In case this is the very first cycle that is run in the project,
-  then the **Production** time is 10h 30min (19:30 - 09:00)
-
-A few notes:
-
-- In the above example we demonstrated that it doesn't matter if your first
-  commit doesn't mention the issue number, you can do this later in any commit
-  of the branch you are working on.
-- You can see that the **Test** stage is not calculated to the overall time of
-  the cycle since it is included in the **Review** process (every MR should be
-  tested).
-- The example above was just **one cycle** of the seven stages. Add multiple
-  cycles, calculate their median time and the result is what the dashboard of
-  Cycle Analytics is showing.
-
-## Permissions
-
-The current permissions on the Cycle Analytics dashboard are:
-
-- Public projects - anyone can access
-- Internal projects - any authenticated user can access
-- Private projects - any member Guest and above can access
-
-You can [read more about permissions][permissions] in general.
-
-## More resources
-
-Learn more about Cycle Analytics in the following resources:
-
-- [Cycle Analytics feature page](https://about.gitlab.com/features/cycle-analytics/)
-- [Cycle Analytics feature preview](https://about.gitlab.com/2016/09/16/feature-preview-introducing-cycle-analytics/)
-- [Cycle Analytics feature highlight](https://about.gitlab.com/2016/09/21/cycle-analytics-feature-highlight/)
-
-[board]: issue_board.md#creating-a-new-list
-[ce-5986]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5986
-[ce-20975]: https://gitlab.com/gitlab-org/gitlab-ce/issues/20975
-[environment]: ../../ci/yaml/README.md#environment
-[GitLab flow]: ../../workflow/gitlab_flow.md
-[idea to production]: https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab
-[issue closing pattern]: issues/automatic_issue_closing.md
-[permissions]: ../permissions.md
-[yml]: ../../ci/yaml/README.md
+This document was moved to [another location](../analytics/cycle_analytics.md)
diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md
index 2f2a9c5eec3..0a83f2e894a 100644
--- a/doc/user/project/deploy_boards.md
+++ b/doc/user/project/deploy_boards.md
@@ -1,4 +1,4 @@
-# Deploy Boards **[PREMIUM]**
+# Deploy Boards **(PREMIUM)**
 
 > [Introduced][ee-1589] in [GitLab Premium][ee] 9.0.
 
@@ -59,14 +59,16 @@ specific environment, there are lot of uses cases. To name a few:
 
 To display the Deploy Boards for a specific [environment] you should:
 
+1. Have [defined an environment](../../ci/environments.md#defining-environments) with a deploy stage.
+
 1. Have a Kubernetes cluster up and running.
 
-    NOTE: **Running on OpenShift:**
-    If you are using OpenShift, ensure that you're using the `Deployment` resource
-    instead of `DeploymentConfiguration`, otherwise the Deploy Boards won't render
-    correctly. For more information, read the
-    [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations)
-    and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab-ee/issues/4584).
+   NOTE: **Running on OpenShift:**
+   If you are using OpenShift, ensure that you're using the `Deployment` resource
+   instead of `DeploymentConfiguration`, otherwise the Deploy Boards won't render
+   correctly. For more information, read the
+   [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations)
+   and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab-ee/issues/4584).
 
 1. [Configure GitLab Runner][runners] with the [Docker][docker-exec] or
    [Kubernetes][kube-exec] executor.
@@ -86,22 +88,18 @@ To display the Deploy Boards for a specific [environment] you should:
    Kubernetes.
 
    NOTE: **Note:**
-   The Kubernetes label of `app` is deprecated and may be removed in next major
-   release, GitLab 12.0.
+   Matching based on the Kubernetes `app` label was removed in [GitLab
+   12.1](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/14020).
+   To migrate, please apply the required annotations (see above) and
+   re-deploy your application.
 
-    ![Deploy Boards Kubernetes Label](img/deploy_boards_kubernetes_label.png)
+   ![Deploy Boards Kubernetes Label](img/deploy_boards_kubernetes_label.png)
 
 Once all of the above are set up and the pipeline has run at least once,
 navigate to the environments page under **Operations > Environments**.
 
 Deploy Boards are visible by default. You can explicitly click
 the triangle next to their respective environment name in order to hide them.
-GitLab will then query Kubernetes for the state of each pod (e.g., waiting,
-deploying, finished, unknown), and the Deploy Board status will finally appear.
-
-GitLab will only display a Deploy Board for top-level environments. Foldered
-environments like `review/*` (usually used for [Review Apps]) won't have a
-Deploy Board attached to them.
 
 ## Canary Deployments
 
@@ -127,6 +125,6 @@ version of your application.
 [kube-service]: integrations/kubernetes.md "Kubernetes project service"
 [review apps]: ../../ci/review_apps/index.md "Review Apps documentation"
 [variables]: ../../ci/variables/README.md "GitLab CI variables"
-[autodeploy]: ../../ci/autodeploy/index.md "GitLab Autodeploy"
+[autodeploy]: ../../topics/autodevops/index.md#auto-deploy "GitLab Autodeploy"
 [kube-image]: https://gitlab.com/gitlab-examples/kubernetes-deploy/container_registry "Kubernetes deploy Container Registry"
 [runners]: ../../ci/runners/README.md
diff --git a/doc/user/project/deploy_tokens/img/deploy_tokens.png b/doc/user/project/deploy_tokens/img/deploy_tokens.png
index 55c537fd1d3..493de8e0fce 100644
--- a/doc/user/project/deploy_tokens/img/deploy_tokens.png
+++ b/doc/user/project/deploy_tokens/img/deploy_tokens.png
diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md
index 92a29b68a22..164d1dddff0 100644
--- a/doc/user/project/deploy_tokens/index.md
+++ b/doc/user/project/deploy_tokens/index.md
@@ -15,7 +15,7 @@ You can create as many deploy tokens as you like from the settings of your proje
 1. Go to the project you want to create Deploy Tokens for.
 1. Go to **Settings** > **Repository**.
 1. Click on "Expand" on **Deploy Tokens** section.
-1. Choose a name and optionally an expiry date for the token.
+1. Choose a name, expiry date (optional), and username (optional) for the token.
 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token).
 1. Click on **Create deploy token**.
 1. Save the deploy token somewhere safe. Once you leave or refresh
@@ -39,6 +39,13 @@ the following table.
 | `read_repository` | Allows read-access to the repository through `git clone` |
 | `read_registry` | Allows read-access to [container registry] images if a project is private and authorization is required. |
 
+## Deploy token custom username
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29639) in GitLab 12.1.
+
+The default username format is `gitlab+deploy-token-#{n}`. Some tools or platforms may not support this format,
+in such case you can specify custom username to be used when creating the deploy token.
+
 ## Usage
 
 ### Git clone a repository
@@ -49,9 +56,9 @@ To download a repository using a Deploy Token, you just need to:
 1. Take note of your `username` and `token`.
 1. `git clone` the project using the Deploy Token:
 
-    ```sh
-    git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git
-    ```
+   ```sh
+   git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git
+   ```
 
 Replace `<username>` and `<deploy_token>` with the proper values.
 
diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md
index 05ad15476ab..f53dc056010 100644
--- a/doc/user/project/description_templates.md
+++ b/doc/user/project/description_templates.md
@@ -25,14 +25,14 @@ templates of the default branch will be taken into account.
 ## Use-cases
 
 - Add a template to be used in every issue for a specific project,
-giving instructions and guidelines, requiring for information specific to that subject.
-For example, if you have a project for tracking new blog posts, you can require the
-title, outlines, author name, author social media information, etc.
+  giving instructions and guidelines, requiring for information specific to that subject.
+  For example, if you have a project for tracking new blog posts, you can require the
+  title, outlines, author name, author social media information, etc.
 - Following the previous example, you can make a template for every MR submitted
-with a new blog post, requiring information about the post date, frontmatter data,
-images guidelines, link to the related issue, reviewer name, etc.
+  with a new blog post, requiring information about the post date, frontmatter data,
+  images guidelines, link to the related issue, reviewer name, etc.
 - You can also create issues and merge request templates for different
-stages of your workflow, e.g., feature proposal, feature improvement, bug report, etc.
+  stages of your workflow, e.g., feature proposal, feature improvement, bug report, etc.
 
 ## Creating issue templates
 
@@ -55,9 +55,10 @@ changes you made after picking the template and return it to its initial status.
 
 ![Description templates](img/description_templates.png)
 
-## Setting a default template for issues and merge requests  **[STARTER]**
+## Setting a default template for merge requests and issues  **(STARTER)**
 
 > **Notes:**
+>
 > - This feature was introduced before [description templates](#overview) and is
 >   available in [GitLab Starter][products]. It can be enabled
 >   in the project's settings.
@@ -65,20 +66,20 @@ changes you made after picking the template and return it to its initial status.
 > - Templates for merge requests were [introduced][ee-7478ece] in GitLab EE 6.9.
 
 The visibility of issues and/or merge requests should be set to either "Everyone
-with access" or "Only team members" in your project's **Settings** otherwise the
+with access" or "Only Project Members" in your project's **Settings / Visibility, project features, permissions** section, otherwise the
 template text areas won't show. This is the default behavior so in most cases
 you should be fine.
 
-Go to your project's **Settings** and fill in the "Default description template
-for issues" and "Default description template for merge requests" text areas
-for issues and merge requests respectively. Since GitLab issues and merge
-request support [Markdown](../markdown.md), you can use special markup like
+Go to your project's **Settings** and under the **Merge requests** header, click *Expand* and fill in the "Default description template
+for merge requests" text area. Under the **Default issue template**, click *Expand* and fill in "Default description template for issues" text area. Since GitLab merge request and issues
+ support [Markdown](../markdown.md), you can use special markup like
 headings, lists, etc.
 
-![Default description templates](img/description_templates_default_settings.png)
+![Default merge request description templates](img/description_templates_merge_request_settings.png)
+![Default issue description templates](img/description_templates_issue_settings.png)
 
 After you add the description, hit **Save changes** for the settings to take
-effect. Now, every time a new issue or merge request is created, it will be
+effect. Now, every time a new merge request or issue is created, it will be
 pre-filled with the text you entered in the template(s).
 
 ## Description template example
diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md
index 3386eb9d0d4..dce8c3a97bc 100644
--- a/doc/user/project/file_lock.md
+++ b/doc/user/project/file_lock.md
@@ -1,8 +1,6 @@
-# File Locking **[PREMIUM]**
+# File Locking **(PREMIUM)**
 
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/440) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.9.
-> - This feature needs to have a license with the "File Lock" option enabled.
-> - If you are using Premium but you don't see the "Lock" button, ask your GitLab administrator.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/440) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.9.
 
 File Locking helps you avoid merge conflicts and better manage your binary files.
 Lock any file or directory, make your changes, and then unlock it so another
@@ -30,12 +28,51 @@ The file locking feature is useful in situations when:
 Locked directories are locked recursively, which means that everything that
 lies under them is also locked.
 
+## Locking a file or a directory
+
+NOTE: **Note:**
+Locking only works for the default branch you have set in the project's settings
+(usually `master`).
+
+To lock a file:
+
+1. Navigate to your project's **Repository > Files**.
+1. Pick the file you want to lock.
+1. Click the "Lock" button.
+
+   ![Locking file](img/file_lock.png)
+
+To lock an entire directory, look for the "Lock" link next to "History".
+
+After you lock a file or directory, it will appear as locked in the repository
+view.
+
+![Repository view](img/file_lock_repository_view.png)
+
+Once locked, any merge request to the default branch will fail
+to merge until the file becomes unlocked.
+
+## Unlocking a file or a directory
+
+To unlock a file or a directory, follow the same procedure as when you locked
+them. For a detailed view of every existing lock, see the next section on
+"Viewing and managing existing locks".
+
+You can unlock a file that yourself or someone else previously locked as long
+as you have Maintainer or above [permissions](../permissions.md) to the project.
+
+## Viewing and managing existing locks
+
+To view or manage every existing lock, navigate to the
+**Project > Repository > Locked Files** area. There, you can view all existing
+locks and [remove the ones you have permission for](#permissions-on-file-locking).
+
 ## Permissions on file locking
 
 The user that locks a file or directory **is the only one** that can edit and
 push their changes back to the repository where the locked objects are located.
 
-Locks can be created by any person who has [push access](../../user/permissions.md) to the repository; i.e.,
+Locks can be created by any person who has [push access](../permissions.md) to the repository; i.e.,
 Developer and higher level, and can be removed solely by their author and any
 user with Maintainer permissions and above.
 
@@ -61,41 +98,3 @@ accepts a merge request, an error message will appear stating that the file
 is locked.
 
 ![Merge request error message](img/file_lock_merge_request_error_message.png)
-
-## Locking a file or a directory
-
->**Note:**
-Locking only works for the default branch you have set in the project's settings
-(usually `master`).
-
-To lock a file, navigate to the repository tree under the **Repository > Files** tab,
-pick the file you want to lock and hit the "Lock" button.
-
-![Locking file](img/file_lock.png)
-
----
-
-To lock an entire directory, look for the "Lock" link next to "History".
-
-![Locking directory](img/file_lock_folders.png)
-
----
-
-After you lock a file or directory, it will appear as locked in the repository
-view.
-
-![Repository view](img/file_lock_repository_view.png)
-
-## Unlocking a file or a directory
-
-To unlock a file or a directory, follow the same procedure as when you locked
-them. For a detailed view of every existing lock, see the next section on
-"Viewing and managing existing locks".
-
-## Viewing and managing existing locks
-
-To view or manage every existing lock, navigate to the
-**Project > Repository > Locked Files** area. There, you can view all existing
-locks and [remove the ones you have permission for](#permissions-on-file-locking).
-
-![Locked Files](img/file_lock_list.png)
diff --git a/doc/user/project/img/autocomplete_characters_example1_v12_0.png b/doc/user/project/img/autocomplete_characters_example1_v12_0.png
new file mode 100644
index 00000000000..9c6fa923b80
--- /dev/null
+++ b/doc/user/project/img/autocomplete_characters_example1_v12_0.png
diff --git a/doc/user/project/img/autocomplete_characters_example2_v12_0.png b/doc/user/project/img/autocomplete_characters_example2_v12_0.png
new file mode 100644
index 00000000000..b2e8a782a0b
--- /dev/null
+++ b/doc/user/project/img/autocomplete_characters_example2_v12_0.png
diff --git a/doc/user/project/img/container_registry.png b/doc/user/project/img/container_registry.png
deleted file mode 100644
index abbaf838538..00000000000
--- a/doc/user/project/img/container_registry.png
+++ /dev/null
diff --git a/doc/user/project/img/cycle_analytics_landing_page.png b/doc/user/project/img/cycle_analytics_landing_page.png
deleted file mode 100644
index cf46098b9a4..00000000000
--- a/doc/user/project/img/cycle_analytics_landing_page.png
+++ /dev/null
diff --git a/doc/user/project/img/deploy_boards_kubernetes_label.png b/doc/user/project/img/deploy_boards_kubernetes_label.png
index 19785c74d07..130ff2caa8a 100644
--- a/doc/user/project/img/deploy_boards_kubernetes_label.png
+++ b/doc/user/project/img/deploy_boards_kubernetes_label.png
diff --git a/doc/user/project/img/description_templates_default_settings.png b/doc/user/project/img/description_templates_default_settings.png
deleted file mode 100644
index ab314e83d06..00000000000
--- a/doc/user/project/img/description_templates_default_settings.png
+++ /dev/null
diff --git a/doc/user/project/img/description_templates_issue_settings.png b/doc/user/project/img/description_templates_issue_settings.png
new file mode 100644
index 00000000000..53328108835
--- /dev/null
+++ b/doc/user/project/img/description_templates_issue_settings.png
diff --git a/doc/user/project/img/description_templates_merge_request_settings.png b/doc/user/project/img/description_templates_merge_request_settings.png
new file mode 100644
index 00000000000..eda264f7f37
--- /dev/null
+++ b/doc/user/project/img/description_templates_merge_request_settings.png
diff --git a/doc/user/project/img/file_lock.png b/doc/user/project/img/file_lock.png
index 33f96f20e91..e881442630b 100644
--- a/doc/user/project/img/file_lock.png
+++ b/doc/user/project/img/file_lock.png
diff --git a/doc/user/project/img/file_lock_folders.png b/doc/user/project/img/file_lock_folders.png
deleted file mode 100644
index 5ff3d4d9dbd..00000000000
--- a/doc/user/project/img/file_lock_folders.png
+++ /dev/null
diff --git a/doc/user/project/img/file_lock_list.png b/doc/user/project/img/file_lock_list.png
deleted file mode 100644
index 2c276335c83..00000000000
--- a/doc/user/project/img/file_lock_list.png
+++ /dev/null
diff --git a/doc/user/project/img/file_lock_merge_request_error_message.png b/doc/user/project/img/file_lock_merge_request_error_message.png
index 65bc3692da0..64bcc86ac0d 100644
--- a/doc/user/project/img/file_lock_merge_request_error_message.png
+++ b/doc/user/project/img/file_lock_merge_request_error_message.png
diff --git a/doc/user/project/img/file_lock_repository_view.png b/doc/user/project/img/file_lock_repository_view.png
index 8f4ef52aacd..ced14198da9 100644
--- a/doc/user/project/img/file_lock_repository_view.png
+++ b/doc/user/project/img/file_lock_repository_view.png
diff --git a/doc/user/project/img/issue_boards_multiple.png b/doc/user/project/img/issue_boards_multiple.png
index 4b1a8356dc9..e6183360610 100644
--- a/doc/user/project/img/issue_boards_multiple.png
+++ b/doc/user/project/img/issue_boards_multiple.png
diff --git a/doc/user/project/img/key_value_labels.png b/doc/user/project/img/key_value_labels.png
deleted file mode 100644
index bec901f127f..00000000000
--- a/doc/user/project/img/key_value_labels.png
+++ /dev/null
diff --git a/doc/user/project/img/labels_default.png b/doc/user/project/img/labels_default.png
deleted file mode 100644
index 221c5cf55a2..00000000000
--- a/doc/user/project/img/labels_default.png
+++ /dev/null
diff --git a/doc/user/project/img/labels_default_v12_1.png b/doc/user/project/img/labels_default_v12_1.png
new file mode 100644
index 00000000000..b36b5dac80b
--- /dev/null
+++ b/doc/user/project/img/labels_default_v12_1.png
diff --git a/doc/user/project/img/labels_delete_v12_1.png b/doc/user/project/img/labels_delete_v12_1.png
new file mode 100644
index 00000000000..566e0519fbe
--- /dev/null
+++ b/doc/user/project/img/labels_delete_v12_1.png
diff --git a/doc/user/project/img/labels_drag_priority_v12_1.gif b/doc/user/project/img/labels_drag_priority_v12_1.gif
new file mode 100644
index 00000000000..a568490da5f
--- /dev/null
+++ b/doc/user/project/img/labels_drag_priority_v12_1.gif
diff --git a/doc/user/project/img/labels_epic_sidebar.png b/doc/user/project/img/labels_epic_sidebar.png
deleted file mode 100644
index f8162d89e9d..00000000000
--- a/doc/user/project/img/labels_epic_sidebar.png
+++ /dev/null
diff --git a/doc/user/project/img/labels_epic_sidebar_v12_1.png b/doc/user/project/img/labels_epic_sidebar_v12_1.png
new file mode 100644
index 00000000000..13fbab33e26
--- /dev/null
+++ b/doc/user/project/img/labels_epic_sidebar_v12_1.png
diff --git a/doc/user/project/img/labels_generate_default.png b/doc/user/project/img/labels_generate_default.png
deleted file mode 100644
index 982a4df999c..00000000000
--- a/doc/user/project/img/labels_generate_default.png
+++ /dev/null
diff --git a/doc/user/project/img/labels_generate_default_v12_1.png b/doc/user/project/img/labels_generate_default_v12_1.png
new file mode 100644
index 00000000000..cbdda2ab4dd
--- /dev/null
+++ b/doc/user/project/img/labels_generate_default_v12_1.png
diff --git a/doc/user/project/img/labels_group_issues.png b/doc/user/project/img/labels_group_issues.png
deleted file mode 100644
index cea1d304d31..00000000000
--- a/doc/user/project/img/labels_group_issues.png
+++ /dev/null
diff --git a/doc/user/project/img/labels_group_issues_v12_1.png b/doc/user/project/img/labels_group_issues_v12_1.png
new file mode 100644
index 00000000000..3f8f93c1dfd
--- /dev/null
+++ b/doc/user/project/img/labels_group_issues_v12_1.png
diff --git a/doc/user/project/img/labels_key_value_v12_1.png b/doc/user/project/img/labels_key_value_v12_1.png
new file mode 100644
index 00000000000..52906b7b458
--- /dev/null
+++ b/doc/user/project/img/labels_key_value_v12_1.png
diff --git a/doc/user/project/img/labels_list.png b/doc/user/project/img/labels_list.png
deleted file mode 100644
index 6940dde68bf..00000000000
--- a/doc/user/project/img/labels_list.png
+++ /dev/null
diff --git a/doc/user/project/img/labels_list_v12_1.png b/doc/user/project/img/labels_list_v12_1.png
new file mode 100644
index 00000000000..47359d05f7f
--- /dev/null
+++ b/doc/user/project/img/labels_list_v12_1.png
diff --git a/doc/user/project/img/new_label_from_sidebar.gif b/doc/user/project/img/labels_new_label_from_sidebar.gif
index 572b29a86e1..572b29a86e1 100644
--- a/doc/user/project/img/new_label_from_sidebar.gif
+++ b/doc/user/project/img/labels_new_label_from_sidebar.gif
diff --git a/doc/user/project/img/labels_prioritized.png b/doc/user/project/img/labels_prioritized.png
deleted file mode 100644
index 7ce2d08b38c..00000000000
--- a/doc/user/project/img/labels_prioritized.png
+++ /dev/null
diff --git a/doc/user/project/img/labels_prioritized_v12_1.png b/doc/user/project/img/labels_prioritized_v12_1.png
new file mode 100644
index 00000000000..512c5d59a5a
--- /dev/null
+++ b/doc/user/project/img/labels_prioritized_v12_1.png
diff --git a/doc/user/project/img/labels_promotion.png b/doc/user/project/img/labels_promotion.png
deleted file mode 100644
index 762a3773692..00000000000
--- a/doc/user/project/img/labels_promotion.png
+++ /dev/null
diff --git a/doc/user/project/img/labels_promotion_v12_1.png b/doc/user/project/img/labels_promotion_v12_1.png
new file mode 100644
index 00000000000..7cd8ff24e02
--- /dev/null
+++ b/doc/user/project/img/labels_promotion_v12_1.png
diff --git a/doc/user/project/img/labels_subscriptions.png b/doc/user/project/img/labels_subscriptions.png
deleted file mode 100644
index f3c4235d051..00000000000
--- a/doc/user/project/img/labels_subscriptions.png
+++ /dev/null
diff --git a/doc/user/project/img/labels_subscriptions_v12_1.png b/doc/user/project/img/labels_subscriptions_v12_1.png
new file mode 100644
index 00000000000..fa83b7db414
--- /dev/null
+++ b/doc/user/project/img/labels_subscriptions_v12_1.png
diff --git a/doc/user/project/img/service_desk_disabled.png b/doc/user/project/img/service_desk_disabled.png
index 3ae64dcbe96..edae7e76986 100644
--- a/doc/user/project/img/service_desk_disabled.png
+++ b/doc/user/project/img/service_desk_disabled.png
diff --git a/doc/user/project/img/service_desk_enabled.png b/doc/user/project/img/service_desk_enabled.png
index 329348e4b52..9c143ff58cd 100644
--- a/doc/user/project/img/service_desk_enabled.png
+++ b/doc/user/project/img/service_desk_enabled.png
diff --git a/doc/user/project/img/service_desk_issue_tracker.png b/doc/user/project/img/service_desk_issue_tracker.png
index 485751fab0a..02d18c9debb 100644
--- a/doc/user/project/img/service_desk_issue_tracker.png
+++ b/doc/user/project/img/service_desk_issue_tracker.png
diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md
index 1cc3bd3363d..e509e333313 100644
--- a/doc/user/project/import/bitbucket.md
+++ b/doc/user/project/import/bitbucket.md
@@ -31,12 +31,12 @@ to enable this if not already.
 ## How it works
 
 When issues/pull requests are being imported, the Bitbucket importer tries to find
-the Bitbucket author/assignee in GitLab's database using the Bitbucket ID. For this
-to work, the Bitbucket author/assignee should have signed in beforehand in GitLab
-and **associated their Bitbucket account**. If the user is not
-found in GitLab's database, the project creator (most of the times the current
-user that started the import process) is set as the author, but a reference on
-the issue about the original Bitbucket author is kept.
+the Bitbucket author/assignee in GitLab's database using the Bitbucket `nickname`.
+For this to work, the Bitbucket author/assignee should have signed in beforehand in GitLab
+and **associated their Bitbucket account**. Their `nickname` must also match their Bitbucket
+`username.`. If the user is not found in GitLab's database, the project creator
+(most of the times the current user that started the import process) is set as the author,
+but a reference on the issue about the original Bitbucket author is kept.
 
 The importer will create any new namespaces (groups) if they don't exist or in
 the case the namespace is taken, the repository will be imported under the user's
@@ -49,17 +49,17 @@ namespace that started the import process.
 
 1. Click on the "Bitbucket Cloud" button.
 
-    ![Bitbucket](img/import_projects_from_new_project_page.png)
+   ![Bitbucket](img/import_projects_from_new_project_page.png)
 
 1. Grant GitLab access to your Bitbucket account
 
-    ![Grant access](img/bitbucket_import_grant_access.png)
+   ![Grant access](img/bitbucket_import_grant_access.png)
 
 1. Click on the projects that you'd like to import or **Import all projects**.
    You can also select the namespace under which each project will be
    imported.
 
-    ![Import projects](img/bitbucket_import_select_project.png)
+   ![Import projects](img/bitbucket_import_select_project.png)
 
 [bb-import]: ../../../integration/bitbucket.md
 [social sign-in]: ../../profile/account/social_sign_in.md
diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md
index d51a0c0ccca..28e211ee2ba 100644
--- a/doc/user/project/import/bitbucket_server.md
+++ b/doc/user/project/import/bitbucket_server.md
@@ -24,15 +24,16 @@ Import your projects from Bitbucket Server to GitLab with minimal effort.
 1. Currently GitLab doesn't allow comments on arbitrary lines of code, so any
    Bitbucket comments out of bounds will be inserted as comments in the merge
    request.
-1. Bitbucket Server allows multiple levels of threading. GitLab
-   import will collapse this into one discussion and quote part of the original
-   comment.
+1. Bitbucket Server allows multiple levels of threading. GitLab import
+   will collapse this into one thread and quote part of the original comment.
 1. Declined pull requests have unreachable commits, which prevents the GitLab
    importer from generating a proper diff. These pull requests will show up as
    empty changes.
 1. Attachments in Markdown are currently not imported.
 1. Task lists are not imported.
 1. Emoji reactions are not imported
+1. Project filtering does not support fuzzy search (only `starts with` or `full
+   match strings` are currently supported)
 
 ## How it works
 
@@ -60,16 +61,16 @@ namespace that started the import process.
 1. Sign in to GitLab and go to your dashboard.
 1. Click on **New project**.
 1. Click on the "Bitbucket Server" button. If the button is not present, enable the importer in
-    **Admin > Application Settings > Visibility and access controls > Import sources**.
+   **Admin > Application Settings > Visibility and access controls > Import sources**.
 
-    ![Bitbucket](img/import_projects_from_new_project_page.png)
+   ![Bitbucket](img/import_projects_from_new_project_page.png)
 
 1. Enter your Bitbucket Server credentials.
 
-    ![Grant access](img/bitbucket_server_import_credentials.png)
+   ![Grant access](img/bitbucket_server_import_credentials.png)
 
 1. Click on the projects that you'd like to import or **Import all projects**.
-   You can also select the namespace under which each project will be
+   You can also filter projects by name and select the namespace under which each project will be
    imported.
 
-    ![Import projects](img/bitbucket_server_import_select_project.png)
+   ![Import projects](img/bitbucket_server_import_select_project_v12_3.png)
diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md
index 7f79ebf6353..cf48189fa6e 100644
--- a/doc/user/project/import/gemnasium.md
+++ b/doc/user/project/import/gemnasium.md
@@ -1,17 +1,21 @@
-# Gemnasium **[ULTIMATE]**
+# Gemnasium **(ULTIMATE)**
 
 This guide describes how to migrate from Gemnasium.com to your own GitLab
 instance or GitLab.com.
 
 ## Why is Gemnasium.com closed?
 
-Gemnasium has been [acquired by GitLab](https://about.gitlab.com/press/releases/2018-01-30-gemnasium-acquisition.html)
+Gemnasium was [acquired by GitLab](https://about.gitlab.com/press/releases/2018-01-30-gemnasium-acquisition.html)
 in January 2018. Since May 15, 2018, the services provided by Gemnasium are no longer available.
 The team behind Gemnasium has joined GitLab as the new Security Products team
-and is working on a wider range of tools than just Dependency Scanning:
-[SAST](../../application_security/sast/index.md),
-[DAST](../../application_security/dast/index.md),
-[Container Scanning](../../application_security/container_scanning/index.md) and more.
+and is working on a [wide range of tools](../../application_security/index.md),
+including:
+
+- [Dependency Scanning](../../application_security/dependency_scanning/index.md)
+- [SAST](../../application_security/sast/index.md)
+- [DAST](../../application_security/dast/index.md)
+- [Container Scanning](../../application_security/container_scanning/index.md)
+
 If you want to continue monitoring your dependencies, see the
 [Migrating to GitLab](#migrating-to-gitlab) section below.
 
@@ -40,14 +44,14 @@ some steps to migrate your projects. There is no automatic import since GitLab
 doesn't know anything about any projects which existed on Gemnasium.com.
 Security features are free for public (open-source) projects hosted on GitLab.com.
 
-### If your project is hosted on GitLab (https://gitlab.com / self-hosted)
+### If your project is hosted on GitLab (`https://gitlab.com` / self-hosted)
 
 You're almost set! If you're already using
 [Auto DevOps](../../../topics/autodevops/), you are already covered.
 Otherwise, you must configure your `.gitlab-ci.yml` according to the
 [dependency scanning page](../../application_security/dependency_scanning/index.md).
 
-### If your project is hosted on GitHub (https://github.com / GitHub Enterprise)
+### If your project is hosted on GitHub (`https://github.com` / GitHub Enterprise)
 
 Since [GitLab 10.6 comes with GitHub integration](https://about.gitlab.com/features/github/),
 GitLab users can now create a CI/CD project in GitLab connected to an external
@@ -57,27 +61,27 @@ back to both GitLab and GitHub when completed.
 
 1. Create a new project, and select the "CI/CD for external repo" tab:
 
-    ![Create new Project](img/gemnasium/create_project.png)
+   ![Create new Project](img/gemnasium/create_project.png)
 
 1. Use the "GitHub" button to connect your repositories.
 
-    ![Connect from GitHub](img/gemnasium/connect_github.png)
+   ![Connect from GitHub](img/gemnasium/connect_github.png)
 
 1. Select the project(s) to be set up with GitLab CI/CD and chose "Connect".
 
-    ![Select projects](img/gemnasium/select_project.png)
+   ![Select projects](img/gemnasium/select_project.png)
 
-    Once the configuration is done, you may click on your new
-    project on GitLab.
+   Once the configuration is done, you may click on your new
+   project on GitLab.
 
-    ![click on connected project](img/gemnasium/project_connected.png)
+   ![click on connected project](img/gemnasium/project_connected.png)
 
-    Your project is now mirrored on GitLab, where the Runners will be able to access
-    your source code and run your tests.
+   Your project is now mirrored on GitLab, where the Runners will be able to access
+   your source code and run your tests.
 
-    Optional step: If you set this up on GitLab.com, make sure the project is
-    public (in the project settings) if your GitHub project is public, since
-    the security feature is available only for [GitLab Ultimate](https://about.gitlab.com/pricing).
+   Optional step: If you set this up on GitLab.com, make sure the project is
+   public (in the project settings) if your GitHub project is public, since
+   the security feature is available only for [GitLab Ultimate](https://about.gitlab.com/pricing).
 
 1. To set up the dependency scanning job, corresponding to what Gemnasium was
    doing, you must create a `.gitlab-ci.yml` file, or update it according to
@@ -85,16 +89,16 @@ back to both GitLab and GitHub when completed.
    The mirroring is pull-only by default, so you may create or update the file on
    GitHub:
 
-    ![Edit gitlab-ci.yml file](img/gemnasium/edit_gitlab-ci.png)
+   ![Edit gitlab-ci.yml file](img/gemnasium/edit_gitlab-ci.png)
 
 1. Once your file has been committed, a new pipeline will be automatically
    triggered if your file is valid:
 
-    ![pipeline](img/gemnasium/pipeline.png)
+   ![pipeline](img/gemnasium/pipeline.png)
 
 1. The result of the job will be visible directly from the pipeline view:
 
-    ![security report](img/gemnasium/report.png)
+   ![security report](img/gemnasium/report.png)
 
 NOTE: **Note:**
 If you don't commit very often to your project, you may want to use
diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md
index e194d57e2e0..cdb7f837158 100644
--- a/doc/user/project/import/github.md
+++ b/doc/user/project/import/github.md
@@ -121,10 +121,10 @@ Depending your GitLab tier, [project mirroring](../../../workflow/repository_mir
 your imported project in sync with its GitHub copy.
 
 Additionally, you can configure GitLab to send pipeline status updates back GitHub with the
-[GitHub Project Integration](../integrations/github.md). **[PREMIUM]**
+[GitHub Project Integration](../integrations/github.md). **(PREMIUM)**
 
 If you import your project using [CI/CD for external repo](../../../ci/ci_cd_for_external_repos/index.md), then both
-of the above are automatically configured. **[PREMIUM]**
+of the above are automatically configured. **(PREMIUM)**
 
 ## Improving the speed of imports on self-hosted instances
 
diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md
index f48a158e2d3..2f87f257754 100644
--- a/doc/user/project/import/gitlab_com.md
+++ b/doc/user/project/import/gitlab_com.md
@@ -1,21 +1,21 @@
 # Project importing from GitLab.com to your private GitLab instance
 
-You can import your existing GitLab.com projects to your GitLab instance. But keep in mind that it is possible only if
-GitLab.com integration is enabled on your GitLab instance.
+You can import your existing GitLab.com projects to your GitLab instance, but keep in
+mind that it is possible only if GitLab.com integration is enabled on your GitLab instance.
 [Read more about GitLab.com integration for self-managed GitLab instances](../../../integration/gitlab.md).
 
 To get to the importer page you need to go to "New project" page.
 
 >**Note:**
-If you are interested in importing Wiki and Merge Request data to your new
-instance, you'll need to follow the instructions for [project export](../settings/import_export.md)
+If you are interested in importing Wiki and Merge Request data to your new instance,
+you'll need to follow the instructions for [exporting a project](../settings/import_export.md#exporting-a-project-and-its-data)
 
-![New project page](img/gitlab_new_project_page.png)
+![New project page](img/gitlab_new_project_page_v12_2.png)
 
-Click on the "Import projects from GitLab.com" link and you will be redirected to GitLab.com
+Go to the **Import Projects** tab, then click on **GitLab.com**, and you will be redirected to GitLab.com
 for permission to access your projects. After accepting, you'll be automatically redirected to the importer.
 
 ![Importer page](img/gitlab_importer.png)
 
-To import a project, you can simple click "Import". The importer will import your repository and issues.
+To import a project, click "Import". The importer will import your repository and issues.
 Once the importer is done, a new GitLab project will be created with your imported data.
diff --git a/doc/user/project/import/img/bitbucket_server_import_select_project.png b/doc/user/project/import/img/bitbucket_server_import_select_project.png
deleted file mode 100644
index e7fddef9955..00000000000
--- a/doc/user/project/import/img/bitbucket_server_import_select_project.png
+++ /dev/null
diff --git a/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png b/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png
new file mode 100644
index 00000000000..1c344853cc8
--- /dev/null
+++ b/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png
diff --git a/doc/user/project/import/img/gitlab_new_project_page.png b/doc/user/project/import/img/gitlab_new_project_page.png
deleted file mode 100644
index c673724f436..00000000000
--- a/doc/user/project/import/img/gitlab_new_project_page.png
+++ /dev/null
diff --git a/doc/user/project/import/img/gitlab_new_project_page_v12_2.png b/doc/user/project/import/img/gitlab_new_project_page_v12_2.png
new file mode 100644
index 00000000000..e79c27f32c0
--- /dev/null
+++ b/doc/user/project/import/img/gitlab_new_project_page_v12_2.png
diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md
index 2b6927bd780..ecd491d8e5b 100644
--- a/doc/user/project/import/index.md
+++ b/doc/user/project/import/index.md
@@ -10,7 +10,7 @@
 1. [From Gitea](gitea.md)
 1. [From Perforce](perforce.md)
 1. [From SVN](svn.md)
-1. [From TFS](tfs.md)
+1. [From TFVC](tfvc.md)
 1. [From repo by URL](repo_by_url.md)
 1. [By uploading a manifest file (AOSP)](manifest.md)
 1. [From Gemnasium](gemnasium.md)
@@ -20,7 +20,7 @@ In addition to the specific migration documentation above, you can import any
 Git repository via HTTP from the New Project page. Be aware that if the
 repository is too large the import can timeout.
 
-There is also the option of [connecting your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **[PREMIUM]**
+There is also the option of [connecting your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)**
 
 ## Migrating from self-hosted GitLab to GitLab.com
 
@@ -34,7 +34,7 @@ This approach assumes all users from the self-hosted instance have already been
 If the users haven't been migrated yet, the user conducting the import
 will take the place of all references to the missing user(s).
 
-If you need to migrate all data over, you can leverage our [api](../../../api/README.md) to migrate from self-hosted to GitLab.com. 
+If you need to migrate all data over, you can leverage our [api](../../../api/README.md) to migrate from self-hosted to GitLab.com.
 The order of assets to migrate from a self-hosted instance to GitLab is the following:
 
 1. [Users](../../../api/users.md)
@@ -54,5 +54,5 @@ perhaps from an old server to a new server for example, is to
 [back up the project](../../../raketasks/backup_restore.md),
 then restore it on the new server.
 
-In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped), 
+In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped),
 refer to the instructions in [Migrating from self-hosted GitLab to GitLab.com](#migrating-from-self-hosted-gitlab-to-gitlabcom).
diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md
index baf410d9c9e..161a4163e42 100644
--- a/doc/user/project/import/manifest.md
+++ b/doc/user/project/import/manifest.md
@@ -1,7 +1,6 @@
 # Import multiple repositories by uploading a manifest file
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28811) in
-GitLab 11.2.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28811) in GitLab 11.2.
 
 GitLab allows you to import all the required Git repositories
 based on a manifest file like the one used by the
@@ -56,4 +55,4 @@ You can start the import with:
    to the import status page with projects list based on the manifest file.
 1. Check the list and click **Import all repositories** to start the import.
 
-    ![Manifest status](img/manifest_status.png)
+   ![Manifest status](img/manifest_status.png)
diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md
index 5c624e3aff6..b8f89caba24 100644
--- a/doc/user/project/import/phabricator.md
+++ b/doc/user/project/import/phabricator.md
@@ -15,6 +15,12 @@ Currently, only the following basic fields are imported:
 - Created at
 - Closed at
 
+## Users
+
+The assignee and author of a user are deducted from a Task's owner and
+author: If a user with the same username has access to the namespace
+of the project being imported into, then the user will be linked.
+
 ## Enabling this feature
 
 While this feature is incomplete, a feature flag is required to enable it so that
diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md
index 4825b005a85..d175ee87f26 100644
--- a/doc/user/project/import/svn.md
+++ b/doc/user/project/import/svn.md
@@ -9,13 +9,13 @@ between the two, for more information consult your favorite search engine.
 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.
+   - 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.
+   - 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
 
@@ -29,7 +29,7 @@ directly in a filesystem level.
 
 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. 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`.
 
diff --git a/doc/user/project/import/tfs.md b/doc/user/project/import/tfs.md
index 8727c2ff6c3..7b3b11b9519 100644
--- a/doc/user/project/import/tfs.md
+++ b/doc/user/project/import/tfs.md
@@ -1,42 +1,5 @@
-# Migrating from TFS
+---
+redirect_to: 'tfvc.md'
+---
 
-[TFS](https://www.visualstudio.com/tfs/) is a set of tools developed by Microsoft
-which also includes a centralized version control system (TFVC) similar to Git.
-
-In this document, we emphasize on the TFVC to Git migration.
-
-## TFVC vs Git
-
-The following list illustrates the main differences between TFVC and Git:
-
-- **Git is distributed** whereas TFVC is centralized using a client-server
-  architecture. This translates to Git having a more flexible workflow since
-  your working area is a copy of the entire repository. This decreases the
-  overhead when switching branches or merging for example, since you don't have
-  to communicate with a remote server.
-- **Storage method.** Changes in CVS are per file (changeset), while in Git
-  a committed file(s) is stored in its entirety (snapshot). That means that's
-  very easy in Git to revert or undo a whole change.
-
-_Check also Microsoft's documentation on the
-[comparison of Git and TFVC](https://www.visualstudio.com/en-us/docs/tfvc/comparison-git-tfvc)
-and the Wikipedia article on
-[comparing the different version control software](https://en.wikipedia.org/wiki/Comparison_of_version_control_software)._
-
-## Why migrate
-
-Migrating to Git/GitLab there is:
-
-- **No licensing costs**, Git is GPL while TFVC is proprietary.
-- **Shorter learning curve**, Git has a big community and a vast number of
-  tutorials to get you started (see our [Git topic](../../../topics/git/index.md)).
-- **Integration with modern tools**, migrating to Git and GitLab you can have
-  an open source end-to-end software development platform with built-in version
-  control, issue tracking, code review, CI/CD, and more.
-
-## How to migrate
-
-The best option to migrate from TFVC to Git is to use the
-[`git-tfs`](https://github.com/git-tfs/git-tfs) tool. A specific guide for the
-migration exists:
-[Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md).
+This document was moved to [another location](tfvc.md).
diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md
new file mode 100644
index 00000000000..375522b77d0
--- /dev/null
+++ b/doc/user/project/import/tfvc.md
@@ -0,0 +1,46 @@
+---
+type: concepts
+---
+
+# Migrating from TFVC to Git
+
+Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/services/devops/server/)
+in 2019, is a set of tools developed by Microsoft which also includes
+[Team Foundation Version Control](https://docs.microsoft.com/en-us/azure/devops/repos/tfvc/overview)
+(TFVC), a centralized version control system similar to Git.
+
+In this document, we focus on the TFVC to Git migration.
+
+## TFVC vs Git
+
+The main differences between TFVC and Git are:
+
+- **Git is distributed:** While TFVC is centralized using a client-server architecture,
+  Git is distributed. This translates to Git having a more flexible workflow since
+  you work with a copy of the entire repository. This allows you to quickly
+  switch branches or merge, for example, without needing to communicate with a remote server.
+- **Storage:** Changes in a centralized version control system are per file (changeset),
+  while in Git a committed file is stored in its entirety (snapshot). That means that it is
+  very easy to revert or undo a whole change in Git.
+
+For more information, see:
+
+- Microsoft's [comparison of Git and TFVC](https://docs.microsoft.com/en-us/azure/devops/repos/tfvc/comparison-git-tfvc?view=azure-devops).
+- The Wikipedia [comparison of version control software](https://en.wikipedia.org/wiki/Comparison_of_version_control_software).
+
+## Why migrate
+
+Advantages of migrating to Git/GitLab:
+
+- **No licensing costs:** Git is open source, while TFVC is proprietary.
+- **Shorter learning curve:** Git has a big community and a vast number of
+  tutorials to get you started (see our [Git topic](../../../topics/git/index.md)).
+- **Integration with modern tools:** After migrating to Git and GitLab, you will have
+  an open source, end-to-end software development platform with built-in version
+  control, issue tracking, code review, CI/CD, and more.
+
+## How to migrate
+
+The best option to migrate from TFVC to Git is to use the [`git-tfs`](https://github.com/git-tfs/git-tfs)
+tool. Read the [Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md)
+guide for more details.
diff --git a/doc/user/project/index.md b/doc/user/project/index.md
index 587b4121e4e..30ff0e9ff07 100644
--- a/doc/user/project/index.md
+++ b/doc/user/project/index.md
@@ -17,7 +17,7 @@ When you create a project in GitLab, you'll have access to a large number of
 
 - [Issue tracker](issues/index.md): Discuss implementations with your team within issues
   - [Issue Boards](issue_board.md): Organize and prioritize your workflow
-  - [Multiple Issue Boards](issue_board.md#multiple-issue-boards-starter): Allow your teams to create their own workflows (Issue Boards) for the same project **[STARTER]**
+  - [Multiple Issue Boards](issue_board.md#multiple-issue-boards-starter): Allow your teams to create their own workflows (Issue Boards) for the same project **(STARTER)**
 - [Repositories](repository/index.md): Host your code in a fully
   integrated platform
   - [Branches](repository/branches/index.md): use Git branching strategies to
@@ -34,11 +34,11 @@ When you create a project in GitLab, you'll have access to a large number of
 
 - [Issue tracker](issues/index.md): Discuss implementations with your team within issues
   - [Issue Boards](issue_board.md): Organize and prioritize your workflow
-  - [Multiple Issue Boards](issue_board.md#multiple-issue-boards-starter): Allow your teams to create their own workflows (Issue Boards) for the same project **[STARTER]**
+  - [Multiple Issue Boards](issue_board.md#multiple-issue-boards-starter): Allow your teams to create their own workflows (Issue Boards) for the same project **(STARTER)**
 - [Merge Requests](merge_requests/index.md): Apply your branching
   strategy and get reviewed by your team
   - [Merge Request Approvals](merge_requests/merge_request_approvals.md): Ask for approval before
-  implementing a change **[STARTER]**
+  implementing a change **(STARTER)**
   - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md):
   Your Git diff tool right from GitLab's UI
   - [Review Apps](../../ci/review_apps/index.md): Live preview the results
@@ -52,6 +52,9 @@ When you create a project in GitLab, you'll have access to a large number of
   templates for issue and merge request description fields for your project
 - [Slash commands (quick actions)](quick_actions.md): Textual shortcuts for
   common actions on issues or merge requests
+- [Autocomplete characters](autocomplete_characters.md): Autocomplete
+  references to users, groups, issues, merge requests, and other GitLab
+  elements.
 - [Web IDE](web_ide/index.md)
 
 **GitLab CI/CD:**
@@ -63,19 +66,19 @@ When you create a project in GitLab, you'll have access to a large number of
   to automatically set up your app's deployment
   - [Enable and disable GitLab CI](../../ci/enable_or_disable_ci.md)
   - [Pipelines](../../ci/pipelines.md): Configure and visualize
-  your GitLab CI/CD pipelines from the UI
-     - [Scheduled Pipelines](pipelines/schedules.md): Schedule a pipeline
-     to start at a chosen time
-     - [Pipeline Graphs](../../ci/pipelines.md#visualizing-pipelines): View your
-     entire pipeline from the UI
-     - [Job artifacts](pipelines/job_artifacts.md): Define,
-     browse, and download job artifacts
-     - [Pipeline settings](pipelines/settings.md): Set up Git strategy (choose the default way your repository is fetched from GitLab in a job),
-     timeout (defines the maximum amount of time in minutes that a job is able run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline's visibility, and much more
+    your GitLab CI/CD pipelines from the UI
+    - [Scheduled Pipelines](pipelines/schedules.md): Schedule a pipeline
+      to start at a chosen time
+    - [Pipeline Graphs](../../ci/pipelines.md#visualizing-pipelines): View your
+      entire pipeline from the UI
+    - [Job artifacts](pipelines/job_artifacts.md): Define,
+      browse, and download job artifacts
+    - [Pipeline settings](pipelines/settings.md): Set up Git strategy (choose the default way your repository is fetched from GitLab in a job),
+      timeout (defines the maximum amount of time in minutes that a job is able run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline's visibility, and much more
   - [Kubernetes cluster integration](clusters/index.md): Connecting your GitLab project
     with a Kubernetes cluster
   - [Feature Flags](operations/feature_flags.md): Feature flags allow you to ship a project in
-    different flavors by dynamically toggling certain functionality **[PREMIUM]**
+    different flavors by dynamically toggling certain functionality **(PREMIUM)**
 - [GitLab Pages](pages/index.md): Build, test, and deploy your static
   website with GitLab Pages
 
@@ -84,18 +87,19 @@ When you create a project in GitLab, you'll have access to a large number of
 - [Wiki](wiki/index.md): document your GitLab project in an integrated Wiki.
 - [Snippets](../snippets.md): store, share and collaborate on code snippets.
 - [Cycle Analytics](cycle_analytics.md): review your development lifecycle.
-- [Insights](insights/index.md): configure the Insights that matter for your projects. **[ULTIMATE]**
-- [Security Dashboard](security_dashboard.md): Security Dashboard. **[ULTIMATE]**
+- [Insights](insights/index.md): configure the Insights that matter for your projects. **(ULTIMATE)**
+- [Security Dashboard](security_dashboard.md): Security Dashboard. **(ULTIMATE)**
 - [Syntax highlighting](highlighting.md): an alternative to customize
   your code blocks, overriding GitLab's default choice of language.
 - [Badges](badges.md): badges for the project overview.
 - [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of
   the source, build output, and other metadata or artifacts
   associated with a released version of your code.
-- [Maven packages](packages/maven_repository.md): your private Maven repository in GitLab. **[PREMIUM]**
-- [NPM packages](packages/npm_registry.md): your private NPM package registry in GitLab. **[PREMIUM]**
-- [Code owners](code_owners.md): specify code owners for certain files **[STARTER]**
-- [License Management](../application_security/license_management/index.md): approve and blacklist licenses for projects. **[ULTIMATE]**
+- [Maven packages](packages/maven_repository.md): your private Maven repository in GitLab. **(PREMIUM)**
+- [NPM packages](packages/npm_registry.md): your private NPM package registry in GitLab. **(PREMIUM)**
+- [Code owners](code_owners.md): specify code owners for certain files **(STARTER)**
+- [License Management](../application_security/license_management/index.md): approve and blacklist licenses for projects. **(ULTIMATE)**
+- [Dependency List](../application_security/dependency_list/index.md): view project dependencies. **(ULTIMATE)**
 
 ### Project integrations
 
@@ -131,7 +135,7 @@ Read through the documentation on [project settings](settings/index.md).
 - [Export a project from GitLab](settings/import_export.md#exporting-a-project-and-its-data)
 - [Importing and exporting projects between GitLab instances](settings/import_export.md)
 
-## CI/CD for external repositories **[PREMIUM]**
+## CI/CD for external repositories **(PREMIUM)**
 
 Instead of importing a repository directly to GitLab, you can connect your repository
 as a CI/CD project.
@@ -193,13 +197,35 @@ password <personal_access_token>
 To quickly access a project from the GitLab UI using the project ID,
 visit the `/projects/:id` URL in your browser or other tool accessing the project.
 
+## Project aliases **(PREMIUM ONLY)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1.
+
+When migrating repositories to GitLab and they are being accessed by other systems,
+it's very useful to be able to access them using the same name especially when
+they are a lot. It reduces the risk of changing significant number of Git URLs in
+a large number of systems.
+
+GitLab provides a functionality to help with this. In GitLab, repositories are
+usually accessed with a namespace and project name. It is also possible to access
+them via a project alias. This feature is only available on Git over SSH.
+
+A project alias can be only created via API and only by GitLab administrators.
+Follow the [Project Aliases API documentation](../../api/project_aliases.md) for
+more details.
+
+Once an alias has been created for a project (e.g., an alias `gitlab-ce` for the
+project `https://gitlab.com/gitlab-org/gitlab-ce`), the repository can be cloned
+using the alias (e.g `git clone git@gitlab.com:gitlab-ce.git` instead of
+`git clone git@gitlab.com:gitlab-org/gitlab-ce.git`).
+
 ## Project APIs
 
 There are numerous [APIs](../../api/README.md) to use with your projects:
 
 - [Badges](../../api/project_badges.md)
 - [Clusters](../../api/project_clusters.md)
-- [Discussions](../../api/discussions.md)
+- [Threads](../../api/discussions.md)
 - [General](../../api/projects.md)
 - [Import/export](../../api/project_import_export.md)
 - [Issue Board](../../api/boards.md)
@@ -212,3 +238,4 @@ There are numerous [APIs](../../api/README.md) to use with your projects:
 - [Templates](../../api/project_templates.md)
 - [Traffic](../../api/project_statistics.md)
 - [Variables](../../api/project_level_variables.md)
+- [Aliases](../../api/project_aliases.md)
diff --git a/doc/user/project/insights/img/insights_example_bar_chart.png b/doc/user/project/insights/img/insights_example_bar_chart.png
index eb96eb4a90f..5fd24265b32 100644
--- a/doc/user/project/insights/img/insights_example_bar_chart.png
+++ b/doc/user/project/insights/img/insights_example_bar_chart.png
diff --git a/doc/user/project/insights/img/insights_example_bar_time_series_chart.png b/doc/user/project/insights/img/insights_example_bar_time_series_chart.png
index 28aa81939d8..2e32df3e2b1 100644
--- a/doc/user/project/insights/img/insights_example_bar_time_series_chart.png
+++ b/doc/user/project/insights/img/insights_example_bar_time_series_chart.png
diff --git a/doc/user/project/insights/img/insights_example_line_chart.png b/doc/user/project/insights/img/insights_example_line_chart.png
index 131dbedd35e..9460b104339 100644
--- a/doc/user/project/insights/img/insights_example_line_chart.png
+++ b/doc/user/project/insights/img/insights_example_line_chart.png
diff --git a/doc/user/project/insights/img/insights_example_pie_chart.png b/doc/user/project/insights/img/insights_example_pie_chart.png
index 518ed7338f9..3480bce6738 100644
--- a/doc/user/project/insights/img/insights_example_pie_chart.png
+++ b/doc/user/project/insights/img/insights_example_pie_chart.png
diff --git a/doc/user/project/insights/img/insights_example_stacked_bar_chart.png b/doc/user/project/insights/img/insights_example_stacked_bar_chart.png
index aafec4b394e..a3fb50488f5 100644
--- a/doc/user/project/insights/img/insights_example_stacked_bar_chart.png
+++ b/doc/user/project/insights/img/insights_example_stacked_bar_chart.png
diff --git a/doc/user/project/insights/img/insights_sidebar_link.png b/doc/user/project/insights/img/insights_sidebar_link.png
index aadb5745992..9fc449baf68 100644
--- a/doc/user/project/insights/img/insights_sidebar_link.png
+++ b/doc/user/project/insights/img/insights_sidebar_link.png
diff --git a/doc/user/project/insights/img/project_insights.png b/doc/user/project/insights/img/project_insights.png
index 2d0292dda54..83674c94110 100644
--- a/doc/user/project/insights/img/project_insights.png
+++ b/doc/user/project/insights/img/project_insights.png
diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md
index 2e2a27f112e..76a6a96eec5 100644
--- a/doc/user/project/insights/index.md
+++ b/doc/user/project/insights/index.md
@@ -1,7 +1,6 @@
-# Insights **[ULTIMATE]**
+# Insights **(ULTIMATE)**
 
-> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9 behind the `insights` feature flag.
-> **Generally Available** (GA) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0.
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0.
 
 Configure the Insights that matter for your projects to explore data such as
 triage hygiene, issues created/closed per a given period, average time for merge
diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md
index 23f1ce7a15a..7c7263704f9 100644
--- a/doc/user/project/integrations/custom_issue_tracker.md
+++ b/doc/user/project/integrations/custom_issue_tracker.md
@@ -17,6 +17,6 @@ Once you have configured and enabled Custom Issue Tracker Service you'll see a l
 
 ## Referencing issues
 
-- Issues are referenced with `ANYTHING-<ID>`, where `ANYTHING` can be any string and `<ID>` is a number used in the target project of the custom integration (example `PROJECT-143`). 
+- Issues are referenced with `ANYTHING-<ID>`, where `ANYTHING` can be any string and `<ID>` is a number used in the target project of the custom integration (example `PROJECT-143`).
 - `ANYTHING` is a placeholder to differentiate against GitLab issues, which are referenced with `#<ID>`. You can use a project name or project key to replace it for example.
-- So with the example above, `PROJECT-143` would refer to `https://customissuetracker.com/project-name/143`.
\ No newline at end of file
+- So with the example above, `PROJECT-143` would refer to `https://customissuetracker.com/project-name/143`.
diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md
index cdb0e34fdf6..d0399f9193b 100644
--- a/doc/user/project/integrations/github.md
+++ b/doc/user/project/integrations/github.md
@@ -1,4 +1,4 @@
-# GitHub project integration **[PREMIUM]**
+# GitHub project integration **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3836) in GitLab Premium 10.6.
 
@@ -14,10 +14,10 @@ and is automatically configured on [GitHub import](../../../integration/github.m
 
 ### Complete these steps on GitHub
 
-This integration requires a [GitHub API token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
+This integration requires a [GitHub API token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line)
 with `repo:status` access granted:
 
-1. Go to your "Personal access tokens" page at https://github.com/settings/tokens
+1. Go to your "Personal access tokens" page at <https://github.com/settings/tokens>
 1. Click "Generate New Token"
 1. Ensure that `repo:status` is checked and click "Generate token"
 1. Copy the generated token to use on GitLab
diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md
index 8e062ca627b..91de64be1fa 100644
--- a/doc/user/project/integrations/gitlab_slack_application.md
+++ b/doc/user/project/integrations/gitlab_slack_application.md
@@ -1,4 +1,4 @@
-# GitLab Slack application **[FREE ONLY]**
+# GitLab Slack application **(FREE ONLY)**
 
 NOTE: **Note:**
 The GitLab Slack application is only configurable for GitLab.com. It will **not**
diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md
index 0fd847d415f..7a0540aa9e3 100644
--- a/doc/user/project/integrations/hipchat.md
+++ b/doc/user/project/integrations/hipchat.md
@@ -23,7 +23,7 @@ allow GitLab to send messages only to *one* room.
 1. Find "Build Your Own!" and click "Create".
 1. Select the desired room, name the integration "GitLab", and click "Create".
 1. In the "Send messages to this room by posting this URL" column, you should
-see a URL in the format:
+   see a URL in the format:
 
 ```
 https://api.hipchat.com/v2/room/<room>/notification?auth_token=<token>
diff --git a/doc/user/project/integrations/img/embed_metrics.png b/doc/user/project/integrations/img/embed_metrics.png
new file mode 100644
index 00000000000..6f9660c9aec
--- /dev/null
+++ b/doc/user/project/integrations/img/embed_metrics.png
diff --git a/doc/user/project/integrations/img/github_configuration.png b/doc/user/project/integrations/img/github_configuration.png
index 9f2d47921c7..5798b826681 100644
--- a/doc/user/project/integrations/img/github_configuration.png
+++ b/doc/user/project/integrations/img/github_configuration.png
diff --git a/doc/user/project/integrations/img/jira_add_user_to_group.png b/doc/user/project/integrations/img/jira_add_user_to_group.png
index d8cf541a81e..b63a851a987 100644
--- a/doc/user/project/integrations/img/jira_add_user_to_group.png
+++ b/doc/user/project/integrations/img/jira_add_user_to_group.png
diff --git a/doc/user/project/integrations/img/jira_added_user_to_group.png b/doc/user/project/integrations/img/jira_added_user_to_group.png
index b3e29a65d6e..f5120a8d42e 100644
--- a/doc/user/project/integrations/img/jira_added_user_to_group.png
+++ b/doc/user/project/integrations/img/jira_added_user_to_group.png
diff --git a/doc/user/project/integrations/img/jira_api_token.png b/doc/user/project/integrations/img/jira_api_token.png
index 4fa7a46854e..d9d37713a4d 100644
--- a/doc/user/project/integrations/img/jira_api_token.png
+++ b/doc/user/project/integrations/img/jira_api_token.png
diff --git a/doc/user/project/integrations/img/jira_api_token_menu.png b/doc/user/project/integrations/img/jira_api_token_menu.png
index 14037bd0b47..a10a59a243d 100644
--- a/doc/user/project/integrations/img/jira_api_token_menu.png
+++ b/doc/user/project/integrations/img/jira_api_token_menu.png
diff --git a/doc/user/project/integrations/img/jira_create_new_group.png b/doc/user/project/integrations/img/jira_create_new_group.png
index 84be3a94a45..4ab7a5eae4e 100644
--- a/doc/user/project/integrations/img/jira_create_new_group.png
+++ b/doc/user/project/integrations/img/jira_create_new_group.png
diff --git a/doc/user/project/integrations/img/jira_create_new_user.png b/doc/user/project/integrations/img/jira_create_new_user.png
index 8460dc98ef9..c74933298e3 100644
--- a/doc/user/project/integrations/img/jira_create_new_user.png
+++ b/doc/user/project/integrations/img/jira_create_new_user.png
diff --git a/doc/user/project/integrations/img/jira_group_access.png b/doc/user/project/integrations/img/jira_group_access.png
index 58cf114bd55..e33f2eed242 100644
--- a/doc/user/project/integrations/img/jira_group_access.png
+++ b/doc/user/project/integrations/img/jira_group_access.png
diff --git a/doc/user/project/integrations/img/jira_issue_reference.png b/doc/user/project/integrations/img/jira_issue_reference.png
index 72c81460df7..db8bc4f0bb9 100644
--- a/doc/user/project/integrations/img/jira_issue_reference.png
+++ b/doc/user/project/integrations/img/jira_issue_reference.png
diff --git a/doc/user/project/integrations/img/jira_merge_request_close.png b/doc/user/project/integrations/img/jira_merge_request_close.png
index 0f82ceba557..9a176daf5f4 100644
--- a/doc/user/project/integrations/img/jira_merge_request_close.png
+++ b/doc/user/project/integrations/img/jira_merge_request_close.png
diff --git a/doc/user/project/integrations/img/jira_service_close_comment.png b/doc/user/project/integrations/img/jira_service_close_comment.png
deleted file mode 100644
index 9af0d38f098..00000000000
--- a/doc/user/project/integrations/img/jira_service_close_comment.png
+++ /dev/null
diff --git a/doc/user/project/integrations/img/jira_service_close_issue.png b/doc/user/project/integrations/img/jira_service_close_issue.png
index c85b1d1dd97..73d6498192c 100644
--- a/doc/user/project/integrations/img/jira_service_close_issue.png
+++ b/doc/user/project/integrations/img/jira_service_close_issue.png
diff --git a/doc/user/project/integrations/img/jira_service_page.png b/doc/user/project/integrations/img/jira_service_page.png
deleted file mode 100644
index 377b69d9d06..00000000000
--- a/doc/user/project/integrations/img/jira_service_page.png
+++ /dev/null
diff --git a/doc/user/project/integrations/img/jira_service_page_v12_2.png b/doc/user/project/integrations/img/jira_service_page_v12_2.png
new file mode 100644
index 00000000000..ba7dad9b438
--- /dev/null
+++ b/doc/user/project/integrations/img/jira_service_page_v12_2.png
diff --git a/doc/user/project/integrations/img/jira_user_management_link.png b/doc/user/project/integrations/img/jira_user_management_link.png
index 43ef18da6c8..caecd1d71fc 100644
--- a/doc/user/project/integrations/img/jira_user_management_link.png
+++ b/doc/user/project/integrations/img/jira_user_management_link.png
diff --git a/doc/user/project/integrations/img/mattermost_configuration.png b/doc/user/project/integrations/img/mattermost_configuration.png
index 75ef0310f2d..6abf5c5c8d6 100644
--- a/doc/user/project/integrations/img/mattermost_configuration.png
+++ b/doc/user/project/integrations/img/mattermost_configuration.png
diff --git a/doc/user/project/integrations/img/prometheus_dashboard_area_panel_type.png b/doc/user/project/integrations/img/prometheus_dashboard_area_panel_type.png
new file mode 100644
index 00000000000..9fdb6dfddac
--- /dev/null
+++ b/doc/user/project/integrations/img/prometheus_dashboard_area_panel_type.png
diff --git a/doc/user/project/integrations/img/prometheus_dashboard_single_stat_panel_type.png b/doc/user/project/integrations/img/prometheus_dashboard_single_stat_panel_type.png
new file mode 100644
index 00000000000..2d7dfb27b49
--- /dev/null
+++ b/doc/user/project/integrations/img/prometheus_dashboard_single_stat_panel_type.png
diff --git a/doc/user/project/integrations/img/prometheus_service_alerts.png b/doc/user/project/integrations/img/prometheus_service_alerts.png
index a81dfe7da14..609c5e5196c 100644
--- a/doc/user/project/integrations/img/prometheus_service_alerts.png
+++ b/doc/user/project/integrations/img/prometheus_service_alerts.png
diff --git a/doc/user/project/integrations/img/slack_configuration.png b/doc/user/project/integrations/img/slack_configuration.png
index a14d2969488..10d2cda6dc7 100644
--- a/doc/user/project/integrations/img/slack_configuration.png
+++ b/doc/user/project/integrations/img/slack_configuration.png
diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md
index 234e3ad31cc..61f6f6c9412 100644
--- a/doc/user/project/integrations/jira.md
+++ b/doc/user/project/integrations/jira.md
@@ -39,21 +39,17 @@ a GitLab project with any single Jira project.
 If you have one Jira instance, you can pre-fill the settings page with a default
 template. See the [Services Templates][services-templates] docs.
 
-Configuration happens via user name and password. Connecting to a Jira server
-via CAS is not possible.
-
-In order to enable the Jira service in GitLab, you need to first configure the
-project in Jira and then enter the correct values in GitLab.
+In order to enable the Jira service in GitLab, you need to first configure the project in Jira and then enter the correct values in GitLab.
 
 ### Configuring Jira
 
-When connecting to **JIRA Server**, which supports basic authentication, a **username and password** are required. Check the link below and proceed to the next step:
+#### Jira Server
 
-- [Setting up a user in JIRA server](jira_server_configuration.md)
+When connecting to **Jira Server**, which supports basic authentication, a **username and password** are required. Note that connecting to a Jira server via CAS is not possible. [Set up a user in Jira Server](jira_server_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab).
 
-When connecting to **JIRA Cloud**, which supports authentication via API token, an **email and API token**, are required. Check the link below and proceed to the next step:
+#### Jira Cloud
 
-- [Setting up a user in JIRA cloud](jira_cloud_configuration.md)
+When connecting to **Jira Cloud**, which supports authentication via API token, an **email and API token**, are required. [Set up a user in Jira Cloud](jira_cloud_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab).
 
 ### Configuring GitLab
 
@@ -68,7 +64,7 @@ When connecting to **JIRA Cloud**, which supports authentication via API token,
 >   to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with
 >   a value of `fromDialog`.
 
-To enable Jira integration in a project, navigate to the
+To enable the Jira integration in a project, navigate to the
 [Integrations page](project_services.md#accessing-the-project-services), click
 the **Jira** service, and fill in the required details on the page as described
 in the table below.
@@ -77,8 +73,8 @@ in the table below.
 | ----- | ----------- |
 | `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. E.g., `https://Jira.example.com`. |
 | `Jira API URL` | The base URL to the Jira instance API. Web URL value will be used if not set. E.g., `https://jira-api.example.com`. |
-| `Username/Email` | Created when [configuring Jira step](#configuring-jira). Use `username` for **JIRA server** or `email` for **JIRA cloud**. |
-| `Password/API token` |Created in [configuring Jira step](#configuring-jira). Use `password` for **JIRA server** or `API token` for **JIRA cloud**. |
+| `Username/Email` | Created when [configuring Jira step](#configuring-jira). Use `username` for **Jira Server** or `email` for **Jira Cloud**. |
+| `Password/API token` |Created in [configuring Jira step](#configuring-jira). Use `password` for **Jira Server** or `API token` for **Jira Cloud**. |
 | `Transition ID` | This is the ID of a transition that moves issues to the desired state. It is possible to insert transition ids separated by `,` or `;` which means the issue will be moved to each state after another using the given order.  **Closing Jira issues via commits or Merge Requests won't work if you don't set the ID correctly.** |
 
 ### Obtaining a transition ID
@@ -97,7 +93,7 @@ even if the status you are changing to is the same.
 After saving the configuration, your GitLab project will be able to interact
 with all Jira projects in your Jira instance and you'll see the Jira link on the GitLab project pages that takes you to the appropriate Jira project.
 
-![Jira service page](img/jira_service_page.png)
+![Jira service page](img/jira_service_page_v12_2.png)
 
 ## Jira issues
 
@@ -127,6 +123,12 @@ ENTITY_TITLE
 
 ![example of mentioning or closing the Jira issue](img/jira_issue_reference.png)
 
+For example, the following commit will reference the Jira issue with `PROJECT-1` as its ID:
+
+```bash
+git commit -m "PROJECT-1 Fix spelling and grammar"
+```
+
 ### Closing Jira Issues
 
 Jira issues can be closed directly from GitLab by using trigger words in
@@ -142,7 +144,7 @@ the same goal:
 - `Closes PROJECT-1`
 - `Fixes PROJECT-1`
 
-where `PROJECT-1` is the issue ID of the Jira project.
+where `PROJECT-1` is the ID of the Jira issue.
 
 > **Notes:**
 >
@@ -174,8 +176,6 @@ with a link to the commit that resolved the issue.
 
 ![The GitLab integration closes Jira issue](img/jira_service_close_issue.png)
 
-![The GitLab integration creates a comment and a link on Jira issue.](img/jira_service_close_comment.png)
-
 ## Troubleshooting
 
 If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured.
diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md
index 849df707521..1d5a4a3d4c7 100644
--- a/doc/user/project/integrations/jira_cloud_configuration.md
+++ b/doc/user/project/integrations/jira_cloud_configuration.md
@@ -1,18 +1,20 @@
-# Creating an API token in JIRA cloud
+# Creating an API token in Jira Cloud
 
-An API token is needed when integrating with JIRA Cloud, follow the steps
+An API token is needed when integrating with Jira Cloud, follow the steps
 below to create one:
 
-1. Log in to <https://id.atlassian.com> with your email.
-1. **Click API tokens**, then **Create API token**.
+1. Log in to <https://id.atlassian.com/manage/api-tokens> with your email address.
 
-![JIRA API token](img/jira_api_token_menu.png)
+   NOTE: **Note**
+   It is important that the user associated with this email address has *write* access
+   to projects in Jira.
 
-![JIRA API token](img/jira_api_token.png)
+1. Click **Create API token**.
 
-1. Make sure to write down your new API token as you will need it in the next [steps](jira.md#configuring-gitlab).
+![Jira API token](img/jira_api_token_menu.png)
 
-NOTE: **Note**
-It is important that the user associated with this email has 'write' access to projects in JIRA.
+![Jira API token](img/jira_api_token.png)
 
-The JIRA configuration is complete. You are going to need this new created token and the email you used to log in when [configuring GitLab in the next section](jira.md#configuring-gitlab).
+1. Click **Copy to clipboard**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configuring-gitlab).
+
+The Jira configuration is complete. You need the newly created token, and the associated email address, when [configuring GitLab](jira.md#configuring-gitlab) in the next section.
diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md
index 13d65c4d8e4..1efd0ff3944 100644
--- a/doc/user/project/integrations/jira_server_configuration.md
+++ b/doc/user/project/integrations/jira_server_configuration.md
@@ -1,10 +1,10 @@
-# Creating a username and password for JIRA server
+# Creating a username and password for Jira Server
 
 We need to create a user in Jira which will have access to all projects that
 need to integrate with GitLab.
 
-As an example, we'll create a user named `gitlab` and add it to the `Jira-developers`
-group.
+As an example, we'll create a user named `gitlab` and add it to a new group
+named `gitlab-developers`.
 
 NOTE: **Note**
 It is important that the Jira user created for the integration is given 'write'
@@ -13,46 +13,46 @@ access to your Jira projects. This is covered in the process below.
 1. Log in to your Jira instance as an administrator and under **Jira Administration**
    go to **User Management** to create a new user.
 
-     ![Jira user management link](img/jira_user_management_link.png)
+   ![Jira user management link](img/jira_user_management_link.png)
 
 1. The next step is to create a new user (e.g., `gitlab`) who has write access
    to projects in Jira. Enter the user's name and a _valid_ e-mail address
    since Jira sends a verification e-mail to set up the password.
    _**Note:** Jira creates the username automatically by using the e-mail
    prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create
-    an HTTP basic authentication password. You can do this by visiting the user
-    profile, looking up the username, and setting a password._
+   an HTTP basic authentication password. You can do this by visiting the user
+   profile, looking up the username, and setting a password._
 
-     ![Jira create new user](img/jira_create_new_user.png)
+   ![Jira create new user](img/jira_create_new_user.png)
 
 1. Create a `gitlab-developers` group. (We will give this group write access to Jira
    projects in a later step). Go to the **Groups** tab on the left, and select **Add group**.
 
-     ![Jira create new user](img/jira_create_new_group.png)
+   ![Jira create new user](img/jira_create_new_group.png)
 
-     Give it a name and click **Add group**.
+   Give it a name and click **Add group**.
 
 1. Add the `gitlab` user to the `gitlab-developers` group by clicking **Edit members**.
    The `gitlab-developers` group should be listed in the leftmost box as a selected group.
    Under **Add members to selected group(s)**, enter `gitlab`.
 
-     ![Jira add user to group](img/jira_add_user_to_group.png)
-     
+   ![Jira add user to group](img/jira_add_user_to_group.png)
+
    Click **Add selected users** and `gitlab` should appear in the **Group member(s)** box.
    This membership is saved automatically.
-   
-     ![Jira added user to group](img/jira_added_user_to_group.png)
+
+   ![Jira added user to group](img/jira_added_user_to_group.png)
 
 1. To give the newly-created group 'write' access, you need to create a **Permission Scheme**.
    To do this, click the gear icon and select **Issues**. Then click **Permission Schemes**.
    Click **Add Permission Scheme** and enter a **Name** and, optionally, a **Description**.
-    
+
 1. Once your permission scheme is created, you'll be taken back to the permissions scheme list.
-   Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, 
+   Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**,
    click **Edit**. In the resulting dialog box, select **Group** and select `gitlab-developers`
    from the dropdown.
 
-     ![Jira group access](img/jira_group_access.png)
+   ![Jira group access](img/jira_group_access.png)
 
 The Jira configuration is complete. Write down the new Jira username and its
 password as they will be needed when [configuring GitLab in the next section](jira.md#configuring-gitlab).
diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md
index d7fd75fd728..6e0f39956d3 100644
--- a/doc/user/project/integrations/mattermost.md
+++ b/doc/user/project/integrations/mattermost.md
@@ -1,5 +1,9 @@
 # Mattermost Notifications Service
 
+The Mattermost Notifications Service allows your GitLab project to send events (e.g., `issue created`) to your existing Mattermost team as notifications. This requires configurations in both Mattermost and GitLab.
+
+You can also use Mattermost slash commands to control GitLab inside Mattermost. This is the separately configured [Mattermost slash commands](mattermost_slash_commands.md).
+
 ## On Mattermost
 
 To enable Mattermost integration you must create an incoming webhook integration:
@@ -10,7 +14,7 @@ To enable Mattermost integration you must create an incoming webhook integration
 1. Save it, copy the **Webhook URL**, we'll need this later for GitLab.
 
 There might be some cases that Incoming Webhooks are blocked by admin, ask your mattermost admin to enable
-it on `https://mattermost.example/admin_console/integrations/custom`.
+it on **Mattermost System Console > Integrations > Integration Management**, or on **Mattermost System Console > Integrations > Custom Integrations** in Mattermost versions 5.11 and earlier.
 
 Display name override is not enabled by default, you need to ask your admin to enable it on that same section.
 
diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md
index 9c69437537a..a3a2568445e 100644
--- a/doc/user/project/integrations/mattermost_slash_commands.md
+++ b/doc/user/project/integrations/mattermost_slash_commands.md
@@ -6,6 +6,9 @@ Mattermost commands give users an extra interface to perform common operations
 from the chat environment. This allows one to, for example, create an issue as
 soon as the idea was discussed in Mattermost.
 
+GitLab can also send events (e.g., `issue created`) to Mattermost as notifications.
+This is the separately configured [Mattermost Notifications Service](mattermost.md).
+
 ## Prerequisites
 
 Mattermost 3.4 and up is required.
@@ -37,17 +40,13 @@ the administrator console.
 1. Log in with an account that has admin privileges and navigate to the system
    console.
 
-    ![Mattermost go to console](img/mattermost_goto_console.png)
-
-    ---
+   ![Mattermost go to console](img/mattermost_goto_console.png)
 
 1. Click **Custom integrations** and set **Enable Custom Slash Commands**,
    **Enable custom integrations to override usernames**, and **Override
    custom integrations to override profile picture icons** to true
 
-    ![Mattermost console](img/mattermost_console_integrations.png)
-
-    ---
+   ![Mattermost console](img/mattermost_console_integrations.png)
 
 1. Click **Save** at the bottom to save the changes.
 
@@ -59,14 +58,12 @@ the administrator console.
    A screen will appear with all the values you need to copy in Mattermost as
    described in the next step. Leave the window open.
 
-    >**Note:**
-    GitLab will propose some values for the Mattermost settings. The only one
-    required to copy-paste as-is is the **Request URL**, all the others are just
-    suggestions.
-
-    ![Mattermost setup instructions](img/mattermost_config_help.png)
+   NOTE: **Note:**
+   GitLab will propose some values for the Mattermost settings. The only one
+   required to copy-paste as-is is the **Request URL**, all the others are just
+   suggestions.
 
-    ---
+   ![Mattermost setup instructions](img/mattermost_config_help.png)
 
 1. Proceed to the next step and create a slash command in Mattermost with the
    above values.
@@ -80,44 +77,38 @@ in a new slash command.
 1. Back to Mattermost, under your team page settings, you should see the
    **Integrations** option.
 
-    ![Mattermost team integrations](img/mattermost_team_integrations.png)
-
-    ---
+   ![Mattermost team integrations](img/mattermost_team_integrations.png)
 
 1. Go to the **Slash Commands** integration and add a new one by clicking the
    **Add Slash Command** button.
 
-    ![Mattermost add command](img/mattermost_add_slash_command.png)
-
-    ---
+   ![Mattermost add command](img/mattermost_add_slash_command.png)
 
 1. Fill in the options for the custom command as described in
    [step 2](#step-2-open-the-mattermost-slash-commands-service-in-gitlab).
 
-    >**Note:**
-    If you plan on connecting multiple projects, pick a slash command trigger
-    word that relates to your projects such as `/gitlab-project-name` or even
-    just `/project-name`. Only use `/gitlab` if you will only connect a single
-    project to your Mattermost team.
+   NOTE: **Note:**
+   If you plan on connecting multiple projects, pick a slash command trigger
+   word that relates to your projects such as `/gitlab-project-name` or even
+   just `/project-name`. Only use `/gitlab` if you will only connect a single
+   project to your Mattermost team.
 
-    ![Mattermost add command configuration](img/mattermost_slash_command_configuration.png)
+   ![Mattermost add command configuration](img/mattermost_slash_command_configuration.png)
 
 1. After you set up all the values, copy the token (we will use it below) and
    click **Done**.
 
-    ![Mattermost slash command token](img/mattermost_slash_command_token.png)
+   ![Mattermost slash command token](img/mattermost_slash_command_token.png)
 
 ### Step 4. Copy the Mattermost token into the Mattermost slash command service
 
 1. In GitLab, paste the Mattermost token you copied in the previous step and
    check the **Active** checkbox.
 
-    ![Mattermost copy token to GitLab](img/mattermost_gitlab_token.png)
+   ![Mattermost copy token to GitLab](img/mattermost_gitlab_token.png)
 
 1. Click **Save changes** for the changes to take effect.
 
----
-
 You are now set to start using slash commands in Mattermost that talk to the
 GitLab project you configured.
 
diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md
index 1c64b275d6e..886094a6531 100644
--- a/doc/user/project/integrations/mock_ci.md
+++ b/doc/user/project/integrations/mock_ci.md
@@ -5,9 +5,9 @@
 To set up the mock CI service server, respond to the following endpoints
 
 - `commit_status`: `#{project.namespace.path}/#{project.path}/status/#{sha}.json`
-   - Have your service return `200 { status: ['failed'|'canceled'|'running'|'pending'|'success'|'success-with-warnings'|'skipped'|'not_found'] }`
+  - Have your service return `200 { status: ['failed'|'canceled'|'running'|'pending'|'success'|'success-with-warnings'|'skipped'|'not_found'] }`
    - If the service returns a 404, it is interpreted as `pending`
 - `build_page`: `#{project.namespace.path}/#{project.path}/status/#{sha}`
-   - Just where the build is linked to, doesn't matter if implemented
+  - Just where the build is linked to, doesn't matter if implemented
 
 For an example of a mock CI server, see [`gitlab-org/gitlab-mock-ci-service`](https://gitlab.com/gitlab-org/gitlab-mock-ci-service)
diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md
index 0bfee3bac99..67274e8d924 100644
--- a/doc/user/project/integrations/project_services.md
+++ b/doc/user/project/integrations/project_services.md
@@ -20,10 +20,10 @@ Below, you will find a list of the currently supported ones accompanied with com
 
 Click on the service links to see further configuration instructions and details.
 
-| Service |	Description |
+| Service | Description |
 | ------- | ----------- |
-| Asana     |	Asana - Teamwork without email |
-| Assembla 	| Project Management Software (Source Commits Endpoint) |
+| Asana     | Asana - Teamwork without email |
+| Assembla | Project Management Software (Source Commits Endpoint) |
 | [Atlassian Bamboo CI](bamboo.md) | A continuous integration and build server |
 | Buildkite | Continuous integration and deployments |
 | [Bugzilla](bugzilla.md) | Bugzilla issue tracker |
@@ -34,12 +34,12 @@ Click on the service links to see further configuration instructions and details
 | [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients |
 | External Wiki | Replaces the link to the internal wiki with a link to an external wiki |
 | Flowdock | Flowdock is a collaboration web app for technical teams |
-| [GitHub](github.md) **[PREMIUM]** | Sends pipeline notifications to GitHub |
+| [GitHub](github.md) **(PREMIUM)** | Sends pipeline notifications to GitHub |
 | [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat |
 | [HipChat](hipchat.md) | Private group chat and IM |
 | [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway |
-| [JIRA](jira.md) | JIRA issue tracker |
-| [Jenkins](../../../integration/jenkins.md) **[STARTER]** | An extendable open source continuous integration server |
+| [Jira](jira.md) | Jira issue tracker |
+| [Jenkins](../../../integration/jenkins.md) **(STARTER)** | An extendable open source continuous integration server |
 | JetBrains TeamCity CI | A continuous integration and build server |
 | [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands |
 | [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost |
@@ -47,8 +47,8 @@ Click on the service links to see further configuration instructions and details
 | Packagist | Update your project on Packagist, the main Composer repository |
 | Pipelines emails | Email the pipeline status to a list of recipients |
 | [Slack Notifications](slack.md) | Send GitLab events (e.g. issue created) to Slack as notifications |
-| [Slack slash commands](slack_slash_commands.md) **[CORE ONLY]** | Use slash commands in Slack to control GitLab |
-| [GitLab Slack application](gitlab_slack_application.md) **[FREE ONLY]** | Use Slack's official application |
+| [Slack slash commands](slack_slash_commands.md) **(CORE ONLY)** | Use slash commands in Slack to control GitLab |
+| [GitLab Slack application](gitlab_slack_application.md) **(FREE ONLY)** | Use Slack's official application |
 | PivotalTracker | Project Management Software (Source Commits Endpoint) |
 | [Prometheus](prometheus.md) | Monitor the performance of your deployed apps |
 | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop |
diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md
index 751e8e44e60..aa7db97c413 100644
--- a/doc/user/project/integrations/prometheus.md
+++ b/doc/user/project/integrations/prometheus.md
@@ -18,6 +18,7 @@ Once enabled, GitLab will automatically detect metrics from known services in th
 ## Enabling Prometheus Integration
 
 ### Managed Prometheus on Kubernetes
+
 > **Note**: [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28916) in GitLab 10.5
 
 GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cluster](../clusters/index.md), making monitoring of your apps easy.
@@ -39,9 +40,9 @@ Once you have a connected Kubernetes cluster with Helm installed, deploying a ma
 
 #### About managed Prometheus deployments
 
-Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/kubernetes/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/).
+Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/).
 
-The Prometheus server will [automatically detect and monitor](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#%3Ckubernetes_sd_config%3E) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/):
+The Prometheus server will [automatically detect and monitor](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/):
 
 - `prometheus.io/scrape` to `true` to enable monitoring of the resource.
 - `prometheus.io/port` to define the port of the metrics endpoint.
@@ -66,9 +67,9 @@ Integration with Prometheus requires the following:
 
 Installing and configuring Prometheus to monitor applications is fairly straight forward.
 
-1. [Install Prometheus](https://prometheus.io/docs/introduction/install/)
+1. [Install Prometheus](https://prometheus.io/docs/prometheus/latest/installation/)
 1. Set up one of the [supported monitoring targets](prometheus_library/index.md)
-1. Configure the Prometheus server to [collect their metrics](https://prometheus.io/docs/operating/configuration/#scrape_config)
+1. Configure the Prometheus server to [collect their metrics](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config)
 
 #### Configuration in GitLab
 
@@ -93,11 +94,14 @@ GitLab will automatically scan the Prometheus server for metrics from known serv
 
 You can view the performance dashboard for an environment by [clicking on the monitoring button](../../../ci/environments.md#monitoring-environments).
 
-### Adding additional metrics **[PREMIUM]**
+### Adding additional metrics **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3799) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6.
 
-Additional metrics can be monitored by adding them on the Prometheus integration page. Once saved, they will be displayed on the environment performance dashboard.
+Custom metrics can be monitored by adding them on the Prometheus integration page. Once saved, they will be displayed on the environment performance dashboard provided that either:
+
+- A [connected Kubernetes cluster](../clusters/index.md#adding-and-removing-clusters) with the environment scope of `*` is used and [Prometheus installed on the cluster](#enabling-prometheus-integration), or
+- Prometheus is [manually configured](#manual-configuration-of-prometheus).
 
 ![Add New Metric](img/prometheus_add_metric.png)
 
@@ -120,7 +124,152 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.htm
 
 To specify a variable in a query, enclose it in curly braces with a leading percent. For example: `%{ci_environment_slug}`.
 
-### Setting up alerts for Prometheus metrics **[ULTIMATE]**
+### Defining custom dashboards per project
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/59974) in GitLab 12.1.
+
+By default, all projects include a GitLab-defined Prometheus dashboard, which
+includes a few key metrics, but you can also define your own custom dashboards.
+
+NOTE: **Note:**
+The custom metrics as defined below do not support alerts, unlike
+[additional metrics](#adding-additional-metrics-premium).
+
+Dashboards have several components:
+
+- Panel groups, which comprise panels.
+- Panels, which support one or more metrics.
+
+To configure a custom dashboard:
+
+1. Create a YAML file with the `.yml` extension under your repository's root
+   directory inside `.gitlab/dashboards/`. For example, create
+   `.gitlab/dashboards/prom_alerts.yml` with the following contents:
+
+   ```yaml
+   dashboard: 'Dashboard Title'
+   panel_groups:
+     - group: 'Group Title'
+       panels:
+         - type: area-chart
+           title: "Chart Title"
+           y_label: "Y-Axis"
+           metrics:
+             - id: metric_of_ages
+               query_range: 'http_requests_total'
+               label: "Metric of Ages"
+               unit: "count"
+   ```
+
+   The above sample dashboard would display a single area chart. Each file should
+   define the layout of the dashboard and the Prometheus queries used to populate
+   data.
+
+1. Save the file, commit, and push to your repository.
+1. Navigate to your project's **Operations > Metrics** and choose the custom
+   dashboard from the dropdown.
+
+NOTE: **Note:**
+Configuration files nested under subdirectories of `.gitlab/dashboards` are not
+supported and will not be available in the UI.
+
+The following tables outline the details of expected properties.
+
+**Dashboard properties:**
+
+| Property | Type | Required | Description |
+| ------ | ------ | ------ | ------ |
+| `dashboard` | string | yes | Heading for the dashboard. Only one dashboard should be defined per file. |
+| `panel_groups` | array | yes | The panel groups which should be on the dashboard. |
+
+**Panel group (`panel_groups`) properties:**
+
+| Property | Type | Required | Description |
+| ------ | ------ | ------ | ------ |
+| `group` | string | required | Heading for the panel group. |
+| `priority` | number | optional, defaults to order in file | Order to appear on the dashboard. Higher number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. |
+| `panels` | array | required | The panels which should be in the panel group. |
+
+**Panel (`panels`) properties:**
+
+| Property | Type | Required | Description |
+| ------ | ------ | ------ | ------- |
+| `type` | enum | no, defaults to `area-chart` | Specifies the chart type to use. |
+| `title` | string | yes | Heading for the panel. |
+| `y_label` | string | no, but highly encouraged | Y-Axis label for the panel. |
+| `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. |
+| `metrics` | array | yes | The metrics which should be displayed in the panel. |
+
+**Metrics (`metrics`) properties:**
+
+| Property | Type | Required | Description |
+| ------ | ------ | ------ | ------ |
+| `id` | string | no | Used for associating dashboard metrics with database records. Must be unique across dashboard configuration files. Required for [alerting](#setting-up-alerts-for-prometheus-metrics-ultimate) (support not yet enabled, see [relevant issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/60319)). |
+| `unit` | string | yes | Defines the unit of the query's return data. |
+| `label` | string | no, but highly encouraged | Defines the legend-label for the query. Should be unique within the panel's metrics. |
+| `query` | string | yes if `query_range` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be utilized. |
+| `query_range` | string | yes if `query` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query_range` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be utilized. |
+
+#### Panel types for dashboards
+
+The below panel types are supported in monitoring dashboards.
+
+##### Area
+
+To add an area panel type to a dashboard, look at the following sample dashboard file:
+
+```yaml
+dashboard: 'Dashboard Title'
+panel_groups:
+  - group: 'Group Title'
+    panels:
+      - type: area-chart
+        title: "Chart Title"
+        y_label: "Y-Axis"
+        metrics:
+          - id: 10
+            query_range: 'http_requests_total'
+            label: "Metric of Ages"
+            unit: "count"
+```
+
+Note the following properties:
+
+| Property | Type | Required | Description |
+| ------ | ------ | ------ | ------ |
+| type | string | no | Type of panel to be rendered. Optional for area panel types |
+| query_range | yes | required | For area panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) |
+
+![area panel type](img/prometheus_dashboard_area_panel_type.png)
+
+##### Single Stat
+
+To add a single stat panel type to a dashboard, look at the following sample dashboard file:
+
+```yaml
+dashboard: 'Dashboard Title'
+panel_groups:
+  - group: 'Group Title'
+    panels:
+      - title: "Single Stat"
+        type: "single-stat"
+        metrics:
+        - id: 10
+          query: 'max(go_memstats_alloc_bytes{job="prometheus"})'
+          unit: MB
+          label: "Total"
+```
+
+Note the following properties:
+
+| Property | Type | Required | Description |
+| ------ | ------ | ------ | ------ |
+| type | string | yes | Type of panel to be rendered. For single stat panel types, set to `single-stat` |
+| query | string | yes | For single stat panel types, you must use an [instant query](https://prometheus.io/docs/prometheus/latest/querying/api/#instant-queries) |
+
+![single stat panel type](img/prometheus_dashboard_single_stat_panel_type.png)
+
+### Setting up alerts for Prometheus metrics **(ULTIMATE)**
 
 #### Managed Prometheus instances
 
@@ -156,11 +305,11 @@ receivers:
   ...
 ```
 
-### Taking action on incidents **[ULTIMATE]**
+### Taking action on incidents **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11.
 
-Alerts can be used to trigger actions, like open an issue automatically. To configure the actions:
+Alerts can be used to trigger actions, like open an issue automatically (enabled by default since `12.1`). To configure the actions:
 
 1. Navigate to your project's **Settings > Operations > Incidents**.
 1. Enable the option to create issues.
@@ -168,7 +317,20 @@ Alerts can be used to trigger actions, like open an issue automatically. To conf
 1. Optionally, select whether to send an email notification to the developers of the project.
 1. Click **Save changes**.
 
-Once enabled, an issue will be opened automatically when an alert is triggered. The author of the issue will be the GitLab Alert Bot. To further customize the issue, you can add labels, mentions, or any other supported [quick action](../quick_actions.md) in the selected issue template.
+Once enabled, an issue will be opened automatically when an alert is triggered which contains values extracted from [alert's payload](https://prometheus.io/docs/alerting/configuration/#webhook_config
+):
+
+- Issue author: `GitLab Alert Bot`
+- Issue title: Extract from `annotations/title`, `annotations/summary` or `labels/alertname`
+- Alert `Summary`: A list of properties
+  - `starts_at`: Alert start time via `startsAt`
+  - `full_query`: Alert query extracted from `generatorURL`
+  - Optional list of attached annotations extracted from `annotations/*`
+- Alert [GFM](../../markdown.md): GitLab Flavored Markdown from `annotations/gitlab_incident_markdown`
+
+To further customize the issue, you can add labels, mentions, or any other supported [quick action](../quick_actions.md) in the selected issue template, which will apply to all incidents. To limit quick actions or other information to only specific types of alerts, use the `annotations/gitlab_incident_markdown` field.
+
+Since [version 12.2](https://gitlab.com/gitlab-org/gitlab-ce/issues/63373), GitLab will tag each incident issue with the `incident` label automatically. If the label does not yet exist, it will be created automatically as well.
 
 If the metric exceeds the threshold of the alert for over 5 minutes, an email will be sent to all [Maintainers and Owners](../../permissions.md#project-members-permissions) of the project.
 
@@ -192,6 +354,27 @@ Prometheus server.
 
 ![Merge Request with Performance Impact](img/merge_request_performance.png)
 
+## Embedding metric charts within Gitlab Flavored Markdown
+
+> [Introduced][ce-29691] in GitLab 12.2.
+> Requires [Kubernetes](prometheus_library/kubernetes.md) metrics.
+
+It is possible to display metrics charts within [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm).
+
+To display a metric chart, include a link of the form `https://<root_url>/<project>/environments/<environment_id>/metrics`.
+
+The following requirements must be met for the metric to unfurl:
+
+- The `<environment_id>` must correspond to a real environment.
+- Prometheus must be monitoring the environment.
+- The GitLab instance must be configured to receive data from the environment.
+- The user must be allowed access to the monitoring dashboard for the environment ([Reporter or higher](../../permissions.md)).
+- The dashboard must have data within the last 8 hours.
+
+ If all of the above are true, then the metric will unfurl as seen below:
+
+![Embedded Metrics](img/embed_metrics.png)
+
 ## Troubleshooting
 
 If the "No data found" screen continues to appear, it could be due to:
@@ -214,4 +397,5 @@ If the "No data found" screen continues to appear, it could be due to:
 [ci-environment-slug]: ../../../ci/variables/#predefined-environment-variables
 [ce-8935]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935
 [ce-10408]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10408
+[ce-29691]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29691
 [promgldocs]: ../../../administration/monitoring/prometheus/index.md
diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md
index 66f1b587070..5049733abdd 100644
--- a/doc/user/project/integrations/prometheus_library/cloudwatch.md
+++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md
@@ -18,9 +18,9 @@ The [Prometheus service](../prometheus.md) must be enabled.
 
 ## Configuring Prometheus to monitor for Cloudwatch metrics
 
-To get started with Cloudwatch monitoring, you should install and configure the [Cloudwatch exporter](https://github.com/hnlq715/nginx-vts-exporter) which retrieves and parses the specified Cloudwatch metrics and translates them into a Prometheus monitoring endpoint.
+To get started with Cloudwatch monitoring, you should install and configure the [Cloudwatch exporter](https://github.com/prometheus/cloudwatch_exporter) which retrieves and parses the specified Cloudwatch metrics and translates them into a Prometheus monitoring endpoint.
 
-Right now, the only AWS resource supported is the Elastic Load Balancer, whose Cloudwatch metrics can be found [here](http://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html).
+Right now, the only AWS resource supported is the Elastic Load Balancer, whose Cloudwatch metrics are [documented here](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html).
 
 A sample Cloudwatch Exporter configuration file, configured for basic AWS ELB monitoring, is [available for download](../samples/cloudwatch.yml).
 
diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md
index abb0c01ad18..90a725f271b 100644
--- a/doc/user/project/integrations/prometheus_library/haproxy.md
+++ b/doc/user/project/integrations/prometheus_library/haproxy.md
@@ -1,4 +1,5 @@
 # Monitoring HAProxy
+
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12621) in GitLab 9.4
 
 GitLab has support for automatically detecting and monitoring HAProxy. This is provided by leveraging the [HAProxy Exporter](https://github.com/prometheus/haproxy_exporter), which translates HAProxy statistics into a Prometheus readable form.
@@ -11,8 +12,8 @@ The [Prometheus service](../prometheus.md) must be enabled.
 
 | Name | Query |
 | ---- | ----- |
-| Throughput (req/sec) | sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m])) by (code) |
-| HTTP Error Rate (%) | sum(rate(haproxy_frontend_http_requests_total{code="5xx",%{environment_filter}}[2m])) / sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m])) |
+| Throughput (req/sec) | `sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m])) by (code)` |
+| HTTP Error Rate (%) | `sum(rate(haproxy_frontend_http_requests_total{code="5xx",%{environment_filter}}[2m])) / sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m]))` |
 
 ## Configuring Prometheus to monitor for HAProxy metrics
 
diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md
index 8b1cf1a251a..9e17edf7d36 100644
--- a/doc/user/project/integrations/prometheus_library/kubernetes.md
+++ b/doc/user/project/integrations/prometheus_library/kubernetes.md
@@ -13,15 +13,15 @@ integration services must be enabled.
 
 - Average Memory Usage (MB):
 
-    ```
-    avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024
-    ```
+  ```
+  avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024
+  ```
 
 - Average CPU Utilization (%):
 
-    ```
-    avg(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name))
-    ```
+  ```
+  avg(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name))
+  ```
 
 ## Configuring Prometheus to monitor for Kubernetes metrics
 
@@ -36,7 +36,7 @@ In order to isolate and only display relevant CPU and Memory metrics for a given
 
 Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-environment-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment.
 
-## Displaying Canary metrics **[PREMIUM]**
+## Displaying Canary metrics **(PREMIUM)**
 
 > Introduced in [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15201).
 
@@ -48,12 +48,12 @@ These metrics expect the [Deployment](https://kubernetes.io/docs/concepts/worklo
 
 - Average Memory Usage (MB)
 
-    ```
-    avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024
-    ```
+  ```
+  avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024
+  ```
 
 - Average CPU Utilization (%)
 
-    ```
-    avg(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name))
-    ```
+  ```
+  avg(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name))
+  ```
diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md
index c4fea178ab5..7db9629c002 100644
--- a/doc/user/project/integrations/prometheus_library/nginx.md
+++ b/doc/user/project/integrations/prometheus_library/nginx.md
@@ -14,9 +14,9 @@ NGINX server metrics are detected, which tracks the pages and content directly s
 
 | Name | Query |
 | ---- | ----- |
-| Throughput (req/sec) | sum(rate(nginx_server_requests{server_zone!="*", server_zone!="_", %{environment_filter}}[2m])) by (code) |
-| Latency (ms) | avg(nginx_server_requestMsec{%{environment_filter}}) |
-| HTTP Error Rate (HTTP Errors / sec) | sum(rate(nginx_server_requests{code="5xx", %{environment_filter}}[2m])) |
+| Throughput (req/sec) | `sum(rate(nginx_server_requests{server_zone!="*", server_zone!="_", %{environment_filter}}[2m])) by (code)` |
+| Latency (ms) | `avg(nginx_server_requestMsec{%{environment_filter}})` |
+| HTTP Error Rate (HTTP Errors / sec) | `sum(rate(nginx_server_requests{code="5xx", %{environment_filter}}[2m]))` |
 
 ## Configuring Prometheus to monitor for NGINX metrics
 
diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md
index de7fc93f0a4..fd743855a8c 100644
--- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md
+++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md
@@ -14,9 +14,9 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI
 
 | Name | Query |
 | ---- | ----- |
-| Throughput (req/sec) | sum(label_replace(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m]), "status_code", "${1}xx", "status", "(.)..")) by (status_code) |
-| Latency (ms) | sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_sum{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_count{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 1000 |
-| HTTP Error Rate (%) | sum(rate(nginx_ingress_controller_requests{status=~"5.*",namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 100 |
+| Throughput (req/sec) | `sum(label_replace(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m]), "status_code", "${1}xx", "status", "(.)..")) by (status_code)` |
+| Latency (ms) | `sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_sum{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_count{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 1000` |
+| HTTP Error Rate (%) | `sum(rate(nginx_ingress_controller_requests{status=~"5.*",namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 100` |
 
 ## Configuring NGINX ingress monitoring
 
diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md
index 31ac53c0d14..b03787b3e0d 100644
--- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md
+++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md
@@ -14,9 +14,9 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI
 
 | Name | Query |
 | ---- | ----- |
-| Throughput (req/sec) | sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) by (status_code) |
-| Latency (ms) | avg(nginx_upstream_response_msecs_avg{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}) |
-| HTTP Error Rate (%) | sum(rate(nginx_upstream_responses_total{status_code="5xx", upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) / sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) * 100 |
+| Throughput (req/sec) | `sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) by (status_code)` |
+| Latency (ms) | `avg(nginx_upstream_response_msecs_avg{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"})` |
+| HTTP Error Rate (%) | `sum(rate(nginx_upstream_responses_total{status_code="5xx", upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) / sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) * 100` |
 
 ## Configuring NGINX ingress monitoring
 
diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md
index bac7eecfce4..25b000b2753 100644
--- a/doc/user/project/integrations/redmine.md
+++ b/doc/user/project/integrations/redmine.md
@@ -5,18 +5,18 @@
    the **Redmine** service, and fill in the required details on the page as described
    in the table below.
 
-    | Field | Description |
-    | ----- | ----------- |
-    | `description`   | A name for the issue tracker (to differentiate between instances, for example) |
-    | `project_url`   | The URL to the project in Redmine which is being linked to this GitLab project |
-    | `issues_url`    | The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. |
-    | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and will be removed in a future release.** |
+   | Field | Description |
+   | ----- | ----------- |
+   | `description`   | A name for the issue tracker (to differentiate between instances, for example) |
+   | `project_url`   | The URL to the project in Redmine which is being linked to this GitLab project |
+   | `issues_url`    | The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. |
+   | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and will be removed in a future release.** |
 
-    Once you have configured and enabled Redmine you'll see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project.
+   Once you have configured and enabled Redmine you'll see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project.
 
-    As an example, below is a configuration for a project named gitlab-ci.
+   As an example, below is a configuration for a project named gitlab-ci.
 
-    ![Redmine configuration](img/redmine_configuration.png)
+   ![Redmine configuration](img/redmine_configuration.png)
 
 1. To disable the internal issue tracking system in a project, navigate to the General page, expand the [permissions](../settings/index.md#sharing-and-permissions) section and switch the **Issues** toggle to disabled.
 
diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md
index bb8d276c2fc..508e72b5753 100644
--- a/doc/user/project/integrations/slack.md
+++ b/doc/user/project/integrations/slack.md
@@ -6,7 +6,7 @@ The Slack Notifications Service allows your GitLab project to send events (e.g.
 
 ## Slack Configuration
 
-1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook/).
+1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook).
 1. Select the Slack channel where notifications will be sent to by default. Click the **Add Incoming WebHooks integration** button to add the configuration.
 1. Copy the **Webhook URL**, which we'll use later in the GitLab configuration.
 
diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md
index 371e78ca3a4..813066c51ac 100644
--- a/doc/user/project/integrations/slack_slash_commands.md
+++ b/doc/user/project/integrations/slack_slash_commands.md
@@ -1,4 +1,4 @@
-# Slack slash commands **[CORE ONLY]**
+# Slack slash commands **(CORE ONLY)**
 
 > Introduced in GitLab 8.15.
 
diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md
index d5f28ddabc1..84adb9637fc 100644
--- a/doc/user/project/integrations/webhooks.md
+++ b/doc/user/project/integrations/webhooks.md
@@ -24,7 +24,7 @@ to the webhook URL.
 
 In most cases, you'll need to set up your own [webhook receiver](#example-webhook-receiver)
 to receive information from GitLab, and send it to another app, according to your needs.
-We already have a [built-in receiver](http://docs.gitlab.com/ce/project_services/slack.html)
+We already have a [built-in receiver](slack.md)
 for sending [Slack](https://api.slack.com/incoming-webhooks) notifications _per project_.
 
 ## Overview
@@ -58,13 +58,13 @@ Navigate to the webhooks page by going to your project's
 If you are writing your own endpoint (web server) that will receive
 GitLab webhooks keep in mind the following things:
 
--   Your endpoint should send its HTTP response as fast as possible. If
-    you wait too long, GitLab may decide the hook failed and retry it.
--   Your endpoint should ALWAYS return a valid HTTP response. If you do
-    not do this then GitLab will think the hook failed and retry it.
-    Most HTTP libraries take care of this for you automatically but if
-    you are writing a low-level hook this is important to remember.
--   GitLab ignores the HTTP status code returned by your endpoint.
+- Your endpoint should send its HTTP response as fast as possible. If
+  you wait too long, GitLab may decide the hook failed and retry it.
+- Your endpoint should ALWAYS return a valid HTTP response. If you do
+  not do this then GitLab will think the hook failed and retry it.
+  Most HTTP libraries take care of this for you automatically but if
+  you are writing a low-level hook this is important to remember.
+- GitLab ignores the HTTP status code returned by your endpoint.
 
 ## Secret token
 
@@ -326,7 +326,7 @@ X-Gitlab-Event: Issue Hook
       "current": 1
     },
     "updated_at": {
-      "previous": "2017-09-15 16:50:55 UTC", 
+      "previous": "2017-09-15 16:50:55 UTC",
       "current": "2017-09-15 16:52:00 UTC"
     },
     "labels": {
@@ -888,7 +888,7 @@ X-Gitlab-Event: Merge Request Hook
       "current": 1
     },
     "updated_at": {
-      "previous": "2017-09-15 16:50:55 UTC", 
+      "previous": "2017-09-15 16:50:55 UTC",
       "current":"2017-09-15 16:52:00 UTC"
     },
     "labels": {
diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md
index 31020de5208..eaca5f8cfb8 100644
--- a/doc/user/project/issue_board.md
+++ b/doc/user/project/issue_board.md
@@ -28,11 +28,11 @@ Issue Boards** (version introduced in GitLab 8.11 - August 2016).
 ### Advanced features of Issue Boards
 
 With [GitLab Starter](https://about.gitlab.com/pricing/), you can create
-[multiple issue boards](#multiple-issue-boards-starter) for a given project. **[STARTER]**
+[multiple issue boards](#multiple-issue-boards-starter) for a given project. **(STARTER)**
 
 With [GitLab Premium](https://about.gitlab.com/pricing/), you can also create multiple
 issue boards for your groups, and add lists for [assignees](#assignee-lists-premium) and
-[milestones](#milestone-lists-premium). **[PREMIUM]**
+[milestones](#milestone-lists-premium). **(PREMIUM)**
 
 Check all the [advanced features of Issue Boards](#gitlab-enterprise-features-for-issue-boards)
 below.
@@ -143,10 +143,10 @@ Create lists for each of your team members and quickly drag-and-drop issues onto
 
 - **Issue Board** - Each board represents a unique view for your issues. It can have multiple lists with each list consisting of issues represented by cards.
 - **List** - A column on the issue board that displays issues matching certain attributes. In addition to the default lists of 'Open' and 'Closed' issue, each additional list will show issues matching your chosen label or assignee. On the top of that list you can see the number of issues that belong to it.
-   - **Label list**: a list based on a label. It shows all opened issues with that label.
-   - **Assignee list**: a list which includes all issues assigned to a user.
-   - **Open** (default): shows all open issues that do not belong to one of the other lists. Always appears as the leftmost list.
-   - **Closed** (default): shows all closed issues. Always appears as the rightmost list.
+  - **Label list**: a list based on a label. It shows all opened issues with that label.
+  - **Assignee list**: a list which includes all issues assigned to a user.
+  - **Open** (default): shows all open issues that do not belong to one of the other lists. Always appears as the leftmost list.
+  - **Closed** (default): shows all closed issues. Always appears as the rightmost list.
 - **Card** - A box in the list that represents an individual issue. The information you can see on a card consists of the issue number, the issue title, the assignee, and the labels associated with the issue. You can drag cards from one list to another to change their label or assignee from that of the source list to that of the destination list.
 
 ## Permissions
@@ -163,7 +163,7 @@ on the following sections.
 
 For a collection of [features per tier](#summary-of-features-per-tier), check the summary below.
 
-### Multiple Issue Boards **[STARTER]**
+### Multiple Issue Boards **(STARTER)**
 
 > Introduced in [GitLab Enterprise Edition 8.13](https://about.gitlab.com/2016/10/22/gitlab-8-13-released/#multiple-issue-boards-ee).
 
@@ -188,7 +188,7 @@ NOTE: **Note:**
 The Multiple Issue Boards feature is available for
 **projects in GitLab Starter Edition** and for **groups in GitLab Premium Edition**.
 
-### Configurable Issue Boards **[STARTER]**
+### Configurable Issue Boards **(STARTER)**
 
 > Introduced in [GitLab Starter Edition 10.2](https://about.gitlab.com/2017/11/22/gitlab-10-2-released/#issue-boards-configuration).
 
@@ -208,7 +208,7 @@ If you don't have editing permission in a board, you're still able to see the co
 
 ![Viewing board configuration](img/issue_board_view_scope.png)
 
-### Focus mode **[STARTER]**
+### Focus mode **(STARTER)**
 
 > Introduced in [GitLab Starter 9.1](https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep).
 
@@ -216,7 +216,7 @@ Click the button at the top right to toggle focus mode on and off. In focus mode
 
 ![Board focus mode](img/issue_board_focus_mode.gif)
 
-### Sum of Issue Weights **[STARTER]**
+### Sum of Issue Weights **(STARTER)**
 
 The top of each list indicates the sum of issue weights for the issues that
 belong to that list. This is useful when using boards for capacity allocation,
@@ -224,7 +224,7 @@ especially in combination with [assignee lists](#assignee-lists-premium).
 
 ![Issue Board summed weights](img/issue_board_summed_weights.png)
 
-### Group Issue Boards **[PREMIUM]**
+### Group Issue Boards **(PREMIUM)**
 
 > Introduced in [GitLab Premium 10.0](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards).
 
@@ -240,7 +240,7 @@ one group issue board per group was made available in GitLab 10.6 Core.
 
 ![Group issue board](img/group_issue_board.png)
 
-### Assignee lists **[PREMIUM]**
+### Assignee lists **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5784) in GitLab 11.0 Premium.
 
@@ -259,7 +259,7 @@ To remove an assignee list, just as with a label list, click the trash icon.
 
 ![Assignee lists](img/issue_board_assignee_lists.png)
 
-### Milestone lists **[PREMIUM]**
+### Milestone lists **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6469) in GitLab 11.2 Premium.
 
@@ -386,6 +386,10 @@ a given board inside your GitLab instance, any time those two issues are subsequ
 loaded in any board in the same instance (could be a different project board or a different group board, for example),
 that ordering will be maintained.
 
+This ordering also affects [issue lists](issues/sorting_issue_lists.md).
+Changing the order in an issue board changes the ordering in an issue list,
+and vice versa.
+
 ### Filtering issues
 
 You should be able to use the filters on top of your Issue Board to show only
diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md
index c3e06b219ff..dab79327d6a 100644
--- a/doc/user/project/issues/automatic_issue_closing.md
+++ b/doc/user/project/issues/automatic_issue_closing.md
@@ -1,63 +1,5 @@
-# Automatic issue closing
-
->**Notes:**
->
-> - This is the user docs. In order to change the default issue closing pattern,
->   follow the steps in the [administration docs].
-> - For performance reasons, automatic issue closing is disabled for the very
->   first push from an existing repository.
-
-When a commit or merge request resolves one or more issues, it is possible to
-automatically have these issues closed when the commit or merge request lands
-in the project's default branch.
-
-If a commit message or merge request description contains a sentence matching
-a certain regular expression, all issues referenced from the matched text will
-be closed. This happens when the commit is pushed to a project's
-[**default** branch](../repository/branches/index.md#default-branch), or when a
-commit or merge request is merged into it.
-
-## Default closing pattern value
-
-When not specified, the default issue closing pattern as shown below will be
-used:
-
-```bash
-((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?|[Rr]esolv(?:e[sd]?|ing)|[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?)|([A-Z][A-Z0-9_]+-\d+))+)
-```
-
-Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's
-source code that can match references to:
-
-- A local issue (`#123`).
-- A cross-project issue (`group/project#123`).
-- A link to an issue
-  (`https://gitlab.example.com/group/project/issues/123`).
-
 ---
-
-This translates to the following keywords:
-
-- Close, Closes, Closed, Closing, close, closes, closed, closing
-- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing
-- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving
-- Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing
-
+redirect_to: 'managing_issues.md#closing-issues-automatically'
 ---
 
-For example the following commit message:
-
-```
-Awesome commit message
-
-Fix #20, Fixes #21 and Closes group/otherproject#22.
-This commit is also related to #17 and fixes #18, #19
-and https://gitlab.example.com/group/otherproject/issues/23.
-```
-
-will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed
-to, as well as `#22` and `#23` in group/otherproject. `#17` won't be closed as
-it does not match the pattern. It works with multi-line commit messages as well
-as one-liners when used with `git commit -m`.
-
-[administration docs]: ../../../administration/issue_closing_pattern.md
+This document was moved to [another location](managing_issues.md#closing-issues-automatically).
diff --git a/doc/user/project/issues/closing_issues.md b/doc/user/project/issues/closing_issues.md
index 1d88745af9f..04f1c8e1a4a 100644
--- a/doc/user/project/issues/closing_issues.md
+++ b/doc/user/project/issues/closing_issues.md
@@ -1,59 +1,5 @@
-# Closing Issues
+---
+redirect_to: 'managing_issues.md#closing-issues'
+---
 
-Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
-
-## Directly
-
-Whenever you decide that's no longer need for that issue,
-close the issue using the close button:
-
-![close issue - button](img/button_close_issue.png)
-
-## Via Merge Request
-
-When a merge request resolves the discussion over an issue, you can
-make it close that issue(s) when merged.
-
-All you need is to use a [keyword](automatic_issue_closing.md)
-accompanying the issue number, add to the description of that MR.
-
-In this example, the keyword "closes" prefixing the issue number will create a relationship
-in such a way that the merge request will close the issue when merged. 
-
-Mentioning various issues in the same line also works for this purpose:
-
-```md
-Closes #333, #444, #555 and #666
-```
-
-If the issue is in a different repository rather then the MR's,
-add the full URL for that issue(s):
-
-```md
-Closes #333, #444, and https://gitlab.com/<username>/<projectname>/issues/<xxx>
-```
-
-All the following keywords will produce the same behaviour:
-
-- Close, Closes, Closed, Closing, close, closes, closed, closing
-- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing
-- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving
-
-![merge request closing issue when merged](img/merge_request_closes_issue.png)
-
-If you use any other word before the issue number, the issue and the MR will
-link to each other, but the MR will NOT close the issue(s) when merged.
-
-![mention issues in MRs - closing and related](img/closing_and_related_issues.png)
-
-## From the Issue Board
-
-You can close an issue from [Issue Boards](../issue_board.md) by dragging an issue card
-from its list and dropping into **Closed**.
-
-![close issue from the Issue Board](img/close_issue_from_board.gif)
-
-## Customizing the issue closing pattern
-
-Alternatively, a GitLab **administrator** can
-[customize the issue closing pattern](../../../administration/issue_closing_pattern.md).
+This document was moved to [another location](managing_issues.md#closing-issues).
diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md
index 2c755e0fb4d..c10ef564f0d 100644
--- a/doc/user/project/issues/confidential_issues.md
+++ b/doc/user/project/issues/confidential_issues.md
@@ -77,3 +77,49 @@ project's search results respectively.
 | Maintainer access | Guest access |
 | :-----------: | :----------: |
 | ![Confidential issues search master](img/confidential_issues_search_master.png) | ![Confidential issues search guest](img/confidential_issues_search_guest.png) |
+
+## Merge Requests for Confidential Issues
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/58583) in GitLab 12.1.
+
+To help prevent confidential information being leaked from a public project
+in the process of resolving a confidential issue, confidential issues can be
+resolved by creating a merge request from a private fork.
+
+The merge request created will target the default branch of the private fork,
+not the default branch of the public upstream project. This prevents the merge
+request, branch, and commits entering the public repository, and revealing
+confidential information prematurely. When the confidential commits are ready
+to be made public, this can be done by opening a merge request from the private
+fork to the public upstream project.
+
+TIP: **Best practice:**
+If you create a long-lived private fork in the same group or in a sub-group of
+the original upstream, all the users with Developer membership to the public
+project will also have the same permissions in the private project. This way,
+all the Developers, who have access to view confidential issues, will have a
+streamlined workflow for fixing them.
+
+### How it works
+
+On a confidential issue, a **Create confidential merge request** button is
+available. Clicking on it will open a dropdown where you can choose to
+**Create confidential merge request and branch** or **Create branch**:
+
+| Create confidential merge request | Create branch |
+| :-------------------------------: | :-----------: |
+| ![Create Confidential Merge Request Dropdown](img/confidential_mr_dropdown_v12_1.png) | ![Create Confidential Branch Dropdown](img/confidential_mr_branch_dropdown_v12_1.png) |
+
+The **Project** dropdown includes the list of private forks the user is a member
+of as at least a Developer and merge requests are enabled.
+
+Whenever the **Branch name** and **Source (branch or tag)** fields change, the
+availability of the target or source branch will be checked. Both branches should
+be available in the private fork selected.
+
+By clicking the **Create confidential merge request** button, GitLab will create
+the branch and merge request in the private fork. When you choose
+**Create branch**, GitLab will only create the branch.
+
+Once the branch is created in the private fork, developers can now push code to
+that branch to fix the confidential issue.
diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md
index c2916c79876..8eec29716c1 100644
--- a/doc/user/project/issues/create_new_issue.md
+++ b/doc/user/project/issues/create_new_issue.md
@@ -1,104 +1,5 @@
-# Create a new Issue
+---
+redirect_to: 'managing_issues.md#create-a-new-issue'
+---
 
-Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
-
-When you create a new issue, you'll be prompted to fill in
-the information illustrated on the image below.
-
-![New issue from the issues list](img/new_issue.png)
-
-Read through the [issue data and actions documentation](issue_data_and_actions.md#parts-of-an-issue)
-to understand these fields one by one.
-
-## New issue from the Issue Tracker
-
-Navigate to your **Project's Dashboard** > **Issues** > **New Issue** to create a new issue:
-
-![New issue from the issue list view](img/new_issue_from_tracker_list.png)
-
-## New issue from an opened issue
-
-From an **opened issue** in your project, click **New Issue** to create a new
-issue in the same project:
-
-![New issue from an open issue](img/new_issue_from_open_issue.png)
-
-## New issue from the project's dashboard
-
-From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown
-menu with a few options. Select **New Issue** to create an issue in that project:
-
-![New issue from a project's dashboard](img/new_issue_from_projects_dashboard.png)
-
-## New issue from the Issue Board
-
-From an Issue Board, create a new issue by clicking on the plus sign (**+**) on the top of a list.
-It opens a new issue for that project labeled after its respective list.
-
-![From the issue board](img/new_issue_from_issue_board.png)
-
-## New issue via email
-
-At the bottom of a project's Issues List page, a link to **Email a new issue to this project**
-is displayed if your GitLab instance has [incoming email](../../../administration/incoming_email.md) configured.
-
-![Bottom of a project issues page](img/new_issue_from_email.png)
-
-When you click this link, an email address is displayed which belongs to you for creating issues in this project.
-You can save this address as a contact in your email client for easy acceess.
-
-CAUTION: **Caution:**
-This is a private email address, generated just for you. **Keep it to yourself**,
-as anyone who gets ahold of it can create issues or merge requests as if they
-were you. If the address is compromised, or you'd like it to be regenerated for
-any reason, click **Email a new issue to this project** again and click the reset link.
-
-Sending an email to this address will create a new issue on your behalf for
-this project, where:
-
-- The email subject becomes the issue title.
-- The email body becomes the issue description.
-- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported.
-
-NOTE: **Note:**
-In GitLab 11.7, we updated the format of the generated email address.
-However the older format is still supported, allowing existing aliases
-or contacts to continue working._
-
-## New issue via Service Desk **[PREMIUM]**
-
-Enable [Service Desk](../service_desk.md) to your project and offer email support.
-By doing so, when your customer sends a new email, a new issue can be created in
-the appropriate project and followed up from there.
-
-## New issue from the group-level Issue Tracker
-
-Head to the Group dashboard and click "Issues" in the sidebar to visit the Issue Tracker
-for all projects in your Group. Select the project you'd like to add an issue for
-using the dropdown button at the top-right of the page.
-
-![Select project to create issue](img/select_project_from_group_level_issue_tracker.png)
-
-We'll keep track of the project you selected most recently, and use it as the default
-for your next visit. This should save you a lot of time and clicks, if you mostly
-create issues for the same project.
-
-![Create issue from group-level issue tracker](img/create_issue_from_group_level_issue_tracker.png)
-
-## New issue via URL with prefilled fields
-
-You can link directly to the new issue page for a given project, with prefilled
-field values using query string parameters in a URL. This is useful for embedding
-a URL in an external HTML page, and also certain scenarios where you want the user to
-create an issue with certain fields prefilled.
-
-The title, description, and description template fields can be prefilled using
-this method. The description and description template fields cannot be pre-entered
-in the same URL (since a description template just populates the description field).
-
-Follow these examples to form your new issue URL with prefilled fields.
-
-- For a new issue in the GitLab Community Edition project with a pre-entered title
-  and a pre-entered description, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea`
-- For a new issue in the GitLab Community Edition project with a pre-entered title
-  and a pre-entered description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal`
+This document was moved to [another location](managing_issues.md#create-a-new-issue).
diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md
index ff5b1f2ce50..ec9eb7b62bb 100644
--- a/doc/user/project/issues/crosslinking_issues.md
+++ b/doc/user/project/issues/crosslinking_issues.md
@@ -25,9 +25,8 @@ git commit -m "this is my commit message. Related to https://gitlab.com/<usernam
 
 Of course, you can replace `gitlab.com` with the URL of your own GitLab instance.
 
-**Note:** Linking your first commit to your issue is going to be relevant
-for tracking your process far ahead with
-[GitLab Cycle Analytics](https://about.gitlab.com/features/cycle-analytics/)).
+NOTE: **Note:** Linking your first commit to your issue is going to be relevant
+for tracking your process with [GitLab Cycle Analytics](https://about.gitlab.com/features/cycle-analytics/).
 It will measure the time taken for planning the implementation of that issue,
 which is the time between creating an issue and making the first commit.
 
@@ -35,28 +34,24 @@ which is the time between creating an issue and making the first commit.
 
 Mentioning related issues in merge requests and other issues is useful
 for your team members and collaborators to know that there are opened
-issues around that same idea.
+issues regarding the same topic.
 
-You do that as explained above, when
-[mentioning an issue from a commit message](#from-commit-messages).
+You do that as explained above, when [mentioning an issue from a commit message](#from-commit-messages).
 
-When mentioning the issue "A" in issue "B", the issue "A" will also
-display a notification in its tracker. The same is valid for mentioning
-issues in merge requests.
+When mentioning issue `#111` in issue `#222`, issue `#111` will also display a notification
+in its tracker. That is, you only need to mention the relationship once for it to
+display in both issues. The same is valid when mentioning issues in [merge requests](#from-merge-requests).
 
 ![issue mentioned in issue](img/mention_in_issue.png)
 
 ## From Merge Requests
 
 Mentioning issues in merge request comments works exactly the same way as
-they do for [related issues](#from-related-issues). 
+they do for [related issues](#from-related-issues).
 
 When you mention an issue in a merge request description, it will simply
 [link the issue and merge request together](#from-related-issues). Additionally,
-you can also [set an issue to close as soon as the merge request is merged](closing_issues.md#via-merge-request).
+you can also [set an issue to close automatically](managing_issues.md#closing-issues-automatically)
+as soon as the merge request is merged.
 
 ![issue mentioned in MR](img/mention_in_merge_request.png)
-
-### Close an issue by merging a merge request
-
-To [close an issue when a merge request is merged](closing_issues.md#via-merge-request), use the [automatic issue closing pattern](automatic_issue_closing.md).
diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md
index 56b94585672..27ce3a814f9 100644
--- a/doc/user/project/issues/csv_export.md
+++ b/doc/user/project/issues/csv_export.md
@@ -1,4 +1,4 @@
-# Export Issues to CSV **[STARTER]**
+# Export Issues to CSV **(STARTER)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1126) in [GitLab Starter 9.0](https://about.gitlab.com/2017/03/22/gitlab-9-0-released/#export-issues-ees-eep).
 
@@ -48,7 +48,6 @@ Exported issues are always sorted by `Issue ID`.
 
 Data will be encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row will be the headers, which are listed in the following table along with a description of the values:
 
-
 | Column  | Description |
 |---------|-------------|
 | Issue ID | Issue `iid` |
@@ -71,7 +70,6 @@ Data will be encoded with a comma as the column delimiter, with `"` used to quot
 | Time Estimate | [Time estimate](../../../workflow/time_tracking.md#estimates) in seconds |
 | Time Spent | [Time spent](../../../workflow/time_tracking.md#time-spent) in seconds |
 
-
 ## Limitations
 
-As the issues will be sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 20MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately.
+As the issues will be sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 15MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately.
diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md
index b0b1cfcfdf7..cc0d5ac9028 100644
--- a/doc/user/project/issues/csv_import.md
+++ b/doc/user/project/issues/csv_import.md
@@ -7,7 +7,8 @@ Issues can be imported to a project by uploading a CSV file with the columns
 
 The user uploading the CSV file will be set as the author of the imported issues.
 
-> **Note:** A permission level of `Developer` or higher is required to import issues.
+NOTE: **Note:** A permission level of [Developer](../../permissions.md), or higher, is required
+to import issues.
 
 ## Prepare for the import
 
@@ -24,42 +25,26 @@ To import issues:
 1. Select the file and click the **Import issues** button.
 
 The file is processed in the background and a notification email is sent
-to you once the import is completed.
+to you once the import is complete.
 
 ## CSV file format
 
-### Header row
+When importing issues from a CSV file, it must be formatted in a certain way:
 
-CSV files must contain a header row where the first column header is `title` and the second is `description`.
-If additional columns are present, they will be ignored.
+- **header row:** CSV files must contain a header row where the first column header
+  is `title` and the second is `description`. If additional columns are present, they
+  will be ignored.
+- **separators:** The column separator is automatically detected from the header row.
+  Supported separator characters are: commas (`,`), semicolons (`;`), and tabs (`\t`).
+  The row separator can be either `CRLF` or `LF`.
+- **double-quote character:** The double-quote (`"`) character is used to quote fields,
+  enabling the use of the column separator within a field (see the third line in the
+  sample CSV data below). To insert a double-quote (`"`) within a quoted
+  field, use two double-quote characters in succession, i.e. `""`.
+- **data rows:** After the header row, succeeding rows must follow the same column
+  order. The issue title is required while the description is optional.
 
-### Column separator
-
-The column separator is automatically detected from the header row.
-
-Supported separator characters are: commas (`,`), semicolons (`;`), and tabs (`\t`).
-
-### Row separator
-
-Lines ending in either `CRLF` or `LF` are supported.
-
-### Quote character
-
-The double-quote (`"`) character is used to quote fields so you can use the column separator within a field. To insert
-a double-quote (`"`) within a quoted field, use two double-quote characters in succession, i.e. `""`.
-
-### Data rows
-
-After the header row, succeeding rows must follow the same column order. The issue title is required while the
-description is optional.
-
-### File size
-
-The limit depends on the configuration value of Max Attachment Size for the GitLab instance.
-
-For GitLab.com, it is set to 10 MB.
-
-## Sample data
+Sample CSV data:
 
 ```csv
 title,description
@@ -67,3 +52,9 @@ My Issue Title,My Issue Description
 Another Title,"A description, with a comma"
 "One More Title","One More Description"
 ```
+
+### File size
+
+The limit depends on the configuration value of Max Attachment Size for the GitLab instance.
+
+For GitLab.com, it is set to 10 MB.
diff --git a/doc/user/project/issues/deleting_issues.md b/doc/user/project/issues/deleting_issues.md
index 536a0de8974..e50259e0dcf 100644
--- a/doc/user/project/issues/deleting_issues.md
+++ b/doc/user/project/issues/deleting_issues.md
@@ -1,13 +1,5 @@
-# Deleting Issues
+---
+redirect_to: 'managing_issues.md#deleting-issues'
+---
 
-> [Introduced][ce-2982] in GitLab 8.6
-
-Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
-
-You can delete an issue by editing it and clicking on the delete button. 
-
-![delete issue - button](img/delete_issue.png)
-
->**Note:** Only [project owners](../../permissions.md) can delete issues.
-
-[ce-2982]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2982
\ No newline at end of file
+This document was moved to [another location](managing_issues.md#deleting-issues).
diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md
new file mode 100644
index 00000000000..1324a90e00b
--- /dev/null
+++ b/doc/user/project/issues/design_management.md
@@ -0,0 +1,79 @@
+# Design Management **(PREMIUM)**
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2.
+
+CAUTION: **Warning:**
+This an **alpha** feature and is subject to change at any time without
+prior notice.
+
+## Overview
+
+Design Management allows you to upload design assets (wireframes, mockups, etc.)
+to GitLab issues and keep them stored in one single place, accessed by the Design
+Management's page within an issue, giving product designers, product managers, and engineers a
+way to collaborate on designs over one single source of truth.
+
+You can easily share mock-ups of designs with your team, or visual regressions can be easily
+viewed and addressed.
+
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For an overview, see the video [Design Management (GitLab 12.2)](https://www.youtube.com/watch?v=CCMtCqdK_aM).
+
+## Requirements
+
+Design Management requires
+[Large File Storage (LFS)](../../../workflow/lfs/manage_large_binaries_with_git_lfs.md)
+to be enabled:
+
+- For GitLab.com, LFS is already enabled.
+- For self-managed instances, a GitLab administrator must have
+  [enabled LFS globally](../../../workflow/lfs/lfs_administration.md).
+- For both GitLab.com and self-managed instances: LFS must be enabled for the project itself.
+  If enabled globally, LFS will be enabled by default to all projects. To enable LFS on the
+  project level, navigate to your project's **Settings > General**, expand **Visibility, project features, permissions**
+  and enable **Git Large File Storage**.
+
+## Limitations
+
+- Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff` or `ico`.
+  The [`svg` extension is not yet supported](https://gitlab.com/gitlab-org/gitlab-ee/issues/12771).
+- Design uploads are limited to 10 files at a time.
+- [Designs cannot yet be deleted](https://gitlab.com/gitlab-org/gitlab-ee/issues/11089).
+- Design Management is
+  [not yet supported in the project export](https://gitlab.com/gitlab-org/gitlab-ee/issues/11090).
+- Design Management data
+  [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab-ee/issues/13429) yet.
+- Design Management data [won't be moved](https://gitlab.com/gitlab-org/gitlab-ee/issues/13426)
+  when an issue is moved, nor [deleted](https://gitlab.com/gitlab-org/gitlab-ee/issues/13427)
+  when an issue is deleted.
+- Design Management
+  [isn't supported by Geo](https://gitlab.com/groups/gitlab-org/-/epics/1633) yet.
+
+## The Design Management page
+
+Navigate to the **Design Management** page from any issue by clicking the **Designs** tab:
+
+![Designs tab](img/design_management_v12_2.png)
+
+## Adding designs
+
+To upload design images, click the **Upload Designs** button and select images to upload.
+
+Designs with the same filename as an existing uploaded design will create a new version
+of the design, and will replace the previous version.
+
+## Viewing designs
+
+Images on the Design Management page can be enlarged by clicking on them.
+
+## Adding annotations to designs
+
+When a design image is displayed, you can add annotations to it by clicking on
+the image. A badge is added to the image and a form is displayed to start a new
+discussion. For example:
+
+![Starting a new discussion on design](img/adding_note_to_design_1.png)
+
+When submitted, the form saves a badge linked to the discussion on the image. Different discussions have different badge numbers. For example:
+
+![Discussions on design annotations](img/adding_note_to_design_2.png)
diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md
index 987c16dfab6..bd3298497d2 100644
--- a/doc/user/project/issues/due_dates.md
+++ b/doc/user/project/issues/due_dates.md
@@ -4,30 +4,32 @@
 
 Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
 
-Due dates can be used in issues to keep track of deadlines and make sure
-features are shipped on time. Due dates require at least [Reporter permissions](../../permissions.md#project-members-permissions)
-to be able to edit them. On the contrary, they can be seen by everybody.
+Due dates can be used in issues to keep track of deadlines and make sure features are
+shipped on time. Users must have at least [Reporter permissions](../../permissions.md)
+to be able to edit them, but they can be seen by everybody with permission to view
+the issue.
 
 ## Setting a due date
 
-When creating or editing an issue, you can see the due date field from where
-a calendar will appear to help you choose the date you want. To remove it,
-select the date text and delete it.
+When creating or editing an issue, you can click in the **due date** field and a calendar
+will appear to help you choose the date you want. To remove the date, select the date
+text and delete it. The date is related to the server's timezone, not the timezone of
+the user setting the due date.
 
 ![Create a due date](img/due_dates_create.png)
 
-A quicker way to set a due date is via the issue sidebar. Simply expand the
-sidebar and select **Edit** to pick a due date or remove the existing one.
+You can also set a due date via the issue sidebar. Expand the
+sidebar and click **Edit** to pick a due date or remove the existing one.
 Changes are saved immediately.
 
 ![Edit a due date via the sidebar](img/due_dates_edit_sidebar.png)
 
 ## Making use of due dates
 
-Issues that have a due date can be distinctively seen in the issue tracker
+Issues that have a due date can be easily seen in the issue tracker,
 displaying a date next to them. Issues where the date is overdue will have
 the icon and the date colored red. You can sort issues by those that are
-_Due soon_ or _Due later_ from the dropdown menu in the right.
+`Due soon` or `Due later` from the dropdown menu on the right.
 
 ![Issues with due dates in the issues index page](img/due_dates_issues_index_page.png)
 
@@ -36,14 +38,13 @@ Due dates also appear in your [todos list](../../../workflow/todos.md).
 ![Issues with due dates in the todos](img/due_dates_todos.png)
 
 The day before an open issue is due, an email will be sent to all participants
-of the issue. Both the due date and the day before are calculated using the
+of the issue. Like the due date, the "day before the due date" is determined by the
 server's timezone.
 
 Issues with due dates can also be exported as an iCalendar feed. The URL of the
 feed can be added to calendar applications. The feed is accessible by clicking
-on the _Subscribe to calendar_ button on the following pages:
+on the **Subscribe to calendar** button on the following pages:
 
-- on the **Assigned Issues** page that is linked on the right-hand side of the
-  GitLab header
+- on the **Assigned Issues** page that is linked on the right-hand side of the GitLab header
 - on the **Project Issues** page
 - on the **Group Issues** page
diff --git a/doc/user/project/issues/img/adding_note_to_design_1.png b/doc/user/project/issues/img/adding_note_to_design_1.png
new file mode 100644
index 00000000000..aa50bbb69ce
--- /dev/null
+++ b/doc/user/project/issues/img/adding_note_to_design_1.png
diff --git a/doc/user/project/issues/img/adding_note_to_design_2.png b/doc/user/project/issues/img/adding_note_to_design_2.png
new file mode 100644
index 00000000000..37cefeb1a15
--- /dev/null
+++ b/doc/user/project/issues/img/adding_note_to_design_2.png
diff --git a/doc/user/project/issues/img/comment-or-discussion.png b/doc/user/project/issues/img/comment-or-discussion.png
index ccecc9fa39f..a29014c984c 100644
--- a/doc/user/project/issues/img/comment-or-discussion.png
+++ b/doc/user/project/issues/img/comment-or-discussion.png
diff --git a/doc/user/project/issues/img/confidential_mr_branch_dropdown_v12_1.png b/doc/user/project/issues/img/confidential_mr_branch_dropdown_v12_1.png
new file mode 100644
index 00000000000..1f4ad5c42bb
--- /dev/null
+++ b/doc/user/project/issues/img/confidential_mr_branch_dropdown_v12_1.png
diff --git a/doc/user/project/issues/img/confidential_mr_dropdown_v12_1.png b/doc/user/project/issues/img/confidential_mr_dropdown_v12_1.png
new file mode 100644
index 00000000000..7b7bd599a71
--- /dev/null
+++ b/doc/user/project/issues/img/confidential_mr_dropdown_v12_1.png
diff --git a/doc/user/project/issues/img/create_mr_from_issue.png b/doc/user/project/issues/img/create_mr_from_issue.png
index 680c42b5df0..d05a678cd17 100644
--- a/doc/user/project/issues/img/create_mr_from_issue.png
+++ b/doc/user/project/issues/img/create_mr_from_issue.png
diff --git a/doc/user/project/issues/img/design_management_v12_2.png b/doc/user/project/issues/img/design_management_v12_2.png
new file mode 100644
index 00000000000..ad803df4e63
--- /dev/null
+++ b/doc/user/project/issues/img/design_management_v12_2.png
diff --git a/doc/user/project/issues/img/issues_main_view_numbered.png b/doc/user/project/issues/img/issues_main_view_numbered.png
index 16cb6b497b0..92b9df44972 100644
--- a/doc/user/project/issues/img/issues_main_view_numbered.png
+++ b/doc/user/project/issues/img/issues_main_view_numbered.png
diff --git a/doc/user/project/issues/img/link_zoom_call_in_issue.png b/doc/user/project/issues/img/link_zoom_call_in_issue.png
new file mode 100644
index 00000000000..3153a0a9b07
--- /dev/null
+++ b/doc/user/project/issues/img/link_zoom_call_in_issue.png
diff --git a/doc/user/project/issues/img/reopen-issue.png b/doc/user/project/issues/img/reopen-issue.png
index 1749be31239..fc48742afe0 100644
--- a/doc/user/project/issues/img/reopen-issue.png
+++ b/doc/user/project/issues/img/reopen-issue.png
diff --git a/doc/user/project/issues/img/report-abuse.png b/doc/user/project/issues/img/report-abuse.png
index f189cbf1d36..f8cef22da03 100644
--- a/doc/user/project/issues/img/report-abuse.png
+++ b/doc/user/project/issues/img/report-abuse.png
diff --git a/doc/user/project/issues/img/show-all-activity.png b/doc/user/project/issues/img/show-all-activity.png
index c43ba75ce25..55c6f5ab5db 100644
--- a/doc/user/project/issues/img/show-all-activity.png
+++ b/doc/user/project/issues/img/show-all-activity.png
diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md
index 76dc6e49bce..bf04ed2d2d0 100644
--- a/doc/user/project/issues/index.md
+++ b/doc/user/project/issues/index.md
@@ -6,8 +6,9 @@ Issues are the fundamental medium for collaborating on ideas and planning work i
 
 The GitLab issue tracker is an advanced tool for collaboratively developing ideas, solving problems, and planning work.
 
-Issues can allow you, your team, and your collaborators to share and discuss proposals before and during their implementation.
-However, they can be used for a variety of other purposes, customized to your needs and workflow.
+Issues can allow you, your team, and your collaborators to share and discuss proposals
+before, and during, their implementation. However, they can be used for a variety of
+other purposes, customized to your needs and workflow.
 
 Issues are always associated with a specific project, but if you have multiple projects in a group,
 you can also view all the issues collectively at the group level.
@@ -17,13 +18,15 @@ you can also view all the issues collectively at the group level.
 - Discussing the implementation of a new idea
 - Tracking tasks and work status
 - Accepting feature proposals, questions, support requests, or bug reports
-- Elaborating new code implementations
+- Elaborating on new code implementations
 
-See also the blog post "[Always start a discussion with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/)".
+See also [Always start a discussion with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/).
 
 ## Parts of an issue
 
-Issues contain a variety of content and metadata, enabling a large range of flexibility in how they are used. Each issue can contain the following attributes, though some items may remain unset.
+Issues contain a variety of content and metadata, enabling a large range of flexibility
+in how they are used. Each issue can contain the following attributes, though not all items
+must be set.
 
 <table class="borderless-table fixed-table">
 <tr>
@@ -70,68 +73,99 @@ Issues contain a variety of content and metadata, enabling a large range of flex
 
 ## Viewing and managing issues
 
-While you can view and manage the full detail of an issue at its URL, you can also work with multiple issues at a time using the Issues List, Issue Boards, Epics **[ULTIMATE]**, and issue references.
+While you can view and manage the full details of an issue on the [issue page](#issue-page),
+you can also work with multiple issues at a time using the [Issues List](#issues-list),
+[Issue Boards](#issue-boards), Issue references, and [Epics](#epics-ultimate)**(ULTIMATE)**.
+
+Key actions for Issues include:
+
+- [Creating issues](managing_issues.md#create-a-new-issue)
+- [Moving issues](managing_issues.md#moving-issues)
+- [Closing issues](managing_issues.md#closing-issues)
+- [Deleting issues](managing_issues.md#deleting-issues)
 
 ### Issue page
 
 ![Issue view](img/issues_main_view.png)
 
-On an issue’s page, you can view all aspects of the issue, and you can also modify them if you you have the necessary [permissions](../../permissions.md).
-
-For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page.
+On an issue's page, you can view [all aspects of the issue](issue_data_and_actions.md),
+and modify them if you have the necessary [permissions](../../permissions.md).
 
 ### Issues list
 
 ![Project issues list view](img/project_issues_list_view.png)
 
-On the Issues List, you can view all issues in the current project, or from multiple projects when opening the Issues List from the higher-level group context. Filter the issue list by [any search query](../../search/index.md#issues-and-merge-requests-per-project) and/or specific metadata, such as label(s), assignees(s), status, and more. From this view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues.
+On the Issues List, you can view all issues in the current project, or from multiple
+projects when opening the Issues List from the higher-level group context. Filter the
+issue list with a [search query](../../search/index.md#issues-and-merge-requests-per-project),
+including specific metadata, such as label(s), assignees(s), status, and more. From this
+view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues.
 
-For more information on interacting with Issues, see the [Issue Data and Actions](issue_data_and_actions.md) page.
+For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page
+for a rundown of all the fields and information in an issue.
 
-For sorting by issue priority, see [Label Priority](../labels.md#label-priority).
+You can sort a list of issues several ways, including by issue creation date, milestone due date,
+etc. For more information, see the [Sorting and Ordering Issue Lists](sorting_issue_lists.md) page.
 
 ### Issue boards
 
 ![Issue board](img/issue_board.png)
 
-Issue boards are Kanban boards with columns that display issues based on their labels or their assignees**[PREMIUM]**. They offer the flexibility to manage issues using highly customizable workflows.
-
-You can reorder issues within a column, or drag an issue card to another column; its associated label or assignee will change to match that of the new column. The entire board can also be filtered to only include issues from a certain milestone or an overarching label.
+[Issue boards](../issue_board.md) are Kanban boards with columns that display issues based on their labels
+or their assignees**(PREMIUM)**. They offer the flexibility to manage issues using
+highly customizable workflows.
 
-For more information, see the [Issue Boards](../issue_board.md) page.
+You can reorder issues within a column. If you drag an issue card to another column, its
+associated label or assignee will change to match that of the new column. The entire
+board can also be filtered to only include issues from a certain milestone or an overarching
+label.
 
-### Epics **[ULTIMATE]**
+### Design Management **(PREMIUM)**
 
-Epics let you manage your portfolio of projects more efficiently and with less effort by tracking groups of issues that share a theme, across projects and milestones.
+With [Design Management](design_management.md), you can upload design
+assets to issues and view them all together to easily share and
+collaborate with your team.
 
-For more information, see the [Epics](../../group/epics/index.md) page.
+### Epics **(ULTIMATE)**
 
-### Related issues **[STARTER]**
+[Epics](../../group/epics/index.md) let you manage your portfolio of projects more
+efficiently and with less effort by tracking groups of issues that share a theme, across
+projects and milestones.
 
-You can mark two issues as related, so that when viewing each one, the other is always listed in its Related Issues section. This can help display important context, such as past work, dependencies, or duplicates.
+### Related issues **(STARTER)**
 
-For more information, see [Related Issues](related_issues.md).
+You can mark two issues as related, so that when viewing one, the other is always
+listed in its [Related Issues](related_issues.md) section. This can help display important
+context, such as past work, dependencies, or duplicates.
 
 ### Crosslinking issues
 
-When you reference an issue from another issue or merge request by including its URL or ID, the referenced issue displays a message in the Activity stream about the reference, with a link to the other issue or MR.
+You can [crosslink issues](crosslinking_issues.md) by referencing an issue from another
+issue or merge request by including its URL or ID. The referenced issue displays a
+message in the Activity stream about the reference, with a link to the other issue or MR.
 
-For more information, see [Crosslinking issues](crosslinking_issues.md).
+### Similar issues
 
-## Issue actions
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22866) in GitLab 11.6.
 
-- [Create an issue](create_new_issue.md)
-- [Create an issue from a template](../../project/description_templates.md#using-the-templates)
-- [Close an issue](closing_issues.md)
-- [Move an issue](moving_issues.md)
-- [Delete an issue](deleting_issues.md)
-- [Create a merge request from an issue](issue_data_and_actions.md#22-create-merge-request)
+To prevent duplication of issues for the same topic, GitLab searches for similar issues
+when new issues are being created.
+
+When typing in the title in the **New Issue** page, GitLab searches titles and descriptions
+across all issues the user has access to in the current project. Up 5 similar issues,
+sorted by most recently updated, are displayed below the title box. Note that this feature
+requires [GraphQL](../../../api/graphql/index.md) to be enabled.
 
-## Advanced issue management
+![Similar issues](img/similar_issues.png)
 
-- [Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues in order to change their status, assignee, milestone, or labels in bulk.
+## Other Issue actions
+
+- [Create an issue from a template](../../project/description_templates.md#using-the-templates)
+- [Set a due date](due_dates.md)
+- [Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues
+  in order to change their status, assignee, milestone, or labels in bulk.
 - [Import issues](csv_import.md)
-- [Export issues](csv_export.md) **[STARTER]**
+- [Export issues](csv_export.md) **(STARTER)**
 - [Issues API](../../../api/issues.md)
-- Configure an [external issue tracker](../../../integration/external-issue-tracker.md) such as Jira, Redmine,
-or Bugzilla.
+- Configure an [external issue tracker](../../../integration/external-issue-tracker.md)
+  such as Jira, Redmine, or Bugzilla.
diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md
index da585022263..d7d168710ef 100644
--- a/doc/user/project/issues/issue_data_and_actions.md
+++ b/doc/user/project/issues/issue_data_and_actions.md
@@ -39,16 +39,24 @@ after it is closed.
 
 ![Report Abuse](img/report-abuse.png)
 
-#### 2. Todos
+#### 2. To Do
 
-You can click **add todo** to add the issue to your [GitLab Todo](../../../workflow/todos.md)
-list. If it is already on your todo list, the buttom will show **mark todo as done**,
-which you can click to mark that issue as done (which will be reflected in the Todo list).
+You can add issues to and remove issues from your [GitLab To-Do List](../../../workflow/todos.md).
+
+The button to do this has a different label depending on whether the issue is already on your To-Do List or not. If the issue is:
+
+- Already on your To-Do List: The button is labeled **Mark as done**. Click the button to remove the issue from your To-Do List.
+- Not on your To-Do List: The button is labelled **Add a To Do**. Click the button to add the issue to your To-Do List.
 
 #### 3. Assignee
 
-An issue can be assigned to yourself, another person, or [many people](#31-multiple-assignees-STARTER).
-The assignee(s) can be changed as much as needed. The idea is that the assignees are
+An issue can be assigned to:
+
+- Yourself.
+- Another person.
+- [Many people](#31-multiple-assignees-STARTER). **(STARTER)**
+
+The assignee(s) can be changed as often as needed. The idea is that the assignees are
 responsible for that issue until it's reassigned to someone else to take it from there.
 When assigned to someone, it will appear in their assigned issues list.
 
@@ -56,7 +64,7 @@ TIP: **Tip:**
 If a user is not member of that project, it can only be
 assigned to them if they created the issue themselves.
 
-##### 3.1. Multiple Assignees **[STARTER]**
+##### 3.1. Multiple Assignees **(STARTER)**
 
 Often multiple people work on the same issue together, which can be especially difficult
 to track in large teams where there is shared ownership of an issue.
@@ -64,7 +72,7 @@ to track in large teams where there is shared ownership of an issue.
 In [GitLab Starter](https://about.gitlab.com/pricing/), you can
 [assign multiple people](multiple_assignees_for_issues.md) to an issue.
 
-#### 4. Epic **[ULTIMATE]**
+#### 4. Epic **(ULTIMATE)**
 
 You can assign issues to an [Epic](../../group/epics/index.md), which allows better
 management of groups of related issues.
@@ -99,7 +107,7 @@ TIP: **Tip:**
 If a label doesn't exist yet, you can click **Edit**, and it opens a dropdown menu
 from which you can select **Create new label**.
 
-#### 9. Weight **[STARTER]**
+#### 9. Weight **(STARTER)**
 
 [Assign a weight](../../../workflow/issue_weight.md) to an issue.
 Larger values are used to indicate more effort is required to complete the issue. Only
@@ -113,13 +121,13 @@ issue boards or the issue list.
 
 #### 11. Lock issue
 
-You can [lock the discussions](../../discussions/index.md#lock-discussions) in the issue,
+You can [lock the threads](../../discussions/index.md#lock-discussions) in the issue,
 to prevent further comments from being added.
 
 #### 12. Participants
 
-All the users involved in that issue. Either they participated in the [discussion](../../discussions/index.md),
-or were mentioned in the description or discussions.
+All the users involved in that issue. Either they participated in the [thread](../../discussions/index.md),
+or were mentioned in the description or threads.
 
 #### 13. Notifications
 
@@ -149,6 +157,19 @@ The plain text title and description of the issue fill the top center of the iss
 The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm),
 allowing many formatting options.
 
+##### Zoom call links
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/62966) in GitLab 12.0.
+
+Including a link to a [Zoom](https://zoom.us) call in the description of an issue
+results in a **Join Zoom meeting** button at the top of the issue, just under the header.
+
+For example:
+
+![Link Zoom Call in Issue](img/link_zoom_call_in_issue.png)
+
+To remove the button, edit the description and remove the Zoom call link.
+
 #### 17. Mentions
 
 You can mention a user or a group present in your GitLab instance with `@username` or
@@ -164,15 +185,15 @@ TIP: **Tip:**
 Avoid mentioning `@all` in issues and merge requests, as it sends an email notification
 to all the members of that project's group, which can be interpreted as spam.
 
-#### 18. Related Issues **[STARTER]**
+#### 18. Related Issues **(STARTER)**
 
 Issues that were mentioned as [related issues](related_issues.md) are listed here.
 You can also click the `+` to add more related issues.
 
 #### 19. Related Merge Requests
 
-Merge requests that were mentioned in that issue's description or in the issue discussion
-thread are listed as [related merge requests](crosslinking_issues.md#from-merge-requests) here.
+Merge requests that were mentioned in that issue's description or in the issue thread 
+are listed as [related merge requests](crosslinking_issues.md#from-merge-requests) here.
 Also, if the current issue was mentioned as related in another merge request, that
 merge request will be listed here.
 
@@ -184,14 +205,22 @@ dropdown list of available [GitLab Flavored Markdown Emoji](../../markdown.md#em
 
 TIP: **Tip:**
 Posting "+1" as a comment in a thread spams all subscribed participants of that issue,
-clutters the discussion threads, and is not recommended. Awarding an emoji is a way
+clutters the threads, and is not recommended. Awarding an emoji is a way
 to let them know your reaction without spamming them.
 
 #### 21. Show all activity
 
 You can filter what is displayed in the issue history by clicking on **Show all activity**
-and selecting either **Show comments only**, which only shows discussions and hides
-updates to the issue, or **Show history only**, which hides discussions and only shows updates.
+and selecting either **Show comments only**, which only shows threads and hides
+updates to the issue, or **Show history only**, which hides threads and only shows updates.
+
+- You can mention a user or a group present in your GitLab instance with
+  `@username` or `@groupname` and they will be notified via To-Do items
+  and email, unless they have [disabled all notifications](#13-notifications)
+  in their profile settings.
+- Mentions for yourself (the current logged in user), will be highlighted
+  in a different color, allowing you to easily see which comments involve you,
+  helping you focus on them quickly.
 
 ![Show all activity](img/show-all-activity.png)
 
@@ -218,15 +247,15 @@ filtered, as shown above.
 Collaborate in the issue by posting comments in its thread. This text field also fully
 supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm).
 
-#### 25. Submit Comment, start a discussion, or comment and close
+#### 25. Submit Comment, start a thread, or comment and close
 
 Once you write a comment, you can:
 
 - Click **Comment** and your comment will be published.
-- Choose **Start discussion** from the dropdown list and start a new [discussion thread](../../discussions/index.md#threaded-discussions)
+- Choose **Start thread** from the dropdown list and start a new [thread](../../discussions/index.md#threaded-discussions)
   within that issue's main thread to discuss specific points. This invites other participants
-  to reply directly to your discussion, keeping related comments grouped together.
+  to reply directly to your thread, keeping related comments grouped together.
 
-![Comment or discussion](img/comment-or-discussion.png)
+![Comment or thread](img/comment-or-discussion.png)
 
 You can also close the issue from here, so you don't need to scroll to the top of the issue page.
diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md
new file mode 100644
index 00000000000..e9b4e591384
--- /dev/null
+++ b/doc/user/project/issues/managing_issues.md
@@ -0,0 +1,227 @@
+# Managing Issues
+
+[GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and
+planning work in GitLab. [Creating](#create-a-new-issue), [moving](#moving-issues),
+[closing](#closing-issues), and [deleting](#deleting-issues) are key actions that
+you can do with issues.
+
+## Create a new Issue
+
+When you create a new issue, you'll be prompted to fill in the [data and fields of the issue](issue_data_and_actions.md#parts-of-an-issue), as illustrated below. If you know
+the values you want to assign to an issue, you can use the [Quick actions](../quick_actions.md)
+feature to input values, instead of selecting them from lists.
+
+![New issue from the issues list](img/new_issue.png)
+
+### Accessing the new Issue form
+
+There are many ways to get to the new Issue form from within a project:
+
+- Navigate to your **Project's Dashboard** > **Issues** > **New Issue**:
+
+  ![New issue from the issue list view](img/new_issue_from_tracker_list.png)
+
+- From an **opened issue** in your project, click **New Issue** to create a new
+  issue in the same project:
+
+  ![New issue from an open issue](img/new_issue_from_open_issue.png)
+
+- From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown
+  menu with a few options. Select **New Issue** to create an issue in that project:
+
+  ![New issue from a project's dashboard](img/new_issue_from_projects_dashboard.png)
+
+- From an **Issue Board**, create a new issue by clicking on the plus sign (**+**) at the top of a list.
+  It opens a new issue for that project, pre-labeled with its respective list.
+
+  ![From the issue board](img/new_issue_from_issue_board.png)
+
+### New issue from the group-level Issue Tracker
+
+Go to the Group dashboard and click "Issues" in the sidebar to visit the Issue Tracker
+for all projects in your Group. Select the project you'd like to add an issue for
+using the dropdown button at the top-right of the page.
+
+![Select project to create issue](img/select_project_from_group_level_issue_tracker.png)
+
+We'll keep track of the project you selected most recently, and use it as the default
+for your next visit. This should save you a lot of time and clicks, if you mostly
+create issues for the same project.
+
+![Create issue from group-level issue tracker](img/create_issue_from_group_level_issue_tracker.png)
+
+### New issue via Service Desk **(PREMIUM)**
+
+Enable [Service Desk](../service_desk.md) for your project and offer email support.
+By doing so, when your customer sends a new email, a new issue can be created in
+the appropriate project and followed up from there.
+
+### New issue via email
+
+A link to **Email a new issue to this project** is displayed at the bottom of a project's
+**Issues List** page, if your GitLab instance has [incoming email](../../../administration/incoming_email.md)
+configured.
+
+![Bottom of a project issues page](img/new_issue_from_email.png)
+
+When you click this link, an email address is generated and displayed, which should be used
+by **you only**, to create issues in this project. You can save this address as a
+contact in your email client for easy acceess.
+
+CAUTION: **Caution:**
+This is a private email address, generated just for you. **Keep it to yourself**,
+as anyone who knows it can create issues or merge requests as if they
+were you. If the address is compromised, or you'd like it to be regenerated for
+any reason, click **Email a new issue to this project** again and click the reset link.
+
+Sending an email to this address will create a new issue in your name for
+this project, where:
+
+- The email subject becomes the issue title.
+- The email body becomes the issue description.
+- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported.
+
+NOTE: **Note:**
+In GitLab 11.7, we updated the format of the generated email address. However the
+older format is still supported, allowing existing aliases or contacts to continue working.
+
+### New issue via URL with prefilled fields
+
+You can link directly to the new issue page for a given project, with prefilled
+field values using query string parameters in a URL. This is useful for embedding
+a URL in an external HTML page, and also certain scenarios where you want the user to
+create an issue with certain fields prefilled.
+
+The title, description, and description template fields can be prefilled using
+this method. You cannot pre-fill both the description and description template fields
+in the same URL (since a description template also populates the description field).
+
+Follow these examples to form your new issue URL with prefilled fields.
+
+- For a new issue in the GitLab Community Edition project with a pre-filled title
+  and a pre-filled description, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea`
+- For a new issue in the GitLab Community Edition project with a pre-filled title
+  and a pre-filled description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal`
+
+## Moving Issues
+
+Moving an issue will copy it to a new location (project), and close it in the old project,
+but it will not be deleted. There will also be a system note added to both issues
+indicating where it came from and went to.
+
+The "Move issue" button is at the bottom of the right-sidebar when viewing the issue.
+
+![move issue - button](img/sidebar_move_issue.png)
+
+### Moving Issues in Bulk
+
+If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**.
+
+To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below script. Please be sure to change **project**, **admin_user** and **target_project** to your values. We do also recommend [creating a backup](../../../raketasks/backup_restore.md#creating-a-backup-of-the-gitlab-system) before attempting any changes in the console.
+
+```ruby
+project = Project.find_by_full_path('full path of the project where issues are moved from')
+issues = project.issues
+admin_user = User.find_by_username('username of admin user') # make sure user has permissions to move the issues
+target_project = Project.find_by_full_path('full path of target project where issues moved to')
+
+issues.each do |issue|
+   if issue.state != "closed" && issue.moved_to.nil?
+      Issues::MoveService.new(project, admin_user).execute(issue, target_project)
+   else
+      puts "issue with id: #{issue.id} and title: #{issue.title} was not moved"
+   end
+end; nil
+```
+
+## Closing Issues
+
+When you decide that an issue is resolved, or no longer needed, you can close the issue
+using the close button:
+
+![close issue - button](img/button_close_issue.png)
+
+You can also close an issue from the [Issue Boards](../issue_board.md) by dragging an issue card
+from its list and dropping it into the **Closed** list.
+
+![close issue from the Issue Board](img/close_issue_from_board.gif)
+
+### Closing issues automatically
+
+NOTE: **Note:**
+For performance reasons, automatic issue closing is disabled for the very first
+push from an existing repository.
+
+When a commit or merge request resolves one or more issues, it is possible to have
+these issues closed automatically when the commit or merge request reaches the project's
+default branch.
+
+If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern),
+all issues referenced in the matched text will be closed. This happens when the commit
+is pushed to a project's [**default** branch](../repository/branches/index.md#default-branch),
+or when a commit or merge request is merged into it.
+
+For example, if `Closes #4, #6, Related to #5` is included in a Merge Request
+description, issues `#4` and `#6` will close automatically when the MR is merged, but not `#5`.
+Using `Related to` flags `#5` as a [related issue](related_issues.md),
+but it will not close automatically.
+
+![merge request closing issue when merged](img/merge_request_closes_issue.png)
+
+If the issue is in a different repository than the MR, add the full URL for the issue(s):
+
+```md
+Closes #4, #6, and https://gitlab.com/<username>/<projectname>/issues/<xxx>
+```
+
+#### Default closing pattern
+
+When not specified, the default issue closing pattern as shown below will be used:
+
+```bash
+((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?|[Rr]esolv(?:e[sd]?|ing)|[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?)|([A-Z][A-Z0-9_]+-\d+))+)
+```
+
+This translates to the following keywords:
+
+- Close, Closes, Closed, Closing, close, closes, closed, closing
+- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing
+- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving
+- Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing
+
+Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's
+source code that can match references to:
+
+- A local issue (`#123`).
+- A cross-project issue (`group/project#123`).
+- A link to an issue (`https://gitlab.example.com/group/project/issues/123`).
+
+For example the following commit message:
+
+```
+Awesome commit message
+
+Fix #20, Fixes #21 and Closes group/otherproject#22.
+This commit is also related to #17 and fixes #18, #19
+and https://gitlab.example.com/group/otherproject/issues/23.
+```
+
+will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to,
+as well as `#22` and `#23` in group/otherproject. `#17` won't be closed as it does
+not match the pattern. It works with multi-line commit messages as well as one-liners
+when used from the command line with `git commit -m`.
+
+#### Customizing the issue closing pattern **(CORE ONLY)**
+
+In order to change the default issue closing pattern, GitLab administrators must edit the
+[`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md)
+of your installation.
+
+## Deleting Issues
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2982) in GitLab 8.6
+
+Users with [project owner permission](../../permissions.md) can delete an issue by
+editing it and clicking on the delete button.
+
+![delete issue - button](img/delete_issue.png)
diff --git a/doc/user/project/issues/moving_issues.md b/doc/user/project/issues/moving_issues.md
index 8aac2c01444..8331f865b83 100644
--- a/doc/user/project/issues/moving_issues.md
+++ b/doc/user/project/issues/moving_issues.md
@@ -1,35 +1,5 @@
-# Moving Issues
-
-Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
-
-Moving an issue will close it and duplicate it on the specified project.
-There will also be a system note added to both issues indicating where it came from or went to.
-
-You can move an issue with the "Move issue" button at the bottom of the right-sidebar when viewing the issue.
-
-![move issue - button](img/sidebar_move_issue.png)
-
-## Troubleshooting
-
-### Moving Issues in Bulk
-
-If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**.
-
-To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below script. Please be sure to change **project**, **admin_user** and **target_project** to your values. We do also recommend [creating a backup](https://docs.gitlab.com/ee/raketasks/backup_restore.html#creating-a-backup-of-the-gitlab-system) before attempting any changes in the console.
-
-```ruby
-project = Project.find_by_full_path('full path of the project where issues are moved from')
-issues = project.issues
-admin_user = User.find_by_username('username of admin user') # make sure user has permissions to move the issues
-target_project = Project.find_by_full_path('full path of target project where issues moved to')
-
-issues.each do |issue|
-   if issue.state != "closed" && issue.moved_to.nil?
-      Issues::MoveService.new(project, admin_user).execute(issue, target_project)
-   else
-      puts "issue with id: #{issue.id} and title: #{issue.title} was not moved"
-   end
-end; nil
-
-```
+---
+redirect_to: 'managing_issues.md#moving-issues'
+---
 
+This document was moved to [another location](managing_issues.md#moving-issues).
diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md
index d1db0790d69..c9efe9f5031 100644
--- a/doc/user/project/issues/multiple_assignees_for_issues.md
+++ b/doc/user/project/issues/multiple_assignees_for_issues.md
@@ -1,4 +1,4 @@
-# Multiple Assignees for Issues **[STARTER]**
+# Multiple Assignees for Issues **(STARTER)**
 
 > **Note:**
 [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1904)
diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md
index e679ebf86e6..d7178506b64 100644
--- a/doc/user/project/issues/related_issues.md
+++ b/doc/user/project/issues/related_issues.md
@@ -1,4 +1,4 @@
-# Related issues **[STARTER]**
+# Related issues **(STARTER)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1797) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.4.
 
@@ -19,7 +19,7 @@ Issues from a different project require additional information like the
 group and the project name. For example:
 
 - same project: `#44`
-- same group: `project#44 `
+- same group: `project#44`
 - different group: `group/project#44`
 
 Valid references will be added to a temporary list that you can review.
diff --git a/doc/user/project/issues/similar_issues.md b/doc/user/project/issues/similar_issues.md
index e90ecd88ec6..9cbac53ee41 100644
--- a/doc/user/project/issues/similar_issues.md
+++ b/doc/user/project/issues/similar_issues.md
@@ -1,16 +1,5 @@
-# Similar issues
+---
+redirect_to: 'index.md#similar-issues'
+---
 
-> [Introduced][ce-22866] in GitLab 11.6.
-
-Similar issues suggests issues that are similar when new issues are being created.
-This features requires [GraphQL] to be enabled.
-
-![Similar issues](img/similar_issues.png)
-
-You can see the similar issues when typing in the title in the new issue form.
-This searches both titles and descriptions across all issues the user has access
-to in the current project. It then displays the first 5 issues sorted by most
-recently updated.
-
-[GraphQL]: ../../../api/graphql/index.md
-[ce-22866]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22866
+This document was moved to [another location](index.md#similar-issues).
diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md
new file mode 100644
index 00000000000..0fe86e6f410
--- /dev/null
+++ b/doc/user/project/issues/sorting_issue_lists.md
@@ -0,0 +1,30 @@
+# Sorting and Ordering Issue Lists
+
+You can sort a list of issues several ways, including by issue creation date, milestone due date,
+etc. The available sorting options can change based on the context of the list.
+For sorting by issue priority, see [Label Priority](../labels.md#label-priority).
+
+In group and project issue lists, it is also possible to order issues manually,
+similar to [issue boards](../issue_board.md#issue-ordering-in-a-list).
+
+## Manual sorting
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/62178) in GitLab 12.2.
+
+When you select **Manual** sorting, you can change
+the order by dragging and dropping the issues. The changed order will persist. Everyone who visits the same list will see the reordered list, with some exceptions.
+
+Each issue is assigned a relative order value, representing its relative
+order with respect to the other issues in the list. When you drag-and-drop reorder 
+an issue, its relative order value changes accordingly.
+
+In addition, any time that issue appears in a manually sorted list,
+the updated relative order value will be used for the ordering.  This means that
+if issue `A` is drag-and-drop reordered to be above issue `B` by any user in
+a given list inside your GitLab instance, any time those two issues are subsequently
+loaded in any list in the same instance (could be a different project issue list or a 
+different group issue list, for example), that ordering will be maintained.
+
+This ordering also affects [issue boards](../issue_board.md#issue-ordering-in-a-list).
+Changing the order in an issue list changes the ordering in an issue board,
+and vice versa.
diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md
index 3eca1313a18..cc1274faa2c 100644
--- a/doc/user/project/labels.md
+++ b/doc/user/project/labels.md
@@ -2,43 +2,52 @@
 
 ## Overview
 
-Labels allow you to categorize issues or merge requests using descriptive titles like `bug`, `feature request`, or `docs`. Each label also has a customizable color. They allow you to quickly and dynamically filter and manage issues or merge requests you care about, and are visible throughout GitLab in most places where issues and merge requests are located.
+Labels allow you to categorize issues or merge requests using descriptive titles like
+`bug`, `feature request`, or `docs`. Each label also has a customizable color. They
+allow you to quickly and dynamically filter and manage issues or merge requests you
+care about, and are visible throughout GitLab in most places where issues and merge
+requests are located.
 
 ## Project labels and group labels
 
 In GitLab, you can create project and group labels:
 
 - **Project labels** can be assigned to issues or merge requests in that project only.
-- **Group labels** can be assigned to any issue or merge request of any project in that group or any subgroups of the group.
+- **Group labels** can be assigned to any issue or merge request in any project in
+  that group, or any subgroups of the group.
 
-## Scoped labels **[PREMIUM]**
+## Scoped labels **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9175) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
 
-Scoped labels allow teams to use the simple and familiar feature of labels to
+Scoped labels allow teams to use the simple and familiar label feature to
 annotate their issues, merge requests, and epics to achieve custom fields and
 custom workflow states by leveraging a special label title syntax.
 
-A scoped label is a kind of label defined only by a special double-colon syntax
+A scoped label is a kind of label defined by a special double-colon syntax
 in the label’s title, using the format `key::value`. For example:
 
-![A sample scoped label](img/key_value_labels.png)
+![A sample scoped label](img/labels_key_value_v12_1.png)
 
 An issue, epic, or merge request cannot have two scoped labels with the same key.
-For example, if an issue is already labeled `priority::3` and you apply the label `priority::2` to it,
-`priority::3` is automatically removed.
+For example, if an issue is already labeled `priority::3`, and then you apply the
+`priority::2` label to it, `priority::3` is automatically removed.
 
 This functionality is demonstrated in a video titled [Use scoped labels in GitLab 11.10 for custom fields and custom workflows](https://www.youtube.com/watch?v=4BCBby6du3c).
 
 ### Labels with multiple colon pairs
 
-If labels have multiple instances of `::`, the longest path from left to right, until the last `::`, is considered the "key" or the "scope".
+If labels have multiple instances of `::`, the longest path from left to right, until
+the last `::`, is considered the "key" or the "scope".
 
-For example, `nested::key1::value1` and `nested::key1::value2` cannot both exist on the same issue. Adding the latter label will automatically remove the former due to the shared scope of `nested::key1`.
+For example, `nested::key1::value1` and `nested::key1::value2` cannot both exist on
+the same issue. Adding the latter label will automatically remove the former due to
+the shared scope of `nested::key1`.
 
-`nested::key1::value1` and `nested::key2::value1` can both exist on the same issue, as these are considered to use two different label scopes, `nested::key1` and `nested::key2`.
+`nested::key1::value1` and `nested::key2::value1` can both exist on the same issue,
+as these are considered to use two different label scopes, `nested::key1` and `nested::key2`.
 
-### Workflows with scoped labels **[PREMIUM]**
+### Workflows with scoped labels
 
 Suppose you wanted a custom field in issues to track the platform operating system
 that your features target, where each issue should only target one platform. You
@@ -58,101 +67,156 @@ be able to advance workflow states consistently in issues themselves.
 
 ## Creating labels
 
->**Note:**
+NOTE: **Note:**
 A permission level of Reporter or higher is required to create labels.
 
 ### New project label
 
 To create a **project label**, navigate to **Issues > Labels** in the project.
-This page only shows project labels in this project and group labels of this project's parent group.
+This page only shows the project labels in this project, and the group labels of the
+project's parent group.
 
-Click the **New label** button. Enter the title, an optional description, and the background color. Click **Create label** to create the label.
+Click the **New label** button. Enter the title, an optional description, and the
+background color. Click **Create label** to create the label.
 
-If a project has no labels, you can generate a default set of project labels from its empty label list page:
+If a project has no labels, you can generate a default set of project labels from
+its empty label list page:
 
-![Labels generate default](img/labels_generate_default.png)
+![Labels generate default](img/labels_generate_default_v12_1.png)
 
 GitLab will add the following default labels to the project:
 
-![Labels default](img/labels_default.png)
+![Labels default](img/labels_default_v12_1.png)
 
 ### New group label
 
-To create a **group label**, follow similar steps from above to project labels. Navigate to **Issues > Labels** in the group and create it from there.
-This page only shows group labels in this group.
-Alternatively, you can create group labels also from Epic sidebar. Please note that the created label will belong to the immediate group to which epic belongs.
+To create a **group label**, navigate to **Issues > Labels** in the **group** and create
+it from there. This page only shows group labels in this group.
+
+Alternatively, you can create group labels from the Epic sidebar. **(ULTIMATE)**
 
-![Create Labels from Epic](img/labels_epic_sidebar.png)
+Please note that the created label will belong to the immediate group to which the
+epic belongs.
+
+![Create Labels from Epic](img/labels_epic_sidebar_v12_1.png)
 
 Group labels appear in every label list page of the group's child projects.
 
-![Labels list](img/labels_list.png)
+![Labels list](img/labels_list_v12_1.png)
 
 ### New project label from sidebar
 
-From the sidebar of an issue or a merge request, you can create a new **project label** inline immediately, instead of navigating to the project label list page.
+From the sidebar of an issue or a merge request, you can create a new **project label**
+inline immediately, instead of navigating to the project label list page.
 
-![Labels inline](img/new_label_from_sidebar.gif)
+![Labels inline](img/labels_new_label_from_sidebar.gif)
 
 ## Editing labels
 
 NOTE: **Note:**
 A permission level of Reporter or higher is required to edit labels.
 
-You can update a label by navigating to **Issues > Labels** in the project or group and clicking the pencil icon.
+To update a label, navigate to **Issues > Labels** in the project or group
+and click the pencil icon. The title, description and color can be changed.
+
+To delete a label, click the three dots next to the `Subscribe` button, and select
+**Delete**.
 
-You can delete a label by clicking the trash icon.
+![Delete label](img/labels_delete_v12_1.png)
 
 ### Promoting project labels to group labels
 
-If you are expanding from a few projects to a larger number of projects within the same group, you may want to share the same label among multiple projects in the same group. If you previously created a project label and now want to make it available for other projects, you can promote it to a group label.
+If you are expanding from a few projects to a larger number of projects within the
+same group, you may want to share the same label among multiple projects in the same
+group. If you previously created a project label and now want to make it available
+for other projects, you can promote it to a group label.
 
-From the project label list page, you can promote a project label to a group label. This will merge all project labels across all projects in this group with the same name into a single group label. All issues and merge requests that previously were assigned one of these project labels will now be assigned the new group label. This action cannot be reversed and the changes are permanent.
+From the project label list page, you can promote a project label to a group label.
+This will merge all project labels with the same name into a single group label, across
+all projects in this group. All issues and merge requests that were previously
+assigned one of these project labels will now be assigned the new group label. This
+action cannot be reversed and the changes are permanent.
 
-![Labels promotion](img/labels_promotion.png)
+![Labels promotion](img/labels_promotion_v12_1.png)
 
 ## Assigning labels from the sidebar
 
-Every issue and merge request can be assigned any number of labels. The labels are visible on every issue and merge request page, in the sidebar. They are also visible in the issue board. From the sidebar, you can assign or unassign a label to the object (i.e. label or unlabel it). You can also perform this as a [quick action](quick_actions.md) in a comment.
+Every issue and merge request can be assigned any number of labels. The labels are
+visible on every issue and merge request page, in the sidebar. They are also visible on:
+
+- Every issue and merge request page in the sidebar.
+- The issue board.
+
+From the sidebar, you can assign or unassign a label to the object (i.e. label or
+unlabel it). You can also perform this as a [quick action](quick_actions.md),
+in a comment.
 
 | View labels in sidebar | Assign labels from sidebar |
-|:---:|:---:|
+|:----------------------:|:--------------------------:|
 | ![Labels sidebar](img/labels_sidebar.png) | ![Labels sidebar assign](img/labels_sidebar_assign.png) |
 
 ## Searching for project labels
 
-You can search for project labels by navigating from the left sidebar to your
-project's **Issues > Labels** and entering your query to the search bar on the
-top-right:
+To search for project labels, go to **Issues > Labels** in the left sidebar, and enter
+your search query in the **Filter** field.
 
 ![Labels project list search](img/labels_project_list_search.png)
 
-GitLab will consider the label title and description for the search.
+GitLab will check both the label titles and descriptions for the search.
+
+## Filtering by label
 
-## Filtering issues, merge requests and epics by label
+The following can be filtered labels:
+
+- Issue lists
+- Merge Request lists
+- Epic lists **(ULTIMATE)**
+- Issue Boards
 
 ### Filtering in list pages
 
-From the project issue list page and the project merge request list page, you can [filter](../search/index.md#issues-and-merge-requests) by both group (including subgroup ancestors) labels and project labels.
+- From the project issue list page and the project merge request list page, you can
+  [filter](../search/index.md#issues-and-merge-requests) by:
+  - Group labels (including subgroup ancestors)
+  - Project labels
 
-From the group issue list page and the group merge request list page, you can [filter](../search/index.md#issues-and-merge-requests) by both group labels (including subgroup ancestors and subgroup descendants) and project labels.
+- From the group issue list page and the group merge request list page, you can
+  [filter](../search/index.md#issues-and-merge-requests) by:
+  - Group labels (including subgroup ancestors and subgroup descendants)
+  - Project labels
 
-From the group epic list page, you can [filter](../search/index.md#issues-and-merge-requests) by both current group labels as well as descendant group labels.
+- You can [filter](../search/index.md#issues-and-merge-requests) the group epic list
+  page by: **(ULTIMATE)**
+  - Current group labels
+  - Descendant group labels
 
-![Labels group issues](img/labels_group_issues.png)
+![Labels group issues](img/labels_group_issues_v12_1.png)
 
 ### Filtering in issue boards
 
-- From [project boards](issue_board.md), you can filter by both group labels and project labels in the [search and filter bar](../search/index.md#issue-boards).
-- From [group issue boards](issue_board.md#group-issue-boards-premium), you can filter by only group labels in the [search and filter bar](../search/index.md#issue-boards). **[PREMIUM]**
-- From [project boards](issue_board.md), you can filter by both group labels and project labels in the [issue board configuration](issue_board.md#configurable-issue-boards-starter). **[STARTER]**
-- From [group issue boards](issue_board.md#group-issue-boards-premium), you can filter by only group labels in the [issue board configuration](issue_board.md#configurable-issue-boards-starter). **[STARTER]**
+- From [project boards](issue_board.md), you can use the [search and filter bar](../search/index.md#issue-boards)
+  to filter by:
+  - Group labels
+  - Project labels
+
+- From [group issue boards](issue_board.md#group-issue-boards-premium), you can use the
+  [search and filter bar](../search/index.md#issue-boards) to filter by group labels only. **(PREMIUM)**
+
+- From [project boards](issue_board.md), in the [issue board configuration](issue_board.md#configurable-issue-boards-starter),
+  you can filter by: **(STARTER)**
+  - Group labels
+  - Project labels
+
+- From [group issue boards](issue_board.md#group-issue-boards-premium), in the [issue board configuration](issue_board.md#configurable-issue-boards-starter),
+  you can filter by group labels only. **(STARTER)**
 
 ## Subscribing to labels
 
-From the project label list page and the group label list page, you can subscribe to [notifications](../../workflow/notifications.md) of a given label, to alert you that the label has been assigned to an issue or merge request.
+From the project label list page and the group label list page, you can subscribe
+to [notifications](../../workflow/notifications.md) of a given label, to alert you
+that the label has been assigned to an issue or merge request.
 
-![Labels subscriptions](img/labels_subscriptions.png)
+![Labels subscriptions](img/labels_subscriptions_v12_1.png)
 
 ## Label priority
 
@@ -161,26 +225,43 @@ From the project label list page and the group label list page, you can subscrib
 > - Introduced in GitLab 8.9.
 > - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554) considers changing this.
 
-Labels can have relative priorities, which are used in the "Label priority" and "Priority" sort orders of the issue and merge request list pages.
+Labels can have relative priorities, which are used in the "Label priority" and
+"Priority" sort orders of the issue and merge request list pages.
+
+From the project label list page, star a label to indicate that it has a priority.
+
+![Labels prioritized](img/labels_prioritized_v12_1.png)
+
+Drag starred labels up and down the list to change their priority. Higher in the list
+means higher priority. Prioritization happens at the project level, only on the project
+label list page, and not on the group label list page.
 
-From the project label list page, star a label to indicate that it has a priority. Drag starred labels up and down to change their priority. Higher means higher priority. Prioritization happens at the project level, only on the project label list page, and not on the group label list page. However, both project and group labels can be prioritized on the project label list page since both types are displayed on the project label list page.
+However, both project and group
+labels can be prioritized on the project label list page since both types are displayed
+on the project label list page.
 
-![Labels prioritized](img/labels_prioritized.png)
+![Drag to change label priority](img/labels_drag_priority_v12_1.gif)
 
-On the project and group issue and merge request list pages, you can sort by `Label priority` and `Priority`, which account for objects (issues and merge requests) that have prioritized labels assigned to them.
+On the merge request and issue pages, for both groups and projects, you can sort by `Label priority`
+and `Priority`, which account for objects (issues and merge requests) that have prioritized
+labels assigned to them.
 
 If you sort by `Label priority`, GitLab considers this sort comparison order:
 
 - Object with a higher priority prioritized label.
 - Object without a prioritized label.
 
-Ties are broken arbitrarily. (Note that we _only_ consider the highest prioritized label in an object, and not any of the lower prioritized labels. [This discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554) considers changing this.)
+Ties are broken arbitrarily. Note that we _only_ consider the highest prioritized label
+in an object, and not any of the lower prioritized labels. [This discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554)
+considers changing this.
 
 ![Labels sort label priority](img/labels_sort_label_priority.png)
 
 If you sort by `Priority`, GitLab considers this sort comparison order:
 
-- Object's assigned [milestone](milestones/index.md)'s due date is sooner, provided the object has a milestone and the milestone has a due date. If this isn't the case, consider the object having a due date in the infinite future.
+- Due date of the assigned [milestone](milestones/index.md) is sooner, provided
+  the object has a milestone and the milestone has a due date. If this isn't the case,
+  consider the object having a due date in the infinite future.
 - Object with a higher priority prioritized label.
 - Object without a prioritized label.
 
diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md
index 2a490e3fd7f..e343fd45488 100644
--- a/doc/user/project/members/index.md
+++ b/doc/user/project/members/index.md
@@ -10,8 +10,6 @@ or import a new user to your project.
 To view, edit, add, and remove project's members, go to your
 project's **Settings > Members**.
 
----
-
 ## Add a user
 
 Right next to **People**, start typing the name or username of the user you
@@ -19,22 +17,16 @@ want to add.
 
 ![Search for people](img/add_user_search_people.png)
 
----
-
 Select the user and the [permission level](../../permissions.md)
 that you'd like to give the user. Note that you can select more than one user.
 
 ![Give user permissions](img/add_user_give_permissions.png)
 
----
-
 Once done, hit **Add users to project** and they will be immediately added to
 your project with the permissions you gave them above.
 
 ![List members](img/add_user_list_members.png)
 
----
-
 From there on, you can either remove an existing user or change their access
 level to the project.
 
@@ -47,8 +39,6 @@ In the dropdown menu, you can see only the projects you are Maintainer on.
 
 ![Import members from another project](img/add_user_import_members_from_another_project.png)
 
----
-
 Select the one you want and hit **Import project members**. A flash message
 notifying you that the import was successful will appear, and the new members
 are now in the project's members list. Notice that the permissions that they
@@ -56,8 +46,6 @@ had on the project you imported from are retained.
 
 ![Members list of new members](img/add_user_imported_members.png)
 
----
-
 ## Invite people using their e-mail address
 
 If a user you want to give access to doesn't have an account on your GitLab
@@ -66,23 +54,17 @@ user search field.
 
 ![Invite user by mail](img/add_user_email_search.png)
 
----
-
 As you can imagine, you can mix inviting multiple people and adding existing
 GitLab users to the project.
 
 ![Invite user by mail ready to submit](img/add_user_email_ready.png)
 
----
-
 Once done, hit **Add users to project** and watch that there is a new member
 with the e-mail address we used above. From there on, you can resend the
 invitation, change their access level, or even delete them.
 
 ![Invite user members list](img/add_user_email_accept.png)
 
----
-
 Once the user accepts the invitation, they will be prompted to create a new
 GitLab account using the same e-mail address the invitation was sent to.
 
@@ -97,15 +79,11 @@ side of your screen.
 
 ![Request access button](img/request_access_button.png)
 
----
-
 Project owners & maintainers will be notified of your request and will be able to approve or
 decline it on the members page.
 
 ![Manage access requests](img/access_requests_management.png)
 
----
-
 If you change your mind before your request is approved, just click the
 **Withdraw Access Request** button.
 
diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md
index 611ff0e6bfb..9340d239677 100644
--- a/doc/user/project/members/share_project_with_groups.md
+++ b/doc/user/project/members/share_project_with_groups.md
@@ -20,18 +20,18 @@ To share 'Project Acme' with the 'Engineering' group:
 
 1. For 'Project Acme' use the left navigation menu to go to **Settings > Members**
 
-    ![share project with groups](img/share_project_with_groups.png)
+   ![share project with groups](img/share_project_with_groups.png)
 
 1. Select the 'Share with group' tab
 1. Add the 'Engineering' group with the maximum access level of your choice
 1. Click **Share** to share it
 
-    ![share project with groups tab](img/share_project_with_groups_tab.png)
+   ![share project with groups tab](img/share_project_with_groups_tab.png)
 
 1. After sharing 'Project Acme' with 'Engineering', the project will be listed
    on the group dashboard
 
-    !['Project Acme' is listed as a shared project for 'Engineering'](img/other_group_sees_shared_project.png)
+   !['Project Acme' is listed as a shared project for 'Engineering'](img/other_group_sees_shared_project.png)
 
 Note that you can only share a project with:
 
diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md
index f6c4f767e3c..49b9826a52a 100644
--- a/doc/user/project/merge_requests/browser_performance_testing.md
+++ b/doc/user/project/merge_requests/browser_performance_testing.md
@@ -2,7 +2,7 @@
 type: reference, howto
 ---
 
-# Browser Performance Testing **[PREMIUM]**
+# Browser Performance Testing **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3507)
 in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3.
@@ -19,7 +19,7 @@ tool for measuring the performance of web sites, and has built a simple
 which outputs the results in a file called `performance.json`. This plugin
 outputs the performance score for each page that is analyzed.
 
-The [Sitespeed.io performance score](http://examples.sitespeed.io/6.0/2017-11-23-23-43-35/help.html)
+The [Sitespeed.io performance score](https://examples.sitespeed.io/6.0/2017-11-23-23-43-35/help.html)
 is a composite value based on best practices, and we will be expanding support
 for [additional metrics](https://gitlab.com/gitlab-org/gitlab-ee/issues/4370)
 in a future release.
diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md
index c3c2bdd94b3..3a409bab19d 100644
--- a/doc/user/project/merge_requests/code_quality.md
+++ b/doc/user/project/merge_requests/code_quality.md
@@ -1,16 +1,27 @@
 ---
 type: reference, howto
+disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html'
 ---
 
-# Code Quality **[STARTER]**
+# Code Quality **(STARTER)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1984)
 in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3.
 
 With the help of [GitLab CI/CD](../../../ci/README.md), you can analyze your
 source code quality using GitLab Code Quality.
-Code Quality uses [Code Climate Engines](https://codeclimate.com), which are
-free and open source. Code Quality doesn't require a Code Climate subscription.
+
+Code Quality:
+
+- Uses [Code Climate Engines](https://codeclimate.com), which are
+  free and open source. Code Quality doesn't require a Code Climate
+  subscription.
+- Runs in [pipelines](../../../ci/pipelines.md) using an Docker image built in
+  [GitLab Code
+  Quality](https://gitlab.com/gitlab-org/security-products/codequality) project.
+- Can make use of a [template](#template-and-examples).
+- Is available with [Auto
+  DevOps](../../../topics/autodevops/index.md#auto-code-quality-starter).
 
 Going a step further, GitLab can show the Code Quality report right
 in the merge request widget area:
@@ -21,22 +32,48 @@ in the merge request widget area:
 
 For instance, consider the following workflow:
 
-1. Your backend team member starts a new implementation for making a certain feature in your app faster
-1. With Code Quality reports, they analyze how their implementation is impacting the code quality
-1. The metrics show that their code degrade the quality in 10 points
-1. You ask a co-worker to help them with this modification
-1. They both work on the changes until Code Quality report displays no degradations, only improvements
-1. You approve the merge request and authorize its deployment to staging
-1. Once verified, their changes are deployed to production
+1. Your backend team member starts a new implementation for making a certain
+   feature in your app faster.
+1. With Code Quality reports, they analyze how their implementation is impacting
+   the code quality.
+1. The metrics show that their code degrade the quality in 10 points.
+1. You ask a co-worker to help them with this modification.
+1. They both work on the changes until Code Quality report displays no
+   degradations, only improvements.
+1. You approve the merge request and authorize its deployment to staging.
+1. Once verified, their changes are deployed to production.
+
+## Template and examples
+
+For most GitLab instances, the supplied template is the preferred method of
+implementing Code Quality. See
+[Analyze your project's Code Quality](../../../ci/examples/code_quality.md) for:
+
+- Information on the builtin GitLab Code Quality template.
+- Examples of manual GitLab configuration for earlier GitLab versions.
 
-## How it works
+## Configuring jobs using variables
 
-First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the
-[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality-starter).
+The Code Quality job supports environment variables that users can set to
+configure job execution at runtime.
 
-The Code Quality report artifact is a subset of the
-[Code Climate spec](https://github.com/codeclimate/spec/blob/master/SPEC.md#data-types).
-It must be a JSON file containing an array of objects with the following properties:
+For a list of available environment variables, see
+[Environment variables](https://gitlab.com/gitlab-org/security-products/codequality/blob/master/README.md#environment-variables).
+
+## Implementing a custom tool
+
+It's possible to have a custom tool provide Code Quality reports in GitLab. To
+do this:
+
+1. Define a job in your `.gitlab-ci.yml` file that generates the
+   [Code Quality report
+   artifact](../../../ci/yaml/README.md#artifactsreportscodequality-starter).
+1. Configure your tool to generate the Code Quality report artifact as a JSON
+   file that implements subset of the [Code Climate
+   spec](https://github.com/codeclimate/spec/blob/master/SPEC.md#data-types).
+
+The Code Quality report artifact JSON file must contain an array of objects
+with the following properties:
 
 | Name                   | Description                                                                            |
 | ---------------------- | -------------------------------------------------------------------------------------- |
@@ -63,13 +100,16 @@ Example:
 ```
 
 NOTE: **Note:**
-Although the Code Climate spec supports more properties, those are ignored by GitLab.
+Although the Code Climate spec supports more properties, those are ignored by
+GitLab.
+
+## Code Quality reports
 
-For more information on what the Code Quality job should look like, check the
-example on [analyzing a project's code quality](../../../ci/examples/code_quality.md).
+Once the Code Quality job has completed, GitLab:
 
-GitLab then checks this report, compares the metrics between the source and target
-branches, and shows the information right on the merge request.
+- Checks the generated report.
+- Compares the metrics between the source and target branches.
+- Shows the information right on the merge request.
 
 If multiple jobs in a pipeline generate a code quality artifact, only the artifact from
 the last created job (the job with the largest job ID) is used. To avoid confusion,
diff --git a/doc/user/project/merge_requests/code_quality_diff.md b/doc/user/project/merge_requests/code_quality_diff.md
index ccc694672a6..0aa108a2e73 100644
--- a/doc/user/project/merge_requests/code_quality_diff.md
+++ b/doc/user/project/merge_requests/code_quality_diff.md
@@ -1,5 +1,4 @@
 ---
-redirect_from: 'code_quality_diff.md'
 redirect_to: 'code_quality.md'
 ---
 
diff --git a/doc/user/project/merge_requests/img/allow_collaboration.png b/doc/user/project/merge_requests/img/allow_collaboration.png
index e40e8a6b11c..cc13493646d 100644
--- a/doc/user/project/merge_requests/img/allow_collaboration.png
+++ b/doc/user/project/merge_requests/img/allow_collaboration.png
diff --git a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png b/doc/user/project/merge_requests/img/allow_collaboration_after_save.png
index 4ba4c84c8c5..bc7678b21ec 100644
--- a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png
+++ b/doc/user/project/merge_requests/img/allow_collaboration_after_save.png
diff --git a/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png b/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png
index b6dc86f312e..2598cc71c33 100644
--- a/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png
+++ b/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png
diff --git a/doc/user/project/merge_requests/img/approvals_premium_project_edit.png b/doc/user/project/merge_requests/img/approvals_premium_project_edit.png
index b6f6188b9cd..6a09412533f 100644
--- a/doc/user/project/merge_requests/img/approvals_premium_project_edit.png
+++ b/doc/user/project/merge_requests/img/approvals_premium_project_edit.png
diff --git a/doc/user/project/merge_requests/img/approvals_starter_project_edit.png b/doc/user/project/merge_requests/img/approvals_starter_project_edit.png
index 868b9d58740..4c554d846cc 100644
--- a/doc/user/project/merge_requests/img/approvals_starter_project_edit.png
+++ b/doc/user/project/merge_requests/img/approvals_starter_project_edit.png
diff --git a/doc/user/project/merge_requests/img/approvals_starter_project_empty.png b/doc/user/project/merge_requests/img/approvals_starter_project_empty.png
index 7375820224c..fc88a59a745 100644
--- a/doc/user/project/merge_requests/img/approvals_starter_project_empty.png
+++ b/doc/user/project/merge_requests/img/approvals_starter_project_empty.png
diff --git a/doc/user/project/merge_requests/img/approve.png b/doc/user/project/merge_requests/img/approve.png
index e68259ac5c2..e2641f48c7a 100644
--- a/doc/user/project/merge_requests/img/approve.png
+++ b/doc/user/project/merge_requests/img/approve.png
diff --git a/doc/user/project/merge_requests/img/approve_additionally.png b/doc/user/project/merge_requests/img/approve_additionally.png
index 3db5a9159e5..bab0cd4e041 100644
--- a/doc/user/project/merge_requests/img/approve_additionally.png
+++ b/doc/user/project/merge_requests/img/approve_additionally.png
diff --git a/doc/user/project/merge_requests/img/create_from_email.png b/doc/user/project/merge_requests/img/create_from_email.png
index 5cb2afaf976..14eef473e27 100644
--- a/doc/user/project/merge_requests/img/create_from_email.png
+++ b/doc/user/project/merge_requests/img/create_from_email.png
diff --git a/doc/user/project/merge_requests/img/cross_project_dependencies_edit_inaccessible_v12_2.png b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_inaccessible_v12_2.png
new file mode 100644
index 00000000000..2dc02634fd8
--- /dev/null
+++ b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_inaccessible_v12_2.png
diff --git a/doc/user/project/merge_requests/img/cross_project_dependencies_edit_v12_2.png b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_v12_2.png
new file mode 100644
index 00000000000..362e7e0ead2
--- /dev/null
+++ b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_v12_2.png
diff --git a/doc/user/project/merge_requests/img/cross_project_dependencies_view_v12_2.png b/doc/user/project/merge_requests/img/cross_project_dependencies_view_v12_2.png
new file mode 100644
index 00000000000..e00231c839b
--- /dev/null
+++ b/doc/user/project/merge_requests/img/cross_project_dependencies_view_v12_2.png
diff --git a/doc/user/project/merge_requests/img/filter_approver_merge_requests.png b/doc/user/project/merge_requests/img/filter_approver_merge_requests.png
index 9c386391a4f..4c28ee17f47 100644
--- a/doc/user/project/merge_requests/img/filter_approver_merge_requests.png
+++ b/doc/user/project/merge_requests/img/filter_approver_merge_requests.png
diff --git a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png
index 8df6a3c9a29..0989b41e2a4 100644
--- a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png
+++ b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png
diff --git a/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png b/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png
new file mode 100644
index 00000000000..ee94dbdea5c
--- /dev/null
+++ b/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png
diff --git a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png
index ea3aff59aa1..ed374b11fbd 100644
--- a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png
+++ b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png
diff --git a/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png b/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png
index 9ae6e350798..dde2680ed74 100644
--- a/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png
+++ b/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png
diff --git a/doc/user/project/merge_requests/img/remove_approval.png b/doc/user/project/merge_requests/img/remove_approval.png
index 6083e1745ef..b178d26cf85 100644
--- a/doc/user/project/merge_requests/img/remove_approval.png
+++ b/doc/user/project/merge_requests/img/remove_approval.png
diff --git a/doc/user/project/merge_requests/img/squash_mr_message.png b/doc/user/project/merge_requests/img/squash_mr_message.png
index 8734cab29aa..8c7dc7886f7 100644
--- a/doc/user/project/merge_requests/img/squash_mr_message.png
+++ b/doc/user/project/merge_requests/img/squash_mr_message.png
diff --git a/doc/user/project/merge_requests/img/wip_blocked_accept_button.png b/doc/user/project/merge_requests/img/wip_blocked_accept_button.png
index b6d38d85165..ab2c8425b83 100644
--- a/doc/user/project/merge_requests/img/wip_blocked_accept_button.png
+++ b/doc/user/project/merge_requests/img/wip_blocked_accept_button.png
diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md
index 447b338928c..2794cbc0f39 100644
--- a/doc/user/project/merge_requests/index.md
+++ b/doc/user/project/merge_requests/index.md
@@ -18,12 +18,12 @@ It is as simple as the name implies: a _request_ to _merge_ one branch into anot
 With GitLab merge requests, you can:
 
 - Compare the changes between two [branches](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell#_git_branching)
-- [Review and discuss](../../discussions/index.md#discussions) the proposed modifications inline
+- [Review and discuss](../../discussions/index.md#threads) the proposed modifications inline
 - Live preview the changes when [Review Apps](../../../ci/review_apps/index.md) is configured for your project
 - Build, test, and deploy your code in a per-branch basis with built-in [GitLab CI/CD](../../../ci/README.md)
 - Prevent the merge request from being merged before it's ready with [WIP MRs](#work-in-progress-merge-requests)
 - View the deployment process through [Pipeline Graphs](../../../ci/pipelines.md#visualizing-pipelines)
-- [Automatically close the issue(s)](../../project/issues/closing_issues.md#via-merge-request) that originated the implementation proposed in the merge request
+- [Automatically close the issue(s)](../../project/issues/managing_issues.md#closing-issues-automatically) that originated the implementation proposed in the merge request
 - Assign it to any registered user, and change the assignee how many times you need
 - Assign a [milestone](../../project/milestones/index.md) and track the development of a broader implementation
 - Organize your issues and merge requests consistently throughout the project with [labels](../../project/labels.md)
@@ -37,16 +37,17 @@ With GitLab merge requests, you can:
 
 With **[GitLab Enterprise Edition][ee]**, you can also:
 
-- Prepare a full review and submit it once it's ready with [Merge Request Reviews](../../discussions/index.md#merge-request-reviews-premium) **[PREMIUM]**
-- View the deployment process across projects with [Multi-Project Pipelines](../../../ci/multi_project_pipelines.md) **[PREMIUM]**
-- Request [approvals](merge_request_approvals.md) from your managers **[STARTER]**
-- Analyze the impact of your changes with [Code Quality reports](code_quality.md) **[STARTER]**
-- Manage the licenses of your dependencies with [License Management](../../application_security/license_management/index.md) **[ULTIMATE]**
-- Analyze your source code for vulnerabilities with [Static Application Security Testing](../../application_security/sast/index.md) **[ULTIMATE]**
-- Analyze your running web applications for vulnerabilities with [Dynamic Application Security Testing](../../application_security/dast/index.md) **[ULTIMATE]**
-- Analyze your dependencies for vulnerabilities with [Dependency Scanning](../../application_security/dependency_scanning/index.md) **[ULTIMATE]**
-- Analyze your Docker images for vulnerabilities with [Container Scanning](../../application_security/container_scanning/index.md) **[ULTIMATE]**
-- Determine the performance impact of changes with [Browser Performance Testing](#browser-performance-testing-premium) **[PREMIUM]**
+- Prepare a full review and submit it once it's ready with [Merge Request Reviews](../../discussions/index.md#merge-request-reviews-premium) **(PREMIUM)**
+- View the deployment process across projects with [Multi-Project Pipelines](../../../ci/multi_project_pipelines.md) **(PREMIUM)**
+- Request [approvals](merge_request_approvals.md) from your managers **(STARTER)**
+- Analyze the impact of your changes with [Code Quality reports](code_quality.md) **(STARTER)**
+- Manage the licenses of your dependencies with [License Management](../../application_security/license_management/index.md) **(ULTIMATE)**
+- Analyze your source code for vulnerabilities with [Static Application Security Testing](../../application_security/sast/index.md) **(ULTIMATE)**
+- Analyze your running web applications for vulnerabilities with [Dynamic Application Security Testing](../../application_security/dast/index.md) **(ULTIMATE)**
+- Analyze your dependencies for vulnerabilities with [Dependency Scanning](../../application_security/dependency_scanning/index.md) **(ULTIMATE)**
+- Analyze your Docker images for vulnerabilities with [Container Scanning](../../application_security/container_scanning/index.md) **(ULTIMATE)**
+- Determine the performance impact of changes with [Browser Performance Testing](#browser-performance-testing-premium) **(PREMIUM)**
+- Specify merge order dependencies with [Cross-project Merge Request Dependencies](#cross-project-merge-request-dependencies-premium) **(PREMIUM)**
 
 ## Use cases
 
@@ -54,9 +55,9 @@ A. Consider you are a software developer working in a team:
 
 1. You checkout a new branch, and submit your changes through a merge request
 1. You gather feedback from your team
-1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md) **[STARTER]**
+1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md) **(STARTER)**
 1. You verify your changes with [JUnit test reports](../../../ci/junit_test_reports.md) in GitLab CI/CD
-1. You avoid using dependencies whose license is not compatible with your project with [License Management reports](license_management.md) **[ULTIMATE]**
+1. You avoid using dependencies whose license is not compatible with your project with [License Management reports](license_management.md) **(ULTIMATE)**
 1. You request the [approval](#merge-request-approvals-starter) from your manager
 1. Your manager pushes a commit with their final review, [approves the merge request](merge_request_approvals.md), and set it to [merge when pipeline succeeds](#merge-when-pipeline-succeeds) (Merge Request Approvals are available in GitLab Starter)
 1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD
@@ -68,7 +69,7 @@ B. Consider you're a web developer writing a webpage for your company's website:
 1. You gather feedback from your reviewers
 1. Your changes are previewed with [Review Apps](../../../ci/review_apps/index.md)
 1. You request your web designers for their implementation
-1. You request the [approval](merge_request_approvals.md) from your manager **[STARTER]**
+1. You request the [approval](merge_request_approvals.md) from your manager **(STARTER)**
 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
 1. Your production team [cherry picks](#cherry-pick-changes) the merge commit into production
 
@@ -155,13 +156,13 @@ and remember to merge the request manually.
 
 [Learn more about merging when pipeline succeeds.](merge_when_pipeline_succeeds.md)
 
-## Resolve discussion comments in merge requests reviews
+## Resolve threads in merge requests reviews
 
 Keep track of the progress during a code review with resolving comments.
 Resolving comments prevents you from forgetting to address feedback and lets
-you hide discussions that are no longer relevant.
+you hide threads that are no longer relevant.
 
-[Read more about resolving discussion comments in merge requests reviews.](../../discussions/index.md)
+[Read more about resolving threads in merge requests reviews.](../../discussions/index.md)
 
 ## Commenting on any file line in merge requests
 
@@ -172,7 +173,7 @@ in a Merge Request. To do so, click the **...** button in the gutter of the Merg
 
 ![Comment on any diff file line](img/comment-on-any-diff-line.png)
 
-## Perform a Review **[PREMIUM]**
+## Perform a Review **(PREMIUM)**
 
 Start a review in order to create multiple comments on a diff and publish them once you're ready.
 Starting a review allows you to get all your thoughts in order and ensure you haven't missed anything
@@ -192,12 +193,12 @@ commit when merging, to allow for a neater commit history.
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6.
 
 As a reviewer, you can add suggestions to change the content in
-merge request discussions, and users with appropriate [permission](../../permissions.md)
+merge request threads, and users with appropriate [permission](../../permissions.md)
 can easily apply them to the codebase directly from the UI. Read
 through the documentation on [Suggest changes](../../discussions/index.md#suggest-changes)
 to learn more.
 
-## Multiple assignees **[STARTER]**
+## Multiple assignees **(STARTER)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/2004)
 in [GitLab Starter 11.11](https://about.gitlab.com/pricing).
@@ -274,7 +275,8 @@ branch already exists, the patches will be applied on top of it.
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/26752) in GitLab 11.10.
 
 NOTE: **Note:**
-Git push options are only available with Git 2.10 or newer.
+Git push options are only available with Git 2.10 or newer. With Git older than 2.18
+`git push --push-option=...` should be used instead of `git push -o ...`.
 
 GitLab supports using
 [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt)
@@ -284,6 +286,9 @@ as pushing changes:
 - Create a new merge request for the pushed branch.
 - Set the target of the merge request to a particular branch.
 - Set the merge request to merge when its pipeline succeeds.
+- Set the merge request to remove the source branch when it's merged.
+- Set the title of the merge request to a particular title.
+- Set the description of the merge request to a particular description.
 
 ### Create a new merge request using git push options
 
@@ -327,6 +332,49 @@ pipeline succeeds at the same time using a `-o` flag per push option:
 git push -o merge_request.create -o merge_request.merge_when_pipeline_succeeds
 ```
 
+### Set removing the source branch using git push options
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/64320) in GitLab 12.2.
+
+To set an existing merge request to remove the source branch when the
+merge request is merged, the
+`merge_request.remove_source_branch` push option can be used:
+
+```sh
+git push -o merge_request.remove_source_branch
+```
+
+You can also use this push option in addition to the
+`merge_request.create` push option.
+
+### Set merge request title using git push options
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/64320) in GitLab 12.2.
+
+To set the title of an existing merge request, use
+the `merge_request.title` push option:
+
+```sh
+git push -o merge_request.title="The title I want"
+```
+
+You can also use this push option in addition to the
+`merge_request.create` push option.
+
+### Set merge request description using git push options
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/64320) in GitLab 12.2.
+
+To set the description of an existing merge request, use
+the `merge_request.description` push option:
+
+```sh
+git push -o merge_request.description="The description I want"
+```
+
+You can also use this push option in addition to the
+`merge_request.create` push option.
+
 ## Find the merge request that introduced a change
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2383) in GitLab 10.5.
@@ -364,7 +412,12 @@ have been marked as a **Work In Progress**.
 
 [Learn more about setting a merge request as "Work In Progress".](work_in_progress_merge_requests.md)
 
-## Merge request approvals **[STARTER]**
+## Merge Requests for Confidential Issues
+
+Create [merge requests to resolve confidential issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues)
+for preventing leakage or early release of sentive data through regular merge requests.
+
+## Merge request approvals **(STARTER)**
 
 > Included in [GitLab Starter][products].
 
@@ -375,7 +428,7 @@ list of approvers that will need to approve every merge request in a project.
 
 [Read more about merge request approvals.](merge_request_approvals.md)
 
-## Code Quality **[STARTER]**
+## Code Quality **(STARTER)**
 
 > Introduced in [GitLab Starter][products] 9.3.
 
@@ -385,7 +438,18 @@ can show the Code Climate report right in the merge request widget area.
 
 [Read more about Code Quality reports.](code_quality.md)
 
-## Browser Performance Testing **[PREMIUM]**
+## Metrics Reports **(PREMIUM)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9788) in [GitLab Premium][products] 11.10.
+Requires GitLab Runner 11.10 and above.
+
+If you are using [GitLab CI][ci], you can configure your job to output custom
+metrics and GitLab will display the Metrics Report on the merge request so
+that it's fast and easy to identify changes to important metrics.
+
+[Read more about Metrics Report](../../../ci/metrics_reports.md).
+
+## Browser Performance Testing **(PREMIUM)**
 
 > Introduced in [GitLab Premium][products] 10.3.
 
@@ -395,7 +459,22 @@ GitLab runs the [Sitespeed.io container][sitespeed-container] and displays the d
 
 [Read more about Browser Performance Testing.](browser_performance_testing.md)
 
-## Security reports **[ULTIMATE]**
+## Cross-project Merge Request Dependencies **(PREMIUM)**
+
+> Introduced in [GitLab Premium][products] 12.2.
+
+A single logical change may be split across several merge requests, across
+several projects. When this happens, the order in which MRs are merged is
+important.
+
+GitLab allows you to specify that a merge request depends on other MRs. With
+this relationship in place, the merge request cannot be merged until all of its
+dependencies have also been merged, helping to maintain the consistency of a
+single logical change.
+
+[Read more about cross-project merge request dependencies.](merge_request_dependencies.md)
+
+## Security reports **(ULTIMATE)**
 
 GitLab can scan and report any vulnerabilities found in your project.
 
@@ -409,15 +488,6 @@ without having to check the entire job log.
 
 [Read more about JUnit test reports](../../../ci/junit_test_reports.md).
 
-## Live preview with Review Apps
-
-If you configured [Review Apps](https://about.gitlab.com/features/review-apps/) for your project,
-you can preview the changes submitted to a feature-branch through a merge request
-in a per-branch basis. No need to checkout the branch, install and preview locally;
-all your changes will be available to preview by anyone with the Review Apps link.
-
-[Read more about Review Apps.](../../../ci/review_apps/index.md)
-
 ## Merge request diff file navigation
 
 When reviewing changes in the **Changes** tab the diff can be navigated using
@@ -427,6 +497,15 @@ list.
 
 ![Merge request diff file navigation](img/merge_request_diff_file_navigation.png)
 
+### Incrementally expand merge request diffs
+
+By default, the diff shows only the parts of a file which are changed.
+To view more unchanged lines above or below a change click on the
+**Expand up** or **Expand down** icons. You can also click on **Show all lines**
+to expand the entire file.
+
+![Incrementally expand merge request diffs](img/incrementally_expand_merge_request_diffs_v12_2.png)
+
 ## Ignore whitespace changes in Merge Request diff view
 
 If you click the **Hide whitespace changes** button, you can see the diff
diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md
index fd151a6df45..5161b25de99 100644
--- a/doc/user/project/merge_requests/merge_request_approvals.md
+++ b/doc/user/project/merge_requests/merge_request_approvals.md
@@ -2,7 +2,7 @@
 type: reference, concepts
 ---
 
-# Merge request approvals **[STARTER]**
+# Merge request approvals **(STARTER)**
 
 > Introduced in [GitLab Enterprise Edition 7.12](https://about.gitlab.com/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only).
 
@@ -12,9 +12,9 @@ to approve a merge request before it can be unblocked for merging.
 ## Use cases
 
 1. Enforcing review of all code that gets merged into a repository.
-2. Specifying code maintainers for an entire repository.
-3. Specifying reviewers for a given proposed code change.
-4. Specifying categories of reviewers, such as BE, FE, QA, DB, etc., for all proposed code changes.
+1. Specifying code maintainers for an entire repository.
+1. Specifying reviewers for a given proposed code change.
+1. Specifying categories of reviewers, such as BE, FE, QA, DB, etc., for all proposed code changes.
 
 ## Enabling the new approvals interface
 
@@ -44,7 +44,7 @@ To edit the merge request approvals:
 1. Navigate to your project's **Settings > General** and expand
    **Merge request approvals**.
 
-    ![Approvals starter project empty](img/approvals_starter_project_empty.png)
+   ![Approvals starter project empty](img/approvals_starter_project_empty.png)
 
 1. Click **Edit**.
 1. Search for users or groups that will be [eligible to approve](#eligible-approvers)
@@ -54,7 +54,7 @@ To edit the merge request approvals:
    box. Note: the minimum can be 0.
 1. Click **Update approvers**.
 
-    ![Approvals starter project edit](img/approvals_starter_project_edit.png)
+   ![Approvals starter project edit](img/approvals_starter_project_edit.png)
 
 The steps above are the minimum required to get approvals working in your
 merge requests, but there are a couple more options available that might be
@@ -64,7 +64,7 @@ suitable to your workflow:
   [overridden per merge request](#overriding-the-merge-request-approvals-default-settings)
 - Choose whether [approvals will be reset with new pushed commits](#resetting-approvals-on-push)
 
-## Editing approvals **[PREMIUM]**
+## Editing approvals **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8.
 
@@ -83,9 +83,9 @@ request approval rules:
 1. Give the approval rule a name that describes the set of approvers selected.
 1. Click **Add approvers** to submit the new rule.
 
-    ![Approvals premium project edit](img/approvals_premium_project_edit.png)
+   ![Approvals premium project edit](img/approvals_premium_project_edit.png)
 
-## Multiple approval rules **[PREMIUM]**
+## Multiple approval rules **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8.
 
@@ -144,14 +144,17 @@ the following is possible:
 
   - If the required number of approvals has _not_ been yet met, they can approve
     it by clicking the displayed **Approve** button.
-      ![Approve](img/approve.png)
+
+    ![Approve](img/approve.png)
+
   - If the required number of approvals has already been met, they can still
     approve it by clicking the displayed **Approve additionally** button.
-      ![Add approval](img/approve_additionally.png)
+
+    ![Add approval](img/approve_additionally.png)
 
 - **They have already approved this merge request**: They can remove their approval.
 
-    ![Remove approval](img/remove_approval.png)
+  ![Remove approval](img/remove_approval.png)
 
 NOTE: **Note:**
 The merge request author is only allowed to approve their own merge request
@@ -159,13 +162,13 @@ if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-thei
 
 For a given merge request, if the approval restrictions have been satisfied,
 the merge request is unblocked and can be merged.
-Note, that meeting the required number of approvals is a necessary, but not
+Note that meeting the required number of approvals is a necessary, but not
 sufficient condition for unblocking a merge request from being merged. There
 are other conditions that may block it, such as merge conflicts,
-[pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-discussions-are-resolved)
+[pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved)
 or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md).
 
-## Code Owners approvals **[PREMIUM]**
+## Code Owners approvals **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9.
 
@@ -203,7 +206,7 @@ First, you have to enable this option in the project's settings:
 1. Tick the "Can override approvers and approvals required per merge request"
    checkbox
 
-    ![Approvals can override](img/approvals_can_override.png)
+   ![Approvals can override](img/approvals_can_override.png)
 
 1. Click **Save changes**
 
@@ -226,27 +229,16 @@ The default approval settings can now be overridden when creating a
    in the **No. approvals required** box.
 1. Click **Update approvers**.
 
-There are however some restrictions:
-
-- The amount of required approvals, if changed, must be greater than the default
-  set at the project level. This ensures that you're not forced to adjust settings
-  when someone is unavailable for approval, yet the process is still enforced.
-
 NOTE: **Note:**
 If you are contributing to a forked project, things are a little different.
 Read what happens  when the
 [source and target branches are not the same](#merge-requests-with-different-source-branch-and-target-branch-projects).
 
-## Overriding merge request approvals default settings **[PREMIUM]**
+## Overriding merge request approvals default settings **(PREMIUM)**
 
-In GitLab Premium, when the approval rules are [set at the project level](#editing-approvals-premium), and
-**Can override approvers and approvals required per merge request** is checked, there are a few more
-restrictions (compared to [GitLab Starter](#overriding-the-merge-request-approvals-default-settings)):
-
-- Approval rules can be added to an MR with no restriction.
-- For project sourced approval rules, editing and removing approvers is not allowed.
-- The approvals required of all approval rules is configurable, but if a rule is backed by a project rule, then it is restricted
-to the minimum approvals required set in the project's corresponding rule.
+In GitLab Premium, when the approval rules are [set at the project level](#editing-approvals-premium),
+and **Can override approvers and approvals required per merge request** is checked,
+approval rules can be added to an MR with no restriction.
 
 ## Resetting approvals on push
 
@@ -259,7 +251,7 @@ new commits are pushed to the source branch of the merge request:
 1. Tick the "Remove all approvals in a merge request when new commits are pushed to its source branch"
    checkbox
 
-    ![Approvals remove on push](img/approvals_remove_on_push.png)
+   ![Approvals remove on push](img/approvals_remove_on_push.png)
 
 1. Click **Save changes**
 
@@ -295,7 +287,7 @@ enabling [**Prevent approval of merge requests by their committers**](#prevent-a
 1. Tick the checkbox **Prevent approval of merge requests by their committers**.
 1. Click **Save changes**.
 
-## Require authentication when approving a merge request **[STARTER]**
+## Require authentication when approving a merge request **(STARTER)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5981) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0.
 
@@ -331,6 +323,16 @@ the dropdown) `approver` and select the user.
 
 ![Filter MRs by an approver](img/filter_approver_merge_requests.png)
 
+## Security approvals in merge requests **(ULTIMATE)**
+
+> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 12.2.
+
+Merge Request Approvals can be configured to require approval from a member
+of your security team when a vulnerability would be introduced by a merge request.
+
+For more information, see 
+[Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests-ultimate).
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues
diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md
new file mode 100644
index 00000000000..b30e24b2386
--- /dev/null
+++ b/doc/user/project/merge_requests/merge_request_dependencies.md
@@ -0,0 +1,142 @@
+---
+type: reference, concepts
+---
+
+# Cross-project Merge Request dependencies **(PREMIUM)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9688) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2.
+
+Cross-project merge request dependencies allows a required order of merging
+between merge requests in different projects to be expressed. If a
+merge request "depends on" another, then it cannot be merged until its
+dependency is itself merged.
+
+NOTE: **Note:**
+Merge requests dependencies are a **PREMIUM** feature, but this restriction is
+only enforced for the dependent merge request. A merge request in a **CORE** or
+**STARTER** project can be a dependency of a **PREMIUM** merge request, but not
+vice-versa.
+
+NOTE: **Note:**
+A merge request can only depend on merge requests in a different project. Two
+merge requests in the same project cannot depend on each other.
+
+## Use cases
+
+- Ensure changes to a library are merged before changes to a project that
+  imports the library.
+- Prevent a documentation-only merge request from being merged before the merge request
+  implementing the feature to be documented.
+- Require an merge request updating a permissions matrix to be merged before merging an
+  merge request from someone who hasn't yet been granted permissions.
+
+It is common for a single logical change to span several merge requests, spread
+out across multiple projects, and the order in which they are merged can be
+significant.
+
+For example, given a project `mycorp/awesome-project` that imports a library
+at `myfriend/awesome-lib`, adding a feature in `awesome-project` may **also**
+require changes to `awesome-lib`, and so necessitate two merge requests. Merging
+the `awesome-project` merge request before the `awesome-lib` one would
+break the `master`branch.
+
+The `awesome-project` merge request could be [marked as
+WIP](work_in_progress_merge_requests.md),
+and the reason for the WIP stated included in the comments. However, this
+requires the state of the `awesome-lib` merge request to be manually
+tracked, and doesn't scale well if the `awesome-project` merge request
+depends on changes to **several** other projects.
+
+By making the `awesome-project` merge request depend on the
+`awesome-lib` merge request instead, this relationship is
+automatically tracked by GitLab, and the WIP state can be used to
+communicate the readiness of the code in each individual merge request
+instead.
+
+## Configuration
+
+To continue the above example, you can configure a dependency when creating the
+new merge request in `awesome-project` (or by editing it, if it already exists).
+The dependency needs to be configured on the **dependent** merge
+request. There is a "Cross-project dependencies" section in the form:
+
+![Cross-project dependencies form control](img/cross_project_dependencies_edit_v12_2.png)
+
+Anyone who can edit a merge request can change the list of dependencies.
+
+New dependencies can be added by reference, or by URL. To remove a dependency,
+press the **X** by its reference.
+
+As dependencies are specified across projects, it's possible that someone else
+has added a dependency for a merge request in a project you don't have access to.
+These are shown as a simple count:
+
+![Cross-project dependencies form control with inaccessible merge requests](img/cross_project_dependencies_edit_inaccessible_v12_2.png)
+
+If necessary, you can remove all the dependencies like this by pressing the
+**X**, just as you would for a single, visible dependency.
+
+Once you're finished, press the **Save changes** button to submit the request,
+or **Cancel** to return without making any changes.
+
+The list of configured dependencies, and the status of each one, is shown in the
+merge request widget:
+
+![Cross-project dependencies in merge request widget](img/cross_project_dependencies_view_v12_2.png)
+
+Until all dependencies have, themselves, been merged, the **Merge**
+button will be disabled for the dependent merge request. In
+particular, note that **closed merge requests** still prevent their
+dependents from being merged - it is impossible to automatically
+determine whether the dependency expressed by a closed merge request
+has been satisfied in some other way or not.
+
+If a merge request has been closed **and** the dependency is no longer relevant,
+it must be removed as a dependency, following the instructions above, before
+merge.
+
+## Limitations
+
+- API support: [gitlab-ee#12551](https://gitlab.com/gitlab-org/gitlab-ee/issues/12551)
+- Dependencies are not preserved across project export/import: [gitlab-ee#12549](https://gitlab.com/gitlab-org/gitlab-ee/issues/12549)
+- Complex merge order dependencies are not supported: [gitlab-ee#11393](https://gitlab.com/gitlab-org/gitlab-ee/issues/11393)
+
+The last item merits a little more explanation. Dependencies between merge
+requests can be described as a graph of relationships. The simplest possible
+graph has one merge request that depends upon another:
+
+```mermaid
+graph LR;
+    myfriend/awesome-lib!10-->mycorp/awesome-project!100;
+```
+
+A more complex (and still supported) graph might have one merge request that
+directly depends upon several others:
+
+```mermaid
+graph LR;
+    myfriend/awesome-lib!10-->mycorp/awesome-project!100;
+    herfriend/another-lib!1-->mycorp/awesome-project!100;
+```
+
+Several different merge requests can also directly depend upon the
+same merge request:
+
+```mermaid
+graph LR;
+    herfriend/another-lib!1-->myfriend/awesome-lib!10;
+    herfriend/another-lib!1-->mycorp/awesome-project!100;
+```
+
+What is **not** supported is a "deep", or "nested" graph of dependencies, e.g.:
+
+```mermaid
+graph LR;
+    herfriend/another-lib!1-->myfriend/awesome-lib!10;
+    myfriend/awesome-lib!10-->mycorp/awesome-project!100;
+```
+
+In this example, `myfriend/awesome-lib!10` depends on `herfriend/another-lib!1`,
+and is itself a dependent of `mycorp/awesome-project!100`. This means that
+`myfriend/awesome-lib!10` becomes an **indirect** dependency of
+`mycorp/awesome-project!100`, which is not yet supported.
diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md
index c93c7a5fe08..50a4e514d49 100644
--- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md
+++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md
@@ -36,12 +36,14 @@ changes to be reviewed.
 ## Only allow merge requests to be merged if the pipeline succeeds
 
 You can prevent merge requests from being merged if their pipeline did not succeed
-or if there are discussions to be resolved.
+or if there are threads to be resolved.
 
 Navigate to your project's settings page and expand the **Merge requests** section.
 In the **Merge checks** subsection, select the **Pipelines must succeed** check
 box and hit **Save** for the changes to take effect.
 
+NOTE: **Note:** This setting also prevents merge requests from being merged if there is no pipeline.
+
 ![Pipelines must succeed settings](img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png)
 
 From now on, every time the pipeline fails you will not be able to merge the
@@ -49,6 +51,21 @@ merge request from the UI, until you make all relevant jobs pass.
 
 ![Only allow merge if pipeline succeeds message](img/merge_when_pipeline_succeeds_only_if_succeeds_msg.png)
 
+### Limitations
+
+When this setting is enabled, a merge request is prevented from being merged if there is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#onlyexcept-advanced) rules are used and they don't generate any pipelines.
+
+Users that expect to be able to merge a merge request in this scenario should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-ce/issues/54226) and that it's succesful.
+
+For example, to that on merge requests there is always a passing job even though `only/except` rules may not generate any other jobs:
+
+```yaml
+enable_merge:
+  only: merge_requests
+  script:
+    - echo true
+```
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues
diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md
index 39fd2588811..38459584eed 100644
--- a/doc/user/project/merge_requests/squash_and_merge.md
+++ b/doc/user/project/merge_requests/squash_and_merge.md
@@ -50,7 +50,10 @@ all you have to do is enable squashing before you press merge to join
 the commits in the merge request into a single commit.
 
 This way, the history of your base branch remains clean with
-meaningful commit messages and is simpler to [revert](revert_changes.md) if necessary.
+meaningful commit messages and:
+
+- It's simpler to [revert](revert_changes.md) if necessary.
+- The merged branch will retain the full commit history.
 
 ## Enabling squash for a merge request
 
diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md
index 9cd868067bc..ea59644fce6 100644
--- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md
+++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md
@@ -5,7 +5,7 @@ type: reference, concepts
 # "Work In Progress" merge requests
 
 If a merge request is not yet ready to be merged, perhaps due to continued development
-or open discussions, you can prevent it from being accepted before it's ready by flagging
+or open threads, you can prevent it from being accepted before it's ready by flagging
 it as a **Work In Progress**. This will disable the "Merge" button, preventing it from
 being merged, and it will stay disabled until the "WIP" flag has been removed.
 
@@ -15,11 +15,11 @@ being merged, and it will stay disabled until the "WIP" flag has been removed.
 
 There are several ways to flag a merge request as a Work In Progress:
 
-- Add "[WIP]" or "WIP:" to the start of the merge request's title. Clicking on
+- Add `[WIP]` or `WIP:` to the start of the merge request's title. Clicking on
   **Start the title with WIP:**, under the title box, when editing the merge request's
   description will have the same effect.
 - Add the `/wip` [quick action](../quick_actions.md#quick-actions-for-issues-and-merge-requests)
-  in a discussion comment in the merge request. This is a toggle, and can be repeated
+  in a comment in the merge request. This is a toggle, and can be repeated
   to change the status back. Note that any other text in the comment will be discarded.
 - Add "wip" or "WIP" to the start of a commit message targeting the merge request's
   source branch. This is not a toggle, and doing it again in another commit will have
@@ -30,11 +30,11 @@ There are several ways to flag a merge request as a Work In Progress:
 Similar to above, when a Merge Request is ready to be merged, you can remove the
 "Work in Progress" flag in several ways:
 
-- Remove "[WIP]" or "WIP:" from the start of the merge request's title. Clicking on
+- Remove `[WIP]` or `WIP:` from the start of the merge request's title. Clicking on
   **Remove the WIP: prefix from the title**, under the title box, when editing the merge
   request's description, will have the same effect.
 - Add the `/wip` [quick action](../quick_actions.md#quick-actions-for-issues-and-merge-requests)
-  in a discussion comment in the merge request. This is a toggle, and can be repeated
+  in a comment in the merge request. This is a toggle, and can be repeated
   to change the status back. Note that any other text in the comment will be discarded.
 - Click on the **Resolve WIP status** button near the bottom of the merge request description,
   next to the "Merge" button (see [image above](#work-in-progress-merge-requests)).
diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md
index 7ffeb032d7f..d4dd9c7d4c3 100644
--- a/doc/user/project/milestones/burndown_charts.md
+++ b/doc/user/project/milestones/burndown_charts.md
@@ -1,6 +1,9 @@
-# Burndown Charts **[STARTER]**
+---
+type: reference
+---
+
+# Burndown Charts **(STARTER)**
 
-> **Notes:**
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1540) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1 for project milestones.
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5354) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.8 for group milestones.
 > - [Added](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6495) to [GitLab Starter](https://about.gitlab.com/pricing/) 11.2 for group milestones.
@@ -20,7 +23,8 @@ yourself to have the same sense of progress.
 
 GitLab Starter plots it for you and presents it in a clear and beautiful chart.
 
-For an overview, check the video demonstration on [Mapping Work Versus Time, With Burndown Charts](https://about.gitlab.com/2017/04/25/mapping-work-to-do-versus-time-with-burndown-charts/).
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For an overview, check the video demonstration on [Mapping work versus time with Burndown Charts](https://www.youtube.com/watch?v=zJU2MuRChzs).
 
 ## Use cases
 
@@ -68,3 +72,15 @@ The Burndown Chart can also be toggled to display the cumulative open issue
 weight for a given day. When using this feature, make sure issue weights have
 been properly assigned, since an open issue with no weight adds zero to the
 cumulative value.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md
index 6cd866b5c0d..453983fa882 100644
--- a/doc/user/project/milestones/index.md
+++ b/doc/user/project/milestones/index.md
@@ -1,3 +1,7 @@
+---
+type: index, reference
+---
+
 # Milestones
 
 ## Overview
@@ -14,12 +18,12 @@ the start and end of your Agile sprint.
 Set the milestone title to the name of your Agile sprint,
 such as `November 2018 sprint`.
 Add an issue to your Agile sprint by associating
-the milestone to the issue.  
+the milestone to the issue.
 
 ## Milestones as releases
 
 Milestones can be used as releases.
-Set the milestone due date to represent the release date of your release. 
+Set the milestone due date to represent the release date of your release.
 (And leave the milestone start date blank.)
 Set the milestone title to the version of your release,
 such as `Version 9.4`.
@@ -84,9 +88,9 @@ From the project issue/merge request list pages and the group issue/merge reques
 ### Filtering in issue boards
 
 - From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [search and filter bar](../../search/index.md#issue-boards).
-- From [group issue boards](../issue_board.md#group-issue-boards-premium), you can filter by only group milestones in the [search and filter bar](../../search/index.md#issue-boards). **[PREMIUM]**
-- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards-starter). **[STARTER]**
-- From [group issue boards](../issue_board.md#group-issue-boards-premium) you can filter by only group milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards-starter). **[STARTER]**
+- From [group issue boards](../issue_board.md#group-issue-boards-premium), you can filter by only group milestones in the [search and filter bar](../../search/index.md#issue-boards). **(PREMIUM)**
+- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards-starter). **(STARTER)**
+- From [group issue boards](../issue_board.md#group-issue-boards-premium) you can filter by only group milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards-starter). **(STARTER)**
 
 ### Special milestone filters
 
@@ -124,13 +128,13 @@ These features are only available for project milestones and not group milestone
 - Participants and labels that are used in issues and merge requests that have the milestone assigned are displayed.
 - [Burndown chart](#project-burndown-charts-starter).
 
-### Project Burndown Charts **[STARTER]**
+### Project Burndown Charts **(STARTER)**
 
 For project milestones in [GitLab Starter](https://about.gitlab.com/pricing), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone.
 
 ![burndown chart](img/burndown_chart.png)
 
-### Group Burndown Charts **[PREMIUM]**
+### Group Burndown Charts **(PREMIUM)**
 
 For group milestones in [GitLab Premium](https://about.gitlab.com/pricing), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone.
 
@@ -145,3 +149,15 @@ The milestone sidebar on the milestone view shows the following:
 For project milestones only, the milestone sidebar shows the total issue weight of all issues that have the milestone assigned.
 
 ![Project milestone page](img/milestones_project_milestone_page.png)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md
index c07c4099f22..8606d92f20c 100644
--- a/doc/user/project/new_ci_build_permissions_model.md
+++ b/doc/user/project/new_ci_build_permissions_model.md
@@ -6,8 +6,6 @@ GitLab 8.12 has a completely redesigned [job permissions] system. You can find
 all discussion and all our concerns when choosing the current approach in issue
 [#18994](https://gitlab.com/gitlab-org/gitlab-ce/issues/18994).
 
----
-
 Jobs permissions should be tightly integrated with the permissions of a user
 who is triggering a job.
 
@@ -30,13 +28,13 @@ The reasons to do it like that are:
 With the new behavior, any job that is triggered by the user, is also marked
 with their read permissions. When a user does a `git push` or changes files through
 the web UI, a new pipeline will be usually created. This pipeline will be marked
-as created be the pusher (local push or via the UI) and any job created in this
+as created by the pusher (local push or via the UI) and any job created in this
 pipeline will have the read permissions of the pusher but not write permissions.
 
 This allows us to make it really easy to evaluate the access for all projects
 that have [Git submodules][gitsub] or are using container images that the pusher
-would have access too. **The permission is granted only for time that job is
-running. The access is revoked after the job is finished.**
+would have access too. **The permission is granted only for the time that the job
+is running. The access is revoked after the job is finished.**
 
 ## Types of users
 
@@ -76,7 +74,7 @@ We try to make sure that this token doesn't leak by:
 
 1. Securing all API endpoints to not expose the job token.
 1. Masking the job token from job logs.
-1. Allowing to use the job token **only** when job is running.
+1. Granting permissions to the job token **only** when the job is running.
 
 However, this brings a question about the Runners security. To make sure that
 this token doesn't leak, you should also make sure that you configure
@@ -88,13 +86,6 @@ your Runners in the most possible secure way, by avoiding the following:
 By using an insecure GitLab Runner configuration, you allow the rogue developers
 to steal the tokens of other jobs.
 
-## Pipeline triggers
-
-Since 9.0 [pipeline triggers][triggers] do support the new permission model.
-The new triggers do impersonate their associated user including their access
-to projects and their project permissions. To migrate trigger to use new permission
-model use **Take ownership**.
-
 ## Before GitLab 8.12
 
 In versions before GitLab 8.12, all CI jobs would use the CI Runner's token
@@ -108,8 +99,6 @@ and to checkout project sources.
 It could also be used with the GitLab Container Registry for that project,
 allowing pulling and pushing Docker images from within the CI job.
 
----
-
 GitLab would create a special checkout URL like:
 
 ```
@@ -185,7 +174,7 @@ The [Job environment variable][jobenv] `CI_JOB_TOKEN` can be used to
 authenticate any clones of dependent repositories. For example:
 
 ```
-git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/myuser/mydependentrepo
+git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/<user>/<mydependentrepo>.git
 ```
 
 It can also be used for system-wide authentication
@@ -208,7 +197,7 @@ Container Registries for private projects.
 > **Notes:**
 >
 > - GitLab Runner versions prior to 1.8 don't incorporate the introduced changes
->   for permissions. This makes the `image:` directive to not work with private
+>   for permissions. This makes the `image:` directive not work with private
 >   projects automatically and it needs to be configured manually on Runner's host
 >   with a predefined account (for example administrator's personal account with
 >   access token created explicitly for this purpose). This issue is resolved with
@@ -232,11 +221,22 @@ test:
     - docker run $CI_REGISTRY/group/other-project:latest
 ```
 
+### Pipeline triggers
+
+Since 9.0 [pipeline triggers][triggers] do support the new permission model.
+The new triggers do impersonate their associated user including their access
+to projects and their project permissions.
+
+### API
+
+GitLab API cannot be used via `CI_JOB_TOKEN` but there is a [proposal](https://gitlab.com/gitlab-org/gitlab-ce/issues/29566)
+to support it.
+
 [job permissions]: ../permissions.md#job-permissions
 [comment]: https://gitlab.com/gitlab-org/gitlab-ce/issues/22484#note_16648302
 [gitsub]: ../../ci/git_submodules.md
 [https]: ../admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols
-[triggers]: ../../ci/triggers/README.md
+[triggers]: ../../ci/triggers/README.md#ci-job-token
 [update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update
 [workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse
 [jobenv]: ../../ci/variables/README.md#predefined-environment-variables
diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md
index a5db3d70bb9..75b0623e6b0 100644
--- a/doc/user/project/operations/feature_flags.md
+++ b/doc/user/project/operations/feature_flags.md
@@ -1,4 +1,4 @@
-# Feature Flags **[PREMIUM]**
+# Feature Flags **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845) in GitLab 11.4.
 
@@ -74,9 +74,9 @@ To define specs for each environment:
 
 1. Navigate to your project's **Operations > Feature Flags**.
 1. Click on the **New Feature Flag** button or edit an existing flag.
-1. Set the status of the default [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) (`*`). This status will be used for _all_ environments.
+1. Set the status of the default [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) (`*`). Choose a rollout strategy. This status and rollout strategy combination will be used for _all_ environments.
 1. If you want to enable/disable the feature on a specific environment, create a new [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) and type the environment name.
-1. Set the status of the additional spec. This status takes precedence over the default spec's status since we always use the most specific match available.
+1. Set the status and rollout strategy of the additional spec. This status and rollout strategy combination takes precedence over the default spec since we always use the most specific match available.
 1. Click **Create feature flag** or **Update feature flag**.
 
 ![Feature flag specs list](img/specs_list.png)
@@ -85,6 +85,46 @@ NOTE: **NOTE**
 We'd highly recommend you to use the [Environment](../../../ci/environments.md)
 feature in order to quickly assess which flag is enabled per environment.
 
+## Rollout Strategy
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8240) in GitLab 12.2.
+
+The selected rollout strategy affects which users will experience the feature enabled.
+
+The status of an environment spec ultimately determines whether or not a feature is enabled at all.
+For instance, a feature will always be disabled for every user if the matching environment spec has a disabled status, regardless of the chosen rollout strategy.
+However, a feature will be enabled for 50% of logged-in users if the matching environment spec has an enabled status along with a **Percent rollout (logged in users)** strategy set to 50%.
+
+### All users
+
+Enables the feature for all users.
+
+**All users** is implemented using the Unleash [default](https://unleash.github.io/docs/activation_strategy#default) activation strategy.
+
+### Percent rollout (logged in users)
+
+**Percent rollout (logged in users)** enables the feature for a percentage of authenticated users. Set a value of 15%, for example, to enable the feature for 15% of authenticated users.
+
+A rollout percentage may be between 0% and 100%.
+
+CAUTION: **Caution:**
+If this strategy is selected, then the Unleash client **must** be given a user id for the feature to be enabled. See the [Ruby example](#ruby-application-example) below.
+
+**Percent rollout (logged in users)** is implemented using the Unleash [gradualRolloutUserId](https://unleash.github.io/docs/activation_strategy#gradualrolloutuserid) activation strategy.
+
+## Target Users
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8240) in GitLab 12.2.
+
+A feature flag may be enabled for a list of target users.
+
+![Feature flag target users](img/target_users_v12_2.png)
+
+CAUTION: **Caution:**
+The Unleash client **must** be given a user id for the feature to be enabled for target users. See the [Ruby example](#ruby-application-example) below.
+
+**Target users** is implemented using the Unleash [userWithId](https://unleash.github.io/docs/activation_strategy#userwithid) activation strategy.
+
 ## Integrating with your application
 
 In order to use Feature Flags, you need to first
@@ -175,3 +215,34 @@ func main() {
     log.Fatal(http.ListenAndServe(":8080", nil))
 }
 ```
+
+### Ruby application example
+
+Here's an example of how to integrate the feature flags in a Ruby application.
+
+The Unleash client is given a user id for use with a **Percent rollout (logged in users)** rollout strategy or a list of **Target Users**.
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'unleash'
+require 'unleash/context'
+
+unleash = Unleash::Client.new({
+  url: 'http://gitlab.com/api/v4/feature_flags/unleash/42',
+  app_name: 'production',
+  instance_id: '29QmjsW6KngPR5JNPMWx'
+})
+
+unleash_context = Unleash::Context.new
+# Replace "123" with the id of an authenticated user.
+# Note that the context's user id must be a string:
+# https://unleash.github.io/docs/unleash_context
+unleash_context.user_id = "123"
+
+if unleash.is_enabled?("my_feature_name", unleash_context)
+  puts "Feature enabled"
+else
+  puts "hello, world!"
+end
+```
diff --git a/doc/user/project/operations/img/error_tracking_list.png b/doc/user/project/operations/img/error_tracking_list.png
index aa0f9867fdb..194c7b440a4 100644
--- a/doc/user/project/operations/img/error_tracking_list.png
+++ b/doc/user/project/operations/img/error_tracking_list.png
diff --git a/doc/user/project/operations/img/external_dashboard_link.png b/doc/user/project/operations/img/external_dashboard_link.png
index 4fb8bce7cd0..82c5e05e467 100644
--- a/doc/user/project/operations/img/external_dashboard_link.png
+++ b/doc/user/project/operations/img/external_dashboard_link.png
diff --git a/doc/user/project/operations/img/external_dashboard_settings.png b/doc/user/project/operations/img/external_dashboard_settings.png
index 8dc380f01e2..e1b7fa56a1c 100644
--- a/doc/user/project/operations/img/external_dashboard_settings.png
+++ b/doc/user/project/operations/img/external_dashboard_settings.png
diff --git a/doc/user/project/operations/img/feature_flags_list.png b/doc/user/project/operations/img/feature_flags_list.png
index 5313a163fec..f3e85b9ce44 100644
--- a/doc/user/project/operations/img/feature_flags_list.png
+++ b/doc/user/project/operations/img/feature_flags_list.png
diff --git a/doc/user/project/operations/img/specs_list.png b/doc/user/project/operations/img/specs_list.png
index 9630c907cfc..43d069c09ce 100644
--- a/doc/user/project/operations/img/specs_list.png
+++ b/doc/user/project/operations/img/specs_list.png
diff --git a/doc/user/project/operations/img/target_users_v12_2.png b/doc/user/project/operations/img/target_users_v12_2.png
new file mode 100644
index 00000000000..c88d2b7be97
--- /dev/null
+++ b/doc/user/project/operations/img/target_users_v12_2.png
diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md
index 84711d1146f..2da9c3e70cf 100644
--- a/doc/user/project/operations/index.md
+++ b/doc/user/project/operations/index.md
@@ -7,6 +7,6 @@ your applications:
 - Deploy to different [environments](../../../ci/environments.md).
 - Connect your project to a [Kubernetes cluster](../clusters/index.md).
 - Discover and view errors generated by your applications with [Error Tracking](error_tracking.md).
-- Create, toggle, and remove [Feature Flags](feature_flags.md). **[PREMIUM]**
-- [Trace](tracing.md) the performance and health of a deployed application. **[ULTIMATE]**
+- Create, toggle, and remove [Feature Flags](feature_flags.md). **(PREMIUM)**
+- [Trace](tracing.md) the performance and health of a deployed application. **(ULTIMATE)**
 - Add a [button to the Monitoring dashboard](linking_to_an_external_dashboard.md) linking directly to your existing external dashboards.
diff --git a/doc/user/project/operations/tracing.md b/doc/user/project/operations/tracing.md
index 0416e096cf2..b92d2e49839 100644
--- a/doc/user/project/operations/tracing.md
+++ b/doc/user/project/operations/tracing.md
@@ -1,4 +1,4 @@
-# Tracing **[ULTIMATE]**
+# Tracing **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/7903) in GitLab Ultimate 11.5.
 
@@ -17,8 +17,8 @@ systems.
 ### Deploying Jaeger
 
 To learn more about deploying Jaeger, read the official
-[Getting Started documentation](https://www.jaegertracing.io/docs/latest/getting-started/).
-There is an easy to use [all-in-one Docker image](https://www.jaegertracing.io/docs/latest/getting-started/#AllinoneDockerimage),
+[Getting Started documentation](https://www.jaegertracing.io/docs/1.13/getting-started/).
+There is an easy to use [all-in-one Docker image](https://www.jaegertracing.io/docs/1.13/getting-started/#AllinoneDockerimage),
 as well as deployment options for [Kubernetes](https://github.com/jaegertracing/jaeger-kubernetes)
 and [OpenShift](https://github.com/jaegertracing/jaeger-openshift).
 
@@ -27,8 +27,8 @@ and [OpenShift](https://github.com/jaegertracing/jaeger-openshift).
 GitLab provides an easy way to open the Jaeger UI from within your project:
 
 1. [Set up Jaeger](#deploying-jaeger) and configure your application using one of the
-   [client libraries](https://www.jaegertracing.io/docs/latest/client-libraries/).
+   [client libraries](https://www.jaegertracing.io/docs/1.13/client-libraries/).
 1. Navigate to your project's **Settings > Operations** and provide the Jaeger URL.
 1. Click **Save changes** for the changes to take effect.
 1. You can now visit **Operations > Tracing** in your project's sidebar and
-   GitLab will redirect you to the configured Jaeger URL.
\ No newline at end of file
+   GitLab will redirect you to the configured Jaeger URL.
diff --git a/doc/user/project/packages/img/npm_package_view.png b/doc/user/project/packages/img/npm_package_view.png
index 8baf7d0ef9f..e0634718c02 100644
--- a/doc/user/project/packages/img/npm_package_view.png
+++ b/doc/user/project/packages/img/npm_package_view.png
diff --git a/doc/user/project/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md
index 9b7af738696..c61402afb2c 100644
--- a/doc/user/project/packages/maven_repository.md
+++ b/doc/user/project/packages/maven_repository.md
@@ -1,4 +1,4 @@
-# GitLab Maven Repository **[PREMIUM]**
+# GitLab Maven Repository **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5811) in
   [GitLab Premium](https://about.gitlab.com/pricing/) 11.3.
@@ -12,7 +12,7 @@ project can have its own space to store its Maven artifacts.
 
 NOTE: **Note:**
 This option is available only if your GitLab administrator has
-[enabled support for the Maven repository](../../../administration/packages.md).**[PREMIUM ONLY]**
+[enabled support for the Maven repository](../../../administration/packages.md).**(PREMIUM ONLY)**
 
 After the Packages feature is enabled, the Maven Repository will be available for
 all new projects by default. To enable it for existing projects, or if you want
@@ -198,7 +198,7 @@ domain name.
 NOTE: **Note:**
 For retrieving artifacts, you can use either the
 [URL encoded](../../../api/README.md#namespaced-path-encoding) path of the group
-(e.g., `group%2Fsubgroup`) or the group's ID (e.g., `12`). 
+(e.g., `group%2Fsubgroup`) or the group's ID (e.g., `12`).
 
 ### Instance level Maven endpoint
 
@@ -279,59 +279,59 @@ shows how to create a new package each time the `master` branch is updated:
    Add the server section with the same id you defined in your `pom.xml` file.
    For example, in our case it's `gitlab-maven`:
 
-    ```xml
-    <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
-      <servers>
-        <server>
-          <id>gitlab-maven</id>
-          <configuration>
-            <httpHeaders>
-              <property>
-                <name>Job-Token</name>
-                <value>${env.CI_JOB_TOKEN}</value>
-              </property>
-            </httpHeaders>
-          </configuration>
-        </server>
-      </servers>
-    </settings>
-    ```
+   ```xml
+   <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+     xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
+     <servers>
+       <server>
+         <id>gitlab-maven</id>
+         <configuration>
+           <httpHeaders>
+             <property>
+               <name>Job-Token</name>
+               <value>${env.CI_JOB_TOKEN}</value>
+             </property>
+           </httpHeaders>
+         </configuration>
+       </server>
+     </servers>
+   </settings>
+   ```
 
 1. Make sure your `pom.xml` file includes the following:
 
-    ```xml
-    <repositories>
-      <repository>
-        <id>gitlab-maven</id>
-        <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url>
-      </repository>
-    </repositories>
-    <distributionManagement>
-      <repository>
-        <id>gitlab-maven</id>
-        <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url>
-      </repository>
-      <snapshotRepository>
-        <id>gitlab-maven</id>
-        <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url>
-      </snapshotRepository>
-    </distributionManagement>
-    ```
-
-    TIP: **Tip:**
-    You can either let Maven utilize the CI environment variables or hardcode your project's ID.
+   ```xml
+   <repositories>
+     <repository>
+       <id>gitlab-maven</id>
+       <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url>
+     </repository>
+   </repositories>
+   <distributionManagement>
+     <repository>
+       <id>gitlab-maven</id>
+       <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url>
+     </repository>
+     <snapshotRepository>
+       <id>gitlab-maven</id>
+       <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url>
+     </snapshotRepository>
+   </distributionManagement>
+   ```
+
+   TIP: **Tip:**
+   You can either let Maven utilize the CI environment variables or hardcode your project's ID.
 
 1. Add a `deploy` job to your `.gitlab-ci.yml` file:
 
-    ```yaml
-    deploy:
-      image: maven:3.3.9-jdk-8
-      script:
-        - 'mvn deploy -s ci_settings.xml'
-      only:
-        - master
-    ```
+   ```yaml
+   deploy:
+     image: maven:3.3.9-jdk-8
+     script:
+       - 'mvn deploy -s ci_settings.xml'
+     only:
+       - master
+   ```
 
 1. Push those files to your repository.
 
diff --git a/doc/user/project/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md
index 2e274573434..e01bac6b26f 100644
--- a/doc/user/project/packages/npm_registry.md
+++ b/doc/user/project/packages/npm_registry.md
@@ -1,4 +1,4 @@
-# GitLab NPM Registry **[PREMIUM]**
+# GitLab NPM Registry **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5934)
   in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7.
@@ -11,16 +11,11 @@ project can have its own space to store NPM packages.
 NOTE: **Note:**
 Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported.
 
-
-NOTE: **Note:**
-As `@group/subgroup/project` is not a valid NPM package name, publishing a package 
-within a subgroup is not supported yet. 
-
 ## Enabling the NPM Registry
 
 NOTE: **Note:**
 This option is available only if your GitLab administrator has
-[enabled support for the NPM registry](../../../administration/packages.md).**[PREMIUM ONLY]**
+[enabled support for the NPM registry](../../../administration/packages.md).**(PREMIUM ONLY)**
 
 After the NPM registry is enabled, it will be available for all new projects
 by default. To enable it for existing projects, or if you want to disable it:
@@ -36,12 +31,15 @@ get familiar with the package naming convention.
 
 ## Package naming convention
 
-**Only packages that have the same path as the project** are supported. For
- example:
+**Packages must be scoped in the root namespace of the project**. The package
+name may be anything but it is preferred that the project name be used unless
+it is not possible due to a naming collision. For example:
 
 | Project                | Package                 | Supported |
 | ---------------------- | ----------------------- | --------- |
 | `foo/bar`              | `@foo/bar`              | Yes       |
+| `foo/bar/baz`          | `@foo/baz`              | Yes       |
+| `foo/bar/buz`          | `@foo/anything`         | Yes       |
 | `gitlab-org/gitlab-ce` | `@gitlab-org/gitlab-ce` | Yes       |
 | `gitlab-org/gitlab-ce` | `@foo/bar`              | No        |
 
@@ -51,41 +49,42 @@ Registry.
 ## Authenticating to the GitLab NPM Registry
 
 If a project is private or you want to upload an NPM package to GitLab,
-credentials will need to be provided for authentication. Support is available
-only for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow).
+credentials will need to be provided for authentication. Support is available for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow) or [personal access tokens](../../profile/personal_access_tokens.md).
 
-CAUTION: **2FA not supported:**
-Authentication for personal access tokens is not yet supported
-([#9140](https://gitlab.com/gitlab-org/gitlab-ee/issues/9140)). If you have 2FA
-enabled, you won't be able to authenticate to the GitLab NPM Registry.
+CAUTION: **2FA is only supported with personal access tokens:**
+If you have 2FA enabled, you need to use a [personal access token](../../profile/personal_access_tokens.md) with OAuth headers. Standard OAuth tokens won't be able to authenticate to the GitLab NPM Registry.
 
 ### Authenticating with an OAuth token
 
-To authenticate with an [OAuth token](../../../api/oauth2.md#resource-owner-password-credentials-flow),
-add a corresponding section to your `.npmrc` file:
+To authenticate with an [OAuth token](../../../api/oauth2.md#resource-owner-password-credentials-flow)
+or [personal access token](../../profile/personal_access_tokens.md), add a corresponding section to your `.npmrc` file:
 
 ```ini
 ; Set URL for your scoped packages.
 ; For example package with name `@foo/bar` will use this URL for download
 @foo:registry=https://gitlab.com/api/v4/packages/npm/
 
-; Add the OAuth token for the scoped packages URL. This will allow you to download
+; Add the token for the scoped packages URL. This will allow you to download
 ; `@foo/` packages from private projects.
-//gitlab.com/api/v4/packages/npm/:_authToken=<your_oauth_token>
+//gitlab.com/api/v4/packages/npm/:_authToken=<your_token>
 
-; Add OAuth token for uploading to the registry. Replace <your_project_id>
+; Add token for uploading to the registry. Replace <your_project_id>
 ; with the project you want your package to be uploaded to.
-//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_oauth_token>
+//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_token>
 ```
 
 Replace `<your_project_id>` with your project ID which can be found on the home page
-of your project and `<your_oauth_token>` with your OAuth token.
+of your project and `<your_token>` with your OAuth or personal access token.
 
 If you have a self-hosted GitLab installation, replace `gitlab.com` with your
 domain name.
 
 You should now be able to download and upload NPM packages to your project.
 
+NOTE: **Note:**
+If you encounter an error message with [Yarn](https://yarnpkg.com/en/), see the
+[troubleshooting section](#troubleshooting).
+
 ## Uploading packages
 
 Before you will be able to upload a package, you need to specify the registry
@@ -113,8 +112,37 @@ npm publish
 You can then navigate to your project's **Packages** page and see the uploaded
 packages or even delete them.
 
+If you attempt to publish a package with a name that already exists within
+a given scope, you will receive a `403 Forbidden!` error.
+
 ## Uploading a package with the same version twice
 
 If you upload a package with a same name and version twice, GitLab will show
 both packages in the UI, but the GitLab NPM Registry will expose the most recent
 one as it supports only one package per version for `npm install`.
+
+## Troubleshooting
+
+### Error running yarn with NPM registry
+
+If you are using [yarn](https://yarnpkg.com/en/) with the NPM registry, you may get
+an error message like:
+
+```sh
+yarn install v1.15.2
+warning package.json: No license field
+info No lockfile found.
+warning XXX: No license field
+[1/4] 🔍  Resolving packages...
+[2/4] 🚚  Fetching packages...
+error An unexpected error occurred: "https://gitlab.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: Request failed \"404 Not Found\"".
+info If you think this is a bug, please open a bug report with the information provided in "/Users/XXX/gitlab-migration/module-util/yarn-error.log".
+info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command
+```
+
+In this case, try adding this to your `.npmrc` file (and replace `<your_oauth_token>`
+with your with your OAuth or personal access token):
+
+```text
+//gitlab.com/api/v4/projects/:_authToken=<your_oauth_token>
+```
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md
new file mode 100644
index 00000000000..3b80370d4a9
--- /dev/null
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md
@@ -0,0 +1,95 @@
+---
+type: concepts
+---
+
+# DNS records overview
+
+_Read this document for a brief overview of DNS records in the scope
+of GitLab Pages, for beginners in web development._
+
+A Domain Name System (DNS) web service routes visitors to websites
+by translating domain names (such as `www.example.com`) into the
+numeric IP addresses (such as `192.0.2.1`) that computers use to
+connect to each other.
+
+A DNS record is created to point a (sub)domain to a certain location,
+which can be an IP address or another domain. In case you want to use
+GitLab Pages with your own (sub)domain, you need to access your domain's
+registrar control panel to add a DNS record pointing it back to your
+GitLab Pages site.
+
+Note that **how to** add DNS records depends on which server your domain
+is hosted on. Every control panel has its own place to do it. If you are
+not an admin of your domain, and don't have access to your registrar,
+you'll need to ask for the technical support of your hosting service
+to do it for you.
+
+To help you out, we've gathered some instructions on how to do that
+for the most popular hosting services:
+
+- [Amazon](http://docs.aws.amazon.com/gettingstarted/latest/swh/getting-started-configure-route53.html)
+- [Bluehost](https://my.bluehost.com/cgi/help/559)
+- [CloudFlare](https://support.cloudflare.com/hc/en-us/articles/200169096-How-do-I-add-A-records-)
+- [cPanel](https://documentation.cpanel.net/display/ALD/Edit+DNS+Zone)
+- [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215414867-How-do-I-add-custom-DNS-records-)
+- [Go Daddy](https://www.godaddy.com/help/add-an-a-record-19238)
+- [Hostgator](http://support.hostgator.com/articles/changing-dns-records)
+- [Inmotion hosting](https://my.bluehost.com/cgi/help/559)
+- [Media Temple](https://mediatemple.net/community/products/dv/204403794/how-can-i-change-the-dns-records-for-my-domain)
+- [Microsoft](https://msdn.microsoft.com/en-us/library/bb727018.aspx)
+
+If your hosting service is not listed above, you can just try to
+search the web for `how to add dns record on <my hosting service>`.
+
+## `A` record
+
+A DNS A record maps a host to an IPv4 IP address.
+It points a root domain as `example.com` to the host's IP address as
+`192.192.192.192`.
+
+Example:
+
+- `example.com` => `A` => `192.192.192.192`
+
+## CNAME record
+
+CNAME records define an alias for canonical name for your server (one defined
+by an A record). It points a subdomain to another domain.
+
+Example:
+
+- `www` => `CNAME` => `example.com`
+
+This way, visitors visiting `www.example.com` will be redirected to
+`example.com`.
+
+## MX record
+
+MX records are used to define the mail exchanges that are used for the domain.
+This helps email messages arrive at your mail server correctly.
+
+Example:
+
+- `MX` => `mail.example.com`
+
+Then you can register emails for `users@mail.example.com`.
+
+## TXT record
+
+A `TXT` record can associate arbitrary text with a host or other name. A common
+use is for site verification.
+
+Example:
+
+- `example.com`=> TXT => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"`
+
+This way, you can verify the ownership for that domain name.
+
+## All combined
+
+You can have one DNS record or more than one combined:
+
+- `example.com` => `A` => `192.192.192.192`
+- `www` => `CNAME` => `example.com`
+- `MX` => `mail.example.com`
+- `example.com`=> TXT => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"`
\ No newline at end of file
diff --git a/doc/user/project/pages/img/add_certificate_to_pages.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png
index d92a981dc60..d92a981dc60 100644
--- a/doc/user/project/pages/img/add_certificate_to_pages.png
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png
diff --git a/doc/user/project/pages/img/dns_add_new_a_record_example_updated_2018.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_add_new_a_record_example_updated_2018.png
index 0150329d4b2..0150329d4b2 100644
--- a/doc/user/project/pages/img/dns_add_new_a_record_example_updated_2018.png
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_add_new_a_record_example_updated_2018.png
diff --git a/doc/user/project/pages/img/dns_cname_record_example.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_cname_record_example.png
index 43d1a838544..43d1a838544 100644
--- a/doc/user/project/pages/img/dns_cname_record_example.png
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_cname_record_example.png
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/get_domain_verification_code_v12_0.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/get_domain_verification_code_v12_0.png
new file mode 100644
index 00000000000..3b93572a8f1
--- /dev/null
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/get_domain_verification_code_v12_0.png
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/lets_encrypt_integration_v12_1.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/lets_encrypt_integration_v12_1.png
new file mode 100644
index 00000000000..5eab04a61a9
--- /dev/null
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/lets_encrypt_integration_v12_1.png
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/retry_domain_verification_v12_0.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/retry_domain_verification_v12_0.png
new file mode 100644
index 00000000000..5f2f100e883
--- /dev/null
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/retry_domain_verification_v12_0.png
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md
new file mode 100644
index 00000000000..1821d954af3
--- /dev/null
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md
@@ -0,0 +1,276 @@
+---
+last_updated: 2019-07-04
+type: reference, howto
+disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html'
+---
+
+# Custom domains and SSL/TLS Certificates
+
+Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages.
+
+To use one or more custom domain names with your Pages site, you can:
+
+- Add a [custom **root domain** or a **subdomain**](#set-up-pages-with-a-custom-domain).
+- Add [SSL/TLS certification](#adding-an-ssltls-certificate-to-pages).
+
+## Set up Pages with a custom domain
+
+To set up Pages with a custom domain name, read the requirements
+and steps below.
+
+### Requirements
+
+- A GitLab Pages website up and running, served under the default Pages domain
+  (`*.gitlab.io`, for GitLab.com).
+- A custom domain name `example.com` or subdomain `subdomain.example.com`.
+- Access to your domain's server control panel to set up DNS records:
+  - A DNS A or CNAME record poiting your domain to GitLab Pages server.
+  - A DNS TXT record to verify your domain's ownership.
+
+### Steps
+
+Follow the steps below to add your custom domain to Pages. See also
+this document for an [overview on DNS records](dns_concepts.md).
+
+#### 1. Add a custom domain to Pages
+
+Navigate to your project's **Setting > Pages** and click **+ New domain**
+to add your custom domain to GitLab Pages. You can choose whether to:
+
+- Add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages).
+- Leave it blank (it can be added later).
+
+Click **Create New Domain**.
+
+![Add new domain](img/add_certificate_to_pages.png)
+
+#### 2. Get the verification code
+
+Once you have added a new domain to Pages, the verification code will be prompted to you. Copy the values from GitLab and paste them in your domain's control panel as a TXT record on the next step.
+
+![Get the verification code](img/get_domain_verification_code_v12_0.png)
+
+#### 3. Set up DNS records for Pages
+
+Read this document for an [overview of DNS records for Pages](dns_concepts.md).
+If you're familiar with the subject, follow the instructions below
+according to the type of domain you want to use with your Pages site:
+
+- [For root domains](#for-root-domains), `example.com`.
+- [For subdomains](#for-subdomains), `subdomain.example.com`.
+- [For both](#for-both-root-and-subdomains).
+
+##### For root domains
+
+Root domains (`example.com`) require:
+
+- A [DNS A record](dns_concepts.md#a-record) pointing your domain to the Pages server.
+- A [TXT record](dns_concepts.md#txt-record) to verify your domain's ownership.
+
+| From | DNS Record | To |
+| ---- | ---------- | -- |
+| example.com | A | 35.185.44.232 |
+| _gitlab-pages-verification-code.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff |
+
+For projects on GitLab.com, this IP is `35.185.44.232`.
+For projects living in other GitLab instances (CE or EE), please contact
+your sysadmin asking for this information (which IP address is Pages
+server running on your instance).
+
+![DNS A record pointing to GitLab.com Pages server](img/dns_add_new_a_record_example_updated_2018.png)
+
+CAUTION: **Caution:**
+Note that if you use your root domain for your GitLab Pages website
+**only**, and if your domain registrar supports this feature, you can
+add a DNS apex `CNAME` record instead of an `A` record. The main
+advantage of doing so is that when GitLab Pages IP on GitLab.com
+changes for whatever reason, you don't need to update your `A` record.
+There may be a few exceptions, but **this method is not recommended**
+as it most likely won't work if you set an [`MX` record](dns_concepts.md#mx-record) for your root domain.
+
+##### For subdomains
+
+Subdomains (`subdomain.example.com`) require:
+
+- A DNS [CNAME record](dns_concepts.md#cname-record) record pointing your subdomain to the Pages server.
+- A DNS [TXT record](dns_concepts.md#txt-record) to verify your domain's ownership.
+
+| From | DNS Record | To |
+| ---- | ---------- | -- |
+| subdomain.example.com | CNAME | namespace.gitlab.io |
+| _gitlab-pages-verification-code.subdomain.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff |
+
+Note that, whether it's a user or a project website, the `CNAME`
+should point to your Pages domain (`namespace.gitlab.io`),
+without any `/project-name`.
+
+![DNS CNAME record pointing to GitLab.com project](img/dns_cname_record_example.png)
+
+##### For both root and subdomains
+
+There are a few cases where you need point both subdomain and root
+domain to the same website, for instance, `example.com` and `www.example.com`.
+
+They require:
+
+- A DNS A record for the domain.
+- A DNS CNAME record for the subdomain.
+- A DNS TXT record for each.
+
+| From | DNS Record | To |
+| ---- | ---------- | -- |
+| example.com | A | 35.185.44.232 |
+| _gitlab-pages-verification-code.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff |
+|---+---|
+| www.example.com | CNAME | namespace.gitlab.io |
+| _gitlab-pages-verification-code.www.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff |
+
+If you're using CloudFlare, check
+[Redirecting `www.domain.com` to `domain.com` with Cloudflare](#redirecting-wwwdomaincom-to-domaincom-with-cloudflare).
+
+> **Notes**:
+>
+> - **Do not** use a CNAME record if you want to point your
+  `domain.com` to your GitLab Pages site. Use an `A` record instead.
+> - **Do not** add any special chars after the default Pages
+  domain. E.g., don't point `subdomain.domain.com` to
+  or `namespace.gitlab.io/`. Some domain hosting providers may request a trailling dot (`namespace.gitlab.io.`), though.
+> - GitLab Pages IP on GitLab.com [was changed](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) in 2017.
+> - GitLab Pages IP on GitLab.com [has changed](https://about.gitlab.com/2018/07/19/gcp-move-update/#gitlab-pages-and-custom-domains)
+  from `52.167.214.135` to `35.185.44.232` in 2018.
+
+#### 4. Verify the domain's ownership
+
+Once you have added all the DNS records:
+
+1. Go back at your project's **Settings > Pages**.
+1. Locate your domain name and click **Details**.
+1. Click the **Retry verification** button to activate your new domain.
+
+![Verify your domain](img/retry_domain_verification_v12_0.png)
+
+As soon as your domain becomes active, your website will be available
+through your domain name.
+
+CAUTION: **Caution:**
+Considering GitLab instances with domain verification enabled,
+if the domain cannot be verified for 7 days, it will be removed
+from the GitLab project.
+
+> **Notes:**
+>
+> - Domain verification is **required for GitLab.com users**;
+  for GitLab self-managed instances, your GitLab administrator has the option
+  to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification).
+> - [DNS propagation may take some time (up to 24h)](http://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes),
+  although it's usually a matter of minutes to complete. Until it does, verification
+  will fail and attempts to visit your domain will respond with a 404.
+> - Once your domain has been verified, leave the verification record
+  in place: your domain will be periodically reverified, and may be
+  disabled if the record is removed.
+
+### Adding more domain aliases
+
+You can add more than one alias (custom domains and subdomains) to the same project.
+An alias can be understood as having many doors leading to the same room.
+
+All the aliases you've set to your site will be listed on **Setting > Pages**.
+From that page, you can view, add, and remove them.
+
+### Redirecting `www.domain.com` to `domain.com` with Cloudflare
+
+If you use Cloudflare, you can redirect `www` to `domain.com`
+without adding both `www.domain.com` and `domain.com` to GitLab.
+
+To do so, you can use Cloudflare's page rules associated to a
+CNAME record to redirect `www.domain.com` to `domain.com`. You
+can use the following setup:
+
+1. In Cloudflare, create a DNS `A` record pointing `domain.com` to `35.185.44.232`.
+1. In GitLab, add the domain to GitLab Pages and get the verification code.
+1. In Cloudflare, create a DNS `TXT` record to verify your domain.
+1. In GitLab, verify your domain.
+1. In Cloudflare, create a DNS `CNAME` record pointing `www` to `domain.com`.
+1. In Cloudflare, add a Page Rule pointing `www.domain.com` to `domain.com`:
+   - Navigate to your domain's dashboard and click **Page Rules**
+     on the top nav.
+   - Click **Create Page Rule**.
+   - Enter the domain `www.domain.com` and click **+ Add a Setting**.
+   - From the dropdown menu, choose **Forwarding URL**, then select the
+     status code **301 - Permanent Redirect**.
+   - Enter the destination URL `https://domain.com`.
+
+## Adding an SSL/TLS certificate to Pages
+
+Read this document for an [overview on SSL/TLS certification](ssl_tls_concepts.md).
+
+To secure your custom domain with GitLab Pages you can opt by:
+
+- Using the [Let's Encrypt integration with GitLab Pages](lets_encrypt_integration.md),
+  which automatically obtains and renews SSL certificates
+  for your Pages domains.
+- Manually adding SSL/TLS certificates to GitLab Pages websites
+  by following the steps below.
+
+### Requirements
+
+- A GitLab Pages website up and running accessible via a custom domain.
+- **A PEM certificate**: it is the certificate generated by the CA,
+  which needs to be added to the field **Certificate (PEM)**.
+- **An [intermediate certificate](https://en.wikipedia.org/wiki/Intermediate_certificate_authority)**: (aka "root certificate"), it is
+  the part of the encryption keychain that identifies the CA.
+  Usually it's combined with the PEM certificate, but there are
+  some cases in which you need to add them manually.
+  [CloudFlare certs](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/)
+  are one of these cases.
+- **A private key**, it's an encrypted key which validates
+  your PEM against your domain.
+
+### Steps
+
+- To add the certificate at the time you add a new domain, go to your
+  project's **Settings > Pages > New Domain**, add the domain name and the certificate.
+- To add the certificate to a domain previously added, go to your
+  project's **Settings > Pages**, locate your domain name, click **Details** and **Edit** to add the certificate.
+
+![Pages project - adding certificates](img/add_certificate_to_pages.png)
+
+1. Add the PEM certificate to its corresponding field.
+1. If your certificate is missing its intermediate, copy
+  and paste the root certificate (usually available from your CA website)
+  and paste it in the [same field as your PEM certificate](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/),
+  just jumping a line between them.
+1. Copy your private key and paste it in the last field.
+
+NOTE: **Note:**
+**Do not** open certificates or encryption keys in
+regular text editors. Always use code editors (such as
+Sublime Text, Atom, Dreamweaver, Brackets, etc).
+
+## Force HTTPS for GitLab Pages websites
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28857) in GitLab 10.7.
+
+To make your website's visitors even more secure, you can choose to
+force HTTPS for GitLab Pages. By doing so, all attempts to visit your
+website via HTTP will be automatically redirected to HTTPS via 301.
+
+It works with both GitLab's default domain and with your custom
+domain (as long as you've set a valid certificate for it).
+
+To enable this setting:
+
+1. Navigate to your project's **Settings > Pages**.
+1. Tick the checkbox **Force HTTPS (requires valid certificates)**.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md
new file mode 100644
index 00000000000..255d535645d
--- /dev/null
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md
@@ -0,0 +1,87 @@
+---
+type: reference
+description: "Automatic Let's Encrypt SSL certificates for GitLab Pages."
+---
+
+# GitLab Pages integration with Let's Encrypt
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28996) in GitLab 12.1.
+
+The GitLab Pages integration with Let's Encrypt (LE) allows you
+to use LE certificates for your Pages website with custom domains
+without the hassle of having to issue and update them yourself;
+GitLab does it for you, out-of-the-box.
+
+[Let's Encrypt](https://letsencrypt.org) is a free, automated, and
+open source Certificate Authority.
+
+CAUTION: **Caution:**
+This feature is in **beta** and might present bugs and UX issues
+such as [#64870](https://gitlab.com/gitlab-org/gitlab-ce/issues/64870).
+See all the related issues linked from this [issue's description](https://gitlab.com/gitlab-org/gitlab-ce/issues/28996)
+for more information.
+
+## Requirements
+
+Before you can enable automatic provisioning of a SSL certificate for your domain, make sure you have:
+
+- Created a [project](../getting_started_part_two.md) in GitLab
+  containing your website's source code.
+- Acquired a domain (`example.com`) and added a [DNS entry](index.md)
+  pointing it to your Pages website.
+- [Added your domain to your Pages project](index.md#1-add-a-custom-domain-to-pages)
+  and verified your ownership.
+- Have your website up and running, accessible through your custom domain.
+
+NOTE: **Note:**
+GitLab's Let's Encrypt integration is enabled and available on GitLab.com.
+For **self-managed** GitLab instances, make sure your administrator has
+[enabled it](../../../../administration/pages/index.md#lets-encrypt-integration).
+
+## Enabling Let's Encrypt integration for your custom domain
+
+Once you've met the requirements, to enable Let's Encrypt integration:
+
+1. Navigate to your project's **Settings > Pages**.
+1. Find your domain and click **Details**.
+1. Click **Edit** in the top-right corner.
+1. Enable Let's Encrypt integration by switching **Automatic certificate management using Let's Encrypt**:
+
+   ![Enable Let's Encrypt](img/lets_encrypt_integration_v12_1.png)
+
+1. Click **Save changes**.
+
+Once enabled, GitLab will obtain a LE certificate and add it to the
+associated Pages domain. It will be also renewed automatically by GitLab.
+
+> **Notes:**
+>
+> - Issuing the certificate and updating Pages configuration
+>   **can take up to an hour**.
+> - If you already have SSL certificate in domain settings it
+>   will continue to work until it will be replaced by Let's Encrypt's certificate.
+
+## Troubleshooting
+
+### Error "Certificate misses intermediates"
+
+If you get an error **Certificate misses intermediates** while trying to enable Let's Encrypt integration for your domain, follow the steps below:
+
+1. Go to your project's **Settings > Pages**.
+1. Turn off **Force HTTPS** if it's turned on.
+1. Click **Details** on your domain.
+1. Click the **Edit** button in the top right corner of domain details page.
+1. Enable Let's Encrypt integration.
+1. Click **Save**.
+1. Go to your project's **Settings > Pages**.
+1. Turn on **Force HTTPS**.
+
+<!-- Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md
new file mode 100644
index 00000000000..ee0550bfca2
--- /dev/null
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md
@@ -0,0 +1,75 @@
+---
+type: concepts
+---
+
+# SSL/TLS Certificates
+
+_Read this document for a brief overview of SSL/TLS certificates in
+the scope of GitLab Pages, for beginners in web development._
+
+Every GitLab Pages project on GitLab.com will be available under
+HTTPS for the default Pages domain (`*.gitlab.io`). Once you set
+up your Pages project with your custom (sub)domain, if you want
+it secured by HTTPS, you will have to issue a certificate for that
+(sub)domain and install it on your project.
+
+NOTE: **Note:**
+Certificates are NOT required to add to your custom
+(sub)domain on your GitLab Pages project, though they are
+highly recommendable.
+
+Let's start with an introduction to the importance of HTTPS.
+
+## Why should I care about HTTPS?
+
+This might be your first question. If our sites are hosted by GitLab Pages,
+they are static, hence we are not dealing with server-side scripts
+nor credit card transactions, then why do we need secure connections?
+
+Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special"
+security measure, necessary just for big companies, like banks and shoppings sites
+with financial transactions.
+Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group):
+
+> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](http://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._
+
+Therefore, the reason why certificates are so important is that they encrypt
+the connection between the **client** (you, me, your visitors)
+and the **server** (where you site lives), through a keychain of
+authentications and validations.
+
+How about taking Josh's advice and protecting our sites too? We will be
+well supported, and we'll contribute to a safer internet.
+
+## Organizations supporting HTTPS
+
+There is a huge movement in favor of securing all the web. W3C fully
+[supports the cause](https://w3ctag.github.io/web-https/) and explains very well
+the reasons for that. Richard Barnes, a writer for Mozilla Security Blog,
+suggested that [Firefox would deprecate HTTP](https://blog.mozilla.org/security/2015/04/30/deprecating-non-secure-http/),
+and would no longer accept unsecured connections. Recently, Mozilla published a
+[communication](https://blog.mozilla.org/security/2016/03/29/march-2016-ca-communication/)
+reiterating the importance of HTTPS.
+
+## Issuing Certificates
+
+GitLab Pages accepts certificates provided in the [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) format, issued by
+[Certificate Authorities (CAs)](https://en.wikipedia.org/wiki/Certificate_authority) or as
+[self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://securingtomorrow.mcafee.com/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/)
+for public websites for security reasons and to ensure that browsers trust your site's certificate.
+
+There are various kinds of certificates, each one
+with a certain security level. A static personal website will
+not require the same security level as an online banking web app,
+for instance.
+
+There are some certificate authorities that
+offer free certificates, aiming to make the internet more secure
+to everyone. The most popular is [Let's Encrypt](https://letsencrypt.org/),
+which issues certificates trusted by most of browsers, it's open
+source, and free to use. See [GitLab Pages integration with Let's Encrypt](../custom_domains_ssl_tls_certification/lets_encrypt_integration.md) to enable HTTPS on your custom domain.
+
+Similarly popular are [certificates issued by CloudFlare](https://www.cloudflare.com/ssl/),
+which also offers a [free CDN service](https://blog.cloudflare.com/cloudflares-free-cdn-and-you/).
+Their certs are valid up to 15 years. See the tutorial on
+[how to add a CloudFlare Certificate to your GitLab Pages website](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/).
diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md
index 8baf41dba78..d844d4222b1 100644
--- a/doc/user/project/pages/getting_started_part_four.md
+++ b/doc/user/project/pages/getting_started_part_four.md
@@ -380,7 +380,7 @@ What you can do with GitLab CI is pretty much up to your
 creativity. Once you get used to it, you start creating
 awesome scripts that automate most of tasks you'd do
 manually in the past. Read through the
-[documentation of GitLab CI](https://docs.gitlab.com/ce/ci/yaml/README.html)
+[documentation of GitLab CI](../../../ci/yaml/README.md)
 to understand how to go even further on your scripts.
 
 - On this blog post, understand the concept of
diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md
index d585c19fc5c..9bc9fe97fd3 100644
--- a/doc/user/project/pages/getting_started_part_three.md
+++ b/doc/user/project/pages/getting_started_part_three.md
@@ -1,303 +1 @@
----
-last_updated: 2019-06-04
-type: concepts, reference, howto
----
-
-# GitLab Pages custom domains and SSL/TLS Certificates
-
-Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages.
-
-These steps assume you've already [set your site up](getting_started_part_two.md) and it's served under the default Pages domain `namespace.gitlab.io`, or `namespace.gitlab.io/project-name`.
-
-## Adding your custom domain to GitLab Pages
-
-To use one or more custom domain with your Pages site, there are two things
-you should consider first, which we'll cover in this guide:
-
-1. Either if you're adding a **root domain** or a **subdomain**, for which
-   you'll need to set up [DNS records](#dns-records)
-1. Whether you want to add an [SSL/TLS certificate](#ssltls-certificates) or not
-
-To finish the association, you need to [add your domain to your project's Pages settings](#add-your-custom-domain-to-gitlab-pages-settings).
-
-Let's start from the beginning with [DNS records](#dns-records).
-If you already know how they work and want to skip the introduction to DNS,
-you may be interested in skipping it until the [TL;DR](#tldr) section below.
-
-### DNS Records
-
-A Domain Name System (DNS) web service routes visitors to websites
-by translating domain names (such as `www.example.com`) into the
-numeric IP addresses (such as `192.0.2.1`) that computers use to
-connect to each other.
-
-A DNS record is created to point a (sub)domain to a certain location,
-which can be an IP address or another domain. In case you want to use
-GitLab Pages with your own (sub)domain, you need to access your domain's
-registrar control panel to add a DNS record pointing it back to your
-GitLab Pages site.
-
-Note that **how to** add DNS records depends on which server your domain
-is hosted on. Every control panel has its own place to do it. If you are
-not an admin of your domain, and don't have access to your registrar,
-you'll need to ask for the technical support of your hosting service
-to do it for you.
-
-To help you out, we've gathered some instructions on how to do that
-for the most popular hosting services:
-
-- [Amazon](http://docs.aws.amazon.com/gettingstarted/latest/swh/getting-started-configure-route53.html)
-- [Bluehost](https://my.bluehost.com/cgi/help/559)
-- [CloudFlare](https://support.cloudflare.com/hc/en-us/articles/200169096-How-do-I-add-A-records-)
-- [cPanel](https://documentation.cpanel.net/display/ALD/Edit+DNS+Zone)
-- [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215414867-How-do-I-add-custom-DNS-records-)
-- [Go Daddy](https://www.godaddy.com/help/add-an-a-record-19238)
-- [Hostgator](http://support.hostgator.com/articles/changing-dns-records)
-- [Inmotion hosting](https://my.bluehost.com/cgi/help/559)
-- [Media Temple](https://mediatemple.net/community/products/dv/204403794/how-can-i-change-the-dns-records-for-my-domain)
-- [Microsoft](https://msdn.microsoft.com/en-us/library/bb727018.aspx)
-
-If your hosting service is not listed above, you can just try to
-search the web for `how to add dns record on <my hosting service>`.
-
-#### DNS A record
-
-In case you want to point a root domain (`example.com`) to your
-GitLab Pages site, deployed to `namespace.gitlab.io`, you need to
-log into your domain's admin control panel and add a DNS `A` record
-pointing your domain to Pages' server IP address. For projects on
-GitLab.com, this IP is `35.185.44.232`. For projects living in
-other GitLab instances (CE or EE), please contact your sysadmin
-asking for this information (which IP address is Pages server
-running on your instance).
-
-**Practical Example:**
-
-![DNS A record pointing to GitLab.com Pages server](img/dns_add_new_a_record_example_updated_2018.png)
-
-CAUTION: **Caution:**
-Note that if you use your root domain for your GitLab Pages website
-**only**, and if your domain registrar supports this feature, you can
-add a DNS apex `CNAME` record instead of an `A` record. The main
-advantage of doing so is that when GitLab Pages IP on GitLab.com
-changes for whatever reason, you don't need to update your `A` record.
-There may be a few exceptions, but **this method is not recommended**
-as it most likely won't work if you set an `MX` record for your root domain.
-
-#### DNS CNAME record
-
-In case you want to point a subdomain (`hello-world.example.com`)
-to your GitLab Pages site initially deployed to `namespace.gitlab.io`,
-you need to log into your domain's admin control panel and add a DNS
-`CNAME` record pointing your subdomain to your website URL
-(`namespace.gitlab.io`) address.
-
-Note that, whether it's a user or a project website, the `CNAME`
-should point to your Pages domain (`namespace.gitlab.io`),
-without any `/project-name`.
-
-**Practical Example:**
-
-![DNS CNAME record pointing to GitLab.com project](img/dns_cname_record_example.png)
-
-#### DNS TXT record
-
-Unless your GitLab administrator has [disabled custom domain verification](../../../administration/pages/index.md#custom-domain-verification),
-you'll have to prove that you own the domain by creating a `TXT` record
-containing a verification code. The code will be displayed after you
-[add your custom domain to GitLab Pages settings](#add-your-custom-domain-to-gitlab-pages-settings).
-
-If using a [DNS A record](#dns-a-record), you can place the TXT record directly
-under the domain. If using a [DNS CNAME record](#dns-cname-record), the two record types won't
-co-exist, so you need to place the TXT record in a special subdomain of its own.
-
-If the domain cannot be verified for 7 days, it will be removed from the GitLab project.
-
-#### TL;DR
-
-For root domains (`domain.com`), set a DNS `A` record and verify your
-domain's ownership with a TXT record:
-
-| From | DNS Record | To |
-| ---- | ---------- | -- |
-| domain.com | A | 35.185.44.232 |
-| domain.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff |
-
-For subdomains (`subdomain.domain.com`), set a DNS `CNAME` record and
-verify your domain's ownership with a TXT record:
-
-| From | DNS Record | To |
-| ---- | ---------- | -- |
-| subdomain.domain.com | CNAME | namespace.gitlab.io |
-| _gitlab-pages-verification-code.subdomain.domain.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff |
-
-> **Notes**:
->
-> - **Do not** use a CNAME record if you want to point your
-  `domain.com` to your GitLab Pages site. Use an `A` record instead.
-> - **Do not** add any special chars after the default Pages
-  domain. E.g., **do not** point your `subdomain.domain.com` to
-  `namespace.gitlab.io.` or `namespace.gitlab.io/`.
-> - GitLab Pages IP on GitLab.com [was changed](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) in 2017
-> - GitLab Pages IP on GitLab.com [has been changed](https://about.gitlab.com/2018/07/19/gcp-move-update/#gitlab-pages-and-custom-domains)
-  from `52.167.214.135` to `35.185.44.232` in 2018
-
-### Add your custom domain to GitLab Pages settings
-
-Once you've set the DNS record, you'll need navigate to your project's
-**Setting > Pages** and click **+ New domain** to add your custom domain to
-GitLab Pages. You can choose whether to add an [SSL/TLS certificate](#ssltls-certificates)
-to make your website accessible under HTTPS or leave it blank. If you don't add a certificate,
-your site will be accessible only via HTTP:
-
-![Add new domain](img/add_certificate_to_pages.png)
-
-Once you have added a new domain, you will need to **verify your ownership**
-(unless the GitLab administrator has disabled this feature). A verification code
-will be shown to you; add it as a [DNS TXT record](#dns-txt-record), then press
-the "Verify ownership" button to activate your new domain:
-
-![Verify your domain](img/verify_your_domain.png)
-
-Once your domain has been verified, leave the verification record in place -
-your domain will be periodically reverified, and may be disabled if the record
-is removed.
-
-You can add more than one alias (custom domains and subdomains) to the same project.
-An alias can be understood as having many doors leading to the same room.
-
-All the aliases you've set to your site will be listed on **Setting > Pages**.
-From that page, you can view, add, and remove them.
-
-Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes),
-although it's usually a matter of minutes to complete. Until it does, verification
-will fail and attempts to visit your domain will respond with a 404.
-
-### Redirecting `www.domain.com` to `domain.com` with Cloudflare
-
-If you use Cloudflare, you can redirect `www` to `domain.com` without the need of adding both
-`www.domain.com` and `domain.com` to GitLab. This happens due to a [Cloudflare feature that creates
-a 301 redirect as a "page rule"](https://gitlab.com/gitlab-org/gitlab-ce/issues/48848#note_87314849) for redirecting `www.domain.com` to `domain.com`. In this case,
-you can use the following setup:
-
-- In Cloudflare, create a DNS `A` record pointing `domain.com` to `35.185.44.232`
-- In GitLab, add the domain to GitLab Pages
-- In Cloudflare, create a DNS `TXT` record to verify your domain
-- In Cloudflare, create a DNS `CNAME` record pointing `www` to `domain.com`
-
-## SSL/TLS Certificates
-
-Every GitLab Pages project on GitLab.com will be available under
-HTTPS for the default Pages domain (`*.gitlab.io`). Once you set
-up your Pages project with your custom (sub)domain, if you want
-it secured by HTTPS, you will have to issue a certificate for that
-(sub)domain and install it on your project.
-
->**Note:**
-Certificates are NOT required to add to your custom
-(sub)domain on your GitLab Pages project, though they are
-highly recommendable.
-
-Let's start with an introduction to the importance of HTTPS.
-Alternatively, jump ahead to [adding certificates to your project](#adding-certificates-to-your-project).
-
-### Why should I care about HTTPS?
-
-This might be your first question. If our sites are hosted by GitLab Pages,
-they are static, hence we are not dealing with server-side scripts
-nor credit card transactions, then why do we need secure connections?
-
-Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special"
-security measure, necessary just for big companies, like banks and shoppings sites
-with financial transactions.
-Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group):
-
-> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](http://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._
-
-Therefore, the reason why certificates are so important is that they encrypt
-the connection between the **client** (you, me, your visitors)
-and the **server** (where you site lives), through a keychain of
-authentications and validations.
-
-How about taking Josh's advice and protecting our sites too? We will be
-well supported, and we'll contribute to a safer internet.
-
-### Organizations supporting HTTPS
-
-There is a huge movement in favor of securing all the web. W3C fully
-[supports the cause](https://w3ctag.github.io/web-https/) and explains very well
-the reasons for that. Richard Barnes, a writer for Mozilla Security Blog,
-suggested that [Firefox would deprecate HTTP](https://blog.mozilla.org/security/2015/04/30/deprecating-non-secure-http/),
-and would no longer accept unsecured connections. Recently, Mozilla published a
-[communication](https://blog.mozilla.org/security/2016/03/29/march-2016-ca-communication/)
-reiterating the importance of HTTPS.
-
-## Issuing Certificates
-
-GitLab Pages accepts certificates provided in the [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) format, issued by
-[Certificate Authorities (CAs)](https://en.wikipedia.org/wiki/Certificate_authority) or as
-[self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://securingtomorrow.mcafee.com/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/)
-for public websites for security reasons and to ensure that browsers trust your site's certificate.
-
-There are various kinds of certificates, each one
-with a certain security level. A static personal website will
-not require the same security level as an online banking web app,
-for instance.
-
-There are some certificate authorities that
-offer free certificates, aiming to make the internet more secure
-to everyone. The most popular is [Let's Encrypt](https://letsencrypt.org/),
-which issues certificates trusted by most of browsers, it's open
-source, and free to use. See our tutorial on [how to secure your GitLab Pages website with Let's Encrypt](lets_encrypt_for_gitlab_pages.md).
-
-Similarly popular are [certificates issued by CloudFlare](https://www.cloudflare.com/ssl/),
-which also offers a [free CDN service](https://blog.cloudflare.com/cloudflares-free-cdn-and-you/).
-Their certs are valid up to 15 years. See the tutorial on
-[how to add a CloudFlare Certificate to your GitLab Pages website](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/).
-
-### Adding certificates to your project
-
-Regardless the CA you choose, the steps to add your certificate to
-your Pages project are the same.
-
-### What do you need
-
-1. A PEM certificate
-1. An intermediate certificate
-1. A private key
-
-![Pages project - adding certificates](img/add_certificate_to_pages.png)
-
-These fields are found under your **Project**'s **Settings** > **Pages** > **New Domain**.
-
-### What's what?
-
-- A PEM certificate is the certificate generated by the CA,
-  which needs to be added to the field **Certificate (PEM)**.
-- An [intermediate certificate](https://en.wikipedia.org/wiki/Intermediate_certificate_authority) (aka "root certificate") is
-  the part of the encryption keychain that identifies the CA.
-  Usually it's combined with the PEM certificate, but there are
-  some cases in which you need to add them manually.
-  [CloudFlare certs](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/)
-  are one of these cases.
-- A private key is an encrypted key which validates
-  your PEM against your domain.
-
-### Now what?
-
-Now that you hopefully understand why you need all
-of this, it's simple:
-
-- Your PEM certificate needs to be added to the first field
-- If your certificate is missing its intermediate, copy
-  and paste the root certificate (usually available from your CA website)
-  and paste it in the [same field as your PEM certificate](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/),
-  just jumping a line between them.
-- Copy your private key and paste it in the last field
-
->**Note:**
-**Do not** open certificates or encryption keys in
-regular text editors. Always use code editors (such as
-Sublime Text, Atom, Dreamweaver, Brackets, etc).
-
-_Read on about [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md)_
+This document was moved to [another location](custom_domains_ssl_tls_certification/index.md).
diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md
index 3e50cd4887c..3bab652ca39 100644
--- a/doc/user/project/pages/getting_started_part_two.md
+++ b/doc/user/project/pages/getting_started_part_two.md
@@ -22,7 +22,7 @@ Optional Features:
    1. **Optional**: an SSL/TLS certificate so your custom
    domain is accessible under HTTPS.
 
-The optional settings, custom domain, DNS records, and SSL/TLS certificates, are described in [Part 3](getting_started_part_three.md)).
+The optional settings, custom domain, DNS records, and SSL/TLS certificates, are described in [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md)).
 
 ## Project
 
@@ -77,23 +77,23 @@ containing the most popular SSGs templates to get you started.
 
 1. [Fork](../../../gitlab-basics/fork-project.md) a sample project from the [GitLab Pages examples](https://gitlab.com/pages) group.
 1. From the left sidebar, navigate to your project's **CI/CD > Pipelines**
-and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your
-site to the server.
+   and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your
+   site to the server.
 1. Once the pipeline has finished successfully, find the link to visit your
-website from your project's **Settings > Pages**.
+   website from your project's **Settings > Pages**.
 
 You can also take some **optional** further steps:
 
 - _Remove the fork relationship._ The fork relationship is necessary to contribute back to the project you originally forked from. If you don't have any intentions to do so, you can remove it. To do so, navigate to your project's **Settings**, expand **Advanced settings**, and scroll down to **Remove fork relationship**:
 
-    ![remove fork relationship](img/remove_fork_relationship.png)
+  ![remove fork relationship](img/remove_fork_relationship.png)
 
 - _Make it a user or group website._ To turn a **project website** forked
-from the Pages group into a **user/group** website, you'll need to:
-    - Rename it to `namespace.gitlab.io`: go to your project's
+  from the Pages group into a **user/group** website, you'll need to:
+  - Rename it to `namespace.gitlab.io`: go to your project's
     **Settings > General** and expand **Advanced**. Scroll down to
     **Rename repository** and change the path to `namespace.gitlab.io`.
-    - Adjust your SSG's [base URL](#urls-and-baseurls) from `"project-name"` to
+  - Adjust your SSG's [base URL](#urls-and-baseurls) from `"project-name"` to
     `""`. This setting will be at a different place for each SSG, as each of them
     have their own structure and file tree. Most likely, it will be in the SSG's
     config file.
@@ -107,12 +107,12 @@ from the Pages group into a **user/group** website, you'll need to:
    files to your project, add, commit and push to GitLab.
 1. From the your **Project**'s page, click **Set up CI/CD**:
 
-    ![setup GitLab CI/CD](img/setup_ci.png)
+   ![setup GitLab CI/CD](img/setup_ci.png)
 
 1. Choose one of the templates from the dropbox menu.
    Pick up the template corresponding to the SSG you're using (or plain HTML).
 
-    ![gitlab-ci templates](img/choose_ci_template.png)
+   ![gitlab-ci templates](img/choose_ci_template.png)
 
 Once you have both site files and `.gitlab-ci.yml` in your project's
 root, GitLab CI/CD will build your site and deploy it with Pages.
@@ -123,20 +123,20 @@ where you'll find its default URL.
 > **Notes:**
 >
 > - GitLab Pages [supports any SSG](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/), but,
-  if you don't find yours among the templates, you'll need
-  to configure your own `.gitlab-ci.yml`. To do that, please
-  read through the article [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md). New SSGs are very welcome among
-  the [example projects](https://gitlab.com/pages). If you set
-  up a new one, please
-  [contribute](https://gitlab.com/pages/pages.gitlab.io/blob/master/CONTRIBUTING.md)
-  to our examples.
+>   if you don't find yours among the templates, you'll need
+>   to configure your own `.gitlab-ci.yml`. To do that, please
+>   read through the article [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md). New SSGs are very welcome among
+>   the [example projects](https://gitlab.com/pages). If you set
+>   up a new one, please
+>   [contribute](https://gitlab.com/pages/pages.gitlab.io/blob/master/CONTRIBUTING.md)
+>   to our examples.
 >
 > - The second step _"Clone it to your local computer"_, can be done
-  differently, achieving the same results: instead of cloning the bare
-  repository to you local computer and moving your site files into it,
-  you can run `git init` in your local website directory, add the
-  remote URL: `git remote add origin git@gitlab.com:namespace/project-name.git`,
-  then add, commit, and push to GitLab.
+>   differently, achieving the same results: instead of cloning the bare
+>   repository to you local computer and moving your site files into it,
+>   you can run `git init` in your local website directory, add the
+>   remote URL: `git remote add origin git@gitlab.com:namespace/project-name.git`,
+>   then add, commit, and push to GitLab.
 
 ## URLs and Baseurls
 
@@ -169,4 +169,4 @@ baseurl: ""
 ## Custom Domains
 
 GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS.
-See [GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md) for more information.
+See [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) for more information.
diff --git a/doc/user/project/pages/img/pages_project_templates_11-8.png b/doc/user/project/pages/img/pages_project_templates_11-8.png
deleted file mode 100644
index a645d28260b..00000000000
--- a/doc/user/project/pages/img/pages_project_templates_11-8.png
+++ /dev/null
diff --git a/doc/user/project/pages/img/pages_project_templates_v11_8.png b/doc/user/project/pages/img/pages_project_templates_v11_8.png
new file mode 100644
index 00000000000..61cae88b5a8
--- /dev/null
+++ b/doc/user/project/pages/img/pages_project_templates_v11_8.png
diff --git a/doc/user/project/pages/img/remove_pages.png b/doc/user/project/pages/img/remove_pages.png
index 60f76f15f93..d6c37ef30cd 100644
--- a/doc/user/project/pages/img/remove_pages.png
+++ b/doc/user/project/pages/img/remove_pages.png
diff --git a/doc/user/project/pages/img/verify_your_domain.png b/doc/user/project/pages/img/verify_your_domain.png
deleted file mode 100644
index d870f9e6505..00000000000
--- a/doc/user/project/pages/img/verify_your_domain.png
+++ /dev/null
diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md
index 04bda212128..a0bc10b0ed7 100644
--- a/doc/user/project/pages/index.md
+++ b/doc/user/project/pages/index.md
@@ -12,7 +12,6 @@ type: index, reference
 > - Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8.
 > - Bundled project templates were [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/47857) in GitLab 11.8.
 
-
 **GitLab Pages is a feature that allows you to publish static websites
 directly from a repository in GitLab.**
 
@@ -102,13 +101,13 @@ To get started with GitLab Pages, you can either:
 1. Select **Create from Template**.
 1. Choose one of the templates starting with **Pages**:
 
-    ![Project templates for Pages](img/pages_project_templates_11-8.png)
+   ![Project templates for Pages](img/pages_project_templates_v11_8.png)
 
 1. From the left sidebar, navigate to your project's **CI/CD > Pipelines**
-and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your
-site to the server.
+   and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your
+   site to the server.
 1. Once the pipeline has finished successfully, find the link to visit your
-website from your project's **Settings > Pages**.
+   website from your project's **Settings > Pages**.
 
 Your website is then visible on your domain, and you can modify yourfiles
 as you wish. For every modification pushed to your repository, GitLab CI/CD
@@ -116,8 +115,8 @@ will run a new pipeline to publish your changes to the server.
 
 _Advanced options:_
 
-- [Use a custom domain](getting_started_part_three.md#adding-your-custom-domain-to-gitlab-pages)
-- Apply [SSL/TLS certification](getting_started_part_three.md#ssltls-certificates) to your custom domain
+- [Use a custom domain](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain)
+- Apply [SSL/TLS certification](custom_domains_ssl_tls_certification/index.md#adding-an-ssltls-certificate-to-pages) to your custom domain
 
 ## Availability
 
@@ -141,11 +140,11 @@ To learn more about configuration options for GitLab Pages, read the following:
 | [Static websites and Pages domains](getting_started_part_one.md) | Understand what is a static website, and how GitLab Pages default domains work. |
 | [Projects and URL structure](getting_started_part_two.md) | Forking projects and creating new ones from scratch, understanding URLs structure and baseurls. |
 | [GitLab CI/CD for GitLab Pages](getting_started_part_four.md) | Understand how to create your own `.gitlab-ci.yml` for your site. |
-| [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI's configuration options, custom 404 pages, limitations, FAQ. |
+| [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI's configuration options, Access Control, custom 404 pages, limitations, FAQ. |
 |---+---|
-| [Custom domains and SSL/TLS Certificates](getting_started_part_three.md) | How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. |
+| [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. |
+| [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates automatically obtained and renewed by GitLab. |
 | [CloudFlare certificates](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) | Secure your Pages site with CloudFlare certificates. |
-| [Let's Encrypt certificates](lets_encrypt_for_gitlab_pages.md) | Secure your Pages site with Let's Encrypt certificates. |
 |---+---|
 | [Static vs dynamic websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) | A conceptual overview on static versus dynamic sites. |
 | [Modern static site generators](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) | A conceptual overview on SSGs. |
diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md
index 4fab7f79e0c..e8984cb8b9f 100644
--- a/doc/user/project/pages/introduction.md
+++ b/doc/user/project/pages/introduction.md
@@ -13,17 +13,17 @@ To familiarize yourself with GitLab Pages first:
 - Read an [introduction to GitLab Pages](index.md#overview).
 - Learn [how to get started with Pages](index.md#getting-started).
 - Learn how to enable GitLab Pages
-across your GitLab instance on the [administrator documentation](../../../administration/pages/index.md).
+  across your GitLab instance on the [administrator documentation](../../../administration/pages/index.md).
 
 ## GitLab Pages requirements
 
 In brief, this is what you need to upload your website in GitLab Pages:
 
 1. Domain of the instance: domain name that is used for GitLab Pages
-(ask your administrator).
+   (ask your administrator).
 1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`][pages] in the root directory of your repository.
 1. A directory called `public` in your site's repo containing the content
-to be published.
+   to be published.
 1. GitLab Runner enabled for the project.
 
 ## GitLab Pages on GitLab.com
@@ -67,7 +67,7 @@ Some static site generators provide plugins for that functionality so that you
 don't have to create and edit HTML files manually. For example, Jekyll has the
 [redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from).
 
-## GitLab Pages Access Control **[CORE ONLY]**
+## GitLab Pages Access Control **(CORE ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5.
 
@@ -83,23 +83,23 @@ You can enable Pages access control on your project, so that only
 1. Navigate to your project's **Settings > General > Permissions**.
 1. Toggle the **Pages** button to enable the access control.
 
-    NOTE: **Note:**
-    If you don't see the toggle button, that means that it's not enabled.
-    Ask your administrator to [enable it](../../../administration/pages/index.md#access-control).
+   NOTE: **Note:**
+   If you don't see the toggle button, that means that it's not enabled.
+   Ask your administrator to [enable it](../../../administration/pages/index.md#access-control).
 
 1. The Pages access control dropdown allows you to set who can view pages hosted
    with GitLab Pages, depending on your project's visibility:
 
-    - If your project is private:
-      - **Only project members**: Only project members will be able to browse the website.
-      - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
-    - If your project is internal:
-      - **Only project members**: Only project members will be able to browse the website.
-      - **Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership.
-      - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
-    - If your project is public:
-      - **Only project members**: Only project members will be able to browse the website.
-      - **Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
+   - If your project is private:
+     - **Only project members**: Only project members will be able to browse the website.
+     - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
+   - If your project is internal:
+     - **Only project members**: Only project members will be able to browse the website.
+     - **Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership.
+     - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
+   - If your project is public:
+     - **Only project members**: Only project members will be able to browse the website.
+     - **Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
 
 1. Click **Save changes**.
 
diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md
index 91a660c0f7a..1338c7e58f5 100644
--- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md
+++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md
@@ -1,10 +1,15 @@
 ---
-description: "How to secure GitLab Pages websites with Let's Encrypt."
+description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)."
 type: howto
-last_updated: 2019-06-04
+last_updated: 2019-07-15
 ---
 
-# Let's Encrypt for GitLab Pages
+# Let's Encrypt for GitLab Pages (manual process, deprecated)
+
+CAUTION: **Warning:**
+This method is still valid but was **deprecated** in favor of the
+[Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md)
+introduced in GitLab 12.1.
 
 If you have a GitLab Pages website served under your own domain,
 you might want to secure it with a SSL/TSL certificate.
@@ -18,9 +23,9 @@ To follow along with this tutorial, we assume you already have:
 
 - Created a [project](getting_started_part_two.md) in GitLab which
   contains your website's source code.
-- Acquired a domain (`example.com`) and added a [DNS entry](getting_started_part_three.md#dns-records)
+- Acquired a domain (`example.com`) and added a [DNS entry](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain)
   pointing it to your Pages website.
-- [Added your domain to your Pages project](getting_started_part_three.md#add-your-custom-domain-to-gitlab-pages-settings)
+- [Added your domain to your Pages project](custom_domains_ssl_tls_certification/index.md#steps)
   and verified your ownership.
 - Cloned your project into your computer.
 - Your website up and running, served under HTTP protocol at `http://example.com`.
@@ -36,111 +41,111 @@ operating systems the steps might be slightly different. Follow the
 [CertBot instructions](https://certbot.eff.org/) according to your OS.
 
 1. On your computer, open a terminal and navigate to your repository's
-  root directory:
+   root directory:
 
-    ```bash
-    cd path/to/dir
-    ```
+   ```bash
+   cd path/to/dir
+   ```
 
 1. Install CertBot (the tool Let's Encrypt uses to issue certificates):
 
-    ```bash
-    brew install certbot
-    ```
+   ```bash
+   brew install certbot
+   ```
 
 1. Request a certificate for your domain (`example.com`) and
-  provide an email account (`your@email.com`) to receive notifications:
+   provide an email account (`your@email.com`) to receive notifications:
 
-    ```bash
-    sudo certbot certonly -a manual -d example.com --email your@email.com
-    ```
+   ```bash
+   sudo certbot certonly -a manual -d example.com --email your@email.com
+   ```
 
-    Alternatively, you can register without adding an e-mail account,
-    but you won't be notified about the certificate expiration's date:
+   Alternatively, you can register without adding an e-mail account,
+   but you won't be notified about the certificate expiration's date:
 
-    ```bash
-    sudo certbot certonly -a manual -d example.com --register-unsafely-without-email
-    ```
+   ```bash
+   sudo certbot certonly -a manual -d example.com --register-unsafely-without-email
+   ```
 
-    TIP: **Tip:**
-    Read through CertBot's documentation on their
-    [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options).
+   TIP: **Tip:**
+   Read through CertBot's documentation on their
+   [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options).
 
 1. You'll be prompted with a message to agree with their terms.
-  Press `A` to agree and `Y` to let they log your IP.
+   Press `A` to agree and `Y` to let they log your IP.
 
-    CertBot will then prompt you with the following message:
+   CertBot will then prompt you with the following message:
 
-    ```bash
-    Create a file containing just this data:
+   ```bash
+   Create a file containing just this data:
 
-    Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb
+   Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb
 
-    And make it available on your web server at this URL:
+   And make it available on your web server at this URL:
 
-    http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP
+   http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP
 
-    Press Enter to Continue
-    ```
+   Press Enter to Continue
+   ```
 
 1. **Do not press Enter yet.** Let's Encrypt will need to verify your
-  domain ownership before issuing the certificate. To do so, create 3
-  consecutive directories under your website's root:
-  `/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/`
-  and add to the last folder an `index.html` file containing the content
-  referred on the previous prompt message:
-
-    ```bash
-    Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb
-    ```
-
-    Note that this file needs to be accessed under
-    `http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP`
-    to allow Let's Encrypt to verify the ownership of your domain,
-    therefore, it needs to be part of the website content under the
-    repo's [`public`](index.md#how-it-works) folder.
+   domain ownership before issuing the certificate. To do so, create 3
+   consecutive directories under your website's root:
+   `/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/`
+   and add to the last folder an `index.html` file containing the content
+   referred on the previous prompt message:
+
+   ```bash
+   Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb
+   ```
+
+   Note that this file needs to be accessed under
+   `http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP`
+   to allow Let's Encrypt to verify the ownership of your domain,
+   therefore, it needs to be part of the website content under the
+   repo's [`public`](index.md#how-it-works) folder.
 
 1. Add, commit, and push the file into your repo in GitLab. Once the pipeline
-  passes, press **Enter** on your terminal to continue issuing your
-  certificate. CertBot will then prompt you with the following message:
-
-    ```bash
-    Waiting for verification...
-    Cleaning up challenges
-
-    IMPORTANT NOTES:
-     - Congratulations! Your certificate and chain have been saved at:
-       /etc/letsencrypt/live/example.com/fullchain.pem
-       Your key file has been saved at:
-       /etc/letsencrypt/live/example.com/privkey.pem
-       Your cert will expire on 2019-03-12. To obtain a new or tweaked
-       version of this certificate in the future, simply run certbot
-       again. To non-interactively renew *all* of your certificates, run
-       "certbot renew"
-     - If you like Certbot, please consider supporting our work by:
-
-       Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
-       Donating to EFF:                    https://eff.org/donate-le
-    ```
+   passes, press **Enter** on your terminal to continue issuing your
+   certificate. CertBot will then prompt you with the following message:
+
+   ```bash
+   Waiting for verification...
+   Cleaning up challenges
+
+   IMPORTANT NOTES:
+    - Congratulations! Your certificate and chain have been saved at:
+      /etc/letsencrypt/live/example.com/fullchain.pem
+      Your key file has been saved at:
+      /etc/letsencrypt/live/example.com/privkey.pem
+      Your cert will expire on 2019-03-12. To obtain a new or tweaked
+      version of this certificate in the future, simply run certbot
+      again. To non-interactively renew *all* of your certificates, run
+      "certbot renew"
+    - If you like Certbot, please consider supporting our work by:
+
+      Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
+      Donating to EFF:                    https://eff.org/donate-le
+   ```
 
 ## Add your certificate to GitLab Pages
 
 Now that your certificate has been issued, let's add it to your Pages site:
 
 1. Back at GitLab, navigate to your project's **Settings > Pages**,
-  find your domain and click **Details** and **Edit** to add your certificate.
+   find your domain and click **Details** and **Edit** to add your certificate.
 1. From your terminal, copy and paste the certificate into the first field
-  **Certificate (PEM)**:
+   **Certificate (PEM)**:
 
-    ```bash
-    sudo cat /etc/letsencrypt/live/example.com/fullchain.pem | pbcopy
-    ```
+   ```bash
+   sudo cat /etc/letsencrypt/live/example.com/fullchain.pem | pbcopy
+   ```
 
 1. Copy and paste the private key into the second field **Key (PEM)**:
 
-    ```bash
-    sudo cat /etc/letsencrypt/live/example.com/privkey.pem | pbcopy
-    ```
+   ```bash
+   sudo cat /etc/letsencrypt/live/example.com/privkey.pem | pbcopy
+   ```
 
 1. Click **Save changes** to apply them to your website.
 1. Wait a few minutes for the configuration changes to take effect.
diff --git a/doc/user/project/pipelines/img/pipeline_schedule_variables.png b/doc/user/project/pipelines/img/pipeline_schedule_variables.png
index 29846206491..ce3c3dc6af1 100644
--- a/doc/user/project/pipelines/img/pipeline_schedule_variables.png
+++ b/doc/user/project/pipelines/img/pipeline_schedule_variables.png
diff --git a/doc/user/project/pipelines/img/pipeline_schedules_new_form.png b/doc/user/project/pipelines/img/pipeline_schedules_new_form.png
index e135dd51070..993fbf8ca00 100644
--- a/doc/user/project/pipelines/img/pipeline_schedules_new_form.png
+++ b/doc/user/project/pipelines/img/pipeline_schedules_new_form.png
diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md
index 002addfc043..ef90899c512 100644
--- a/doc/user/project/pipelines/job_artifacts.md
+++ b/doc/user/project/pipelines/job_artifacts.md
@@ -1,24 +1,24 @@
+---
+type: reference, howto
+---
+
 # Introduction to job artifacts
 
-> **Notes:**
->
-> - Since GitLab 8.2 and GitLab Runner 0.7.0, job artifacts that are created by
->   GitLab Runner are uploaded to GitLab and are downloadable as a single archive
->   (`tar.gz`) using the GitLab UI.
-> - Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format
->   changed to `ZIP`, and it is now possible to browse its contents, with the added
->   ability of downloading the files separately.
-> - Starting with GitLab 8.17, builds are renamed to jobs.
-> - The artifacts browser will be available only for new artifacts that are sent
->   to GitLab using GitLab Runner version 1.0 and up. It will not be possible to
->   browse old artifacts already uploaded to GitLab.
->- This is the user documentation. For the administration guide see
->   [administration/job_artifacts](../../../administration/job_artifacts.md).
-
-Artifacts is a list of files and directories which are attached to a job
-after it finishes. This feature is enabled by default in all
+> - Introduced in GitLab 8.2 and GitLab Runner 0.7.0.
+> - Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format changed to `ZIP`, and it is now possible to browse its contents, with the added ability of downloading the files separately.
+> - In GitLab 8.17, builds were renamed to jobs.
+> - The artifacts browser will be available only for new artifacts that are sent to GitLab using GitLab Runner version 1.0 and up. It will not be possible to browse old artifacts already uploaded to GitLab.
+
+Artifacts are a list of files and directories which created by a job
+once it finishes. This feature is [enabled by default](../../../administration/job_artifacts.md) in all
 GitLab installations.
 
+Job artifacts that are created by GitLab Runner are uploaded to GitLab and are downloadable as a single archive using the GitLab UI.
+
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For an overview, watch the video [GitLab CI Pipeline, Artifacts, and Environments](https://www.youtube.com/watch?v=PCKDICEe10s).
+Watch also [GitLab CI pipeline tutorial for beginners](https://www.youtube.com/watch?v=Jav4vbUrqII).
+
 ## Defining artifacts in `.gitlab-ci.yml`
 
 A simple example of using the artifacts definition in `.gitlab-ci.yml` would be
@@ -50,11 +50,8 @@ For more examples on artifacts, follow the [artifacts reference in
 
 ## Browsing artifacts
 
-> **Note:**
 > With GitLab 9.2, PDFs, images, videos and other formats can be previewed
 > directly in the job artifacts browser without the need to download them.
->
-> **Note:**
 > With [GitLab 10.1][ce-14399], HTML files in a public project can be previewed
 > directly in a new tab without the need to download them when
 > [GitLab Pages](../../../administration/pages/index.md) is enabled.
@@ -67,8 +64,6 @@ artifacts in case you changed your mind and want to keep them.
 
 ![Job artifacts browser button](img/job_artifacts_browser_button.png)
 
----
-
 The archive browser shows the name and the actual file size of each file in the
 archive. If your artifacts contained directories, then you are also able to
 browse inside them.
@@ -80,8 +75,6 @@ one HTML file that you can view directly online when
 
 ![Job artifacts browser](img/job_artifacts_browser.png)
 
----
-
 ## Downloading artifacts
 
 If you need to download the whole archive, there are buttons in various places
@@ -90,29 +83,29 @@ inside GitLab that make that possible.
 1. While on the pipelines page, you can see the download icon for each job's
    artifacts archive in the right corner:
 
-    ![Job artifacts in Pipelines page](img/job_artifacts_pipelines_page.png)
+   ![Job artifacts in Pipelines page](img/job_artifacts_pipelines_page.png)
 
 1. While on the **Jobs** page, you can see the download icon for each job's
    artifacts archive in the right corner:
 
-    ![Job artifacts in Builds page](img/job_artifacts_builds_page.png)
+   ![Job artifacts in Builds page](img/job_artifacts_builds_page.png)
 
 1. While inside a specific job, you are presented with a download button
    along with the one that browses the archive:
 
-    ![Job artifacts browser button](img/job_artifacts_browser_button.png)
+   ![Job artifacts browser button](img/job_artifacts_browser_button.png)
 
 1. And finally, when browsing an archive you can see the download button at
    the top right corner:
 
-    ![Job artifacts browser](img/job_artifacts_browser.png)
+   ![Job artifacts browser](img/job_artifacts_browser.png)
 
 ## Downloading the latest artifacts
 
 It is possible to download the latest artifacts of a job via a well known URL
 so you can use it for scripting purposes.
 
->**Note:**
+NOTE: **Note:**
 The latest artifacts are considered as the artifacts created by jobs in the
 latest pipeline that succeeded for the specific ref.
 Artifacts for other pipelines can be accessed with direct access to them.
@@ -173,9 +166,9 @@ https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/artifacts/master/file/htmlcov/ind
 The latest builds are also exposed in the UI in various places. Specifically,
 look for the download button in:
 
-- the main project's page
-- the branches page
-- the tags page
+- The main project's page
+- The branches page
+- The tags page
 
 If the latest job has failed to upload the artifacts, you can see that
 information in the UI.
@@ -187,9 +180,13 @@ information in the UI.
 DANGER: **Warning:**
 This is a destructive action that leads to data loss. Use with caution.
 
-If you have at least Developer [permissions](../../permissions.md#gitlab-cicd-permissions)
-on the project, you can erase a single job via the UI which will also remove the
-artifacts and the job's trace.
+You can erase a single job via the UI, which will also remove the job's
+artifacts and trace, if you are:
+
+- The owner of the job.
+- A [Maintainer](../../permissions.md#gitlab-cicd-permissions) of the project.
+
+To erase a job:
 
 1. Navigate to a job's page.
 1. Click the trash icon at the top right of the job's trace.
@@ -201,3 +198,15 @@ In order to retrieve a job artifact of a different project, you might need to us
 
 [expiry date]: ../../../ci/yaml/README.md#artifactsexpire_in
 [ce-14399]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14399
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md
index dd5427ab35a..f3e9c950efd 100644
--- a/doc/user/project/pipelines/schedules.md
+++ b/doc/user/project/pipelines/schedules.md
@@ -1,10 +1,14 @@
+---
+type: reference, howto
+---
+
 # Pipeline schedules
 
-> **Notes**:
->
 > - Introduced in GitLab 9.1 as [Trigger Schedule](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10533).
 > - [Renamed to Pipeline Schedule](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10853) in GitLab 9.2.
-> - Cron notation is parsed by [Fugit](https://github.com/floraison/fugit).
+
+NOTE: **Note:**
+Cron notation is parsed by [Fugit](https://github.com/floraison/fugit).
 
 Pipelines are normally run based on certain conditions being met. For example, when a branch is pushed to repository.
 
@@ -118,3 +122,15 @@ on the target branch, the schedule will stop creating new pipelines. This can
 happen if, for example, the owner is blocked or removed from the project, or
 the target branch or tag is protected. In this case, someone with sufficient
 privileges must take ownership of the schedule.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md
index 16f48c462eb..456209c2180 100644
--- a/doc/user/project/pipelines/settings.md
+++ b/doc/user/project/pipelines/settings.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # Pipelines settings
 
 To reach the pipelines settings navigate to your project's
@@ -5,6 +9,10 @@ To reach the pipelines settings navigate to your project's
 
 The following settings can be configured per project.
 
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For an overview, watch the video [GitLab CI Pipeline, Artifacts, and Environments](https://www.youtube.com/watch?v=PCKDICEe10s).
+Watch also [GitLab CI pipeline tutorial for beginners](https://www.youtube.com/watch?v=Jav4vbUrqII).
+
 ## Git strategy
 
 With Git strategy, you can choose the default way your repository is fetched
@@ -24,10 +32,11 @@ in `.gitlab-ci.yml`.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/28919) in GitLab 12.0.
 
-NOTE: **Note**: As of GitLab 12.0, newly created projects will automaticallyl have a default 
+NOTE: **Note**:
+As of GitLab 12.0, newly created projects will automatically have a default
 `git depth` value of `50`.
 
-It is possible to limit the number of changes that GitLab CI/CD will fetch when cloning 
+It is possible to limit the number of changes that GitLab CI/CD will fetch when cloning
 a repository. Setting a limit to `git depth` can speed up Pipelines execution. Maximum
 allowed value is `1000`.
 
@@ -67,6 +76,13 @@ Here are some valid examples:
 - `my/path/.gitlab-ci.yml`
 - `my/path/.my-custom-file.yml`
 
+The path can be customized at a project level. To customize the path:
+
+1. Go to the project's **Settings > CI / CD**.
+1. Expand the **General pipelines** section.
+1. Provide a value in the **Custom CI config path** field.
+1. Click **Save changes**.
+
 ## Test coverage parsing
 
 If you use test coverage in your code, GitLab can capture its output in the
@@ -88,6 +104,22 @@ in the jobs table.
 A few examples of known coverage tools for a variety of languages can be found
 in the pipelines settings page.
 
+### Removing color codes
+
+Some test coverage tools output with ANSI color codes that won't be
+parsed correctly by the regular expression and will cause coverage 
+parsing to fail. 
+
+If your coverage tool doesn't provide an option to disable color
+codes in the output, you can pipe the output of the coverage tool through a 
+small one line script that will strip the color codes off.
+
+For example:
+
+```bash
+lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g'
+```
+
 ## Visibility of pipelines
 
 Access to pipelines and job details (including output of logs and artifacts)
@@ -199,3 +231,15 @@ https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?st
 ## Environment Variables
 
 [Environment variables](../../../ci/variables/README.html#gitlab-cicd-environment-variables) can be set in an environment to be available to a runner.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md
index 56e8f1731ae..7a79cdbcaee 100644
--- a/doc/user/project/protected_branches.md
+++ b/doc/user/project/protected_branches.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # Protected Branches
 
 [Permissions](../permissions.md) in GitLab are fundamentally defined around the
@@ -9,13 +13,13 @@ created protected branches.
 
 By default, a protected branch does four simple things:
 
-- it prevents its creation, if not already created, from everybody except users
-  with Maintainer permission
-- it prevents pushes from everybody except users with Maintainer permission
-- it prevents **anyone** from force pushing to the branch
-- it prevents **anyone** from deleting the branch
+- It prevents its creation, if not already created, from everybody except users
+  with Maintainer permission.
+- It prevents pushes from everybody except users with Maintainer permission.
+- It prevents **anyone** from force pushing to the branch.
+- It prevents **anyone** from deleting the branch.
 
->**Note**:
+NOTE: **Note:**
 A GitLab admin is allowed to push to the protected branches.
 
 See the [Changelog](#changelog) section for changes over time.
@@ -30,11 +34,11 @@ that the `master` branch is protected by default.
 1. From the **Branch** dropdown menu, select the branch you want to protect and
    click **Protect**. In the screenshot below, we chose the `develop` branch.
 
-    ![Protected branches page](img/protected_branches_page.png)
+   ![Protected branches page](img/protected_branches_page.png)
 
 1. Once done, the protected branch will appear in the "Protected branches" list.
 
-    ![Protected branches list](img/protected_branches_list.png)
+   ![Protected branches list](img/protected_branches_list.png)
 
 ## Using the Allowed to merge and Allowed to push settings
 
@@ -66,9 +70,9 @@ dropdown list in the "Already protected" area.
 If you don't choose any of those options while creating a protected branch,
 they are set to "Maintainers" by default.
 
-## Restricting push and merge access to certain users **[STARTER]**
+## Restricting push and merge access to certain users **(STARTER)**
 
-> This feature was [introduced][ce-5081] in [GitLab Starter][ee] 8.11.
+> [Introduced][ce-5081] in [GitLab Starter][ee] 8.11.
 
 With GitLab Enterprise Edition you can restrict access to protected branches
 by choosing a role (Maintainers, Developers) as well as certain users. From the
@@ -141,7 +145,7 @@ branches via GitLab's web interface:
 1. In order to prevent accidental deletion, an additional confirmation is
    required
 
-    ![Delete protected branches](img/protected_branches_delete.png)
+   ![Delete protected branches](img/protected_branches_delete.png)
 
 Deleting a protected branch is only allowed via the web interface, not via Git.
 This means that you can't accidentally delete a protected branch from your
@@ -174,12 +178,21 @@ for details about the pipelines security model.
 - Allow developers to merge into a protected branch without having push access [gitlab-org/gitlab-ce!4892][ce-4892]
 - Allow specifying protected branches using wildcards [gitlab-org/gitlab-ce!4665][ce-4665]
 
----
-
 [ce-4665]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4665 "Allow specifying protected branches using wildcards"
 [ce-4892]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4892 "Allow developers to merge into a protected branch without having push access"
 [ce-5081]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5081 "Allow creating protected branches that can't be pushed to"
 [ce-21393]: https://gitlab.com/gitlab-org/gitlab-ce/issues/21393
-[ee-restrict]: http://docs.gitlab.com/ee/user/project/protected_branches.html#restricting-push-and-merge-access-to-certain-users
 [perm]: ../permissions.md
 [ee]: https://about.gitlab.com/pricing/
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md
index 26bec323f02..5cc3b8a7fc3 100644
--- a/doc/user/project/protected_tags.md
+++ b/doc/user/project/protected_tags.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # Protected Tags
 
 > [Introduced][ce-10356] in GitLab 9.1.
@@ -14,21 +18,21 @@ Protected tags will prevent anyone from updating or deleting the tag, as and wil
 
 To protect a tag, you need to have at least Maintainer permission level.
 
-1. Navigate to the project's Settings -> Repository page
+1. Navigate to the project's **Settings > Repository**:
 
-    ![Repository Settings](img/project_repository_settings.png)
+   ![Repository Settings](img/project_repository_settings.png)
 
-1. From the **Tag** dropdown menu, select the tag you want to protect or type and click `Create wildcard`. In the screenshot below, we chose to protect all tags matching `v*`.
+1. From the **Tag** dropdown menu, select the tag you want to protect or type and click **Create wildcard**. In the screenshot below, we chose to protect all tags matching `v*`:
 
-    ![Protected tags page](img/protected_tags_page.png)
+   ![Protected tags page](img/protected_tags_page.png)
 
-1. From the `Allowed to create` dropdown, select who will have permission to create matching tags and then click `Protect`.
+1. From the **Allowed to create** dropdown, select who will have permission to create matching tags and then click **Protect**:
 
-    ![Allowed to create tags dropdown](img/protected_tags_permissions_dropdown.png)
+   ![Allowed to create tags dropdown](img/protected_tags_permissions_dropdown.png)
 
-1. Once done, the protected tag will appear in the "Protected tags" list.
+1. Once done, the protected tag will appear in the **Protected tags** list:
 
-    ![Protected tags list](img/protected_tags_list.png)
+   ![Protected tags list](img/protected_tags_list.png)
 
 ## Wildcard protected tags
 
@@ -45,13 +49,23 @@ matching the wildcard. For example:
 Two different wildcards can potentially match the same tag. For example,
 `*-stable` and `production-*` would both match a `production-stable` tag.
 In that case, if _any_ of these protected tags have a setting like
-"Allowed to create", then `production-stable` will also inherit this setting.
+**Allowed to create**, then `production-stable` will also inherit this setting.
 
 If you click on a protected tag's name, you will be presented with a list of
 all matching tags:
 
 ![Protected tag matches](img/protected_tag_matches.png)
 
----
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
 
 [ce-10356]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10356 "Protected Tags"
diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md
index 1d640966013..647250bd02a 100644
--- a/doc/user/project/quick_actions.md
+++ b/doc/user/project/quick_actions.md
@@ -1,13 +1,18 @@
-# GitLab quick actions
+---
+type: reference
+---
+
+# GitLab Quick Actions
 
 Quick actions are textual shortcuts for common actions on issues, epics, merge requests,
 and commits that are usually done by clicking buttons or dropdowns in GitLab's UI.
 You can enter these commands while creating a new issue or merge request, or
 in comments of issues, epics, merge requests, and commits. Each command should be
 on a separate line in order to be properly detected and executed. Once executed,
-the commands are removed from the text body and not visible to anyone else.
 
-## Quick actions for issues and merge requests
+> From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/26672), an alert is displayed when a quick action is successfully applied.
+
+## Quick Actions for issues and merge requests
 
 The following quick actions are applicable to both issues and merge requests threads,
 discussions, and descriptions:
@@ -16,8 +21,8 @@ discussions, and descriptions:
 |:---------------------------|:------------------------------ |:------|:--------------|
 | `/tableflip <Comment>`     | Append the comment with `(╯°□°)╯︵ ┻━┻` | ✓ | ✓        |
 | `/shrug <Comment>`         | Append the comment with `¯\＿(ツ)＿/¯` | ✓ | ✓         |
-| `/todo`                    | Add a todo                     | ✓     | ✓             |
-| `/done`                    | Mark todo as done              | ✓     | ✓             |
+| `/todo`                    | Add a To Do                    | ✓     | ✓             |
+| `/done`                    | Mark To Do as done             | ✓     | ✓             |
 | `/subscribe`               | Subscribe                      | ✓     | ✓             |
 | `/unsubscribe`             | Unsubscribe                    | ✓     | ✓             |
 | `/close`                   | Close                          | ✓     | ✓             |
@@ -26,37 +31,59 @@ discussions, and descriptions:
 | `/award :emoji:`           | Toggle emoji award             | ✓     | ✓             |
 | `/assign me`               | Assign yourself                | ✓     | ✓             |
 | `/assign @user`            | Assign one user                | ✓     | ✓             |
-| `/assign @user1 @user2`    | Assign multiple users **[STARTER]** | ✓ | ✓            |
-| `/unassign @user1 @user2`  | Remove assignee(s) **[STARTER]** | ✓     | ✓             |
-| `/reassign @user1 @user2`  | Change assignee **[STARTER]**  | ✓     | ✓             |
+| `/assign @user1 @user2`    | Assign multiple users **(STARTER)** | ✓ | ✓            |
+| `/unassign @user1 @user2`  | Remove assignee(s) **(STARTER)** | ✓     | ✓             |
+| `/reassign @user1 @user2`  | Change assignee **(STARTER)**  | ✓     | ✓             |
 | `/unassign`                | Remove current assignee        | ✓     | ✓             |
 | `/milestone %milestone`    | Set milestone                  | ✓     | ✓             |
 | `/remove_milestone`        | Remove milestone               | ✓     | ✓             |
 | `/label ~label1 ~label2`   | Add label(s). Label names can also start without ~ but mixed syntax is not supported.                   | ✓     | ✓             |
 | `/unlabel ~label1 ~label2` | Remove all or specific label(s)| ✓     | ✓             |
-| `/relabel ~label1 ~label2` | Replace label                  | ✓     | ✓             |
-| <code>/copy_metadata #issue &#124; !merge_request</code> | Copy labels and milestone from other issue or merge request in the project | ✓     | ✓             |
-| <code>/estimate &lt;1w 3d 2h 14m&gt;</code> | Set time estimate | ✓     | ✓             |
+| `/relabel ~label1 ~label2` | Replace existing label(s) with those specified | ✓     | ✓             |
+| `/copy_metadata <#issue>` | Copy labels and milestone from another issue in the project | ✓     | ✓             |
+| `/copy_metadata <!merge_request>` | Copy labels and milestone from another merge request in the project | ✓     | ✓             |
+| `/estimate <1w 3d 2h 14m>` | Set time estimate | ✓     | ✓             |
 | `/remove_estimate`       | Remove time estimate             | ✓     | ✓             |
-| <code>/spend &lt;time(1h 30m &#124; -1h 5m)&gt; &lt;date(YYYY-MM-DD)&gt;</code> | Add or subtract spent time; optionally, specify the date that time was spent on | ✓     | ✓             |
+| `/spend <time(1h 30m)> <date(YYYY-MM-DD)>` | Add spent time; optionally, specify the date that time was spent on | ✓     | ✓             |
+| `/spend <time(-1h 5m)> <date(YYYY-MM-DD)>` | Subtract spent time; optionally, specify the date that time was spent on | ✓     | ✓             |
 | `/remove_time_spent`       | Remove time spent              | ✓     | ✓             |
-| `/lock`                    | Lock the discussion            | ✓     | ✓             |
-| `/unlock`                  | Unlock the discussion          | ✓     | ✓             |
-| <code>/due &lt;in 2 days &#124; this Friday &#124; December 31st&gt;</code>| Set due date | ✓ | |
+| `/lock`                    | Lock the thread                | ✓     | ✓             |
+| `/unlock`                  | Unlock the thread              | ✓     | ✓             |
+| `/due <date>` | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | ✓ | |
 | `/remove_due_date`         | Remove due date                | ✓     |               |
-| `/weight 0,1,2, ...`       | Set weight **[STARTER]**       | ✓     |               |
-| `/clear_weight`            | Clears weight **[STARTER]**    | ✓     |               |
-| `/epic <&epic &#124; group&epic &#124; Epic URL>` | Add to epic **[ULTIMATE]** | ✓ |             |
-| `/remove_epic`             | Removes from epic **[ULTIMATE]** | ✓   |               |
-| `/promote`                 | Promote issue to epic **[ULTIMATE]** | ✓   |               |
+| `/weight <value>` | Set weight. Valid options for `<value>` include `0`, `1`, `2`, etc. **(STARTER)**       | ✓     |               |
+| `/clear_weight`            | Clears weight **(STARTER)**    | ✓     |               |
+| `/epic <epic>` | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic` or `epic-URL`. **(ULTIMATE)** | ✓ |             |
+| `/remove_epic`             | Removes from epic **(ULTIMATE)** | ✓   |               |
+| `/promote`                 | Promote issue to epic **(ULTIMATE)** | ✓   |               |
 | `/confidential`            | Make confidential              | ✓     |               |
-| `/duplicate #issue`        | Mark this issue as a duplicate of another issue | ✓    |
-| `/move path/to/project`    | Move this issue to another project | ✓ |               |
+| `/duplicate <#issue>`        | Mark this issue as a duplicate of another issue | ✓    |
+| `/move <path/to/project>`    | Move this issue to another project | ✓ |               |
 | `/target_branch <Local branch Name>` | Set target branch    |       | ✓             |
 | `/wip`                     | Toggle the Work In Progress status |   | ✓             |
 | `/approve`                 | Approve the merge request      |       | ✓             |
 | `/merge`                   | Merge (when pipeline succeeds) |       | ✓             |
 | `/create_merge_request <branch name>` | Create a new merge request starting from the current issue | ✓ | |
+| `/relate #issue1 #issue2`  | Mark issues as related **(STARTER)** | ✓     |               |
+
+## Autocomplete characters
+
+Many quick actions require a parameter, for example: username, milestone, and
+label. [Autocomplete characters](autocomplete_characters.md) can make it easier
+to enter a parameter, compared to selecting items from a list.
+
+## Quick actions parameters
+
+The easiest way to set parameters for quick actions is to use autocomplete. If
+you manually enter a parameter, it must be enclosed in double quotation marks
+(`"`), unless it contains only:
+
+1. ASCII letters.
+1. Numerals.
+1. Underscore, hyphen, question mark, dot, and ampersand.
+
+Parameters are also case-sensitive. Autocomplete handles this, and the insertion
+of quotation marks, automatically.
 
 ## Quick actions for commit messages
 
@@ -66,7 +93,7 @@ The following quick actions are applicable for commit messages:
 |:------------------------|:------------------------------------------|
 | `/tag v1.2.3 <message>` | Tags this commit with an optional message |
 
-## Quick actions for Epics **[ULTIMATE]**
+## Quick actions for Epics **(ULTIMATE)**
 
 The following quick actions are applicable for epics threads and description:
 
@@ -74,8 +101,8 @@ The following quick actions are applicable for epics threads and description:
 |:---------------------------|:----------------------------------------|
 | `/tableflip <Comment>`     | Append the comment with `(╯°□°)╯︵ ┻━┻` |
 | `/shrug <Comment>`         | Append the comment with `¯\＿(ツ)＿/¯`  |
-| `/todo`                    | Add a todo                              |
-| `/done`                    | Mark todo as done                       |
+| `/todo`                    | Add a To Do                              |
+| `/done`                    | Mark To Do as done                       |
 | `/subscribe`               | Subscribe                               |
 | `/unsubscribe`             | Unsubscribe                             |
 | `/close`                   | Close                                   |
@@ -84,4 +111,20 @@ The following quick actions are applicable for epics threads and description:
 | `/award :emoji:`           | Toggle emoji award                      |
 | `/label ~label1 ~label2`   | Add label(s)                            |
 | `/unlabel ~label1 ~label2` | Remove all or specific label(s)         |
-| `/relabel ~label1 ~label2` | Replace label                           |
+| `/relabel ~label1 ~label2` | Replace existing label(s) with those specified |
+| `/child_epic <epic>` | Adds child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic` or `epic-URL`. ([Introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ee/issues/7330)) **(ULTIMATE)**|
+| `/remove_child_epic <epic>` | Removes child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic` or `epic-URL`. ([Introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ee/issues/7330)) **(ULTIMATE)** |
+| `/parent_epic <epic>` | Sets parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic` or `epic-URL`. ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ee/issues/10556)) **(ULTIMATE)** |
+| `/remove_parent_epic` | Removes parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ee/issues/10556)) |
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/releases/img/releases.png b/doc/user/project/releases/img/releases.png
index f8b1b7305ad..da5bcd9d913 100644
--- a/doc/user/project/releases/img/releases.png
+++ b/doc/user/project/releases/img/releases.png
diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md
index 00a4f6c6a6b..aae253467f0 100644
--- a/doc/user/project/releases/index.md
+++ b/doc/user/project/releases/index.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # Releases
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7.
@@ -60,3 +64,15 @@ Navigate to **Project > Releases** in order to see the list of releases for a gi
 project.
 
 ![Releases list](img/releases.png)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/repository/img/compare_branches.png b/doc/user/project/repository/branches/img/compare_branches.png
index 52d5c518c45..52d5c518c45 100644
--- a/doc/user/project/repository/img/compare_branches.png
+++ b/doc/user/project/repository/branches/img/compare_branches.png
diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md
index 13e4f2ce163..a864665602e 100644
--- a/doc/user/project/repository/branches/index.md
+++ b/doc/user/project/repository/branches/index.md
@@ -1,17 +1,41 @@
+---
+type: concepts, howto
+---
+
 # Branches
 
-Read through GiLab's branching documentation:
+A branch is a version of a project's working tree. You create a branch for each
+set of related changes you make. This keeps each set of changes separate from
+each other, allowing changes to be made in parallel, without affecting each
+other.
+
+After pushing your changes to a new branch, you can:
+
+- Create a [merge request](../../merge_requests/index.md)
+- Perform inline code review
+- [Discuss](../../../discussions/index.md) your implementation with your team
+- Preview changes submitted to a new branch with [Review Apps](../../../../ci/review_apps/index.md).
+
+With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request
+[approval](../../merge_requests/merge_request_approvals.md) from your managers.
+
+For more information on managing branches using the GitLab UI, see:
+
+- [Default branches](#default-branch)
+- [Create a branch](../web_editor.md#create-a-new-branch)
+- [Protected branches](../../protected_branches.md#protected-branches)
+- [Delete merged branches](#delete-merged-branches)
+- [Branch filter search box](#branch-filter-search-box)
+
+You can also manage branches using the
+[command line](../../../../gitlab-basics/start-using-git.md#create-a-branch).
 
-- [Create a branch](../web_editor.md#create-a-new-branch).
-- [Default branch](#default-branch).
-- [Protected branches](../../protected_branches.md#protected-branches).
-- [Delete merged branches](#delete-merged-branches).
-- [Branch filter search box](#branch-filter-search-box).
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>Watch the video [GitLab Flow](https://www.youtube.com/watch?v=InKNIvky2KE).
 
 See also:
 
 - [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API.
-- [GitLab Flow](../../../../university/training/gitlab_flow.md). Use the best of GitLab for your branching strategies.
+- [GitLab Flow](../../../../university/training/gitlab_flow.md) documentation.
 - [Getting started with Git](../../../../topics/git/index.md) and GitLab.
 
 ## Default branch
@@ -21,7 +45,7 @@ branch for your project. You can choose another branch to be your project's
 default under your project's **Settings > Repository**.
 
 The default branch is the branch affected by the
-[issue closing pattern](../../issues/automatic_issue_closing.md),
+[issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically),
 which means that _an issue will be closed when a merge request is merged to
 the **default branch**_.
 
@@ -29,6 +53,17 @@ The default branch is also protected against accidental deletion. Read through
 the documentation on [protected branches](../../protected_branches.md#protected-branches)
 to learn more.
 
+## Compare
+
+To compare branches in a repository:
+
+1. Navigate to your project's repository.
+1. Select **Repository > Compare** in the sidebar.
+1. Select branches to compare using the [branch filter search box](#branch-filter-search-box)
+1. Click **Compare** to view the changes inline:
+
+![compare branches](img/compare_branches.png)
+
 ## Delete merged branches
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6449) in GitLab 8.14.
@@ -57,3 +92,15 @@ Sometimes when you have hundreds of branches you may want a more flexible matchi
 
 - `^feature` will only match branch names that begin with 'feature'.
 - `feature$` will only match branch names that end with 'feature'.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md
index 3260a355fdc..b929c6a681a 100644
--- a/doc/user/project/repository/gpg_signed_commits/index.md
+++ b/doc/user/project/repository/gpg_signed_commits/index.md
@@ -1,38 +1,39 @@
-# Signing commits with GPG
+---
+type: concepts, howto
+---
 
-NOTE: **Note:**
-The term GPG is used for all OpenPGP/PGP/GPG related material and
-implementations.
+# Signing commits with GPG
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9546) in GitLab 9.5.
 > - Subkeys support was added in GitLab 10.1.
 
-GitLab can show whether a commit is verified or not when signed with a GPG key.
-All you need to do is upload the public GPG key in your profile settings.
-
-GPG verified tags are not supported yet.
+You can use a GPG key to sign Git commits made in a GitLab repository. Signed
+commits are labeled **Verified** if the identity of the committer can be
+verified. To verify the identity of a committer, GitLab requires their public
+GPG key.
 
-## Getting started with GPG
+NOTE: **Note:**
+The term GPG is used for all OpenPGP/PGP/GPG related material and
+implementations.
 
-Here are a few guides to get you started with GPG:
+GPG verified tags are not supported yet.
 
-- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
-- [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys)
-- [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices)
-- [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced)
+See the [further reading](#further-reading) section for more details on GPG.
 
 ## How GitLab handles GPG
 
 GitLab uses its own keyring to verify the GPG signature. It does not access any
 public key server.
 
-In order to have a commit verified on GitLab the corresponding public key needs
-to be uploaded to GitLab. For a signature to be verified three conditions need
-to be met:
+For a commit to be verified by GitLab:
 
-1. The public key needs to be added your GitLab account
-1. One of the emails in the GPG key matches a **verified** email address you use in GitLab
-1. The committer's email matches the verified email from the gpg key
+- The committer must have a GPG public/private key pair.
+- The committer's public key must have been uploaded to their GitLab
+  account.
+- One of the emails in the GPG key must match a **verified** email address
+  used by the committer in GitLab.
+- The committer's email address must match the verified email address from the
+  GPG key.
 
 ## Generating a GPG key
 
@@ -45,94 +46,94 @@ started:
 1. Generate the private/public key pair with the following command, which will
    spawn a series of questions:
 
-    ```sh
-    gpg --full-gen-key
-    ```
+   ```sh
+   gpg --full-gen-key
+   ```
 
-    NOTE: **Note:**
-    In some cases like Gpg4win on Windows and other macOS versions, the command
-    here may be `gpg --gen-key`.
+   NOTE: **Note:**
+   In some cases like Gpg4win on Windows and other macOS versions, the command
+   here may be `gpg --gen-key`.
 
 1. The first question is which algorithm can be used.  Select the kind you want
    or press <kbd>Enter</kbd> to choose the default (RSA and RSA):
 
-    ```
-    Please select what kind of key you want:
-       (1) RSA and RSA (default)
-       (2) DSA and Elgamal
-       (3) DSA (sign only)
-       (4) RSA (sign only)
-    Your selection? 1
-    ```
-
-1. The next question is key length. We recommend to choose the highest value
-   which is `4096`:
-
-    ```
-    RSA keys may be between 1024 and 4096 bits long.
-    What keysize do you want? (2048) 4096
-    Requested keysize is 4096 bits
-    ```
-1. Next, you need to specify the validity period of your key. This is something
-   subjective, and you can use the default value which is to never expire:
-
-    ```
-    Please specify how long the key should be valid.
-             0 = key does not expire
-          <n>  = key expires in n days
-          <n>w = key expires in n weeks
-          <n>m = key expires in n months
-          <n>y = key expires in n years
-    Key is valid for? (0) 0
-    Key does not expire at all
-    ```
+   ```
+   Please select what kind of key you want:
+      (1) RSA and RSA (default)
+      (2) DSA and Elgamal
+      (3) DSA (sign only)
+      (4) RSA (sign only)
+   Your selection? 1
+   ```
+
+1. The next question is key length. We recommend you choose `4096`:
+
+   ```
+   RSA keys may be between 1024 and 4096 bits long.
+   What keysize do you want? (2048) 4096
+   Requested keysize is 4096 bits
+   ```
+
+1. Specify the validity period of your key. This is something
+   subjective, and you can use the default value, which is to never expire:
+
+   ```
+   Please specify how long the key should be valid.
+            0 = key does not expire
+         <n>  = key expires in n days
+         <n>w = key expires in n weeks
+         <n>m = key expires in n months
+         <n>y = key expires in n years
+   Key is valid for? (0) 0
+   Key does not expire at all
+   ```
 
 1. Confirm that the answers you gave were correct by typing `y`:
 
-    ```
-    Is this correct? (y/N) y
-    ```
+   ```
+   Is this correct? (y/N) y
+   ```
 
-1. Enter you real name, the email address to be associated with this key (should
-   match a verified email address you use in GitLab) and an optional comment
-   (press <kbd>Enter</kbd> to skip):
+1. Enter your real name, the email address to be associated with this key
+   (should match a verified email address you use in GitLab) and an optional
+   comment (press <kbd>Enter</kbd> to skip):
 
-    ```
-    GnuPG needs to construct a user ID to identify your key.
+   ```
+   GnuPG needs to construct a user ID to identify your key.
 
-    Real name: Mr. Robot
-    Email address: <your_email>
-    Comment:
-    You selected this USER-ID:
-        "Mr. Robot <your_email>"
+   Real name: Mr. Robot
+   Email address: <your_email>
+   Comment:
+   You selected this USER-ID:
+       "Mr. Robot <your_email>"
 
-    Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
-    ```
+   Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
+   ```
 
 1. Pick a strong password when asked and type it twice to confirm.
 1. Use the following command to list the private GPG key you just created:
 
-    ```
-    gpg --list-secret-keys --keyid-format LONG <your_email>
-    ```
+   ```
+   gpg --list-secret-keys --keyid-format LONG <your_email>
+   ```
 
-    Replace `<your_email>` with the email address you entered above.
+   Replace `<your_email>` with the email address you entered above.
 
 1. Copy the GPG key ID that starts with `sec`. In the following example, that's
    `30F2B65B9246B6CA`:
 
-    ```
-    sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
-          D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
-    uid                   [ultimate] Mr. Robot <your_email>
-    ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
-    ```
+   ```
+   sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
+         D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
+   uid                   [ultimate] Mr. Robot <your_email>
+   ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
+   ```
 
 1. Export the public key of that ID (replace your key ID from the previous step):
 
-    ```
-    gpg --armor --export 30F2B65B9246B6CA
-    ```
+   ```
+   gpg --armor --export 30F2B65B9246B6CA
+   ```
 
 1. Finally, copy the public key and [add it in your profile settings](#adding-a-gpg-key-to-your-account)
 
@@ -146,17 +147,17 @@ You can add a GPG key in your profile's settings:
 
 1. On the upper right corner, click on your avatar and go to your **Settings**.
 
-    ![Settings dropdown](../../../profile/img/profile_settings_dropdown.png)
+   ![Settings dropdown](../../../profile/img/profile_settings_dropdown.png)
 
 1. Navigate to the **GPG keys** tab and paste your _public_ key in the 'Key'
    box.
 
-    ![Paste GPG public key](img/profile_settings_gpg_keys_paste_pub.png)
+   ![Paste GPG public key](img/profile_settings_gpg_keys_paste_pub.png)
 
 1. Finally, click on **Add key** to add it to GitLab. You will be able to see
    its fingerprint, the corresponding email address and creation date.
 
-    ![GPG key single page](img/profile_settings_gpg_keys_single_key.png)
+   ![GPG key single page](img/profile_settings_gpg_keys_single_key.png)
 
 ## Associating your GPG key with Git
 
@@ -166,29 +167,29 @@ key to use.
 
 1. Use the following command to list the private GPG key you just created:
 
-    ```sh
-    gpg --list-secret-keys --keyid-format LONG <your_email>
-    ```
+   ```sh
+   gpg --list-secret-keys --keyid-format LONG <your_email>
+   ```
 
-    Replace `<your_email>` with the email address you entered above.
+   Replace `<your_email>` with the email address you entered above.
 
 1. Copy the GPG key ID that starts with `sec`. In the following example, that's
    `30F2B65B9246B6CA`:
 
-    ```
-    sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
-          D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
-    uid                   [ultimate] Mr. Robot <your_email>
-    ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
-    ```
+   ```
+   sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
+         D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
+   uid                   [ultimate] Mr. Robot <your_email>
+   ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
+   ```
 
 1. Tell Git to use that key to sign the commits:
 
-    ```sh
-    git config --global user.signingkey 30F2B65B9246B6CA
-    ```
+   ```sh
+   git config --global user.signingkey 30F2B65B9246B6CA
+   ```
 
-    Replace `30F2B65B9246B6CA` with your GPG key ID.
+   Replace `30F2B65B9246B6CA` with your GPG key ID.
 
 1. (Optional) If Git is using `gpg` and you get errors like `secret key not available`
    or `gpg: signing failed: secret key not available`, run the following command to
@@ -206,9 +207,9 @@ commits:
 
 1. Commit like you used to, the only difference is the addition of the `-S` flag:
 
-    ```
-    git commit -S -m "My commit msg"
-    ```
+   ```
+   git commit -S -m "My commit msg"
+   ```
 
 1. Enter the passphrase of your GPG key when asked.
 1. Push to GitLab and check that your commits [are verified](#verifying-commits).
@@ -227,13 +228,13 @@ git config --global commit.gpgsign true
    "Verified" or "Unverified", depending on the verification status of the GPG
    signature.
 
-    ![Signed and unsigned commits](img/project_signed_and_unsigned_commits.png)
+   ![Signed and unsigned commits](img/project_signed_and_unsigned_commits.png)
 
 1. By clicking on the GPG badge, details of the signature are displayed.
 
-    ![Signed commit with verified signature](img/project_signed_commit_verified_signature.png)
+   ![Signed commit with verified signature](img/project_signed_commit_verified_signature.png)
 
-    ![Signed commit with verified signature](img/project_signed_commit_unverified_signature.png)
+   ![Signed commit with verified signature](img/project_signed_commit_unverified_signature.png)
 
 ## Revoking a GPG key
 
@@ -261,7 +262,7 @@ To remove a GPG key from your account:
 1. Navigate to the **GPG keys** tab.
 1. Click on the trash icon besides the GPG key you want to delete.
 
-## Rejecting commits that are not signed **[PREMIUM]**
+## Rejecting commits that are not signed **(PREMIUM)**
 
 You can configure your project to reject commits that aren't GPG-signed
 via [push rules](../../../../push_rules/push_rules.md).
@@ -269,3 +270,24 @@ via [push rules](../../../../push_rules/push_rules.md).
 ## GPG signing API
 
 Learn how to [get the GPG signature from a commit via API](../../../../api/commits.md#get-gpg-signature-of-a-commit).
+
+## Further reading
+
+For more details about GPG, see:
+
+- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
+- [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys)
+- [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices)
+- [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/repository/img/download_source_code.png b/doc/user/project/repository/img/download_source_code.png
index 17f2cb4b3e8..56808061980 100644
--- a/doc/user/project/repository/img/download_source_code.png
+++ b/doc/user/project/repository/img/download_source_code.png
diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md
index 6fccfd40987..84d63d29929 100644
--- a/doc/user/project/repository/index.md
+++ b/doc/user/project/repository/index.md
@@ -1,3 +1,7 @@
+---
+type: concepts, howto
+---
+
 # Repository
 
 A [repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository)
@@ -68,7 +72,7 @@ according to the markup language.
 | Plain text | `txt` |
 | [Markdown](../../markdown.md) | `mdown`, `mkd`, `mkdn`, `md`, `markdown` |
 | [reStructuredText](http://docutils.sourceforge.net/rst.html) | `rst` |
-| [Asciidoc](https://asciidoctor.org/docs/what-is-asciidoc/) | `adoc`, `ad`, `asciidoc` |
+| [AsciiDoc](../../asciidoc.md) | `adoc`, `ad`, `asciidoc` |
 | [Textile](https://txstyle.org/) | `textile` |
 | [rdoc](http://rdoc.sourceforge.net/doc/index.html)  | `rdoc` |
 | [Orgmode](https://orgmode.org/) | `org` |
@@ -111,33 +115,7 @@ GitLab.
 
 ## Branches
 
-When you submit changes in a new [branch](branches/index.md), you create a new version
-of that project's file tree. Your branch contains all the changes
-you are presenting, which are detected by Git line by line.
-
-To continue your workflow, once you pushed your changes to a new branch,
-you can create a [merge request](../merge_requests/index.md), perform
-inline code review, and [discuss](../../discussions/index.md)
-your implementation with your team.
-You can live preview changes submitted to a new branch with
-[Review Apps](../../../ci/review_apps/index.md).
-
-With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request
-[approval](../merge_requests/merge_request_approvals.md) from your managers.
-
-To create, delete, and view [branches](branches/index.md) via GitLab's UI:
-
-- [Default branches](branches/index.md#default-branch)
-- [Create a branch](web_editor.md#create-a-new-branch)
-- [Protected branches](../protected_branches.md#protected-branches)
-- [Delete merged branches](branches/index.md#delete-merged-branches)
-- [Branch filter search box](branches/index.md#branch-filter-search-box)
-
-Alternatively, you can use the
-[command line](../../../gitlab-basics/start-using-git.md#create-a-branch).
-
-To learn more about branching strategies read through the
-[GitLab Flow](../../../university/training/gitlab_flow.md) documentation.
+For details, see [Branches](branches/index.md).
 
 ## Commits
 
@@ -171,17 +149,14 @@ Via command line, you can commit multiple times before pushing.
 - **Sign a commit:**
   Use GPG to [sign your commits](gpg_signed_commits/index.md).
 
-## Repository size
-
-A project's repository size is reported on the project's **Details** page. The reported size is
-updated every 15 minutes at most, so may not reflect recent activity.
+## Project and repository size
 
-The repository size for:
+A project's size is reported on the project's **Details** page. The reported size is
+updated every 15 minutes at most, so may not reflect recent activity. The displayed files size includes repository files, artifacts, and LFS.
 
-- GitLab.com [is set by GitLab](../../gitlab_com/index.md#repository-size-limit).
-- Self-managed instances is set by your GitLab administrators.
+The project size may differ slightly from one instance to another due to compression, housekeeping, and other factors.
 
-You can [reduce a repository's size using Git](reducing_the_repo_size_using_git.md).
+[Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by admins. GitLab.com's repository size limit [is set by GitLab](../../gitlab_com/index.md#repository-size-limit).
 
 ## Contributors
 
@@ -216,15 +191,7 @@ detected, add the following to `.gitattributes` in the root of your repository.
 
 > *.proto linguist-detectable=true
 
-## Compare
-
-Select branches to compare using the [branch filter search box](branches/index.md#branch-filter-search-box), then click the **Compare** button to view the changes inline:
-
-![compare branches](img/compare_branches.png)
-
-Find it under your project's **Repository > Compare**.
-
-## Locked files **[PREMIUM]**
+## Locked files **(PREMIUM)**
 
 Use [File Locking](../file_lock.md) to
 lock your files to prevent any conflicting changes.
@@ -259,3 +226,15 @@ By clicking the download icon, a dropdown will open with links to download the f
   `tar`, `tar.gz`, and `tar.bz2`.
 - **Artifacts:**
   allows users to download the artifacts of the latest CI build.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md
index e3d771524ce..3adf66e4b6f 100644
--- a/doc/user/project/repository/reducing_the_repo_size_using_git.md
+++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md
@@ -1,3 +1,7 @@
+---
+type: howto
+---
+
 # Reducing the repository size using Git
 
 A GitLab Enterprise Edition administrator can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md)
@@ -35,16 +39,16 @@ BFG Repo-Cleaner](#using-the-bfg-repo-cleaner). It's faster and simpler than
 `git filter-branch`, and GitLab can use its account of what has changed to clean
 up its own internal state, maximizing the space saved.
 
-> **Warning:**
-> Make sure to first make a copy of your repository since rewriting history will
-> purge the files and information you are about to delete. Also make sure to
-> inform any collaborators to not use `pull` after your changes, but use `rebase`.
+CAUTION: **Caution:**
+Make sure to first make a copy of your repository since rewriting history will
+purge the files and information you are about to delete. Also make sure to
+inform any collaborators to not use `pull` after your changes, but use `rebase`.
 
-> **Warning:**
-> This process is not suitable for removing sensitive data like password or keys
-> from your repository. Information about commits, including file content, is
-> cached in the database, and will remain visible even after they have been
-> removed from the repository.
+CAUTION: **Caution:**
+This process is not suitable for removing sensitive data like password or keys
+from your repository. Information about commits, including file content, is
+cached in the database, and will remain visible even after they have been
+removed from the repository.
 
 ## Using the BFG Repo-Cleaner
 
@@ -54,87 +58,100 @@ up its own internal state, maximizing the space saved.
 
 1. Navigate to your repository:
 
-    ```
-    cd my_repository/
-    ```
+   ```
+   cd my_repository/
+   ```
 
 1. Change to the branch you want to remove the big file from:
 
-    ```
-    git checkout master
-    ```
+   ```
+   git checkout master
+   ```
 
 1. Create a commit removing the large file from the branch, if it still exists:
 
-    ```
-    git rm path/to/big_file.mpg
-    git commit -m 'Remove unneeded large file'
-    ```
+   ```
+   git rm path/to/big_file.mpg
+   git commit -m 'Remove unneeded large file'
+   ```
 
 1. Rewrite history:
 
-    ```
-    bfg --delete-files path/to/big_file.mpg
-    ```
+   ```
+   bfg --delete-files path/to/big_file.mpg
+   ```
 
-    An object map file will be written to `object-id-map.old-new.txt`. Keep it
-    around - you'll need it for the final step!
+   An object map file will be written to `object-id-map.old-new.txt`. Keep it
+   around - you'll need it for the final step!
 
 1. Force-push the changes to GitLab:
 
-    ```
-    git push --force-with-lease origin master
-    ```
+   ```
+   git push --force-with-lease origin master
+   ```
 
-    If this step fails, someone has changed the `master` branch while you were
-    rewriting history. You could restore the branch and re-run BFG to preserve
-    their changes, or use `git push --force` to overwrite their changes.
+   If this step fails, someone has changed the `master` branch while you were
+   rewriting history. You could restore the branch and re-run BFG to preserve
+   their changes, or use `git push --force` to overwrite their changes.
 
 1. Navigate to **Project > Settings > Repository > Repository Cleanup**:
 
-    ![Repository settings cleanup form](img/repository_cleanup.png)
+   ![Repository settings cleanup form](img/repository_cleanup.png)
 
-    Upload the `object-id-map.old-new.txt` file and press **Start cleanup**.
-    This will remove any internal git references to the old commits, and run
-    `git gc` against the repository. You will receive an email once it has
-    completed.
+   Upload the `object-id-map.old-new.txt` file and press **Start cleanup**.
+   This will remove any internal git references to the old commits, and run
+   `git gc` against the repository. You will receive an email once it has
+   completed.
 
+NOTE: **Note:**
 This process will remove some copies of the rewritten commits from GitLab's
 cache and database, but there are still numerous gaps in coverage - at present,
-some of the copies may persist indefinitely. [Clearing the instance cache]
-(../../../administration/raketasks/maintenance.md#clear-redis-cache) may help to
-remove some of them, but it should not be depended on for security purposes!
+some of the copies may persist indefinitely. [Clearing the instance cache](../../../administration/raketasks/maintenance.md#clear-redis-cache)
+may help to remove some of them, but it should not be depended on for security
+purposes!
 
 ## Using `git filter-branch`
 
 1. Navigate to your repository:
 
-    ```
-    cd my_repository/
-    ```
+   ```
+   cd my_repository/
+   ```
 
 1. Change to the branch you want to remove the big file from:
 
-    ```
-    git checkout master
-    ```
+   ```
+   git checkout master
+   ```
 
 1. Use `filter-branch` to remove the big file:
 
-    ```
-    git filter-branch --force --tree-filter 'rm -f path/to/big_file.mpg' HEAD
-    ```
+   ```
+   git filter-branch --force --tree-filter 'rm -f path/to/big_file.mpg' HEAD
+   ```
 
 1. Instruct Git to purge the unwanted data:
 
-    ```
-    git reflog expire --expire=now --all && git gc --prune=now --aggressive
-    ```
+   ```
+   git reflog expire --expire=now --all && git gc --prune=now --aggressive
+   ```
 
 1. Lastly, force push to the repository:
 
-    ```
-    git push --force origin master
-    ```
+   ```
+   git push --force origin master
+   ```
 
 Your repository should now be below the size limit.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md
index ce9d23bf911..b5299eaca27 100644
--- a/doc/user/project/repository/web_editor.md
+++ b/doc/user/project/repository/web_editor.md
@@ -1,3 +1,7 @@
+---
+type: howto
+---
+
 # GitLab Web Editor
 
 Sometimes it's easier to make quick changes directly from the GitLab interface
@@ -13,8 +17,6 @@ Choose **New file** from the dropdown.
 
 ![New file dropdown menu](img/web_editor_new_file_dropdown.png)
 
----
-
 Enter a file name in the **File name** box. Then, add file content in the editor
 area. Add a descriptive commit message and choose a branch. The branch field
 will default to the branch you were viewing in the file browser. If you enter
@@ -59,8 +61,6 @@ selector. Choose **Upload file** from the dropdown.
 
 ![Upload file dropdown menu](img/web_editor_upload_file_dropdown.png)
 
----
-
 Once the upload dialog pops up there are two ways to upload your file. Either
 drag and drop a file on the pop up or use the **click to upload** link. A file
 preview will appear once you have selected a file to upload.
@@ -80,8 +80,6 @@ Choose **New directory** from the dropdown.
 
 ![New directory dropdown](img/web_editor_new_directory_dropdown.png)
 
----
-
 In the new directory dialog enter a directory name, a commit message and choose
 the target branch. Click **Create directory** to finish.
 
@@ -107,14 +105,14 @@ Once you click it, a new branch will be created that diverges from the default
 branch of your project, by default `master`. The branch name will be based on
 the title of the issue and as a prefix, it will have its internal ID. Thus, the example
 screenshot above will yield a branch named
-`2-et-cum-et-sed-expedita-repellat-consequatur-ut-assumenda-numquam-rerum`.
+`23177-add-support-for-rich-references-to-referables`.
 
 Since GitLab 9.0, when you click the `New branch` in an empty repository project, GitLab automatically creates the master branch, commits a blank `README.md` file to it and creates and redirects you to a new branch based on the issue title.
 If your [project is already configured with a deployment service][project-services-doc] (e.g. Kubernetes), GitLab takes one step further and prompts you to set up [auto deploy][auto-deploy-doc] by helping you create a `.gitlab-ci.yml` file.
 
 After the branch is created, you can edit files in the repository to fix
 the issue. When a merge request is created based on the newly created branch,
-the description field will automatically display the [issue closing pattern]
+the description field will automatically display the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically)
 `Closes #ID`, where `ID` the ID of the issue. This will close the issue once the
 merge request is merged.
 
@@ -129,8 +127,6 @@ choose **New branch** from the dropdown.
 
 ![New branch dropdown](img/web_editor_new_branch_dropdown.png)
 
----
-
 Enter a new **Branch name**. Optionally, change the **Create from** field
 to choose which branch, tag or commit SHA this new branch will originate from.
 This field will autocomplete if you start typing an existing branch or tag.
@@ -139,8 +135,6 @@ branch.
 
 ![New branch page](img/web_editor_new_branch_page.png)
 
----
-
 You can now make changes to any files, as needed. When you're ready to merge
 the changes back to master you can use the widget at the top of the screen.
 This widget only appears for a period of time after you create the branch or
@@ -156,8 +150,6 @@ SHA. From a project's files page, choose **New tag** from the dropdown.
 
 ![New tag dropdown](img/web_editor_new_tag_dropdown.png)
 
----
-
 Give the tag a name such as `v1.0.0`. Choose the branch or SHA from which you
 would like to create this new tag. You can optionally add a message and
 release notes. The release notes section supports markdown format and you can
@@ -181,4 +173,15 @@ through the web editor, you can choose to use another of your linked email
 addresses from the **User Settings > Edit Profile** page.
 
 [ce-2808]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2808
-[issue closing pattern]: ../issues/automatic_issue_closing.md
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md
index 1a582164d03..645b9bffcc1 100644
--- a/doc/user/project/service_desk.md
+++ b/doc/user/project/service_desk.md
@@ -1,4 +1,4 @@
-# Service Desk **[PREMIUM]**
+# Service Desk **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/149) in [GitLab Premium 9.1](https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#service-desk-eep).
 
@@ -53,36 +53,35 @@ Service Desk is enabled on GitLab.com. If you're a
 [Silver subscriber](https://about.gitlab.com/gitlab-com/),
 you can skip the step 1 below; you only need to enable it per project.
 
-1.   [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. This must
-     support [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing).
-2.   Navigate to your project's **Settings** and scroll down to the **Service Desk**
-     section.
-3.   If you have the correct access and an Premium license,
-     you will see an option to set up Service Desk:
+1. [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. This must
+   support [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing).
+1. Navigate to your project's **Settings** and scroll down to the **Service Desk**
+   section.
+1. If you have the correct access and an Premium license,
+   you will see an option to set up Service Desk:
 
-     ![Activate Service Desk option](img/service_desk_disabled.png)
+   ![Activate Service Desk option](img/service_desk_disabled.png)
 
-4.   Checking that box will enable Service Desk for the project, and show a
-     unique email address to email issues to the project. These issues will be
-     [confidential](issues/confidential_issues.md), so they will only be visible to project members.
+1. Checking that box will enable Service Desk for the project, and show a
+   unique email address to email issues to the project. These issues will be
+   [confidential](issues/confidential_issues.md), so they will only be visible to project members.
 
-     **Warning**: this email address can be used by anyone to create an issue on
-     this project, whether or not they have access to your GitLab instance.
-     We recommend **putting this behind an alias** so that it can be changed if
-     needed, and **[enabling Akismet](../../integration/akismet.md)** on your GitLab instance to add spam
-     checking to this service.  Unblocked email spam would result in many spam
-     issues being created, and may disrupt your GitLab service.
+   **Warning**: this email address can be used by anyone to create an issue on
+   this project, whether or not they have access to your GitLab instance.
+   We recommend **putting this behind an alias** so that it can be changed if
+   needed, and **[enabling Akismet](../../integration/akismet.md)** on your GitLab instance to add spam
+   checking to this service.  Unblocked email spam would result in many spam
+   issues being created, and may disrupt your GitLab service.
 
-     ![Service Desk enabled](img/service_desk_enabled.png)
+   ![Service Desk enabled](img/service_desk_enabled.png)
 
-     _In GitLab 11.7, we updated the format of the generated email address.
-     However the older format is still supported, allowing existing aliases
-     or contacts to continue working._
+   _In GitLab 11.7, we updated the format of the generated email address.
+   However the older format is still supported, allowing existing aliases
+   or contacts to continue working._
 
+1. Service Desk is now enabled for this project! You should be able to access it from your project's navigation **Issue submenu**:
 
-5.   Service Desk is now enabled for this project! You should be able to access it from your project's navigation **Issue submenu**:
-
-     ![Service Desk Navigation Item](img/service_desk_nav_item.png)
+   ![Service Desk Navigation Item](img/service_desk_nav_item.png)
 
 ## Using Service Desk
 
diff --git a/doc/user/project/settings/img/general_settings.png b/doc/user/project/settings/img/general_settings.png
index 4ff6fff5ca3..f88a158d2be 100644
--- a/doc/user/project/settings/img/general_settings.png
+++ b/doc/user/project/settings/img/general_settings.png
diff --git a/doc/user/project/settings/img/import_export_download_export.png b/doc/user/project/settings/img/import_export_download_export.png
index ab81c87bf5f..c7ab7565fc7 100644
--- a/doc/user/project/settings/img/import_export_download_export.png
+++ b/doc/user/project/settings/img/import_export_download_export.png
diff --git a/doc/user/project/settings/img/import_export_export_button.png b/doc/user/project/settings/img/import_export_export_button.png
index 9e368739695..6933e3edfcc 100644
--- a/doc/user/project/settings/img/import_export_export_button.png
+++ b/doc/user/project/settings/img/import_export_export_button.png
diff --git a/doc/user/project/settings/img/import_export_mail_link.png b/doc/user/project/settings/img/import_export_mail_link.png
index 985c37650d3..1bd9a071178 100644
--- a/doc/user/project/settings/img/import_export_mail_link.png
+++ b/doc/user/project/settings/img/import_export_mail_link.png
diff --git a/doc/user/project/settings/img/import_export_new_project.png b/doc/user/project/settings/img/import_export_new_project.png
index fc1f73c5d6e..0e2365ecb68 100644
--- a/doc/user/project/settings/img/import_export_new_project.png
+++ b/doc/user/project/settings/img/import_export_new_project.png
diff --git a/doc/user/project/settings/img/import_export_select_file.png b/doc/user/project/settings/img/import_export_select_file.png
index e3e1a5ef980..90a3e8d5c4e 100644
--- a/doc/user/project/settings/img/import_export_select_file.png
+++ b/doc/user/project/settings/img/import_export_select_file.png
diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md
index 819515d7a4c..9c1a31fb7c3 100644
--- a/doc/user/project/settings/import_export.md
+++ b/doc/user/project/settings/import_export.md
@@ -2,33 +2,33 @@
 
 >**Notes:**
 >
->  - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/3050) in GitLab 8.9.
->  - Importing will not be possible if the import instance version differs from
->    that of the exporter.
->  - For GitLab admins, please read through 
->    [Project import/export administration](../../../administration/raketasks/project_import_export.md).
->  - For existing installations, the project import option has to be enabled in
->    application settings (`/admin/application_settings`) under 'Import sources'.
->    Ask your administrator if you don't see the **GitLab export** button when
->    creating a new project.
->  - Starting with GitLab 10.0, administrators can disable the project export option
->    on the GitLab instance in application settings (`/admin/application_settings`)
->    under 'Visibility and Access Controls'.
->  - You can find some useful raketasks if you are an administrator in the
->    [import_export](../../../administration/raketasks/project_import_export.md) raketask.
->  - The exports are stored in a temporary [shared directory](../../../development/shared_files.md) 
->    and are deleted every 24 hours by a specific worker.
->  - Group members will get exported as project members, as long as the user has
->    maintainer or admin access to the group where the exported project lives. An admin
->    in the import side is required to map the users, based on email or username.
->    Otherwise, a supplementary comment is left to mention the original author and
->    the MRs, notes or issues will be owned by the importer.
->  - Project members with owner access will get imported as maintainers.
->  - Control project Import/Export with the [API](../../../api/project_import_export.md).
->  - If an imported project contains merge requests originated from forks, 
->    then new branches associated with such merge requests will be created 
->    within a project during the import/export. Thus, the number of branches 
->    in the exported project could be bigger than in the original project.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/3050) in GitLab 8.9.
+> - Importing will not be possible if the import instance version differs from
+>   that of the exporter.
+> - For GitLab admins, please read through
+>   [Project import/export administration](../../../administration/raketasks/project_import_export.md).
+> - For existing installations, the project import option has to be enabled in
+>   application settings (`/admin/application_settings`) under 'Import sources'.
+>   Ask your administrator if you don't see the **GitLab export** button when
+>   creating a new project.
+> - Starting with GitLab 10.0, administrators can disable the project export option
+>   on the GitLab instance in application settings (`/admin/application_settings`)
+>   under 'Visibility and Access Controls'.
+> - You can find some useful raketasks if you are an administrator in the
+>   [import_export](../../../administration/raketasks/project_import_export.md) raketask.
+> - The exports are stored in a temporary [shared directory](../../../development/shared_files.md)
+>   and are deleted every 24 hours by a specific worker.
+> - Group members will get exported as project members, as long as the user has
+>   maintainer or admin access to the group where the exported project lives. An admin
+>   in the import side is required to map the users, based on email or username.
+>   Otherwise, a supplementary comment is left to mention the original author and
+>   the MRs, notes or issues will be owned by the importer.
+> - Project members with owner access will get imported as maintainers.
+> - Control project Import/Export with the [API](../../../api/project_import_export.md).
+> - If an imported project contains merge requests originated from forks,
+>   then new branches associated with such merge requests will be created
+>   within a project during the import/export. Thus, the number of branches
+>   in the exported project could be bigger than in the original project.
 
 Existing projects running on any GitLab instance or GitLab.com can be exported
 with all their related data and be moved into a new GitLab instance.
@@ -66,6 +66,7 @@ The following items will be exported:
 - Issues with comments, merge requests with diffs and comments, labels, milestones, snippets,
   and other project entities
 - LFS objects
+- Issue boards
 
 The following items will NOT be exported:
 
@@ -74,6 +75,13 @@ The following items will NOT be exported:
 - CI variables
 - Webhooks
 - Any encrypted tokens
+- Merge Request Approvers
+- Push Rules
+- Awards
+
+NOTE: **Note:**
+For more details on the specific data persisted in a project export, see the
+[`import_export.yml`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/import_export/import_export.yml) file.
 
 ## Exporting a project and its data
 
@@ -83,29 +91,34 @@ The following items will NOT be exported:
 
 1. Scroll down to find the **Export project** button:
 
-    ![Export button](img/import_export_export_button.png)
+   ![Export button](img/import_export_export_button.png)
 
 1. Once the export is generated, you should receive an e-mail with a link to
    download the file:
 
-    ![Email download link](img/import_export_mail_link.png)
+   ![Email download link](img/import_export_mail_link.png)
 
 1. Alternatively, you can come back to the project settings and download the
    file from there, or generate a new export. Once the file available, the page
    should show the **Download export** button:
 
-    ![Download export](img/import_export_download_export.png)
+   ![Download export](img/import_export_download_export.png)
 
 ## Importing the project
 
-1. The GitLab project import feature is the first import option when creating a 
+1. The GitLab project import feature is the first import option when creating a
    new project. Click on **GitLab export**:
 
-    ![New project](img/import_export_new_project.png)
+   ![New project](img/import_export_new_project.png)
 
 1. Enter your project name and URL. Then select the file you exported previously:
 
-    ![Select file](img/import_export_select_file.png)
+   ![Select file](img/import_export_select_file.png)
 
 1. Click on **Import project** to begin importing. Your newly imported project
    page will appear soon.
+
+NOTE: **Note:**
+If use of the `Internal` visibility level
+[is restricted](../../../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects),
+all imported projects are given the visibility of `Private`.
diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md
index ba890c5ac01..4e3db95b6d6 100644
--- a/doc/user/project/settings/index.md
+++ b/doc/user/project/settings/index.md
@@ -9,7 +9,7 @@ to your project's homepage and clicking **Settings**.
 
 ## General settings
 
-Under a project's general settings you can find everything concerning the
+Under a project's general settings, you can find everything concerning the
 functionality of a project.
 
 ### General project settings
@@ -18,7 +18,7 @@ Adjust your project's name, description, avatar, [default branch](../repository/
 
 ![general project settings](img/general_settings.png)
 
-The project description also partially supports [standard markdown](../../markdown.md#standard-markdown). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description.
+The project description also partially supports [standard markdown](../../markdown.md#standard-markdown-and-extensions-in-gitlab). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description.
 
 ### Sharing and permissions
 
@@ -26,12 +26,18 @@ Set up your project's access, [visibility](../../../public_access/public_access.
 
 ![projects sharing permissions](img/sharing_and_permissions_settings.png)
 
-If Issues are disabled, or you can't access Issues because you're not a project member, then Lables and Milestones 
+If Issues are disabled, or you can't access Issues because you're not a project member, then Labels and Milestones
 links will be missing from the sidebar UI.
 
-You can still access them with direct links if you can access Merge Requests. This is deliberate, if you can see 
+You can still access them with direct links if you can access Merge Requests. This is deliberate, if you can see
 Issues or Merge Requests, both of which use Labels and Milestones, then you shouldn't be denied access to Labels and Milestones pages.
 
+#### Disabling email notifications
+
+You can disable all email notifications related to the project by selecting the 
+**Disable email notifications** checkbox.  Only the project owner is allowed to change
+this setting.
+
 ### Issue settings
 
 Add an [issue description template](../description_templates.md#description-templates) to your project, so that every new issue will start with a custom template.
@@ -42,13 +48,13 @@ Set up your project's merge request settings:
 
 - Set up the merge request method (merge commit, [fast-forward merge](../merge_requests/fast_forward_merge.html)).
 - Merge request [description templates](../description_templates.md#description-templates).
-- Enable [merge request approvals](../merge_requests/merge_request_approvals.md). **[STARTER]**
+- Enable [merge request approvals](../merge_requests/merge_request_approvals.md). **(STARTER)**
 - Enable [merge only of pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md).
-- Enable [merge only when all discussions are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-discussions-are-resolved).
+- Enable [merge only when all discussions are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved).
 
 ![project's merge request settings](img/merge_requests_settings.png)
 
-### Service Desk **[PREMIUM]**
+### Service Desk **(PREMIUM)**
 
 Enable [Service Desk](../service_desk.md) for your project to offer customer support.
 
@@ -109,8 +115,8 @@ You can transfer an existing project into a [group](../../group/index.md) if:
 1. You have at least **Maintainer** [permissions] to that group.
 1. The project is in a subgroup you own.
 1. You are at least a **Maintainer** of the project under your personal namespace.
-Similarly, if you are an owner of a group, you can transfer any of its projects
-under your own user.
+   Similarly, if you are an owner of a group, you can transfer any of its projects
+   under your own user.
 
 To transfer a project:
 
@@ -135,6 +141,6 @@ namespace if needed.
 
 Configure Error Tracking to discover and view [Sentry errors within GitLab](../operations/error_tracking.md).
 
-### Jaeger tracing **[ULTIMATE]**
+### Jaeger tracing **(ULTIMATE)**
 
 Add the URL of a Jaeger server to allow your users to [easily access the Jaeger UI from within GitLab](../operations/tracing.md).
diff --git a/doc/user/project/web_ide/img/terminal_status.png b/doc/user/project/web_ide/img/terminal_status.png
new file mode 100644
index 00000000000..91c341a9854
--- /dev/null
+++ b/doc/user/project/web_ide/img/terminal_status.png
diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md
index a634a8b2f54..9bf400e7dff 100644
--- a/doc/user/project/web_ide/index.md
+++ b/doc/user/project/web_ide/index.md
@@ -67,8 +67,8 @@ shows you a preview of the merge request diff if you commit your changes.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19279) in [GitLab Core][ce] 11.0.
 
-You can use the Web IDE to quickly fix failing tests by opening 
-the branch or merge request in the Web IDE and opening the logs of the failed 
+You can use the Web IDE to quickly fix failing tests by opening
+the branch or merge request in the Web IDE and opening the logs of the failed
 job. You can access the status of all jobs for the most recent pipeline and job
 traces for the current commit by clicking the **Pipelines** button in the top
 right.
@@ -80,8 +80,8 @@ left.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19318) in [GitLab Core][ce] 11.0.
 
-To switch between your authored and assigned merge requests, click the 
-dropdown in the top of the sidebar to open a list of merge requests. You will 
+To switch between your authored and assigned merge requests, click the
+dropdown in the top of the sidebar to open a list of merge requests. You will
 need to commit or discard all your changes before switching to a different merge
 request.
 
@@ -89,9 +89,9 @@ request.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20850) in [GitLab Core][ce] 11.2.
 
-To switch between branches of the current project repository, click the dropdown 
-in the top of the sidebar to open a list of branches. 
-You will need to commit or discard all your changes before switching to a 
+To switch between branches of the current project repository, click the dropdown
+in the top of the sidebar to open a list of branches.
+You will need to commit or discard all your changes before switching to a
 different branch.
 
 ## Client Side Evaluation
@@ -117,7 +117,7 @@ GitLab.com
 ![Admin Client Side Evaluation setting](img/admin_clientside_evaluation.png)
 
 Once you have done that, you can preview projects with a `package.json` file and
-a `main` entry point inside the Web IDE. An example `package.json` is shown 
+a `main` entry point inside the Web IDE. An example `package.json` is shown
 below.
 
 ```json
@@ -129,33 +129,29 @@ below.
 }
 ```
 
-## Interactive Web Terminals for the Web IDE **[ULTIMATE ONLY]**
+## Interactive Web Terminals for the Web IDE **(ULTIMATE ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6.
 
 CAUTION: **Warning:**
 Interactive Web Terminals for the Web IDE is currently in **Beta**.
+Shared Runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab-ce/issues/52611),
+so you would need to use your own private Runner(s) to make use of this feature.
 
-[Interactive web terminals](../../../ci/interactive_web_terminal/index.md)
-give the user access to a terminal to interact with the Runner directly from
+[Interactive Web Terminals](../../../ci/interactive_web_terminal/index.md)
+give the project [Maintainers](../../permissions.md#project-members-permissions)
+user access to a terminal to interact with the Runner directly from
 GitLab, including through the Web IDE.
 
-Only project [**maintainers**](../../permissions.md#project-members-permissions)
-can run Interactive Web Terminals through the Web IDE.
-
-CAUTION: **Warning:**
-GitLab.com [does not support Interactive Web Terminals yet](https://gitlab.com/gitlab-org/gitlab-ce/issues/52611).
-Shared Runners in private instances are not supported either.
-
 ### Runner configuration
 
 Some things need to be configured in the runner for the interactive web terminal
 to work:
 
-- The Runner needs to have 
+- The Runner needs to have
   [`[session_server]` configured properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section).
 - If you are using a reverse proxy with your GitLab instance, web terminals need to be
-  [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **[ULTIMATE ONLY]**
+  [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **(ULTIMATE ONLY)**
 
 If you have the terminal open and the job has finished with its tasks, the
 terminal will block the job from finishing for the duration configured in
@@ -175,13 +171,13 @@ syntax but with some restrictions:
 - No global blocks can be defined (ie: `before_script` or `after_script`)
 - Only one job named `terminal` can be added to this file.
 - Only the keywords `image`, `services`, `tags`, `before_script`, `script`, and
-`variables` are allowed to be used to configure the job.
+  `variables` are allowed to be used to configure the job.
 - To connect to the interactive terminal, the `terminal` job must be still alive
-and running, otherwise the terminal won't be able to connect to the job's session.
-By default the `script` keyword has the value `sleep 60` to prevent
-the job from ending and giving the Web IDE enough time to connect. This means
-that, if you override the default `script` value, you'll have to add a command
-which would keep the job running, like `sleep`.
+  and running, otherwise the terminal won't be able to connect to the job's session.
+  By default the `script` keyword has the value `sleep 60` to prevent
+  the job from ending and giving the Web IDE enough time to connect. This means
+  that, if you override the default `script` value, you'll have to add a command
+  which would keep the job running, like `sleep`.
 
 In the code below there is an example of this configuration file:
 
@@ -204,7 +200,7 @@ the selected branch of the Web IDE.
 
 If there is no configuration file in a branch, an error message will be shown.
 
-### Running Interactive Terminals in the Web IDE
+### Running interactive terminals in the Web IDE
 
 If Interactive Terminals are available for the current user, the **Terminal** button
 will be visible in the right sidebar of the Web IDE. Click this button to open
@@ -212,7 +208,7 @@ or close the terminal tab.
 
 Once open, the tab will show the **Start Web Terminal** button. This button may
 be disabled if the environment is not configured correctly. If so, a status
-message will describe the issue. Here are some reasons why **Start Web Terminal** 
+message will describe the issue. Here are some reasons why **Start Web Terminal**
 may be disabled:
 
 - `.gitlab/.gitlab-webide.yml` does not exist or is set up incorrectly.
@@ -231,9 +227,62 @@ While the terminal is running, it can be stopped by clicking **Stop Terminal**.
 This will disconnect the terminal and stop the runner's terminal job. From here,
 click **Restart Terminal** to start a new terminal session.
 
+### File syncing to web terminal
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5276) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0.
+
+File changes in the Web IDE can be synced to a running web terminal.
+This enables users to test their code changes in a preconfigured terminal
+environment.
+
+NOTE: **Note:**
+Only file changes in the Web IDE are synced to the terminal.
+Changes made in the terminal are **not** synced to the Web IDE.
+This feature is only available for Kubernetes Runners.
+
+To enable file syncing to the web terminal, the `.gitlab/.gitlab-webide.yml`
+file needs to have a `webide-file-sync` service configured. Here is an example
+configuration for a Node JS project which uses this service:
+
+```yaml
+terminal:
+  # This can be any image that has the necessary runtime environment for your project.
+  image:
+    name: node:10-alpine
+  services:
+    - name: registry.gitlab.com/gitlab-org/webide-file-sync:latest
+      alias: webide-file-sync
+      entrypoint: ["/bin/sh"]
+      command: ["-c", "sleep 5 && ./webide-file-sync -project-dir $CI_PROJECT_DIR"]
+      ports:
+        # The `webide-file-sync` executable defaults to port 3000.
+        - number: 3000
+```
+
+- The `webide-file-sync` executable must start **after** the project
+  directory is available. This is why we need to add `sleep 5` to the `command`.
+  See [this issue](https://gitlab.com/gitlab-org/webide-file-sync/issues/7) for
+  more info.
+- `$CI_PROJECT_DIR` is a
+  [predefined environment variable](../../../ci/variables/predefined_variables.md)
+  for GitLab Runners. This is where your project's repository will be.
+
+Once you have configured the web terminal for file syncing, then when the web
+terminal is started, a **Terminal** status will be visible in the status bar.
+
+![Web IDE Client Side Evaluation](img/terminal_status.png)
+
+Changes made to your files via the Web IDE will sync to the running terminal
+when:
+
+- <kbd>Ctrl</kbd> + <kbd>S</kbd> (or <kbd>Cmd</kbd> + <kbd>S</kbd> on Mac)
+  is pressed while editing a file.
+- Anything outside the file editor is clicked after editing a file.
+- A file or folder is created, deleted, or renamed.
+
 ### Limitations
 
-Interactive Terminals is in a beta phase and will continue to be improved upon in upcoming 
+Interactive Terminals is in a beta phase and will continue to be improved upon in upcoming
 releases. In the meantime, please note that the user is limited to having only one
 active terminal at a time.
 
@@ -246,6 +295,5 @@ active terminal at a time.
   connect to the runner. Please try to stop and restart the terminal. If the
   problem persists, double check your runner configuration.
 
-
 [ce]: https://about.gitlab.com/pricing/
 [ee]: https://about.gitlab.com/pricing/
diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md
index 9e8475d8294..68532ccee65 100644
--- a/doc/user/reserved_names.md
+++ b/doc/user/reserved_names.md
@@ -40,19 +40,18 @@ It is currently not possible to create a project with the following names:
 
 Currently the following names are reserved as top level groups:
 
-- 503.html
 - \-
 - .well-known
 - 404.html
 - 422.html
 - 500.html
 - 502.html
+- 503.html
 - abuse_reports
 - admin
 - api
 - apple-touch-icon-precomposed.png
 - apple-touch-icon.png
-- files
 - assets
 - autocomplete
 - ci
@@ -61,12 +60,14 @@ Currently the following names are reserved as top level groups:
 - explore
 - favicon.ico
 - favicon.png
+- files
 - groups
 - health_check
 - help
 - import
 - invites
 - jwt
+- login
 - notification_settings
 - oauth
 - profile
@@ -78,8 +79,6 @@ Currently the following names are reserved as top level groups:
 - sent_notifications
 - slash-command-logo.png
 - snippets
-- u
-- unicorn_test
 - unsubscribes
 - uploads
 - users
@@ -88,22 +87,5 @@ Currently the following names are reserved as top level groups:
 These group names are unavailable as subgroup names:
 
 - \-
-- activity
-- analytics
-- audit_events
-- avatar
-- edit
-- group_members
-- hooks
-- issues
-- labels
-- ldap
-- ldap_group_links
-- merge_requests
-- milestones
-- notification_setting
-- pipeline_quota
-- projects
-- subgroups
 
 [reserved]:  https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/path_regex.rb
diff --git a/doc/user/search/advanced_global_search.md b/doc/user/search/advanced_global_search.md
index f80f4183802..52da6d65000 100644
--- a/doc/user/search/advanced_global_search.md
+++ b/doc/user/search/advanced_global_search.md
@@ -1,4 +1,4 @@
-# Advanced Global Search **[STARTER ONLY]**
+# Advanced Global Search **(STARTER ONLY)**
 
 > - [Introduced][ee-109] in GitLab [Starter][ee] 8.4.
 > - This is the user documentation. To install and configure Elasticsearch,
diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md
index d302cb7a809..c3d22e4fd29 100644
--- a/doc/user/search/advanced_search_syntax.md
+++ b/doc/user/search/advanced_search_syntax.md
@@ -1,4 +1,4 @@
-# Advanced Syntax Search **[STARTER ONLY]**
+# Advanced Syntax Search **(STARTER ONLY)**
 
 > **Notes:**
 > - Introduced in [GitLab Enterprise Starter][ee] 9.2
@@ -50,9 +50,9 @@ here's a quick guide:
 
 The Advanced Syntax Search also supports the use of filters. The available filters are:
 
- - filename: Filters by filename. You can use the glob (`*`) operator for fuzzy matching.
- - path: Filters by path. You can use the glob (`*`) operator for fuzzy matching.
- - extension: Filters by extension in the filename. Please write the extension without a leading dot. Exact match only.
+- filename: Filters by filename. You can use the glob (`*`) operator for fuzzy matching.
+- path: Filters by path. You can use the glob (`*`) operator for fuzzy matching.
+- extension: Filters by extension in the filename. Please write the extension without a leading dot. Exact match only.
 
 To use them, simply add them to your query in the format `<filter_name>:<value>` without
  any spaces between the colon (`:`) and the value.
diff --git a/doc/user/search/index.md b/doc/user/search/index.md
index bb6c48471c7..8d7b4a429aa 100644
--- a/doc/user/search/index.md
+++ b/doc/user/search/index.md
@@ -55,12 +55,12 @@ Selecting **Any** does the opposite. It returns results that have a non-empty va
 You can filter issues and merge requests by specific terms included in titles or descriptions.
 
 - Syntax
-    - Searches look for all the words in a query, in any order. E.g.: searching
-      issues for `display bug` will return all issues matching both those words, in any order.
-    - To find the exact term, use double quotes: `"display bug"`
+  - Searches look for all the words in a query, in any order. E.g.: searching
+    issues for `display bug` will return all issues matching both those words, in any order.
+  - To find the exact term, use double quotes: `"display bug"`
 - Limitation
-    - For performance reasons, terms shorter than 3 chars are ignored. E.g.: searching
-      issues for `included in titles` is same as `included titles`
+  - For performance reasons, terms shorter than 3 chars are ignored. E.g.: searching
+    issues for `included in titles` is same as `included titles`
 
 ![filter issues by specific terms](img/issue_search_by_term.png)
 
@@ -97,10 +97,10 @@ quickly access issues and merge requests created or assigned to you within that
 
 ![search per project - shortcut](img/project_search.png)
 
-## Todos
+## To-Do List
 
-Your [todos](../../workflow/todos.md#gitlab-todos) can be searched by "to do" and "done".
-You can [filter](../../workflow/todos.md#filtering-your-todos) them per project,
+Your [To-Do List](../../workflow/todos.md#gitlab-to-do-list) can be searched by "to do" and "done".
+You can [filter](../../workflow/todos.md#filtering-your-to-do-list) them per project,
 author, type, and action. Also, you can sort them by
 [**Label priority**](../../user/project/labels.md#label-priority),
 **Last created** and **Oldest created**.
@@ -143,14 +143,14 @@ and **Labels**, select multiple issues to add to a list of your choice:
 
 ![search and select issues to add to board](img/search_issues_board.png)
 
-## Advanced Global Search **[STARTER]**
+## Advanced Global Search **(STARTER)**
 
 Leverage Elasticsearch for faster, more advanced code search across your entire
 GitLab instance.
 
 [Learn how to use the Advanced Global Search.](advanced_global_search.md)
 
-## Advanced Syntax Search **[STARTER]**
+## Advanced Syntax Search **(STARTER)**
 
 Use advanced queries for more targeted search results.
 
diff --git a/doc/workflow/README.md b/doc/workflow/README.md
index 40e2486ace5..c6396672e59 100644
--- a/doc/workflow/README.md
+++ b/doc/workflow/README.md
@@ -4,7 +4,7 @@ comments: false
 
 # Workflow
 
-- [Automatic issue closing](../user/project/issues/automatic_issue_closing.md)
+- [Automatic issue closing](../user/project/issues/managing_issues.md#closing-issues-automatically)
 - [Change your time zone](timezone.md)
 - [Cycle Analytics](../user/project/cycle_analytics.md)
 - [Description templates](../user/project/description_templates.md)
@@ -13,15 +13,15 @@ comments: false
 - [Groups](../user/group/index.md)
 - Issues - The GitLab Issue Tracker is an advanced and complete tool for
   tracking the evolution of a new idea or the process of solving a problem.
-  - [Exporting Issues](../user/project/issues/csv_export.md) **[STARTER]** Export issues as a CSV, emailed as an attachment.
+  - [Exporting Issues](../user/project/issues/csv_export.md) **(STARTER)** Export issues as a CSV, emailed as an attachment.
   - [Confidential issues](../user/project/issues/confidential_issues.md)
   - [Due date for issues](../user/project/issues/due_dates.md)
 - [Issue Board](../user/project/issue_board.md)
 - [Keyboard shortcuts](shortcuts.md)
 - [File finder](file_finder.md)
-- [File lock](../user/project/file_lock.md) **[PREMIUM]**
+- [File lock](../user/project/file_lock.md) **(PREMIUM)**
 - [Labels](../user/project/labels.md)
-- [Issue weight](issue_weight.md) **[STARTER]**
+- [Issue weight](issue_weight.md) **(STARTER)**
 - [Notification emails](notifications.md)
 - [Projects](../user/project/index.md)
 - [Project forking workflow](forking_workflow.md)
@@ -38,15 +38,15 @@ comments: false
   - [Authorization for merge requests](../user/project/merge_requests/authorization_for_merge_requests.md)
   - [Cherry-pick changes](../user/project/merge_requests/cherry_pick_changes.md)
   - [Merge when pipeline succeeds](../user/project/merge_requests/merge_when_pipeline_succeeds.md)
-  - [Resolve discussion comments in merge requests reviews](../user/discussions/index.md)
+  - [Resolve threads in merge requests reviews](../user/discussions/index.md)
   - [Resolve merge conflicts in the UI](../user/project/merge_requests/resolve_conflicts.md)
   - [Revert changes in the UI](../user/project/merge_requests/revert_changes.md)
   - [Merge requests versions](../user/project/merge_requests/versions.md)
   - ["Work In Progress" merge requests](../user/project/merge_requests/work_in_progress_merge_requests.md)
   - [Fast-forward merge requests](../user/project/merge_requests/fast_forward_merge.md)
-  - [Merge request approvals](../user/project/merge_requests/merge_request_approvals.md) **[STARTER]**
-- [Repository mirroring](repository_mirroring.md) **[STARTER]**
-- [Service Desk](../user/project/service_desk.md) **[PREMIUM]**
+  - [Merge request approvals](../user/project/merge_requests/merge_request_approvals.md) **(STARTER)**
+- [Repository mirroring](repository_mirroring.md) **(STARTER)**
+- [Service Desk](../user/project/service_desk.md) **(PREMIUM)**
 - [Manage large binaries with Git LFS](lfs/manage_large_binaries_with_git_lfs.md)
 - [Importing from SVN, GitHub, Bitbucket, etc](importing/README.md)
 - [Todos](todos.md)
diff --git a/doc/workflow/file_finder.md b/doc/workflow/file_finder.md
index 8d87b030c83..52c83caeea8 100644
--- a/doc/workflow/file_finder.md
+++ b/doc/workflow/file_finder.md
@@ -2,8 +2,6 @@
 
 > [Introduced][gh-9889] in GitLab 8.4.
 
----
-
 The file finder feature allows you to quickly shortcut your way when you are
 searching for a file in a repository using the GitLab UI.
 
@@ -12,8 +10,6 @@ project.
 
 ![Find file button](img/file_finder_find_button.png)
 
----
-
 For those who prefer to keep their fingers on the keyboard, there is a
 [shortcut button](shortcuts.md) as well, which you can invoke from _anywhere_
 in a project.
diff --git a/doc/workflow/forking_workflow.md b/doc/workflow/forking_workflow.md
index 02be0ad191d..869a0a621c3 100644
--- a/doc/workflow/forking_workflow.md
+++ b/doc/workflow/forking_workflow.md
@@ -10,31 +10,25 @@ document more information about using branches to work together.
 
 Forking a project is in most cases a two-step process.
 
-1.  Click on the fork button located in the middle of the page or a project's
-    home page right next to the stars button.
+1. Click on the fork button located in the middle of the page or a project's
+   home page right next to the stars button.
 
-    ![Fork button](img/forking_workflow_fork_button.png)
+   ![Fork button](img/forking_workflow_fork_button.png)
 
-    ---
+1. Once you do that, you'll be presented with a screen where you can choose
+   the namespace to fork to. Only namespaces (groups and your own
+   namespace) where you have write access to, will be shown. Click on the
+   namespace to create your fork there.
 
-1.  Once you do that, you'll be presented with a screen where you can choose
-    the namespace to fork to. Only namespaces (groups and your own
-    namespace) where you have write access to, will be shown. Click on the
-    namespace to create your fork there.
+   ![Choose namespace](img/forking_workflow_choose_namespace.png)
 
-    ![Choose namespace](img/forking_workflow_choose_namespace.png)
+   **Note:**
+   If the namespace you chose to fork the project to has another project with
+   the same path name, you will be presented with a warning that the forking
+   could not be completed. Try to resolve the error and repeat the forking
+   process.
 
-    ---
-
-    **Note:**
-    If the namespace you chose to fork the project to has another project with
-    the same path name, you will be presented with a warning that the forking
-    could not be completed. Try to resolve the error and repeat the forking
-    process.
-
-    ![Path taken error](img/forking_workflow_path_taken_error.png)
-
-    ---
+   ![Path taken error](img/forking_workflow_path_taken_error.png)
 
 After the forking is done, you can start working on the newly created
 repository. There, you will have full [Owner](../user/permissions.md)
diff --git a/doc/workflow/git_annex.md b/doc/workflow/git_annex.md
index 84d25951908..9543859f86f 100644
--- a/doc/workflow/git_annex.md
+++ b/doc/workflow/git_annex.md
@@ -54,13 +54,13 @@ sudo yum install epel-release && sudo yum install git-annex
 For omnibus-gitlab packages, only one configuration setting is needed.
 The Omnibus package will internally set the correct options in all locations.
 
-1.  In `/etc/gitlab/gitlab.rb` add the following line:
+1. In `/etc/gitlab/gitlab.rb` add the following line:
 
-    ```ruby
-    gitlab_shell['git_annex_enabled'] = true
-    ```
+   ```ruby
+   gitlab_shell['git_annex_enabled'] = true
+   ```
 
-1.  Save the file and [reconfigure GitLab][] for the changes to take effect.
+1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
 ### Configuration for installations from source
 
@@ -69,20 +69,20 @@ There are 2 settings to enable git-annex on your GitLab server.
 One is located in `config/gitlab.yml` of the GitLab repository and the other
 one is located in `config.yml` of gitlab-shell.
 
-1.  In `config/gitlab.yml` add or edit the following lines:
+1. In `config/gitlab.yml` add or edit the following lines:
 
-    ```yaml
-    gitlab_shell:
-      git_annex_enabled: true
-    ```
+   ```yaml
+   gitlab_shell:
+     git_annex_enabled: true
+   ```
 
-1.  In `config.yml` of gitlab-shell add or edit the following lines:
+1. In `config.yml` of gitlab-shell add or edit the following lines:
 
-    ```yaml
-    git_annex_enabled: true
-    ```
+   ```yaml
+   git_annex_enabled: true
+   ```
 
-1.  Save the files and [restart GitLab][] for the changes to take effect.
+1. Save the files and [restart GitLab][] for the changes to take effect.
 
 ## Using GitLab git-annex
 
diff --git a/doc/workflow/gitlab_flow.md b/doc/workflow/gitlab_flow.md
index 3e24557591c..2f365e42cc9 100644
--- a/doc/workflow/gitlab_flow.md
+++ b/doc/workflow/gitlab_flow.md
@@ -1,7 +1,8 @@
-![GitLab Flow](gitlab_flow.png)
 
 # Introduction to GitLab Flow
 
+![GitLab Flow](img/gitlab_flow.png)
+
 Git allows a wide variety of branching strategies and workflows.
 Because of this, many organizations end up with workflows that are too complicated, not clearly defined, or not integrated with issue tracking systems.
 Therefore, we propose GitLab flow as a clearly defined set of best practices.
@@ -11,7 +12,7 @@ Organizations coming to Git from other version control systems frequently find i
 This article describes GitLab flow, which integrates the Git workflow with an issue tracking system.
 It offers a simple, transparent, and effective way to work with Git.
 
-![Four stages (working copy, index, local repo, remote repo) and three steps between them](four_stages.png)
+![Four stages (working copy, index, local repo, remote repo) and three steps between them](img/four_stages.png)
 
 When converting to Git, you have to get used to the fact that it takes three steps to share a commit with colleagues.
 Most version control systems have only one step: committing from the working copy to a shared server.
@@ -19,7 +20,7 @@ In Git, you add files from the working copy to the staging area. After that, you
 The third step is pushing to a shared remote repository.
 After getting used to these three steps, the next challenge is the branching model.
 
-![Multiple long-running branches and merging in all directions](messy_flow.png)
+![Multiple long-running branches and merging in all directions](img/messy_flow.png)
 
 Since many organizations new to Git have no conventions for how to work with it, their repositories can quickly become messy.
 The biggest problem is that many long-running branches emerge that all contain part of the changes.
@@ -31,7 +32,7 @@ For a video introduction of how this works in GitLab, see [GitLab Flow](https://
 
 ## Git flow and its problems
 
-![Git Flow timeline by Vincent Driessen, used with permission](gitdashflow.png)
+![Git Flow timeline by Vincent Driessen, used with permission](img/gitdashflow.png)
 
 Git flow was one of the first proposals to use Git branches, and it has received a lot of attention.
 It suggests a `master` branch and a separate `develop` branch, as well as supporting branches for features, releases, and hotfixes.
@@ -54,7 +55,7 @@ For example, many projects do releases but don't need to do hotfixes.
 
 ## GitHub flow as a simpler alternative
 
-![Master branch with feature branches merged in](github_flow.png)
+![Master branch with feature branches merged in](img/github_flow.png)
 
 In reaction to Git flow, GitHub created a simpler alternative.
 [GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `master` branch.
@@ -66,7 +67,7 @@ With GitLab flow, we offer additional guidance for these questions.
 
 ## Production branch with GitLab flow
 
-![Master branch and production branch with an arrow that indicates a deployment](production_branch.png)
+![Master branch and production branch with an arrow that indicates a deployment](img/production_branch.png)
 
 GitHub flow assumes you can deploy to production every time you merge a feature branch.
 While this is possible in some cases, such as SaaS applications, there are many cases where this is not possible.
@@ -82,7 +83,7 @@ This flow prevents the overhead of releasing, tagging, and merging that happens
 
 ## Environment branches with GitLab flow
 
-![Multiple branches with the code cascading from one to another](environment_branches.png)
+![Multiple branches with the code cascading from one to another](img/environment_branches.png)
 
 It might be a good idea to have an environment that is automatically updated to the `master` branch.
 Only, in this case, the name of this environment might differ from the branch name.
@@ -98,7 +99,7 @@ If this is not possible because more manual testing is required, you can send me
 
 ## Release branches with GitLab flow
 
-![Master and multiple release branches that vary in length with cherry-picks from master](release_branches.png)
+![Master and multiple release branches that vary in length with cherry-picks from master](img/release_branches.png)
 
 You only need to work with release branches if you need to release software to the outside world.
 In this case, each branch contains a minor version, for example, 2-3-stable, 2-4-stable, etc.
@@ -114,7 +115,7 @@ In this flow, it is not common to have a production branch (or Git flow `master`
 
 ## Merge/pull requests with GitLab flow
 
-![Merge request with inline comments](mr_inline_comments.png)
+![Merge request with inline comments](img/mr_inline_comments.png)
 
 Merge or pull requests are created in a Git management application. They ask an assigned person to merge two branches.
 Tools such as GitHub and Bitbucket choose the name "pull request" since the first manual action is to pull the feature branch.
@@ -147,11 +148,11 @@ It also ensures that if someone reopens the issue, they can use the same branch
 NOTE: **Note:**
 When you reopen an issue you need to create a new merge request.
 
-![Remove checkbox for branch in merge requests](remove_checkbox.png)
+![Remove checkbox for branch in merge requests](img/remove_checkbox.png)
 
 ## Issue tracking with GitLab flow
 
-![Merge request with the branch name "15-require-a-password-to-change-it" and assignee field shown](merge_request.png)
+![Merge request with the branch name "15-require-a-password-to-change-it" and assignee field shown](img/merge_request.png)
 
 GitLab flow is a way to make the relation between the code and the issue tracker more transparent.
 
@@ -175,7 +176,7 @@ A merge request is an online place to discuss the change and review the code.
 
 If you open the merge request but do not assign it to anyone, it is a "Work In Progress" merge request.
 These are used to discuss the proposed implementation but are not ready for inclusion in the `master` branch yet.
-Start the title of the merge request with "[WIP]" or "WIP:" to prevent it from being merged before it's ready.
+Start the title of the merge request with `[WIP]` or `WIP:` to prevent it from being merged before it's ready.
 
 When you think the code is ready, assign the merge request to a reviewer.
 The reviewer can merge the changes when they think the code is ready for inclusion in the `master` branch.
@@ -192,7 +193,7 @@ It is possible that one feature branch solves more than one issue.
 
 ## Linking and closing issues from merge requests
 
-![Merge request showing the linked issues that will be closed](close_issue_mr.png)
+![Merge request showing the linked issues that will be closed](img/close_issue_mr.png)
 
 Link to issues by mentioning them in commit messages or the description of a merge request, for example, "Fixes #16" or "Duck typing is preferred. See #12."
 GitLab then creates links to the mentioned issues and creates comments in the issues linking back to the merge request.
@@ -203,7 +204,7 @@ If you have an issue that spans across multiple repositories, create an issue fo
 
 ## Squashing commits with rebase
 
-![Vim screen showing the rebase view](rebase.png)
+![Vim screen showing the rebase view](img/rebase.png)
 
 With Git, you can use an interactive rebase (`rebase -i`) to squash multiple commits into one or reorder them.
 This functionality is useful if you want to replace a couple of small commits with a single commit, or if you want to make the order more logical.
@@ -229,7 +230,7 @@ Git does not allow you to merge the code again otherwise.
 
 ## Reducing merge commits in feature branches
 
-![List of sequential merge commits](merge_commits.png)
+![List of sequential merge commits](img/merge_commits.png)
 
 Having lots of merge commits can make your repository history messy.
 Therefore, you should try to avoid merge commits in feature branches.
@@ -289,7 +290,7 @@ Sharing your work before it's complete also allows for discussion and feedback a
 
 ## How to write a good commit message
 
-![Good and bad commit message](good_commit.png)
+![Good and bad commit message](img/good_commit.png)
 
 A commit message should reflect your intention, not just the contents of the commit.
 It is easy to see the changes in a commit, so the commit message should explain why you made those changes.
@@ -300,7 +301,7 @@ For more information about formatting commit messages, please see this excellent
 
 ## Testing before merging
 
-![Merge requests showing the test states: red, yellow, and green](ci_mr.png)
+![Merge requests showing the test states: red, yellow, and green](img/ci_mr.png)
 
 In old workflows, the continuous integration (CI) server commonly ran tests on the `master` branch only.
 Developers had to ensure their code did not break the `master` branch.
@@ -317,7 +318,7 @@ As said before, if you often have feature branches that last for more than a few
 
 ## Working with feature branches
 
-![Shell output showing git pull output](git_pull.png)
+![Shell output showing git pull output](img/git_pull.png)
 
 When creating a feature branch, always branch from an up-to-date `master`.
 If you know before you start that your work depends on another branch, you can also branch from there.
diff --git a/doc/workflow/ci_mr.png b/doc/workflow/img/ci_mr.png
index 85a609cb814..85a609cb814 100644
--- a/doc/workflow/ci_mr.png
+++ b/doc/workflow/img/ci_mr.png
diff --git a/doc/workflow/close_issue_mr.png b/doc/workflow/img/close_issue_mr.png
index 70de2fb6cee..70de2fb6cee 100644
--- a/doc/workflow/close_issue_mr.png
+++ b/doc/workflow/img/close_issue_mr.png
diff --git a/doc/workflow/environment_branches.png b/doc/workflow/img/environment_branches.png
index 0aff33c6bb8..0aff33c6bb8 100644
--- a/doc/workflow/environment_branches.png
+++ b/doc/workflow/img/environment_branches.png
diff --git a/doc/workflow/four_stages.png b/doc/workflow/img/four_stages.png
index 3ef6a33d2d4..3ef6a33d2d4 100644
--- a/doc/workflow/four_stages.png
+++ b/doc/workflow/img/four_stages.png
diff --git a/doc/workflow/git_pull.png b/doc/workflow/img/git_pull.png
index 0e56e59471c..0e56e59471c 100644
--- a/doc/workflow/git_pull.png
+++ b/doc/workflow/img/git_pull.png
diff --git a/doc/workflow/gitdashflow.png b/doc/workflow/img/gitdashflow.png
index 65900853d84..65900853d84 100644
--- a/doc/workflow/gitdashflow.png
+++ b/doc/workflow/img/gitdashflow.png
diff --git a/doc/workflow/github_flow.png b/doc/workflow/img/github_flow.png
index 21a22becdb6..21a22becdb6 100644
--- a/doc/workflow/github_flow.png
+++ b/doc/workflow/img/github_flow.png
diff --git a/doc/workflow/gitlab_flow.png b/doc/workflow/img/gitlab_flow.png
index a6f3c947843..a6f3c947843 100644
--- a/doc/workflow/gitlab_flow.png
+++ b/doc/workflow/img/gitlab_flow.png
diff --git a/doc/workflow/good_commit.png b/doc/workflow/img/good_commit.png
index ceb0d4b1691..ceb0d4b1691 100644
--- a/doc/workflow/good_commit.png
+++ b/doc/workflow/img/good_commit.png
diff --git a/doc/workflow/merge_commits.png b/doc/workflow/img/merge_commits.png
index 4a80811c6e3..4a80811c6e3 100644
--- a/doc/workflow/merge_commits.png
+++ b/doc/workflow/img/merge_commits.png
diff --git a/doc/workflow/merge_request.png b/doc/workflow/img/merge_request.png
index 010e95983fc..010e95983fc 100644
--- a/doc/workflow/merge_request.png
+++ b/doc/workflow/img/merge_request.png
diff --git a/doc/workflow/messy_flow.png b/doc/workflow/img/messy_flow.png
index 4fa22d2bb5d..4fa22d2bb5d 100644
--- a/doc/workflow/messy_flow.png
+++ b/doc/workflow/img/messy_flow.png
diff --git a/doc/workflow/mr_inline_comments.png b/doc/workflow/img/mr_inline_comments.png
index a18801f56e4..a18801f56e4 100644
--- a/doc/workflow/mr_inline_comments.png
+++ b/doc/workflow/img/mr_inline_comments.png
diff --git a/doc/workflow/img/notification_global_settings.png b/doc/workflow/img/notification_global_settings.png
index 72f7418f1f8..699f726c442 100644
--- a/doc/workflow/img/notification_global_settings.png
+++ b/doc/workflow/img/notification_global_settings.png
diff --git a/doc/workflow/production_branch.png b/doc/workflow/img/production_branch.png
index c132d51bfb6..c132d51bfb6 100644
--- a/doc/workflow/production_branch.png
+++ b/doc/workflow/img/production_branch.png
diff --git a/doc/workflow/rebase.png b/doc/workflow/img/rebase.png
index fe865177ba8..fe865177ba8 100644
--- a/doc/workflow/rebase.png
+++ b/doc/workflow/img/rebase.png
diff --git a/doc/workflow/release_branches.png b/doc/workflow/img/release_branches.png
index 0a7f61d0248..0a7f61d0248 100644
--- a/doc/workflow/release_branches.png
+++ b/doc/workflow/img/release_branches.png
diff --git a/doc/workflow/remove_checkbox.png b/doc/workflow/img/remove_checkbox.png
index fb0e792b37b..fb0e792b37b 100644
--- a/doc/workflow/remove_checkbox.png
+++ b/doc/workflow/img/remove_checkbox.png
diff --git a/doc/workflow/issue_weight.md b/doc/workflow/issue_weight.md
index 267160dae2a..a80519f0748 100644
--- a/doc/workflow/issue_weight.md
+++ b/doc/workflow/issue_weight.md
@@ -1,4 +1,4 @@
-# Issue Weight **[STARTER]**
+# Issue Weight **(STARTER)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/76)
 > in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3.
@@ -9,7 +9,7 @@ value or complexity a given issue has or will cost.
 
 You can set the weight of an issue during its creation, by simply changing the
 value in the dropdown menu. You can set it to a non-negative integer
-value from 0, 1, 2, and so on. (The database stores a 4-byte value, so the 
+value from 0, 1, 2, and so on. (The database stores a 4-byte value, so the
 upper bound is essentially limitless).
 You can remove weight from an issue
 as well.
diff --git a/doc/workflow/lfs/lfs_administration.md b/doc/workflow/lfs/lfs_administration.md
index 6d941135bf2..7e880b3009d 100644
--- a/doc/workflow/lfs/lfs_administration.md
+++ b/doc/workflow/lfs/lfs_administration.md
@@ -46,15 +46,14 @@ In `config/gitlab.yml`:
 
 ## Storing LFS objects in remote object storage
 
-> [Introduced][ee-2760] in [GitLab Premium][eep] 10.0. Brought to GitLab Core
-in 10.7.
+> [Introduced][ee-2760] in [GitLab Premium][eep] 10.0. Brought to GitLab Core in 10.7.
 
 It is possible to store LFS objects in remote object storage which allows you
 to offload local hard disk R/W operations, and free up disk space significantly.
 GitLab is tightly integrated with `Fog`, so you can refer to its [documentation](http://fog.io/about/provider_documentation.html)
 to check which storage services can be integrated with GitLab.
 You can also use external object storage in a private local network. For example,
-[Minio](https://www.minio.io/) is a standalone object storage service, is easy to set up, and works well with GitLab instances.
+[Minio](https://min.io/) is a standalone object storage service, is easy to set up, and works well with GitLab instances.
 
 GitLab provides two different options for the uploading mechanism: "Direct upload" and "Background upload".
 
@@ -91,6 +90,7 @@ Here is a configuration example with S3.
 | `aws_access_key_id` | AWS credentials, or compatible | `ABC123DEF456` |
 | `aws_secret_access_key` | AWS credentials, or compatible | `ABC123DEF456ABC123DEF456ABC123DEF456` |
 | `aws_signature_version` | AWS signature version to use. 2 or 4 are valid options. Digital Ocean Spaces and other providers may need 2. | 4 |
+| `enable_signature_v4_streaming` | Set to true to enable HTTP chunked transfers with [AWS v4 signatures](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be false | true |
 | `region` | AWS region | us-east-1 |
 | `host` | S3 compatible host for when not using AWS, e.g. `localhost` or `storage.example.com` | s3.amazonaws.com |
 | `endpoint` | Can be used when configuring an S3 compatible service such as [Minio](https://www.minio.io), by entering a URL such as `http://127.0.0.1:9000` | (optional) |
@@ -106,7 +106,9 @@ Here is a configuration example with GCS.
 | `google_client_email` | The email address of the service account | `foo@gcp-project-12345.iam.gserviceaccount.com` |
 | `google_json_key_location` | The json key path | `/path/to/gcp-project-12345-abcde.json` |
 
-_NOTE: The service account must have permission to access the bucket. [See more](https://cloud.google.com/storage/docs/authentication)_
+NOTE: **Note:**
+The service account must have permission to access the bucket.
+[See more](https://cloud.google.com/storage/docs/authentication)
 
 Here is a configuration example with Rackspace Cloud Files.
 
@@ -118,7 +120,13 @@ Here is a configuration example with Rackspace Cloud Files.
 | `rackspace_region` | The Rackspace storage region to use, a three letter code from the [list of service access endpoints](https://developer.rackspace.com/docs/cloud-files/v1/general-api-info/service-access/) | `iad` |
 | `rackspace_temp_url_key` | The private key you have set in the Rackspace API for temporary URLs. Read more [here](https://developer.rackspace.com/docs/cloud-files/v1/use-cases/public-access-to-your-cloud-files-account/#tempurl) | `ABC123DEF456ABC123DEF456ABC123DE` |
 
-_NOTES: Regardless of whether the container has public access enabled or disabled, Fog will use the TempURL method to grant access to LFS objects. If you see errors in logs referencing instantiating storage with a temp-url-key, ensure that you have set they key properly on the Rackspace API and in gitlab.rb. You can verify the value of the key Rackspace has set by sending a GET request with token header to the service access endpoint URL and comparing the output of the returned headers._
+NOTE: **Note:**
+Regardless of whether the container has public access enabled or disabled, Fog will
+use the TempURL method to grant access to LFS objects. If you see errors in logs referencing
+instantiating storage with a temp-url-key, ensure that you have set they key properly
+on the Rackspace API and in gitlab.rb. You can verify the value of the key Rackspace
+has set by sending a GET request with token header to the service access endpoint URL
+and comparing the output of the returned headers.
 
 ### Manual uploading to an object storage
 
@@ -148,31 +156,31 @@ On Omnibus installations, the settings are prefixed by `lfs_object_store_`:
 1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with
    the values you want:
 
-	```ruby
-	gitlab_rails['lfs_object_store_enabled'] = true
-	gitlab_rails['lfs_object_store_remote_directory'] = "lfs-objects"
-	gitlab_rails['lfs_object_store_connection'] = {
-	  'provider' => 'AWS',
-	  'region' => 'eu-central-1',
-	  'aws_access_key_id' => '1ABCD2EFGHI34JKLM567N',
-	  'aws_secret_access_key' => 'abcdefhijklmnopQRSTUVwxyz0123456789ABCDE',
-	  # The below options configure an S3 compatible host instead of AWS
-	  'host' => 'localhost',
-	  'endpoint' => 'http://127.0.0.1:9000',
-	  'path_style' => true
-	}
-	```
+   ```ruby
+   gitlab_rails['lfs_object_store_enabled'] = true
+   gitlab_rails['lfs_object_store_remote_directory'] = "lfs-objects"
+   gitlab_rails['lfs_object_store_connection'] = {
+     'provider' => 'AWS',
+     'region' => 'eu-central-1',
+     'aws_access_key_id' => '1ABCD2EFGHI34JKLM567N',
+     'aws_secret_access_key' => 'abcdefhijklmnopQRSTUVwxyz0123456789ABCDE',
+     # The below options configure an S3 compatible host instead of AWS
+     'host' => 'localhost',
+     'endpoint' => 'http://127.0.0.1:9000',
+     'path_style' => true
+   }
+   ```
 
 1. Save the file and [reconfigure GitLab]s for the changes to take effect.
 1. Migrate any existing local LFS objects to the object storage:
 
-    ```bash
-    gitlab-rake gitlab:lfs:migrate
-    ```
+   ```bash
+   gitlab-rake gitlab:lfs:migrate
+   ```
 
-    This will migrate existing LFS objects to object storage. New LFS objects
-    will be forwarded to object storage unless
-    `gitlab_rails['lfs_object_store_background_upload']` is set to false.
+   This will migrate existing LFS objects to object storage. New LFS objects
+   will be forwarded to object storage unless
+   `gitlab_rails['lfs_object_store_background_upload']` is set to false.
 
 ### S3 for installations from source
 
@@ -182,33 +190,33 @@ For source installations the settings are nested under `lfs:` and then
 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
    lines:
 
-	```yaml
-	lfs:
-	enabled: true
-	object_store:
-	  enabled: false
-	  remote_directory: lfs-objects # Bucket name
-	  connection:
-	    provider: AWS
-	    aws_access_key_id: 1ABCD2EFGHI34JKLM567N
-	    aws_secret_access_key: abcdefhijklmnopQRSTUVwxyz0123456789ABCDE
-	    region: eu-central-1
-	    # Use the following options to configure an AWS compatible host such as Minio
-	    host: 'localhost'
-	    endpoint: 'http://127.0.0.1:9000'
-	    path_style: true
-	```
+   ```yaml
+   lfs:
+   enabled: true
+   object_store:
+     enabled: false
+     remote_directory: lfs-objects # Bucket name
+     connection:
+       provider: AWS
+       aws_access_key_id: 1ABCD2EFGHI34JKLM567N
+       aws_secret_access_key: abcdefhijklmnopQRSTUVwxyz0123456789ABCDE
+       region: eu-central-1
+       # Use the following options to configure an AWS compatible host such as Minio
+       host: 'localhost'
+       endpoint: 'http://127.0.0.1:9000'
+       path_style: true
+   ```
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 1. Migrate any existing local LFS objects to the object storage:
 
-    ```bash
-    sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production
-    ```
+   ```bash
+   sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production
+   ```
 
-    This will migrate existing LFS objects to object storage. New LFS objects
-    will be forwarded to object storage unless `background_upload` is set to
-    false.
+   This will migrate existing LFS objects to object storage. New LFS objects
+   will be forwarded to object storage unless `background_upload` is set to
+   false.
 
 ## Storage statistics
 
diff --git a/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md b/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md
index 202f2e39975..f5593927cc2 100644
--- a/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md
+++ b/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md
@@ -35,9 +35,10 @@ Documentation for GitLab instance administrators is under [LFS administration do
 - Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have
   to add the URL to Git config manually (see [troubleshooting](#troubleshooting))
 
->**Note**: With 8.12 GitLab added LFS support to SSH. The Git LFS communication
- still goes over HTTP, but now the SSH client passes the correct credentials
- to the Git LFS client, so no action is required by the user.
+NOTE: **Note:**
+With 8.12 GitLab added LFS support to SSH. The Git LFS communication
+still goes over HTTP, but now the SSH client passes the correct credentials
+to the Git LFS client, so no action is required by the user.
 
 ## Using Git LFS
 
@@ -61,12 +62,13 @@ git commit -am "Added Debian iso"     # commit the file meta data
 git push origin master                # sync the git repo and large file to the GitLab server
 ```
 
-> **Note**: Make sure that `.gitattributes` is tracked by git. Otherwise Git
-> LFS will not be working properly for people cloning the project.
->
-> ```bash
-> git add .gitattributes
-> ```
+NOTE: **Note:**
+**Make sure** that `.gitattributes` is tracked by Git. Otherwise Git
+LFS will not be working properly for people cloning the project.
+
+```bash
+git add .gitattributes
+```
 
 Cloning the repository works the same as before. Git automatically detects the
 LFS-tracked files and clones them via HTTP. If you performed the git clone
@@ -84,6 +86,10 @@ that are on the remote repository, eg. for a branch from origin:
 git lfs fetch origin master
 ```
 
+### Migrate an existing repo to Git LFS
+
+Read the documentation on how to [migrate an existing Git repo with Git LFS](../../topics/git/migrate_to_git_lfs/index.md).
+
 ## File Locking
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/35856) in GitLab 10.5.
@@ -212,9 +218,10 @@ git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs"
 
 ### Credentials are always required when pushing an object
 
->**Note**: With 8.12 GitLab added LFS support to SSH. The Git LFS communication
- still goes over HTTP, but now the SSH client passes the correct credentials
- to the Git LFS client, so no action is required by the user.
+NOTE: **Note:**
+With 8.12 GitLab added LFS support to SSH. The Git LFS communication
+still goes over HTTP, but now the SSH client passes the correct credentials
+to the Git LFS client, so no action is required by the user.
 
 Given that Git LFS uses HTTP Basic Authentication to authenticate the user pushing
 the LFS object on every push for every object, user HTTPS credentials are required.
@@ -250,7 +257,7 @@ If you are storing LFS files outside of GitLab you can disable LFS on the projec
 
 It is possible to host LFS objects externally by setting a custom LFS url with `git config -f .lfsconfig lfs.url https://example.com/<project>.git/info/lfs`.
 
-You might choose to do this if you are using an appliance like a Sonatype Nexus to store LFS data. If you choose to use an external LFS store, 
+You might choose to do this if you are using an appliance like a Sonatype Nexus to store LFS data. If you choose to use an external LFS store,
 GitLab will not be able to verify LFS objects which means that pushes will fail if you have GitLab LFS support enabled.
 
 To stop push failure, LFS support can be disabled in the [Project settings](../../user/project/settings/index.md). This means you will lose GitLab LFS value-adds (Verifying LFS objects, UI integration for LFS).
diff --git a/doc/workflow/lfs/migrate_from_git_annex_to_git_lfs.md b/doc/workflow/lfs/migrate_from_git_annex_to_git_lfs.md
index 71c73e3dffe..5ceeb3253f1 100644
--- a/doc/workflow/lfs/migrate_from_git_annex_to_git_lfs.md
+++ b/doc/workflow/lfs/migrate_from_git_annex_to_git_lfs.md
@@ -46,25 +46,24 @@ need to do (we assume you have [git-annex enabled](../git_annex.md#using-gitlab-
 repository and that you have made backups in case something goes wrong).
 Fire up a terminal, navigate to your Git repository and:
 
-
 1. Disable `git-annex`:
 
-    ```bash
-    git annex sync --content
-    git annex direct
-    git annex uninit
-    git annex indirect
-    ```
+   ```bash
+   git annex sync --content
+   git annex direct
+   git annex uninit
+   git annex indirect
+   ```
 
 1. Enable `git-lfs`:
 
-    ```
-    git lfs install
-    git lfs track <files>
-    git add .
-    git commit -m "commit message"
-    git push
-    ```
+   ```
+   git lfs install
+   git lfs track <files>
+   git add .
+   git commit -m "commit message"
+   git push
+   ```
 
 ### Disabling Git Annex in your repo
 
@@ -77,7 +76,7 @@ Here you'll find a guide on
 Since Annex files are stored as objects with symlinks and cannot be directly
 modified, we need to first remove those symlinks.
 
->**Note:**
+NOTE: **Note:**
 Make sure the you read about the [`direct` mode][annex-direct] as it contains
 useful information that may fit in your use case. Note that `annex direct` is
 deprecated in Git Annex version 6, so you may need to upgrade your repository
@@ -86,72 +85,72 @@ if the server also has Git Annex 6 installed. Read more in the
 
 1. Backup your repository
 
-    ```bash
-    cd repository
-    git annex sync --content
-    cd ..
-    git clone repository repository-backup
-    cd repository-backup
-    git annex get
-    cd ..
-    ```
+   ```bash
+   cd repository
+   git annex sync --content
+   cd ..
+   git clone repository repository-backup
+   cd repository-backup
+   git annex get
+   cd ..
+   ```
 
 1. Use `annex direct`:
 
-    ```bash
-    cd repository
-    git annex direct
-    ```
+   ```bash
+   cd repository
+   git annex direct
+   ```
 
-    The output should be similar to this:
+   The output should be similar to this:
 
-    ```bash
-    commit
-    On branch master
-    Your branch is up-to-date with 'origin/master'.
-    nothing to commit, working tree clean
-    ok
-    direct debian.iso ok
-    direct  ok
-    ```
+   ```bash
+   commit
+   On branch master
+   Your branch is up-to-date with 'origin/master'.
+   nothing to commit, working tree clean
+   ok
+   direct debian.iso ok
+   direct  ok
+   ```
 
 1. Disable Git Annex with [`annex uninit`][uninit]:
 
-    ```bash
-    git annex uninit
-    ```
+   ```bash
+   git annex uninit
+   ```
 
-    The output should be similar to this:
+   The output should be similar to this:
 
-    ```bash
-    unannex debian.iso ok
-    Deleted branch git-annex (was 2534d2c).
-    ```
+   ```bash
+   unannex debian.iso ok
+   Deleted branch git-annex (was 2534d2c).
+   ```
 
-    This will `unannex` every file in the repository, leaving the original files.
+   This will `unannex` every file in the repository, leaving the original files.
 
 1. Switch back to `indirect` mode:
 
-    ```bash
-    git annex indirect
-    ```
-
-    The output should be similar to this:
+   ```bash
+   git annex indirect
+   ```
 
-    ```bash
-    (merging origin/git-annex into git-annex...)
-    (recording state in git...)
-    commit  (recording state in git...)
+   The output should be similar to this:
 
-    ok
-    (recording state in git...)
-    [master fac3194] commit before switching to indirect mode
-     1 file changed, 1 deletion(-)
-     delete mode 120000 alpine-virt-3.4.4-x86_64.iso
-    ok
-    indirect  ok
-    ok
-    ```
+   ```bash
+   (merging origin/git-annex into git-annex...)
+   (recording state in git...)
+   commit  (recording state in git...)
+
+   ok
+   (recording state in git...)
+   [master fac3194] commit before switching to indirect mode
+    1 file changed, 1 deletion(-)
+    delete mode 120000 alpine-virt-3.4.4-x86_64.iso
+   ok
+   indirect  ok
+   ok
+   ```
 
 ---
 
@@ -216,16 +215,16 @@ branches created by Git Annex: `git-annex`, and all under `synced/`.
 
 ![repository branches](images/git-annex-branches.png)
 
-You can also do this on the commandline with:
+You can also do this on the command line with:
 
-    ```bash
-    git branch -d synced/master
-    git branch -d synced/git-annex
-    git push origin :synced/master
-    git push origin :synced/git-annex
-    git push origin :git-annex
-    git remote prune origin
-    ```
+```bash
+git branch -d synced/master
+git branch -d synced/git-annex
+git push origin :synced/master
+git push origin :synced/git-annex
+git push origin :git-annex
+git remote prune origin
+```
 
 If there are still some Annex objects inside your repository (`.git/annex/`)
 or references inside `.git/config`, run `annex uninit` again:
diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md
index 5d560f2e000..ccb8844aea3 100644
--- a/doc/workflow/notifications.md
+++ b/doc/workflow/notifications.md
@@ -51,6 +51,10 @@ Organization like this is suitable for users that belong to different groups but
 same need for being notified for every group they are member of.
 These settings can be configured on group page under the name of the group. It will be the dropdown with the bell icon. They can also be configured on the user profile notifications dropdown.
 
+The group owner can disable email notifications for a group, which also includes
+it's subgroups and projects.  If this is the case, you will not receive any corresponding notifications,
+and the notification button will be disabled with an explanatory tooltip. 
+
 ### Project Settings
 
 ![notification settings](img/notification_project_settings.png)
@@ -60,22 +64,26 @@ other setting.
 This is suitable for users that have different needs for notifications per project basis.
 These settings can be configured on project page under the name of the project. It will be the dropdown with the bell icon. They can also be configured on the user profile notifications dropdown.
 
+The project owner (or it's group owner) can disable email notifications for the project.
+If this is the case, you will not receive any corresponding notifications, and the notification
+button will be disabled with an explanatory tooltip. 
+
 ## Notification events
 
 Below is the table of events users can be notified of:
 
-| Event                        | Sent to                                                           | Settings level               |
-|------------------------------|-------------------------------------------------------------------|------------------------------|
-| New SSH key added            | User                                                              | Security email, always sent. |
-| New email added              | User                                                              | Security email, always sent. |
-| Email changed                | User                                                              | Security email, always sent. |
-| Password changed             | User                                                              | Security email, always sent. |
-| New user created             | User                                                              | Sent on user creation, except for omniauth (LDAP)|
-| User added to project        | User                                                              | Sent when user is added to project |
-| Project access level changed | User                                                              | Sent when user project access level is changed |
-| User added to group          | User                                                              | Sent when user is added to group |
-| Group access level changed   | User                                                              | Sent when user group access level is changed |
-| Project moved                | Project members [1]                                               | [1] not disabled |
+| Event                        | Sent to             | Settings level               |
+|------------------------------|---------------------|------------------------------|
+| New SSH key added            | User                | Security email, always sent. |
+| New email added              | User                | Security email, always sent. |
+| Email changed                | User                | Security email, always sent. |
+| Password changed             | User                | Security email, always sent. |
+| New user created             | User                | Sent on user creation, except for omniauth (LDAP)|
+| User added to project        | User                | Sent when user is added to project |
+| Project access level changed | User                | Sent when user project access level is changed |
+| User added to group          | User                | Sent when user is added to group |
+| Group access level changed   | User                | Sent when user group access level is changed |
+| Project moved                | Project members (1) | (1) not disabled |
 
 ### Issue / Epics / Merge request events
 
@@ -84,11 +92,11 @@ In most of the below cases, the notification will be sent to:
 - Participants:
   - the author and assignee of the issue/merge request
   - authors of comments on the issue/merge request
-  - anyone mentioned by `@username` in the title or description of the issue, merge request or epic **[ULTIMATE]**
+  - anyone mentioned by `@username` in the title or description of the issue, merge request or epic **(ULTIMATE)**
   - anyone with notification level "Participating" or higher that is mentioned by `@username`
-    in any of the comments on the issue, merge request, or epic **[ULTIMATE]**
+    in any of the comments on the issue, merge request, or epic **(ULTIMATE)**
 - Watchers: users with notification level "Watch"
-- Subscribers: anyone who manually subscribed to the issue, merge request, or epic **[ULTIMATE]**
+- Subscribers: anyone who manually subscribed to the issue, merge request, or epic **(ULTIMATE)**
 - Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below
 
 | Event                  | Sent to |
@@ -111,9 +119,9 @@ In most of the below cases, the notification will be sent to:
 | New comment            | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher |
 | Failed pipeline        | The author of the pipeline |
 | Successful pipeline    | The author of the pipeline, if they have the custom notification setting for successful pipelines set |
-| New epic **[ULTIMATE]** |        |
-| Close epic **[ULTIMATE]** |      |
-| Reopen epic **[ULTIMATE]** |     |
+| New epic **(ULTIMATE)** |        |
+| Close epic **(ULTIMATE)** |      |
+| Reopen epic **(ULTIMATE)** |     |
 
 In addition, if the title or description of an Issue or Merge Request is
 changed, notifications will be sent to any **new** mentions by `@username` as
@@ -138,7 +146,7 @@ Notification emails include headers that provide extra content about the notific
 | X-GitLab-Project-Id         | The ID of the project                                                   |
 | X-GitLab-Project-Path       | The path of the project                                                 |
 | X-GitLab-(Resource)-ID      | The ID of the resource the notification is for, where resource is `Issue`, `MergeRequest`, `Commit`, etc|
-| X-GitLab-Discussion-ID      | Only in comment emails, the ID of the discussion the comment is from    |
+| X-GitLab-Discussion-ID      | Only in comment emails, the ID of the thread the comment is from    |
 | X-GitLab-Pipeline-Id        | Only in pipeline emails, the ID of the pipeline the notification is for |
 | X-GitLab-Reply-Key          | A unique token to support reply by email                                |
 | X-GitLab-NotificationReason | The reason for being notified. "mentioned", "assigned", etc             |
diff --git a/doc/workflow/repository_mirroring.md b/doc/workflow/repository_mirroring.md
index 9772bd385ba..753518d0424 100644
--- a/doc/workflow/repository_mirroring.md
+++ b/doc/workflow/repository_mirroring.md
@@ -13,7 +13,7 @@ Repository mirroring is useful when you want to use a repository outside of GitL
 There are two kinds of repository mirroring supported by GitLab:
 
 - Push: for mirroring a GitLab repository to another location.
-- Pull: for mirroring a repository from another location to GitLab. **[STARTER]**
+- Pull: for mirroring a repository from another location to GitLab. **(STARTER)**
 
 When the mirror repository is updated, all new branches, tags, and commits will be visible in the
 project's activity feed.
@@ -30,15 +30,14 @@ The following are some possible use cases for repository mirroring:
 
 - You migrated to GitLab but still need to keep your project in another source. In that case, you
   can simply set it up to mirror to GitLab (pull) and all the essential history of commits, tags,
-  and branches will be available in your GitLab instance. **[STARTER]**
+  and branches will be available in your GitLab instance. **(STARTER)**
 - You have old projects in another source that you don't use actively anymore, but don't want to
   remove for archiving purposes. In that case, you can create a push mirror so that your active
   GitLab repository can push its changes to the old location.
 
-## Pushing to a remote repository **[CORE]**
+## Pushing to a remote repository **(CORE)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/249) in GitLab Enterprise
-> Edition 8.7. [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715) in 10.8.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/249) in GitLab Enterprise Edition 8.7. [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715) in 10.8.
 
 For an existing project, you can set up push mirroring as follows:
 
@@ -65,17 +64,16 @@ Changes pushed to files in the repository are automatically pushed to the remote
 In the case of a diverged branch, you will see an error indicated at the **Mirroring repositories**
 section.
 
-### Push only protected branches **[CORE]**
+### Push only protected branches **(CORE)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3350) in
-> [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715) in 10.8.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3350) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715) in 10.8.
 
 You can choose to only push your protected branches from GitLab to your remote repository.
 
 To use this option, check the **Only mirror protected branches** box when creating a repository
 mirror.
 
-## Setting up a push mirror from GitLab to GitHub **[CORE]**
+## Setting up a push mirror from GitLab to GitHub **(CORE)**
 
 To set up a mirror from GitLab to GitHub, you need to follow these steps:
 
@@ -92,14 +90,16 @@ The repository will push soon. To force a push, click the appropriate button.
 
 1. On the destination GitLab instance, create a [personal access token](../user/profile/personal_access_tokens.md) with `API` scope.
 1. On the source GitLab instance:
-    1. Fill in the **Git repository URL** field using this format: `https://oauth2@<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`.
-    1. Fill in **Password** field with the GitLab personal access token created on the destination GitLab instance.
-    1. Click the **Mirror repository** button.
+   1. Fill in the **Git repository URL** field using this format: `https://oauth2@<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`.
+   1. Fill in **Password** field with the GitLab personal access token created on the destination GitLab instance.
+   1. Click the **Mirror repository** button.
 
-## Pulling from a remote repository **[STARTER]**
+## Pulling from a remote repository **(STARTER)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/51) in GitLab Enterprise Edition 8.2.
-> [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab-ee/issues/10871) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.11.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/51) in GitLab Enterprise Edition 8.2. [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab-ee/issues/10871) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.11.
+
+NOTE: **Note:** This feature [is available for free](https://gitlab.com/gitlab-org/gitlab-ee/issues/10361) to
+GitLab.com users until September 22nd, 2019.
 
 You can set up a repository to automatically have its branches, tags, and commits updated from an
 upstream repository.
@@ -115,9 +115,9 @@ To configure mirror pulling for an existing project:
 1. Select **Pull** from the **Mirror direction** dropdown.
 1. Select an authentication method from the **Authentication method** dropdown, if necessary.
 1. If necessary, check the following boxes:
-    - **Overwrite diverged branches**.
-    - **Trigger pipelines for mirror updates**.
-    - **Only mirror protected branches**.
+   - **Overwrite diverged branches**.
+   - **Trigger pipelines for mirror updates**.
+   - **Only mirror protected branches**.
 1. Click the **Mirror repository** button to save the configuration.
 
 ![Repository mirroring pull settings screen - upper part](img/repository_mirroring_pull_settings_upper.png)
@@ -154,8 +154,7 @@ Repository mirrors are updated as Sidekiq becomes available to process them. If
 
 ### SSH authentication
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2551) for Pull mirroring in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5.
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22982) for Push mirroring in [GitLab Core](https://about.gitlab.com/pricing/) 11.6
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2551) for Pull mirroring in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5. [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22982) for Push mirroring in [GitLab Core](https://about.gitlab.com/pricing/) 11.6
 
 SSH authentication is mutual:
 
@@ -240,10 +239,9 @@ If you need to change the key at any time, you can remove and re-add the mirror
 to generate a new key. You'll have to update the other repository with the new
 key to keep the mirror running.
 
-### Overwrite diverged branches **[STARTER]**
+### Overwrite diverged branches **(STARTER)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4559) in
-> [GitLab Starter](https://about.gitlab.com/pricing/) 10.6.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4559) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6.
 
 You can choose to always update your local branches with remote versions, even if they have
 diverged from the remote.
@@ -253,20 +251,18 @@ For mirrored branches, enabling this option results in the loss of local changes
 
 To use this option, check the **Overwrite diverged branches** box when creating a repository mirror.
 
-### Only mirror protected branches **[STARTER]**
+### Only mirror protected branches **(STARTER)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3326) in
-> [GitLab Starter](https://about.gitlab.com/pricing/) 10.3.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3326) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3.
 
 You can choose to pull mirror only the protected branches from your remote repository to GitLab.
 Non-protected branches are not mirrored and can diverge.
 
 To use this option, check the **Only mirror protected branches** box when creating a repository mirror.
 
-### Hard failure **[STARTER]**
+### Hard failure **(STARTER)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3117) in
-> [GitLab Starter](https://about.gitlab.com/pricing/) 10.2.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3117) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2.
 
 Once the mirroring process is unsuccessfully retried 14 times in a row, it will get marked as hard
 failed. This will become visible in either the:
@@ -277,25 +273,24 @@ failed. This will become visible in either the:
 When a project is hard failed, it will no longer get picked up for mirroring. A user can resume the
 project mirroring again by [Forcing an update](#forcing-an-update-core).
 
-### Trigger update using API **[STARTER]**
+### Trigger update using API **(STARTER)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3453) in
-[GitLab Starter](https://about.gitlab.com/pricing/) 10.3.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3453) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3.
 
 Pull mirroring uses polling to detect new branches and commits added upstream, often minutes
-afterwards. If you notify GitLab by [API](https://docs.gitlab.com/ee/api/projects.html#start-the-pull-mirroring-process-for-a-project-starter),
+afterwards. If you notify GitLab by [API](../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter),
 updates will be pulled immediately.
 
-For more information, see [Start the pull mirroring process for a Project](https://docs.gitlab.com/ee/api/projects.html#start-the-pull-mirroring-process-for-a-project-starter).
+For more information, see [Start the pull mirroring process for a Project](../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter).
 
-## Forcing an update **[CORE]**
+## Forcing an update **(CORE)**
 
 While mirrors are scheduled to update automatically, you can always force an update by using the
 update button which is available on the **Mirroring repositories** section of the **Repository Settings** page.
 
 ![Repository mirroring force update user interface](img/repository_mirroring_force_update.png)
 
-## Bidirectional mirroring **[STARTER]**
+## Bidirectional mirroring **(STARTER)**
 
 CAUTION: **Caution:**
 Bidirectional mirroring may cause conflicts.
@@ -322,9 +317,10 @@ protected branches.
 
 ### Preventing conflicts using a `pre-receive` hook
 
-> **Warning:** The solution proposed will negatively impact the performance of
-> Git push operations because they will be proxied to the upstream Git
-> repository.
+CAUTION: **Warning:**
+The solution proposed will negatively impact the performance of
+Git push operations because they will be proxied to the upstream Git
+repository.
 
 A server-side `pre-receive` hook can be used to prevent the race condition
 described above by only accepting the push after first pushing the commit to
@@ -392,7 +388,7 @@ else
 fi
 ```
 
-### Mirroring with Perforce Helix via Git Fusion **[STARTER]**
+### Mirroring with Perforce Helix via Git Fusion **(STARTER)**
 
 CAUTION: **Warning:**
 Bidirectional mirroring should not be used as a permanent configuration. Refer to
diff --git a/doc/workflow/shortcuts.md b/doc/workflow/shortcuts.md
index 5068b5d4d20..5d08bf5e77d 100644
--- a/doc/workflow/shortcuts.md
+++ b/doc/workflow/shortcuts.md
@@ -35,11 +35,11 @@ You can see GitLab's keyboard shortcuts by using <kbd>shift</kbd> + <kbd>?</kbd>
 
 | Keyboard Shortcut | Description |
 | ----------------- | ----------- |
-| <kbd>g</kbd> + <kbd>a</kbd> | Go to the activity feed |
-| <kbd>g</kbd> + <kbd>p</kbd> | Go to projects |
-| <kbd>g</kbd> + <kbd>i</kbd> | Go to issues |
-| <kbd>g</kbd> + <kbd>m</kbd> | Go to merge requests |
-| <kbd>g</kbd> + <kbd>t</kbd> | Go to todos |
+| <kbd>Shift</kbd> + <kbd>a</kbd> | Go to the activity feed |
+| <kbd>Shift</kbd> + <kbd>p</kbd> | Go to projects |
+| <kbd>Shift</kbd> + <kbd>i</kbd> | Go to issues |
+| <kbd>Shift</kbd> + <kbd>m</kbd> | Go to merge requests |
+| <kbd>Shift</kbd> + <kbd>t</kbd> | Go to todos |
 
 ## Project
 
@@ -84,8 +84,10 @@ You can see GitLab's keyboard shortcuts by using <kbd>shift</kbd> + <kbd>?</kbd>
 | <kbd>l</kbd> | Change label |
 | <kbd>]</kbd> or <kbd>j</kbd> | Move to next file |
 | <kbd>[</kbd> or <kbd>k</kbd> | Move to previous file |
+| <kbd>n</kbd> | Move to next unresolved discussion     |
+| <kbd>p</kbd> | Move to previous unresolved discussion |
 
-## Epics **[ULTIMATE]**
+## Epics **(ULTIMATE)**
 
 | Keyboard Shortcut | Description |
 | ----------------- | ----------- |
diff --git a/doc/workflow/time_tracking.md b/doc/workflow/time_tracking.md
index c03dffa967d..fad853f8a44 100644
--- a/doc/workflow/time_tracking.md
+++ b/doc/workflow/time_tracking.md
@@ -22,8 +22,8 @@ below.
 
 ## How to enter data
 
-Time Tracking uses two [quick actions] that GitLab introduced with this new
-feature: `/spend` and `/estimate`.
+Time Tracking uses two [quick actions](../user/project/quick_actions.md)
+that GitLab introduced with this new feature: `/spend` and `/estimate`.
 
 Quick actions can be used in the body of an issue or a merge request, but also
 in a comment in both an issue or a merge request.
@@ -73,8 +73,15 @@ The following time units are available:
 
 Default conversion rates are 1mo = 4w, 1w = 5d and 1d = 8h.
 
-Other interesting links:
+### Limit displayed units to hours **(CORE ONLY)**
 
-- [Time Tracking landing page on about.gitlab.com](https://about.gitlab.com/solutions/time-tracking/)
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29469/) in GitLab 12.1.
+
+In GitLab self-managed instances, the display of time units can be limited to
+hours through the option in **Admin Area > Settings > Preferences** under **Localization**.
+
+With this option enabled, `75h` is displayed instead of `1w 4d 3h`.
 
-[quick actions]: ../user/project/quick_actions.md
+## Other interesting links
+
+- [Time Tracking landing page on about.gitlab.com](https://about.gitlab.com/solutions/time-tracking/)
diff --git a/doc/workflow/timezone.md b/doc/workflow/timezone.md
index da51c0f2c93..60a4d0f19de 100644
--- a/doc/workflow/timezone.md
+++ b/doc/workflow/timezone.md
@@ -2,13 +2,12 @@
 
 The global time zone configuration parameter can be changed in `config/gitlab.yml`:
 
-```
+```text
 # time_zone: 'UTC'
 ```
 
 Uncomment and customize if you want to change the default time zone of the GitLab application.
 
-
 ## Viewing available timezones
 
 To see all available time zones, run `bundle exec rake time:zones:all`.
@@ -26,14 +25,13 @@ To obtain a list of timezones, log in to your GitLab application server and run
 
 To update, add the timezone that best applies to your location. For example:
 
-```
+```ruby
 gitlab_rails['time_zone'] = 'America/New_York'
 ```
 
 After adding the configuration parameter, reconfigure and restart your GitLab instance:
 
-```
+```sh
 gitlab-ctl reconfigure
 gitlab-ctl restart
 ```
-
diff --git a/doc/workflow/todos.md b/doc/workflow/todos.md
index 32907db4f46..211d242e2d3 100644
--- a/doc/workflow/todos.md
+++ b/doc/workflow/todos.md
@@ -1,48 +1,55 @@
-# GitLab Todos
+# GitLab To-Do List
 
 > [Introduced][ce-2817] in GitLab 8.5.
 
 When you log into GitLab, you normally want to see where you should spend your
-time and take some action, or what you need to keep an eye on. All without the
-mess of a huge pile of e-mail notifications. GitLab is where you do your work,
-so being able to get started quickly is very important.
+time, take some action, or know what you need to keep an eye on without
+a huge pile of e-mail notifications. GitLab is where you do your work,
+so being able to get started quickly is important.
 
-Todos is a chronological list of to-dos that are waiting for your input, all
+Your To-Do List offers a chronological list of items that are waiting for your input, all
 in a simple dashboard.
 
-![Todos screenshot showing a list of items to check on](img/todos_index.png)
+![To Do screenshot showing a list of items to check on](img/todos_index.png)
 
----
+You can quickly access your To-Do List by clicking the checkmark icon next to the
+search bar in the top navigation. If the count is:
 
-You can quickly access the Todos dashboard using the checkmark icon next to the
-search bar in the upper right corner. The number in blue is the number of Todos
-you still have open if the count is < 100, else it's 99+. The exact number
-will still be shown in the body of the _To do_ tab.
+- Less than 100, the number in blue is the number of To-Do items.
+- 100 or more, the number displays as 99+. The exact number displays
+  on the To-Do List.
+you still have open. Otherwise, the number displays as 99+. The exact number
+displays on the To-Do List.
 
-![Todos icon](img/todos_icon.png)
+![To Do icon](img/todos_icon.png)
 
-## What triggers a Todo
+## What triggers a To Do
 
-A Todo appears in your Todos dashboard when:
+A To Do displays on your To-Do List when:
 
-- an issue or merge request is assigned to you
-- you are `@mentioned` in the description or in a comment of an issue, merge request, or epic **[ULTIMATE]**
-- you are `@mentioned` in a comment on a commit,
-- a job in the CI pipeline running for your merge request failed, but this
-  job is not allowed to fail.
-- an open merge request becomes unmergeable due to conflict, and you are either:
-  - the author, or
-  - have set it to automatically merge once pipeline succeeds.
+- An issue or merge request is assigned to you
+- You are `@mentioned` in the description or comment of an:
+  - Issue
+  - Merge Request
+  - Epic **(ULTIMATE)**
+- You are `@mentioned` in a comment on a commit
+- A job in the CI pipeline running for your merge request failed, but this
+  job is not allowed to fail
+- An open merge request becomes unmergeable due to conflict, and you are either:
+  - The author
+  - Have set it to automatically merge once the pipeline succeeds
+
+To-do triggers are not affected by [GitLab Notification Email settings](notifications.md).
 
 NOTE: **Note:**
-When an user no longer has access to a resource related to a Todo like an issue, merge request, project or group the related Todos, for security reasons, gets deleted within the next hour. The delete is delayed to prevent data loss in case user got their access revoked by mistake.
+When a user no longer has access to a resource related to a To Do (like an issue, merge request, project, or group) the related To-Do items are deleted within the next hour for security reasons. The delete is delayed to prevent data loss, in case the user's access was revoked by mistake.
 
-### Directly addressed Todos
+### Directly addressing a To Do
 
 > [Introduced][ce-7926] in GitLab 9.0.
 
-If you are mentioned at the start of a line, the todo you receive will be listed
-as 'directly addressed'. For instance, in this comment:
+If you are mentioned at the start of a line, the To Do you receive will be listed
+as 'directly addressed'. For example, in this comment:
 
 ```markdown
 @alice What do you think? cc: @bob
@@ -56,67 +63,76 @@ as 'directly addressed'. For instance, in this comment:
 @erin @frank thank you!
 ```
 
-The people receiving directly addressed todos are `@alice`, `@erin`, and
-`@frank`. Directly addressed todos only differ from mention todos in their type,
-for filtering; otherwise, they appear as normal.
+The people receiving directly addressed To-Do items are `@alice`, `@erin`, and
+`@frank`. Directly addressed To-Do items only differ from mentions in their type
+for filtering purposes; otherwise, they appear as normal.
+
+### Manually creating a To Do
+
+You can also add the following to your To-Do List by clicking the **Add a To Do** button on an:
+
+- Issue
+- Merge Request
+- Epic **(ULTIMATE)**
 
-### Manually creating a Todo
+![Adding a To Do from the issuable sidebar](img/todos_add_todo_sidebar.png)
 
-You can also add an issue, merge request or epic to your Todos dashboard by clicking
-the "Add todo" button in the sidebar of the issue, merge request, or epic **[ULTIMATE]**.
+## Marking a To Do as done
 
-![Adding a Todo from the issuable sidebar](img/todos_add_todo_sidebar.png)
+Any action to the following will mark the corresponding To Do as done:
 
-## Marking a Todo as done
+- Issue
+- Merge Request
+- Epic **(ULTIMATE)**
 
-Any action to the corresponding issue, merge request or epic **[ULTIMATE]** will mark your Todo as
-**Done**. Actions that dismiss Todos include:
+Actions that dismiss To-Do items include:
 
-- changing the assignee
-- changing the milestone
-- adding/removing a label
-- commenting on the issue
+- Changing the assignee
+- Changing the milestone
+- Adding/removing a label
+- Commenting on the issue
 
----
+Your To-Do List is personal, and items are only marked as done if the action comes from
+you. If you close the issue or merge request, your To Do is automatically
+marked as done.
 
-Todos are personal, and they're only marked as done if the action is coming from
-you. If you close the issue or merge request, your Todo will automatically
-be marked as done.
+To prevent other users from closing issues without you being notified, if someone else closes, merges, or takes action on the any of the following, your To Do will remain pending:
 
-If someone else closes, merges, or takes action on the issue, epic or merge
-request, your Todo will remain pending. This prevents other users from closing issues without you being notified.
+- Issue
+- Merge request
+- Epic **(ULTIMATE)**
 
-There is just one Todo per issue, epic or merge request, so mentioning a user a
-hundred times in an issue will only trigger one Todo.
+There is just one To Do for each of these, so mentioning a user a hundred times in an issue will only trigger one To Do.
 
----
+If no action is needed, you can manually mark the To Do as done by clicking the
+corresponding **Done** button, and it will disappear from your To-Do List.
 
-If no action is needed, you can manually mark the Todo as done by clicking the
-corresponding **Done** button, and it will disappear from your Todo list.
+![A To Do in the To-Do List](img/todo_list_item.png)
 
-![A Todo in the Todos dashboard](img/todo_list_item.png)
+You can also mark a To Do as done by clicking the **Mark as done** button in the sidebar of the following:
 
-A Todo can also be marked as done from the issue, merge request or epic sidebar using
-the "Mark todo as done" button.
+- Issue
+- Merge Request
+- Epic **(ULTIMATE)**
 
-![Mark todo as done from the issuable sidebar](img/todos_mark_done_sidebar.png)
+![Mark as done from the issuable sidebar](img/todos_mark_done_sidebar.png)
 
-You can mark all your Todos as done at once by clicking on the **Mark all as
+You can mark all your To-Do items as done at once by clicking the **Mark all as
 done** button.
 
-## Filtering your Todos
+## Filtering your To-Do List
 
-There are four kinds of filters you can use on your Todos dashboard.
+There are four kinds of filters you can use on your To-Do List.
 
 | Filter  | Description |
 | ------- | ----------- |
 | Project | Filter by project |
 | Group   | Filter by group |
-| Author  | Filter by the author that triggered the Todo |
-| Type    | Filter by issue, merge request, or epic **[ULTIMATE]** |
-| Action  | Filter by the action that triggered the Todo |
+| Author  | Filter by the author that triggered the To Do |
+| Type    | Filter by issue, merge request, or epic **(ULTIMATE)** |
+| Action  | Filter by the action that triggered the To Do |
 
-You can also filter by more than one of these at the same time. The possible Actions are `Any Action`, `Assigned`, `Mentioned`, `Added`, `Pipelines`, and `Directly Addressed`, [as described above](#what-triggers-a-todo).
+You can also filter by more than one of these at the same time. The possible Actions are `Any Action`, `Assigned`, `Mentioned`, `Added`, `Pipelines`, and `Directly Addressed`, [as described above](#what-triggers-a-to-do).
 
 [ce-2817]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2817
 [ce-7926]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7926
diff --git a/doc/workflow/workflow.md b/doc/workflow/workflow.md
index f70e41df842..7fac41c3b6f 100644
--- a/doc/workflow/workflow.md
+++ b/doc/workflow/workflow.md
@@ -1,31 +1,31 @@
 # Feature branch workflow
 
-1.  Clone project:
+1. Clone project:
 
-    ```bash
-    git clone git@example.com:project-name.git
-    ```
+   ```bash
+   git clone git@example.com:project-name.git
+   ```
 
-1.  Create branch with your feature:
+1. Create branch with your feature:
 
-    ```bash
-    git checkout -b $feature_name
-    ```
+   ```bash
+   git checkout -b $feature_name
+   ```
 
-1.  Write code. Commit changes:
+1. Write code. Commit changes:
 
-    ```bash
-    git commit -am "My feature is ready"
-    ```
+   ```bash
+   git commit -am "My feature is ready"
+   ```
 
-1.  Push your branch to GitLab:
+1. Push your branch to GitLab:
 
-    ```bash
-    git push origin $feature_name
-    ```
+   ```bash
+   git push origin $feature_name
+   ```
 
-1.  Review your code on commits page.
+1. Review your code on commits page.
 
-1.  Create a merge request.
+1. Create a merge request.
 
-1.  Your team lead will review the code &amp; merge it to the main branch.
+1. Your team lead will review the code &amp; merge it to the main branch.