Merge branch 'doc/add-build-email-service' into 'master'

Add documentation about build emails service

Closes #12497

See merge request !2871

4 files changed, 29 insertions, 4 deletions

diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md
index ae7b760fa67..07e566e3710 100644
--- a/doc/ci/quick_start/README.md
+++ b/doc/ci/quick_start/README.md
@@ -36,13 +36,13 @@ file and start builds on _Runners_ according to the contents of the file,
 for that commit.
 
 Because `.gitlab-ci.yml` is in the repository, it is version controlled,
-old versions still build succesfully, forks can easily make use of CI,
+old versions still build successfully, forks can easily make use of CI,
 branches can have separate builds and you have a single source of truth for CI.
 You can read more about the reasons why we are using `.gitlab-ci.yml`
 [in our blog about it][blog-ci].
 
 **Note:** `.gitlab-ci.yml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file
-so you have to pay extra attention to the identation. Always use spaces, not
+so you have to pay extra attention to the indentation. Always use spaces, not
 tabs.
 
 ### Creating a simple `.gitlab-ci.yml` file
@@ -168,7 +168,7 @@ To enable **Shared Runners** you have to go to your project's
 
 ## Seeing the status of your build
 
-After configuring the Runner succesfully, you should see the status of your
+After configuring the Runner successfully, you should see the status of your
 last commit change from _pending_ to either _running_, _success_ or _failed_.
 
 You can view all builds, by going to the **Builds** page in your project.
@@ -184,6 +184,15 @@ you expected.
 You are also able to view the status of any commit in the various pages in
 GitLab, such as **Commits** and **Merge Requests**.
 
+## Enabling build emails
+
+If you want to receive e-mail notifications about the result status of the
+builds, you should explicitly enable the **Builds Emails** service under your
+project's settings.
+
+For more information read the [Builds emails service documentation]
+(../../project_services/builds_emails.md).
+
 ## Builds badge
 
 You can access a builds badge image using following link:
diff --git a/doc/project_services/builds_emails.md b/doc/project_services/builds_emails.md
new file mode 100644
index 00000000000..af0b1a287c7
--- /dev/null
+++ b/doc/project_services/builds_emails.md
@@ -0,0 +1,16 @@
+## Enabling build emails
+
+To receive e-mail notifications about the result status of your builds, visit
+your project's **Settings > Services > Builds emails** and activate the service.
+
+In the _Recipients_ area, provide a list of e-mails separated by comma.
+
+Check the _Add pusher_ checkbox if you want the committer to also receive
+e-mail notifications about each build's status.
+
+If you enable the _Notify only broken builds_ option, e-mail notifications will
+be sent only for failed builds.
+
+---
+
+![Builds emails service settings](img/builds_emails_service.png)
diff --git a/doc/project_services/img/builds_emails_service.png b/doc/project_services/img/builds_emails_service.png
new file mode 100644
index 00000000000..e604dd73ffa
--- /dev/null
+++ b/doc/project_services/img/builds_emails_service.png
diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md
index 55db3e4f2f3..3fea2cff0b9 100644
--- a/doc/project_services/project_services.md
+++ b/doc/project_services/project_services.md
@@ -12,7 +12,7 @@ further configuration instructions and details. Contributions are welcome.
 | Assembla 	| Project Management Software (Source Commits Endpoint) |
 | [Atlassian Bamboo CI](bamboo.md) | A continuous integration and build server |
 | Buildkite | Continuous integration and deployments |
-| Builds emails |	Email the builds status to a list of recipients |
+| [Builds emails](builds_emails.md) |	Email the builds status to a list of recipients |
 | Campfire | Simple web-based real-time group chat |
 | Custom Issue Tracker | Custom issue tracker |
 | Drone CI | Continuous Integration platform built on Docker, written in Go |