Commit 86ca1a77 authored by Douwe Maan's avatar Douwe Maan

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

Add user documentation for badges

Closes #41174 and #41176

See merge request gitlab-org/gitlab-ce!18200
parents 14f183de 42411b05
# 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",
......
# 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",
......
# 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
......@@ -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
......
......@@ -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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment