Merge branch 'docs-repo-merge-26-project-misc' into 'master'

Docs: Merge EE doc/user/project/*.md to CE

See merge request gitlab-org/gitlab-ce!27984

35 files changed, 673 insertions, 10 deletions

diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md
new file mode 100644
index 00000000000..cce862b0911
--- /dev/null
+++ b/doc/user/project/canary_deployments.md
@@ -0,0 +1,71 @@
+# Canary Deployments **[PREMIUM]**
+
+> [Introduced][ee-1659] in [GitLab Premium][eep] 9.1.
+
+A popular [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration)
+strategy, where a small portion of the fleet is updated to the new version of
+your application.
+
+## Overview
+
+When embracing [Continuous Delivery][cd-blog], a company needs to decide what
+type of deployment strategy to use. One of the most popular strategies is canary
+deployments, where a small portion of the fleet is updated to the new version
+first. This subset, the canaries, then serve as the proverbial
+[canary in the coal mine](https://en.wiktionary.org/wiki/canary_in_a_coal_mine).
+
+If there is a problem with the new version of the application, only a small
+percentage of users are affected and the change can either be fixed or quickly
+reverted.
+
+Leveraging [Kubernetes' Canary deployments][kube-canary], visualize your canary
+deployments right inside the [Deploy Board], without the need to leave GitLab.
+
+## Use cases
+
+Canary deployments can be used when you want to ship features to only a portion of
+your pods fleet and watch their behavior as a percentage of your user base
+visits the temporarily deployed feature. If all works well, you can deploy the
+feature to production knowing that it won't cause any problems.
+
+Canary deployments are also especially useful for backend refactors, performance
+improvements, or other changes where the user interface doesn't change, but you
+want to make sure the performance stays the same, or improves. Developers need
+to be careful when using canaries with user-facing changes, because by default,
+requests from the same user will be randomly distributed between canary and
+non-canary pods, which could result in confusion or even errors. If needed, you
+may want to consider [setting `service.spec.sessionAffinity` to `ClientIP` in
+your Kubernetes service definitions][kube-net], but that is beyond the scope of
+this document.
+
+## Enabling Canary Deployments
+
+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]
+   template for canary deployments that GitLab provides.
+
+Depending on the deploy, the label should be either `stable` or `canary`.
+Usually, `stable` and blank or missing label means the same thing, and `canary`
+or any other track means canary/temporary.
+This allows GitLab to discover whether deployment is stable or canary (temporary).
+
+Once all of the above are set up and the pipeline has run at least once,
+navigate to the environments page under **Pipelines > Environments**.
+As the pipeline executes Deploy Boards will clearly mark canary pods, enabling
+quick and easy insight into the status of each environment and deployment.
+
+Canary deployments are marked with a yellow dot in the Deploy Board so that you
+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
+[deploy board]: deploy_boards.md
+[cd-blog]: https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/
+[kube-net]: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies
diff --git a/doc/user/project/ci_cd_for_external_repo.md b/doc/user/project/ci_cd_for_external_repo.md
new file mode 100644
index 00000000000..51b86a68c7b
--- /dev/null
+++ b/doc/user/project/ci_cd_for_external_repo.md
@@ -0,0 +1,5 @@
+---
+redirect_to: 'https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html'
+---
+
+This document was moved to [another location](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html).
diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md
new file mode 100644
index 00000000000..a4937e6cf6b
--- /dev/null
+++ b/doc/user/project/code_owners.md
@@ -0,0 +1,85 @@
+# Code Owners **[STARTER]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6916)
+in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.
+
+You can use a `CODEOWNERS` file to specify users that are responsible
+for certain files in a repository.
+
+You can choose and add the `CODEOWNERS` file in three places:
+
+- to the root directory of the repository
+- inside the `.gitlab/` directory
+- inside the `docs/` directory
+
+The `CODEOWNERS` file is scoped to a branch, which means that with the
+introduction of new files, the person adding the new content can
+specify themselves as a code owner, all before the new changes
+get merged to the default branch.
+
+When a file matches multiple entries in the `CODEOWNERS` file,
+the users from all entries are displayed on the blob page of
+the given file.
+
+## The syntax of Code Owners files
+
+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.
+
+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
+owners.
+
+Starting a line with a `#` indicates a comment. This needs to be
+escaped using `\#` to address files for which the name starts with a
+`#`.
+
+Example `CODEOWNERS` file:
+
+```
+# This is an example code owners file, lines starting with a `#` will
+# be ignored.
+
+# app/ @commented-rule
+
+# We can specifiy a default match using wildcards:
+* @default-codeowner
+
+# Rules defined later in the file take precedence over the rules
+# defined before.
+# This will match all files for which the file name ends in `.rb`
+*.rb @ruby-owner
+
+# 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
+
+# Both usernames or email addresses can be used to match
+# users. Everything else will be ignored. For example this will
+# specify `@legal` and a user with email `janedoe@gitlab.com` as the
+# owner for the LICENSE file
+LICENSE @legal this_does_not_match janedoe@gitlab.com
+
+# Ending a path in a `/` will specify the code owners for every file
+# nested in that directory, on any level
+/docs/ @all-docs
+
+# Ending a path in `/*` will specify code owners for every file in
+# that directory, but not nested deeper. This will match
+# `docs/index.md` but not `docs/projects/index.md`
+/docs/* @root-docs
+
+# This will make a `lib` directory nested anywhere in the repository
+# match
+lib/ @lib-owner
+
+# This will only match a `config` directory in the root of the
+# repository
+/config/ @config-owner
+
+# If the path contains spaces, these need to be escaped like this:
+path\ with\ spaces/ @space-owner
+```
diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md
new file mode 100644
index 00000000000..2f2a9c5eec3
--- /dev/null
+++ b/doc/user/project/deploy_boards.md
@@ -0,0 +1,132 @@
+# Deploy Boards **[PREMIUM]**
+
+> [Introduced][ee-1589] in [GitLab Premium][ee] 9.0.
+
+GitLab's Deploy Boards offer a consolidated view of the current health and
+status of each CI [environment] 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.
+
+## Overview
+
+With Deploy Boards you can gain more insight into deploys with benefits such as:
+
+- Following a deploy from the start, not just when it's done
+- Watching the rollout of a build across multiple servers
+- Finer state detail (Waiting, Deploying, Finished, Unknown)
+- See [Canary Deployments](canary_deployments.md)
+
+Here's an example of a Deploy Board of the production environment.
+
+![Deploy Boards landing page](img/deploy_boards_landing_page.png)
+
+The squares represent pods in your Kubernetes cluster that are associated with
+the given environment. Hovering above each square you can see the state of a
+deploy rolling out. The percentage is the percent of the pods that are updated
+to the latest release.
+
+Since Deploy Boards are tightly coupled with Kubernetes, there is some required
+knowledge. In particular you should be familiar with:
+
+- [Kubernetes pods](https://kubernetes.io/docs/user-guide/pods)
+- [Kubernetes labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
+- [Kubernetes namespaces](https://kubernetes.io/docs/user-guide/namespaces/)
+- [Kubernetes canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments)
+
+## Use cases
+
+Since the Deploy Board is a visual representation of the Kubernetes pods for a
+specific environment, there are lot of uses cases. To name a few:
+
+- You want to promote what's running in staging, to production. You go to the
+  environments list, verify that what's running in staging is what you think is
+  running, then click on the [manual action](../../ci/yaml/README.md#whenmanual) to deploy to production.
+- You trigger a deploy, and you've got lots of containers to upgrade so you know
+  it'll take a while (you've also throttled your deploy to only take down X
+  containers at a time). But you need to tell someone when it's deployed, so you
+  go to the environments list, look at the production environment to see what
+  the progress is in real-time as each pod is rolled.
+- You get a report that something is weird in production, so you look at the
+  production environment to see what is running, and if a deploy is ongoing or
+  stuck or failed.
+- You've got an MR that looks good, but you want to run it on staging because
+  staging is set up in some way closer to production. You go to the environment
+  list, find the [Review App][review apps] you're interested in, and click the
+  manual action to deploy it to staging.
+
+## Enabling Deploy Boards
+
+To display the Deploy Boards for a specific [environment] you should:
+
+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).
+
+1. [Configure GitLab Runner][runners] with the [Docker][docker-exec] or
+   [Kubernetes][kube-exec] executor.
+1. Configure the [Kubernetes service][kube-service] in your project for the
+   cluster. The Kubernetes namespace is of particular note as you will need it
+   for your deployment scripts (exposed by the `KUBE_NAMESPACE` env variable).
+1. Ensure Kubernetes annotations of `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG`
+   and `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` are applied to the
+   deployments, replica sets, and pods, where `$CI_ENVIRONMENT_SLUG` and
+   `$CI_PROJECT_PATH_SLUG` are the values of the CI variables. This is so we can
+   lookup the proper environment in a cluster/namespace which may have more
+   than one. These resources should be contained in the namespace defined in
+   the Kubernetes service setting. You can use an [Autodeploy] `.gitlab-ci.yml`
+   template which has predefined stages and commands to use, and automatically
+   applies the annotations. Each project will need to have a unique namespace in
+   Kubernetes as well. The image below demonstrates how this is shown inside
+   Kubernetes.
+
+   NOTE: **Note:**
+   The Kubernetes label of `app` is deprecated and may be removed in next major
+   release, GitLab 12.0.
+
+    ![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
+
+A popular CI strategy, where a small portion of the fleet is updated to the new
+version of your application.
+
+[Read more about Canary Deployments.](canary_deployments.md)
+
+## Further reading
+
+- [GitLab Autodeploy][autodeploy]
+- [GitLab CI environment variables][variables]
+- [Environments and deployments][environment]
+- [Kubernetes deploy example][kube-deploy]
+
+[ee-1589]: https://gitlab.com/gitlab-org/gitlab-ee/issues/1589 "Deploy Boards initial issue"
+[ee]: https://about.gitlab.com/pricing/ "GitLab Enterprise Edition landing page"
+[kube-deploy]: https://gitlab.com/gitlab-examples/kubernetes-deploy "Kubernetes deploy example project"
+[kubernetes]: https://kubernetes.io "Kubernetes website"
+[environment]: ../../ci/environments.md "Environments and deployments documentation"
+[docker-exec]: https://docs.gitlab.com/runner/executors/docker.html "GitLab Runner Docker executor"
+[kube-exec]: https://docs.gitlab.com/runner/executors/kubernetes.html "GitLab Runner Kubernetes executor"
+[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"
+[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/description_templates.md b/doc/user/project/description_templates.md
index 08647caaf07..e230444fa67 100644
--- a/doc/user/project/description_templates.md
+++ b/doc/user/project/description_templates.md
@@ -2,8 +2,12 @@
 
 >[Introduced][ce-4981] in GitLab 8.11.
 
+We all know that a properly submitted issue is more likely to be addressed in
+a timely manner by the developers of a project.
+
 Description templates allow you to define context-specific templates for issue
-and merge request description fields for your project.
+and merge request description fields for your project, as well as help filter
+out a lot of unnecessary noise from issues.
 
 ## Overview
 
@@ -18,6 +22,18 @@ Description templates must be written in [Markdown](../markdown.md) and stored
 in your project's repository under a directory named `.gitlab`. Only the
 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.
+- 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.
+- You can also create issues and merge request templates for different
+stages of your workflow, e.g., feature proposal, feature improvement, bug report, etc.
+
 ## Creating issue templates
 
 Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/`
@@ -39,6 +55,32 @@ 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]**
+
+> **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.
+> - Templates for issues were [introduced][ee-28] in GitLab EE 8.1.
+> - 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
+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
+headings, lists, etc.
+
+![Default description templates](img/description_templates_default_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
+pre-filled with the text you entered in the template(s).
+
 ## Description template example
 
 We make use of Description Templates for Issues and Merge Requests within the GitLab Community Edition project. Please refer to the [`.gitlab` folder][gitlab-ce-templates] for some examples.
@@ -93,3 +135,6 @@ Possible fixes
 
 [ce-4981]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4981
 [gitlab-ce-templates]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/.gitlab
+[ee-28]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/28 "Merge Request for adding issues template"
+[ee-7478ece]: https://gitlab.com/gitlab-org/gitlab-ee/commit/7478ece8b48e80782b5465b96c79f85cc91d391b "Commit that introduced merge requests templates"
+[products]: https://about.gitlab.com/pricing/
diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md
new file mode 100644
index 00000000000..541023692ea
--- /dev/null
+++ b/doc/user/project/file_lock.md
@@ -0,0 +1,107 @@
+# File Locking **[PREMIUM]**
+
+> **Notes:**
+> - [Introduced][ee-440] in [GitLab Premium][ee] 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.
+
+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
+member of the team can edit it.
+
+## Overview
+
+Working with multiple people on the same file can be a risk. Conflicts
+when merging a non-text file are hard to overcome and will require a lot
+of manual work to resolve. With GitLab Premium, File
+Locking helps you avoid merge conflicts and better manage your binary
+files by preventing everyone, except you, from modifying a specific file
+or entire directory.
+
+## Use-cases
+
+The file locking feature is useful in situations when:
+
+- Multiple people are working on the same file and you want to avoid merge
+  conflicts.
+- Your repository contains binary files in which situation there is no easy
+  way to tell the diff between yours and your colleagues' changes.
+- Prevent design assets from being overwritten.
+
+Locked directories are locked recursively, which means that everything that
+lies under them is also locked.
+
+## 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] 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.
+
+If a file is locked and you are not the author of its locked state, a
+pre-receive hook will reject your changes when you try to push. In the
+following example, a user who has no permissions on the locked `.gitignore`
+file will see the message below:
+
+```bash
+Counting objects: 3, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (3/3), done.
+Writing objects: 100% (3/3), 320 bytes | 0 bytes/s, done.
+Total 3 (delta 1), reused 0 (delta 0)
+remote: GitLab: The path '.gitignore' is locked by Administrator
+To https://example.com/gitlab-org/gitlab-ce.git
+ ! [remote rejected] master -> master (pre-receive hook declined)
+ error: failed to push some refs to 'https://example.com/gitlab-org/gitlab-ce.git'
+```
+
+Similarly, when a user that is not the author of the locked state of a file
+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)
+
+[ee-440]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/440 "File Lock"
+[ee]: https://about.gitlab.com/pricing/
+[push access]: ../../user/permissions.md
diff --git a/doc/user/project/img/assignee_lists.png b/doc/user/project/img/assignee_lists.png
new file mode 100644
index 00000000000..f2660cd8f80
--- /dev/null
+++ b/doc/user/project/img/assignee_lists.png
diff --git a/doc/user/project/img/deploy_boards_canary_deployments.png b/doc/user/project/img/deploy_boards_canary_deployments.png
new file mode 100644
index 00000000000..037b4a908ab
--- /dev/null
+++ b/doc/user/project/img/deploy_boards_canary_deployments.png
diff --git a/doc/user/project/img/deploy_boards_kubernetes_label.png b/doc/user/project/img/deploy_boards_kubernetes_label.png
new file mode 100644
index 00000000000..19785c74d07
--- /dev/null
+++ b/doc/user/project/img/deploy_boards_kubernetes_label.png
diff --git a/doc/user/project/img/deploy_boards_landing_page.png b/doc/user/project/img/deploy_boards_landing_page.png
new file mode 100644
index 00000000000..c9621a06860
--- /dev/null
+++ b/doc/user/project/img/deploy_boards_landing_page.png
diff --git a/doc/user/project/img/description_templates_default_settings.png b/doc/user/project/img/description_templates_default_settings.png
new file mode 100644
index 00000000000..ab314e83d06
--- /dev/null
+++ b/doc/user/project/img/description_templates_default_settings.png
diff --git a/doc/user/project/img/file_lock.png b/doc/user/project/img/file_lock.png
new file mode 100644
index 00000000000..33f96f20e91
--- /dev/null
+++ 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
new file mode 100644
index 00000000000..5ff3d4d9dbd
--- /dev/null
+++ b/doc/user/project/img/file_lock_folders.png
diff --git a/doc/user/project/img/file_lock_list.png b/doc/user/project/img/file_lock_list.png
new file mode 100644
index 00000000000..2c276335c83
--- /dev/null
+++ b/doc/user/project/img/file_lock_list.png
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
new file mode 100644
index 00000000000..65bc3692da0
--- /dev/null
+++ 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
new file mode 100644
index 00000000000..8f4ef52aacd
--- /dev/null
+++ b/doc/user/project/img/file_lock_repository_view.png
diff --git a/doc/user/project/img/key_value_labels.png b/doc/user/project/img/key_value_labels.png
new file mode 100644
index 00000000000..bec901f127f
--- /dev/null
+++ b/doc/user/project/img/key_value_labels.png
diff --git a/doc/user/project/img/labels_epic_sidebar.png b/doc/user/project/img/labels_epic_sidebar.png
new file mode 100644
index 00000000000..f8162d89e9d
--- /dev/null
+++ b/doc/user/project/img/labels_epic_sidebar.png
diff --git a/doc/user/project/img/project_security_dashboard.png b/doc/user/project/img/project_security_dashboard.png
new file mode 100644
index 00000000000..3294e59e943
--- /dev/null
+++ b/doc/user/project/img/project_security_dashboard.png
diff --git a/doc/user/project/img/protected_branches_select_roles_and_users.png b/doc/user/project/img/protected_branches_select_roles_and_users.png
new file mode 100644
index 00000000000..4f62b057cc7
--- /dev/null
+++ b/doc/user/project/img/protected_branches_select_roles_and_users.png
diff --git a/doc/user/project/img/protected_branches_select_roles_and_users_list.png b/doc/user/project/img/protected_branches_select_roles_and_users_list.png
new file mode 100644
index 00000000000..519f2267496
--- /dev/null
+++ b/doc/user/project/img/protected_branches_select_roles_and_users_list.png
diff --git a/doc/user/project/img/service_desk_confirmation_email.png b/doc/user/project/img/service_desk_confirmation_email.png
new file mode 100644
index 00000000000..e08dced1e38
--- /dev/null
+++ b/doc/user/project/img/service_desk_confirmation_email.png
diff --git a/doc/user/project/img/service_desk_disabled.png b/doc/user/project/img/service_desk_disabled.png
new file mode 100644
index 00000000000..3ae64dcbe96
--- /dev/null
+++ 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
new file mode 100644
index 00000000000..329348e4b52
--- /dev/null
+++ 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
new file mode 100644
index 00000000000..485751fab0a
--- /dev/null
+++ b/doc/user/project/img/service_desk_issue_tracker.png
diff --git a/doc/user/project/img/service_desk_nav_item.png b/doc/user/project/img/service_desk_nav_item.png
new file mode 100644
index 00000000000..3420e355f67
--- /dev/null
+++ b/doc/user/project/img/service_desk_nav_item.png
diff --git a/doc/user/project/img/service_desk_reply.png b/doc/user/project/img/service_desk_reply.png
new file mode 100644
index 00000000000..ae6ce31713b
--- /dev/null
+++ b/doc/user/project/img/service_desk_reply.png
diff --git a/doc/user/project/img/service_desk_thread.png b/doc/user/project/img/service_desk_thread.png
new file mode 100644
index 00000000000..8d8ac39cc5b
--- /dev/null
+++ b/doc/user/project/img/service_desk_thread.png
diff --git a/doc/user/project/index.md b/doc/user/project/index.md
index 64139f9dbe9..6b3b40bf9f8 100644
--- a/doc/user/project/index.md
+++ b/doc/user/project/index.md
@@ -13,7 +13,7 @@ the number of private projects you create.
 When you create a project in GitLab, you'll have access to a large number of
 [features](https://about.gitlab.com/features/):
 
-**Issues and merge requests:**
+**Repositories:**
 
 - [Issue tracker](issues/index.md): Discuss implementations with your team within issues
   - [Issue Boards](issue_board.md): Organize and prioritize your workflow
@@ -28,6 +28,13 @@ When you create a project in GitLab, you'll have access to a large number of
   permission to create tags, and prevent accidental update or deletion
   - [Signing commits](gpg_signed_commits/index.md): use GPG to sign your commits
   - [Deploy tokens](deploy_tokens/index.md): Manage project-based deploy tokens that allow permanent access to the repository and Container Registry.
+- [Web IDE](web_ide/index.md)
+
+**Issues and merge requests:**
+
+- [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]**
 - [Merge Requests](merge_requests/index.md): Apply your branching
   strategy and get reviewed by your team
   - [Merge Request Approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html): Ask for approval before
@@ -67,6 +74,8 @@ When you create a project in GitLab, you'll have access to a large number of
      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](https://docs.gitlab.com/ee/user/project/operations/feature_flags.html): Feature flags allow you to ship a project in
+    different flavors by dynamically toggling certain functionality **[PREMIUM]**
 - [GitLab Pages](pages/index.md): Build, test, and deploy your static
   website with GitLab Pages
 
@@ -75,12 +84,17 @@ 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.
+- [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](https://docs.gitlab.com/ee/user/project/packages/maven_repository.html): your private Maven repository in GitLab. **[PREMIUM]**
+- [NPM packages](https://docs.gitlab.com/ee/user/project/packages/npm_registry.html): your private NPM package registry in GitLab. **[PREMIUM]**
+- [Code owners](code_owners.md): specify code owners for certain files **[STARTER]**
+- [License Management](https://docs.gitlab.com/ee/user/application_security/license_management/index.html): approve and blacklist licenses for projects. **[ULTIMATE]**
 
 ### Project integrations
 
@@ -116,6 +130,13 @@ 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]**
+
+Instead of importing a repository directly to GitLab, you can connect your repository
+as a CI/CD project.
+
+Read through the documentation on [CI/CD for external repositories](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html).
+
 ## Project members
 
 Learn how to [add members to your projects](members/index.md).
diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md
index 73d61bedde1..bfc3e3a7de0 100644
--- a/doc/user/project/labels.md
+++ b/doc/user/project/labels.md
@@ -8,9 +8,48 @@ Labels allow you to categorize issues or merge requests using descriptive titles
 
 In GitLab, you can create project and group labels:
 
-- **Project labels** can be assigned to issues or merge requests in that project only. 
+- **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.
 
+## 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
+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
+in the label’s title, using the format `key::value`. For example:
+
+![A sample scoped label](img/key_value_labels.png)
+
+Two scoped labels with the same key but a different value cannot simultaneeously
+apply to an issue, epic, or merge request. For example, if an issue already has `priority::3`
+and you apply `priority::2` to it, `priority::3` is automatically removed from the issue.
+
+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.
+
+### Workflows with scoped labels **[PREMIUM]**
+
+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
+would then create labels `platform::iOS`, `platform::Android`, `platform::Linux`,
+etc., as necessary. Applying any one of these labels on a given issue would
+automatically remove any other existing label that starts with `platform::`.
+
+The same pattern could be applied to represent the workflow states of your teams.
+Suppose you have the labels `workflow::development`, `workflow::review`, and
+`workflow::deployed`. If an issue already has the label `workflow::development`
+applied, and a developer wanted to advance the issue to `workflow::review`, they
+would simply apply that label, and the `workflow::development` label would
+automatically be removed. This behavior already exists when you move issues
+across label lists in an [issue board](issue_board.md#creating-workflows), but
+now, team members who may not be working in an issue board directly would still
+be able to advance workflow states consistently in issues themselves.
+
 ## Creating labels
 
 >**Note:**
@@ -35,6 +74,9 @@ GitLab will add the following default labels to the project:
 
 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.
+
+![Create Labels from Epic](img/labels_epic_sidebar.png)
 
 Group labels appear in every label list page of the group's child projects.
 
@@ -81,7 +123,7 @@ top-right:
 
 GitLab will consider the label title and description for the search.
 
-## Filtering issues and merge requests by label
+## Filtering issues, merge requests and epics by label
 
 ### Filtering in list pages
 
@@ -89,11 +131,16 @@ From the project issue list page and the project merge request list page, you ca
 
 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 epic list page, you can [filter](../search/index.md#issues-and-merge-requests) by both current group labels as well as decendent group labels.
+
 ![Labels group issues](img/labels_group_issues.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]**
 
 ## Subscribing to labels
 
diff --git a/doc/user/project/maven_packages.md b/doc/user/project/maven_packages.md
new file mode 100644
index 00000000000..d32d6084b38
--- /dev/null
+++ b/doc/user/project/maven_packages.md
@@ -0,0 +1,5 @@
+---
+redirect_to: 'https://docs.gitlab.com/ee/user/project/packages/maven_repository.html'
+---
+
+This document was moved to [another location](https://docs.gitlab.com/ee/user/project/packages/maven_repository.html).
diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md
index 2060b5dd4a2..56e8f1731ae 100644
--- a/doc/user/project/protected_branches.md
+++ b/doc/user/project/protected_branches.md
@@ -15,12 +15,10 @@ By default, a protected branch does four simple things:
 - it prevents **anyone** from force pushing to the branch
 - it prevents **anyone** from deleting the branch
 
-See the [Changelog](#changelog) section for changes over time.
+>**Note**:
+A GitLab admin is allowed to push to the protected branches.
 
->
->Additional functionality for GitLab Enterprise Edition:
->
->- Restrict push and merge access to [certain users][ee-restrict]
+See the [Changelog](#changelog) section for changes over time.
 
 ## Configuring protected branches
 
@@ -68,6 +66,21 @@ 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]**
+
+> This feature was [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
+dropdown menu select the role and/or the users you want to have merge or push
+access.
+
+![Select roles and users](img/protected_branches_select_roles_and_users.png)
+
+Click **Protect** and the branch will appear in the "Protected branch" list.
+
+![Roles and users list](img/protected_branches_select_roles_and_users_list.png)
+
 ## Wildcard protected branches
 
 > [Introduced][ce-4665] in GitLab 8.10.
@@ -169,3 +182,4 @@ for details about the pipelines security model.
 [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/
diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md
index 2040e2ee004..15eb862b431 100644
--- a/doc/user/project/quick_actions.md
+++ b/doc/user/project/quick_actions.md
@@ -46,13 +46,15 @@ discussions, and descriptions:
 | `/remove_due_date`         | Remove due date                | ✓     |               |
 | `/weight 0,1,2, ...`       | Set weight **[STARTER]**       | ✓     |               |
 | `/clear_weight`            | Clears weight **[STARTER]**    | ✓     |               |
-| `/epic <group&epic &#124; Epic URL>` | Add to epic **[ULTIMATE]** | ✓ |             |
+| `/epic <&epic &#124; group&epic &#124; Epic URL>` | Add to epic **[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 | ✓ |               |
 | `/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 | ✓ | |
 
diff --git a/doc/user/project/security_dashboard.md b/doc/user/project/security_dashboard.md
new file mode 100644
index 00000000000..43e910b29fe
--- /dev/null
+++ b/doc/user/project/security_dashboard.md
@@ -0,0 +1,5 @@
+---
+redirect_to: 'https://docs.gitlab.com/ee/user/application_security/security_dashboard/index.html'
+---
+
+This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/security_dashboard/index.html).
diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md
new file mode 100644
index 00000000000..1a582164d03
--- /dev/null
+++ b/doc/user/project/service_desk.md
@@ -0,0 +1,124 @@
+# 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).
+
+## Overview
+
+Service Desk is a module that allows your team to connect directly
+with any external party through email right inside of GitLab; no external tools required.
+An ongoing conversation right where your software is built ensures that user feedback ends
+up directly where it's needed, helping you build the right features to solve your users'
+real problems.
+
+With Service Desk, you can provide efficient email support to your customers, who can now
+email you bug reports, feature requests, or general feedback that will all end up in your
+GitLab project as new issues. In turn, your team can respond straight from the project.
+
+As Service Desk is built right into GitLab itself, the complexity and inefficiencies
+of multiple tools and external integrations are eliminated, significantly shortening
+the cycle time from feedback to software update.
+
+For an overview, check the video demonstration on [GitLab Service Desk](https://about.gitlab.com/2017/05/09/demo-service-desk/).
+
+## Use cases
+
+For instance, let's assume you develop a game for iOS or Android.
+The codebase is hosted in your GitLab instance, built and deployed
+with GitLab CI.
+
+Here's how Service Desk will work for you:
+
+1. You'll provide a project-specific email address to your paying customers, who can email you directly from within the app
+1. Each email they send creates an issue in the appropriate project
+1. Your team members navigate to the Service Desk issue tracker, where they can see new support requests and respond inside associated issues
+1. Your team communicates back and forth with the customer to understand the request
+1. Your team starts working on implementing code to solve your customer's problem
+1. When your team finishes the implementation, whereupon the merge request is merged and the issue is closed automatically
+1. The customer will have been attended successfully via email, without having real access to your GitLab instance
+1. Your team saved time by not having to leave GitLab (or setup any integrations) to follow up with your customer
+
+## How it works
+
+GitLab Service Desk is a simple way to allow people to create issues in your
+GitLab instance without needing their own user account.
+
+It provides a unique email address for end users to create issues in a project,
+and replies can be sent either through the GitLab interface or by email. End
+users will only see the thread through email.
+
+## Configuring Service Desk
+
+> **Note:**
+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:
+
+     ![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.
+
+     **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)
+
+     _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._
+
+
+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)
+
+## Using Service Desk
+
+### As an end user (issue creator)
+
+To create a Service Desk issue, an end user doesn't need to know anything about
+the GitLab instance. They just send an email to the address they are given, and
+receive an email back confirming receipt:
+
+![Service Desk enabled](img/service_desk_confirmation_email.png)
+
+This also gives the end user an option to unsubscribe.
+
+If they don't choose to unsubscribe, then any new comments added to the issue
+will be sent as emails:
+
+![Service Desk reply email](img/service_desk_reply.png)
+
+And any responses they send will be displayed in the issue itself.
+
+### As a responder to the issue
+
+For responders to the issue, everything works as usual. They'll see a familiar looking
+issue tracker, where they can see issues created via customer support requests and
+filter and interact with them just like other GitLab issues.
+
+![Service Desk Issue tracker](img/service_desk_issue_tracker.png)
+
+Messages from the end user will show as coming from the special Support Bot user, but apart from that,
+you can read and write comments as you normally do:
+
+![Service Desk issue thread](img/service_desk_thread.png)
+
+> Note that the project's visibility (private, internal, public) does not affect Service Desk.
+
+### Support Bot user
+
+Behind the scenes, Service Desk works by the special Support Bot user creating issues. This user
+does not count toward the license limit count.