diff --git a/README.md b/README.md
index 40f9a5007407b792b3aecaa47894184cfb164dbd_UkVBRE1FLm1k..a7bf1186369e78c46953922a2c10d91229d7f8ea_UkVBRE1FLm1k 100644
--- a/README.md
+++ b/README.md
@@ -531,35 +531,7 @@
 
 ### Changing gitlab.yml settings
 
-Some of GitLab's features can be customized through
-[gitlab.yml][gitlab.yml.example]. If you want to change a `gitlab.yml` setting
-with omnibus-gitlab, you need to do so via `/etc/gitlab/gitlab.rb`. The
-translation works as follows.
-
-In `gitlab.yml`, you will find structure like this:
-
-```yaml
-production: &base
-  gitlab:
-    default_projects_limit: 10
-```
-
-In `gitlab.rb`, this translates to:
-
-```ruby
-gitlab_rails['gitlab_default_projects_limit'] = 10
-```
-
-What happens here is that we forget about `production: &base`, and join
-`gitlab:` with `default_projects_limit:` into `gitlab_default_projects_limit`.
-Note that not all `gitlab.yml` settings can be changed via `gitlab.rb` yet; see
-the [gitlab.yml ERB template][gitlab.yml.erb].  If you think an attribute is
-missing please create a merge request on the omnibus-gitlab repository.
-
-Run `sudo gitlab-ctl reconfigure` for changes in `gitlab.rb` to take effect.
-
-Do not edit the generated file in `/var/opt/gitlab/gitlab-rails/etc/gitlab.yml`
-since it will be overwritten on the next `gitlab-ctl reconfigure` run.
+See [doc/settings/gitlab.yml.md](doc/settings/gitlab.yml.md).
 
 ### Specify numeric user and group identifiers
 
@@ -1055,6 +1027,5 @@
 [gitlab.yml.erb]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/templates/default/gitlab.yml.erb
 [database.yml.postgresql]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/database.yml.postgresql
 [database.yml.mysql]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/database.yml.mysql
-[gitlab.yml.example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example
 [svlogd]: http://smarden.org/runit/svlogd.8.html
 [installation]: https://about.gitlab.com/installation/
diff --git a/doc/settings/README.md b/doc/settings/README.md
index 40f9a5007407b792b3aecaa47894184cfb164dbd_ZG9jL3NldHRpbmdzL1JFQURNRS5tZA==..a7bf1186369e78c46953922a2c10d91229d7f8ea_ZG9jL3NldHRpbmdzL1JFQURNRS5tZA== 100644
--- a/doc/settings/README.md
+++ b/doc/settings/README.md
@@ -3,3 +3,4 @@
 - [SMTP](smtp.md)
 - [Unicorn](unicorn.md)
 - [Environment variables](environment-variables.md).
+- [gitlab.yml](gitlab.yml.md)
diff --git a/doc/settings/gitlab.yml.md b/doc/settings/gitlab.yml.md
new file mode 100644
index 0000000000000000000000000000000000000000..a7bf1186369e78c46953922a2c10d91229d7f8ea_ZG9jL3NldHRpbmdzL2dpdGxhYi55bWwubWQ=
--- /dev/null
+++ b/doc/settings/gitlab.yml.md
@@ -0,0 +1,42 @@
+# Changing gitlab.yml and application.yml settings
+
+Some of GitLab's features can be customized through
+[gitlab.yml][gitlab.yml.example] and [application.yml (GitLab
+CI)][application.yml.example]. If you want to change a `gitlab.yml` setting
+with omnibus-gitlab, you need to do so via `/etc/gitlab/gitlab.rb`. The
+translation works as follows.
+
+In `gitlab.yml`, you will find structure like this:
+
+```yaml
+production: &base
+  gitlab:
+    default_projects_limit: 10
+```
+
+In `gitlab.rb`, this translates to:
+
+```ruby
+gitlab_rails['gitlab_default_projects_limit'] = 10
+```
+
+What happens here is that we forget about `production: &base`, and join
+`gitlab:` with `default_projects_limit:` into `gitlab_default_projects_limit`.
+Note that not all `gitlab.yml` settings can be changed via `gitlab.rb` yet; see
+the [gitlab.yml ERB template][gitlab.yml.erb].  If you think an attribute is
+missing please create a merge request on the omnibus-gitlab repository.
+
+The same principle applies to GitLab CI's
+[application.yml][application.yml.example]:
+
+```ruby
+gitlab_ci['gitlab_ci_all_broken_builds'] = false
+```
+
+Run `sudo gitlab-ctl reconfigure` for changes in `gitlab.rb` to take effect.
+
+Do not edit the generated file in `/var/opt/gitlab/gitlab-rails/etc/gitlab.yml`
+since it will be overwritten on the next `gitlab-ctl reconfigure` run.
+
+[gitlab.yml.example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example
+[application.yml.example]: https://gitlab.com/gitlab-org/gitlab-ci/blob/master/config/application.yml.example