diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md
index 3e0683f378d9db399945ee5fbb61b691f767558a..0d7d0fd9c421540f26793ca621a2f5d10ffafd55 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 3f6e348b5b428b05592b5859b1c0554b5dace007..94389273e9c162beff377ef894b58ee056e9dfac 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 0000000000000000000000000000000000000000..c4e59444ef7c4bef3df47c55af517db4cce8d192
--- /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.
+
+
+
+## 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 0000000000000000000000000000000000000000..3067a7dfa131daaab3640149cb9d1a1da740bdcd
Binary files /dev/null and b/doc/user/project/img/project_overview_badges.png differ
diff --git a/doc/user/project/index.md b/doc/user/project/index.md
index 2b8efed900a17a797f81b3be2d502b66083abca1..00907016bb201457dc2b59268bf67b6666aca3af 100644
--- a/doc/user/project/index.md
+++ b/doc/user/project/index.md
@@ -81,6 +81,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 6cead7b9961d99a9b9ff4e2eec0953f6f8f37726..14f2e522f0175b68d3ef9c88c3fd79b4aff9d4d1 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