doc/user/project/badges.md
{{< details >}}
{{< /details >}}
Badges are a unified way to present condensed pieces of information about your projects. A badge consists of a small image and a URL that the image points to. In GitLab, badges are displayed on the project overview page, below the project description. You can use badges at the project and group level.
GitLab provides the following pipeline badges:
GitLab also supports adjusting badge style.
The pipeline status badge indicates the status of the latest pipeline in a project. Depending on the status of your pipeline, the badge can have one of the following values:
pendingrunningpassedfailedskippedmanualcanceledunknownYou can access a pipeline status badge image by using the following link:
https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg
To make the pipeline status badge display only the last non-skipped status, use the ?ignore_skipped=true query parameter:
https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ignore_skipped=true
The test coverage report badge indicates the percentage of code that is tested in a project. The value is calculated based on the latest successful pipeline.
You can access a test coverage report badge image by using the following link:
https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg
You can define the regular expression for the code coverage that each job log is matched against. This means that each job in the pipeline can have the test coverage percentage value defined.
To get the coverage report from a specific job, add the job=coverage_job_name parameter to the URL.
For example, you can use code similar to the following to add the test coverage report badge of the
coverage job to a Markdown file:
The following table shows the default test coverage limits and badge colors:
| Test coverage | Percentage limits | Badge color |
|---|---|---|
| Good | 95 up to and including 100% | <span style="color: #4c1">■</span> #4c1 |
| Acceptable | 90 up to 95% | <span style="color:#a3c51c"> ■</span> #a3c51c |
| Medium | 75 up to 90% | <span style="color: #dfb317">■</span> #dfb317 |
| Low | 0 up to 75% | <span style="color: #e05d44">■</span> #e05d44 |
| Unknown | No coverage | <span style="color: #9f9f9f">■</span> #9f9f9f |
[!note] Up to means up to, but not including, the upper bound.
You can override the default limits by passing the following query parameters in the coverage report badge URL:
| Query parameter | Acceptable values | Default |
|---|---|---|
min_good | Any value between 3 and 100 | 95 |
min_acceptable | Any value between 2 and min_good−1 | 90 |
min_medium | Any value between 1 and min_acceptable−1 | 75 |
For example:
https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?min_good=98&min_acceptable=75
If you set an invalid boundary, GitLab automatically adjusts it to be valid. For example,
if you set min_good to 80 and min_acceptable to 85, GitLab sets min_acceptable
to 79 (min_good - 1) because the minimum acceptable value cannot be higher than
the minimum good value.
The latest release badge indicates the latest release tag name for your project.
If there is no release, it shows none.
You can access a latest release badge image by using the following link:
https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg
By default, the badge fetches the release sorted using the released_at
time with the ?order_by query parameter.
https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg?order_by=release_at
You can change the width of the release name field by using the value_width parameter (Introduced in GitLab 15.10).
The value must be between 1 and 200, and the default value is 54.
If you set an out of range value, GitLab automatically adjusts it to the default value.
Badges can be added to a project by Maintainers or Owners, and are 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.
A common project badge presents the GitLab CI pipeline status.
To add this badge to a project:
https://gitlab.example.com/%{project_path}/-/commits/%{default_branch}https://gitlab.example.com/%{project_path}/badges/%{default_branch}/pipeline.svgBadges can be added to a group by Owners, and are visible on the Overview page of any project that belongs to the group. By adding a badge to a group, you add and enforce a project-level badge for all projects in the group.
[!note] While these badges appear as project-level badges in the codebase, they cannot be edited or deleted at the project level.
If you need individual badges for each project, either:
To view badges available in a project or group:
To add a new badge to a project or group:
You can view the exact link for your badges. Then you can use the link to embed the badge in your HTML or Markdown pages.
[!note] The pipeline status badge is based on specific Git revisions (branches). Ensure you select the appropriate branch to view the correct pipeline status.
{{< details >}}
{{< /details >}}
{{< history >}}
custom_project_badges. Disabled by default.{{< /history >}}
You can customize how badges appear in your project:
You can customize the following aspects of all badge types:
Pipeline, coverage, release, and custom badges can be rendered in different styles by adding the style=style_name parameter to the URL. Two styles are available:
Flat (default):
https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat
Flat square:
https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square
The text for the left side on the badge can be customize. For example, to differentiate between multiple coverage jobs that run in the same pipeline.
Customize the badge key text by adding the key_text=custom_text parameter to the URL:
https://gitlab.example.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130
Customize the badge key width by adding the key_width=width parameter to the URL:
https://gitlab.example.com/%{project_path}/-/badges/coverage.svg?key_width=130
Customize the badge value width by adding the value_width=width parameter to the URL:
https://gitlab.example.com/%{project_path}/-/badges/coverage.svg?value_width=130
Custom badges give you complete control over both sides of the badge. Unlike standard badges that show predefined information (like pipeline status), custom badges let you:
In addition to the basic customization options, custom badges support these additional customization options:
You can add a custom badge by using the following link:
https://gitlab.example.com/%{project_path}/-/badges/custom.svg
For example, you can use placeholders to create a badge for the latest tag:
https://gitlab.example.com/%{project_path}/-/badges/custom.svg?key_text=Latest_tag&value_text=%{latest_tag}&key_color=white&value_color=7bc043
[!warning] Placeholders allow badges to expose otherwise-private information, such as the default branch or commit SHA when the project is configured to have a private repository. This behavior is intentional, as badges are intended to be used publicly. Avoid using these placeholders if the information is sensitive.
Customize the text displayed on the right side by adding the value_text=text parameter to the URL:
https://gitlab.example.com/%{project_path}/-/badges/custom.svg?value_text=badge
Customize the background color on the right side by adding the value_color=color parameter to the URL:
Colors can be passed as:
bluefff or 7bc043 (without leading #)https://gitlab.example.com/%{project_path}/-/badges/custom.svg?value_color=red
Customize the background color on the left side by adding the value_color=color parameter to the URL:
Colors can be passed as:
bluefff or 7bc043 (without leading #)https://gitlab.example.com/%{project_path}/-/badges/custom.svg?key_color=green
Prerequisites:
To add a custom badge with an image:
In the top bar, select Search or go to and find your project or group.
Select Settings > General.
Expand Badges.
Under Name, enter the name for the badge.
Under Link, enter the URL that the badge should point to.
Under Badge image URL, enter the URL for your custom image. For example, to use an image from your repository:
https://gitlab.example.com/<project_path>/-/raw/<default_branch>/custom-image.svg
Select Add badge.
To use custom images generated through a pipeline, see accessing the latest job artifacts by URL.
To edit a badge in a project or group:
To delete a badge in a project or group:
[!note] Badges associated with a group can be edited or deleted only at the group level.
Both the URL a badge points to and the image URL can contain placeholders, which are evaluated when displaying the badge. The following placeholders are available:
%{project_path}: Path of a project including the parent groups%{project_title}: Title of a project%{project_name}: Name of a project%{project_id}: Database ID associated with a project%{project_namespace}: Project namespace of a project%{group_name}: Group of a project%{gitlab_server}: Server of a project%{gitlab_pages_domain}: Domain hosting GitLab Pages%{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%{latest_tag}: Latest tag added to the project's repository<!-- -->[!warning] Placeholders allow badges to expose otherwise-private information, such as the default branch or commit SHA when the project is configured to have a private repository. This behavior is intentional, as badges are intended to be used publicly. Avoid using these placeholders if the information is sensitive.
[!warning] Due to issue 481729
%{gitlab_server}and%{gitlab_pages_domain}cannot be used to specify the hostname in the URL, but only for other parameters.