Merge branch 'doc_enable_disable_ci' into 'master'

Add documentation on enabling/disabling GitLab CI

Closes #4289

See merge request !2320

4 files changed, 72 insertions, 0 deletions

diff --git a/doc/README.md b/doc/README.md
index f4553a899d3..25fe3abcb9a 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -19,6 +19,7 @@
 ## CI Documentation
 
 - [Quick Start](ci/quick_start/README.md)
+- [Enable or disable GitLab CI](ci/enable_or_disable_ci.md)
 - [Configuring project (.gitlab-ci.yml)](ci/yaml/README.md)
 - [Configuring runner](ci/runners/README.md)
 - [Configuring deployment](ci/deployment/README.md)
diff --git a/doc/ci/README.md b/doc/ci/README.md
index a1f5513d88e..4cdd2e1ad33 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -3,6 +3,7 @@
 ### User documentation
 
 * [Quick Start](quick_start/README.md)
+* [Enable or disable GitLab CI](enable_or_disable_ci.md)
 * [Configuring project (.gitlab-ci.yml)](yaml/README.md)
 * [Configuring runner](runners/README.md)
 * [Configuring deployment](deployment/README.md)
diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md
new file mode 100644
index 00000000000..9bd2f5aff22
--- /dev/null
+++ b/doc/ci/enable_or_disable_ci.md
@@ -0,0 +1,70 @@
+## Enable or disable GitLab CI
+
+_To effectively use GitLab CI, you need a valid [`.gitlab-ci.yml`](yaml/README.md)
+file present at the root directory of your project and a
+[runner](runners/README.md) properly set up. You can read our
+[quick start guide](quick_start/README.md) to get you started._
+
+If you are using an external CI server like Jenkins or Drone CI, it is advised
+to disable GitLab CI in order to not have any conflicts with the commits status
+API.
+
+---
+
+As of GitLab 8.2, GitLab CI is mainly exposed via the `/builds` page of a
+project. Disabling GitLab CI in a project does not delete any previous builds.
+In fact, the `/builds` page can still be accessed, although it's hidden from
+the left sidebar menu.
+
+GitLab CI is enabled by default on new installations and can be disabled either
+individually under each project's settings, or site-wide by modifying the
+settings in `gitlab.yml` and `gitlab.rb` for source and Omnibus installations
+respectively.
+
+### Per-project user setting
+
+The setting to enable or disable GitLab CI can be found with the name **Builds**
+under the **Features** area of a project's settings along with **Issues**,
+**Merge Requests**, **Wiki** and **Snippets**. Select or deselect the checkbox
+and hit **Save** for the settings to take effect.
+
+![Features settings](img/features_settings.png)
+
+---
+
+### Site-wide administrator setting
+
+You can disable GitLab CI site-wide, by modifying the settings in `gitlab.yml`
+and `gitlab.rb` for source and Omnibus installations respectively.
+
+Two things to note:
+
+1. Disabling GitLab CI, will affect only newly-created projects. Projects that
+   had it enabled prior to this modification, will work as before.
+1. Even if you disable GitLab CI, users will still be able to enable it in the
+   project's settings.
+
+---
+
+For installations from source, open `gitlab.yml` with your editor and set
+`builds` to `false`:
+
+```yaml
+## Default project features settings
+default_projects_features:
+  issues: true
+  merge_requests: true
+  wiki: true
+  snippets: false
+  builds: false
+```
+
+Save the file and restart GitLab: `sudo service gitlab restart`.
+
+For Omnibus installations, edit `/etc/gitlab/gitlab.rb` and add the line:
+
+```
+gitlab-rails['gitlab_default_projects_features_builds'] = false
+```
+
+Save the file and reconfigure GitLab: `sudo gitlab-ctl reconfigure`.
diff --git a/doc/ci/img/features_settings.png b/doc/ci/img/features_settings.png
new file mode 100644
index 00000000000..17aba5d14d8
--- /dev/null
+++ b/doc/ci/img/features_settings.png