Merge branch 'winh-badges-docs' into 'master'

Add user documentation for badges

Closes #41174 and #41176

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

6 files changed, 83 insertions, 3 deletions

diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md
index 3e0683f378d..0d7d0fd9c42 100644
--- a/doc/api/group_badges.md
+++ b/doc/api/group_badges.md
@@ -1,5 +1,8 @@
 # Group badges API
 
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17082)
+in GitLab 10.6.
+
 ## Placeholder tokens
 
 Badges support placeholders that will be replaced in real time in both the link and image URL. The allowed placeholders are:
@@ -182,7 +185,7 @@ curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/a
 Example response:
 
 ```json
-{  
+{
   "link_url": "http://example.com/ci_status.svg?project=%{project_path}&ref=%{default_branch}",
   "image_url": "https://shields.io/my/badge",
   "rendered_link_url": "http://example.com/ci_status.svg?project=example-org/example-project&ref=master",
diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md
index 3f6e348b5b4..94389273e9c 100644
--- a/doc/api/project_badges.md
+++ b/doc/api/project_badges.md
@@ -1,5 +1,8 @@
 # Project badges API
 
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17082)
+in GitLab 10.6.
+
 ## Placeholder tokens
 
 Badges support placeholders that will be replaced in real time in both the link and image URL. The allowed placeholders are:
@@ -179,7 +182,7 @@ curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/a
 Example response:
 
 ```json
-{  
+{
   "link_url": "http://example.com/ci_status.svg?project=%{project_path}&ref=%{default_branch}",
   "image_url": "https://shields.io/my/badge",
   "rendered_link_url": "http://example.com/ci_status.svg?project=example-org/example-project&ref=master",
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md
new file mode 100644
index 00000000000..c4e59444ef7
--- /dev/null
+++ b/doc/user/project/badges.md
@@ -0,0 +1,73 @@
+# Badges
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41174)
+in GitLab 10.7.
+
+Badges are a unified way to present condensed pieces of information about your
+projects. They consist of a small image and additionally a URL that the image
+points to. Examples for badges can be the [pipeline status], [test coverage],
+or ways to contact the project maintainers.
+
+![Badges on Project overview page](img/project_overview_badges.png)
+
+## Project badges
+
+Badges can be added to a project and will then be visible on the project's overview page.
+If you find that you have to add the same badges to several projects, you may want to add them at the [group level](#group-badges).
+
+To add a new badge to a project:
+
+1.  Navigate to your project's **Settings > 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
+clicking on the trash icon.
+
+Badges associated with a group can only be edited or deleted on the
+[group level](#group-badges).
+
+## Group badges
+
+Badges can be added to a group and will then be visible on every project's
+overview page that's under that group. In this case, they cannot be edited or
+deleted on the project level. If you need to have individual badges for each
+project, consider adding them on the [project level](#project-badges) or use
+[placeholders](#placeholders).
+
+To add a new badge to a group:
+
+1.  Navigate to your group's **Settings > Project 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
+by clicking on the trash icon.
+
+Badges directly associated with a project can be configured on the
+[project level](#project-badges).
+
+## Placeholders
+
+The URL a badge points to, as well as the image URL, can contain placeholders
+which will be evaluated when displaying the badge. The following placeholders
+are available:
+
+- `%{project_path}`: Path of a project including the parent groups
+- `%{project_id}`: Database ID associated with a project
+- `%{default_branch}`: Default branch name configured for a project's repository
+- `%{commit_sha}`: ID of the most recent commit to the default branch of a
+  project's repository
+
+## API
+
+You can also configure badges via the GitLab API. As in the settings, there is
+a distinction between endpoints for badges on the
+[project level](../../api/project_badges.md) and [group level](../../api/group_badges.md).
+
+[pipeline status]: pipelines/settings.md#pipeline-status-badge
+[test coverage]: pipelines/settings.md#test-coverage-report-badge
diff --git a/doc/user/project/img/project_overview_badges.png b/doc/user/project/img/project_overview_badges.png
new file mode 100644
index 00000000000..3067a7dfa13
--- /dev/null
+++ b/doc/user/project/img/project_overview_badges.png
diff --git a/doc/user/project/index.md b/doc/user/project/index.md
index ba6651624f9..5ce4ebfa811 100644
--- a/doc/user/project/index.md
+++ b/doc/user/project/index.md
@@ -74,6 +74,7 @@ website with GitLab Pages
 - [Cycle Analytics](cycle_analytics.md): Review your development lifecycle
 - [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
 
 ### Project's integrations
 
diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md
index 6cead7b9961..14f2e522f01 100644
--- a/doc/user/project/pipelines/settings.md
+++ b/doc/user/project/pipelines/settings.md
@@ -106,7 +106,7 @@ If you want to auto-cancel all pending non-HEAD pipelines on branch, when
 new pipeline will be created (after your git push or manually from UI),
 check **Auto-cancel pending pipelines** checkbox and save the changes.
 
-## Badges
+## Pipeline Badges
 
 In the pipelines settings page you can find pipeline status and test coverage
 badges for your project. The latest successful pipeline will be used to read