diff options
Diffstat (limited to 'doc/user/project/badges.md')
| -rw-r--r-- | doc/user/project/badges.md | 243 |
1 files changed, 204 insertions, 39 deletions
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index dc650bd9482..0ea1a80bc54 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,39 +1,145 @@ --- -stage: Create -group: Source Code +stage: Manage +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Badges **(FREE)** -Badges are a unified way to present condensed pieces of information about your -projects. They consist of a small image and a URL that the image -points to. Examples for badges can be the [pipeline status](../../ci/pipelines/settings.md#pipeline-status-badge), -[test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), [latest release](../../ci/pipelines/settings.md#latest-release-badge), or ways to contact the -project maintainers. +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 below the project description. +You can use badges at the [project](#project-badges) and [group](#group-badges) level.  +## Available badges + +GitLab provides the following pipeline badges: + +- [Pipeline status badge](#pipeline-status-badges) +- [Test coverage report badge](#test-coverage-report-badges) +- [Latest release badge](#latest-release-badges) + +GitLab also supports [custom badges](#customize-badges). + +## Pipeline status badges + +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: + +- `pending` +- `running` +- `passed` +- `failed` +- `skipped` +- `manual` +- `canceled` +- `unknown` + +You can access a pipeline status badge image by using the following link: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg +``` + +### Display only non-skipped status + +To make the pipeline status badge display only the last non-skipped status, use the `?ignore_skipped=true` query parameter: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ignore_skipped=true +``` + +## Test coverage report badges + +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: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg +``` + +You can define the regular expression for the [coverage report](../../ci/pipelines/settings.md#merge-request-test-coverage-results) +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: + +```markdown + +``` + +### Test coverage report badge colors and limits + +The default colors and limits for the badge are as follows: + +- 95 up to and including 100% - good (`#4c1`) +- 90 up to 95% - acceptable (`#a3c51c`) +- 75 up to 90% - medium (`#dfb317`) +- 0 up to 75% - low (`#e05d44`) +- no coverage - unknown (`#9f9f9f`) + +NOTE: +*Up to* means up to, but not including, the upper bound. + +You can overwrite the limits by using the following additional parameters ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28317) in GitLab 14.4): + +- `min_good` (default 95, can use any value between 3 and 100) +- `min_acceptable` (default 90, can use any value between 2 and min_good-1) +- `min_medium` (default 75, can use any value between 1 and min_acceptable-1) + +If an invalid boundary is set, GitLab automatically adjusts it to be valid. For example, +if `min_good` is set `80`, and `min_acceptable` is set to `85` (too high), GitLab automatically +sets `min_acceptable` to `79` (`min_good` - `1`). + +## Latest release badges + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33368) in GitLab 14.8. + +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: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/release.svg +``` + +By default, the badge fetches the release sorted using the [`released_at`](../../api/releases/index.md#create-a-release) +time with the `?order_by` query parameter. + +```plaintext +https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg?order_by=release_at +``` + ## Project badges 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](#group-badges). +### Add a badge to a project + To add a new badge to a project: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **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. Under **Link**, enter the URL that the badges should point to. +1. Under **Badge image URL**, enter the URL of the image that should be displayed. 1. Select **Add badge**. -After adding a badge to a project, you can see it in the list below the form. -You can edit the badge by selecting **Edit** (**{pencil}**) next to it or delete it by -selecting **Delete** (**{remove}**). +After adding a badge to a project, you can see the badge in the list below the form. -Badges associated with a group can only be edited or deleted on the -[group level](#group-badges). +### Edit or delete a project badge + +To edit a badge, select **Edit** (**{pencil}**). + +To delete a badge, select **Delete** (**{remove}**). ### Example project badge: Pipeline Status @@ -66,6 +172,8 @@ If you need individual badges for each project, either: - Add the badge at the [project level](#project-badges). - Use [placeholders](#placeholders). +### Add a badge to a group + To add a new badge to a group: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -76,33 +184,70 @@ To add a new badge to a group: 1. Select **Add badge**. After adding a badge to a group, you can see it in the list below the form. -You can edit the badge by selecting **Edit** (**{pencil}**) next to it or delete it by -selecting **Delete** (**{remove}**). -Badges directly associated with a project can be configured on the -[project level](#project-badges). +### Edit or delete a group badge -## Placeholders +To edit a badge, select **Edit** (**{pencil}**). -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: +To delete a badge, select **Delete** (**{remove}**). -- `%{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 -- `%{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 +Badges associated with a group can be edited or deleted only at the [group level](#group-badges). -NOTE: -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 is by design, as badges are intended to be used publicly. Avoid -using these placeholders if the information is sensitive. +## View the URL of pipeline badges + +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. + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **General pipelines**. +1. In the **Pipeline status**, **Coverage report**, or **Latest release** sections, view the URLs for the images. + + + +## Customize badges + +You can customize the following aspects of a badge: + +- Style +- Text +- Width +- Image + +### Customize badge style + +Pipeline badges can be rendered in different styles by adding the `style=style_name` parameter to the URL. Two styles are available: + +- Flat (default): + + ```plaintext + https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat + ``` + +  + +- Flat square ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30120) in GitLab 11.8): -## Use custom badge images + ```plaintext + https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square + ``` + +  + +### Customize badge text + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17555) in GitLab 13.1. + +The text for a badge can be customized to differentiate between multiple coverage jobs that run in the same pipeline. +Customize the badge text and width by adding the `key_text=custom_text` and `key_width=custom_key_width` parameters to the URL: + +```plaintext +https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130 +``` + + + +### Customize badge image Use custom badge images in a project or a group if you want to use badges other than the default ones. @@ -118,7 +263,7 @@ Using placeholders, here is an example badge image URL referring to a raw image https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg ``` -To add a new badge to a group or project with a custom image: +To add a new badge with a custom image to a group or project: 1. On the top bar, select **Main menu** and find your group or project. 1. On the left sidebar, select **Settings > General**. @@ -129,11 +274,31 @@ To add a new badge to a group or project with a custom image: displayed. 1. Select **Add badge**. -To learn how to use custom images generated via a pipeline, see our documentation on +To learn how to use custom images generated through a pipeline, see the documentation on [accessing the latest job artifacts by URL](../../ci/pipelines/job_artifacts.md#access-the-latest-job-artifacts). -## API +## Placeholders + +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 +- `%{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 + +NOTE: +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. + +## Configure badges through the API You can also configure badges via the GitLab API. As in the settings, there is -a distinction between endpoints for badges on the +a distinction between endpoints for badges at the [project level](../../api/project_badges.md) and [group level](../../api/group_badges.md). |