debian-mirror-gitlab/doc/user/project/badges.md

138 lines
5.5 KiB
Markdown
Raw Normal View History

2020-10-24 23:57:45 +05:30
---
stage: Create
group: Source Code
2022-11-25 23:54:43 +05:30
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
2020-10-24 23:57:45 +05:30
---
2021-03-11 19:13:27 +05:30
# Badges **(FREE)**
2018-05-09 12:01:36 +05:30
Badges are a unified way to present condensed pieces of information about your
2021-01-03 14:25:43 +05:30
projects. They consist of a small image and a URL that the image
2020-04-22 19:07:51 +05:30
points to. Examples for badges can be the [pipeline status](../../ci/pipelines/settings.md#pipeline-status-badge),
2022-05-07 20:08:51 +05:30
[test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), [latest release](../../ci/pipelines/settings.md#latest-release-badge), or ways to contact the
2020-04-22 19:07:51 +05:30
project maintainers.
2018-05-09 12:01:36 +05:30
2021-09-04 01:27:46 +05:30
![Badges on Project information page](img/project_overview_badges_v13_10.png)
2018-05-09 12:01:36 +05:30
## Project badges
2021-04-17 20:07:23 +05:30
Badges can be added to a project by Maintainers or Owners, and are visible on the project's overview page.
2018-05-09 12:01:36 +05:30
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:
2022-10-11 01:57:18 +05:30
1. On the top bar, select **Main menu > Projects** and find your project.
2021-11-18 22:05:49 +05:30
1. On the left sidebar, select **Settings > General**.
1. Expand **Badges**.
2019-10-12 21:52:04 +05:30
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.
2021-11-18 22:05:49 +05:30
1. Select **Add badge**.
2018-05-09 12:01:36 +05:30
After adding a badge to a project, you can see it in the list below the form.
2021-11-18 22:05:49 +05:30
You can edit the badge by selecting **Edit** (**{pencil}**) next to it or delete it by
selecting **Delete** (**{remove}**).
2018-05-09 12:01:36 +05:30
Badges associated with a group can only be edited or deleted on the
[group level](#group-badges).
2020-10-24 23:57:45 +05:30
### Example project badge: Pipeline Status
A common project badge presents the GitLab CI pipeline status.
To add this badge to a project:
2022-10-11 01:57:18 +05:30
1. On the top bar, select **Main menu > Projects** and find your project.
2021-11-18 22:05:49 +05:30
1. On the left sidebar, select **Settings > General**.
1. Expand **Badges**.
2020-10-24 23:57:45 +05:30
1. Under **Name**, enter _Pipeline Status_.
1. Under **Link**, enter the following URL:
`https://gitlab.com/%{project_path}/-/commits/%{default_branch}`
1. Under **Badge image URL**, enter the following URL:
`https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg`
2021-11-18 22:05:49 +05:30
1. Select **Add badge**.
2020-10-24 23:57:45 +05:30
2018-05-09 12:01:36 +05:30
## Group badges
2021-12-11 22:18:48 +05:30
By adding a badge to a group, you add and enforce a project-level badge
for all projects in the group. The group badge is visible on the **Overview**
page of any project that belongs to 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:
- Add the badge at the [project level](#project-badges).
- Use [placeholders](#placeholders).
2018-05-09 12:01:36 +05:30
To add a new badge to a group:
2022-10-11 01:57:18 +05:30
1. On the top bar, select **Main menu > Groups** and find your group.
2021-11-18 22:05:49 +05:30
1. On the left sidebar, select **Settings > General**.
1. Expand **Badges**.
2019-10-12 21:52:04 +05:30
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.
2021-11-18 22:05:49 +05:30
1. Select **Add badge**.
2018-05-09 12:01:36 +05:30
After adding a badge to a group, you can see it in the list below the form.
2021-11-18 22:05:49 +05:30
You can edit the badge by selecting **Edit** (**{pencil}**) next to it or delete it by
selecting **Delete** (**{remove}**).
2018-05-09 12:01:36 +05:30
Badges directly associated with a project can be configured on the
[project level](#project-badges).
## Placeholders
2022-03-02 08:16:31 +05:30
Both the URL a badge points to and the image URL can contain placeholders
2021-04-17 20:07:23 +05:30
which are evaluated when displaying the badge. The following placeholders
2018-05-09 12:01:36 +05:30
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
2021-02-22 17:27:13 +05:30
NOTE:
2019-07-07 11:18:12 +05:30
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.
2021-09-04 01:27:46 +05:30
## Use custom badge images
Use custom badge images in a project or a group if you want to use badges other than the default
ones.
Prerequisites:
- A valid URL that points directly to the desired image for the badge.
If the image is located in a GitLab repository, use the raw link to the image.
Using placeholders, here is an example badge image URL referring to a raw image at the root of a repository:
```plaintext
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:
2022-10-11 01:57:18 +05:30
1. On the top bar, select **Main menu** and find your group or project.
2021-11-18 22:05:49 +05:30
1. On the left sidebar, select **Settings > General**.
2021-09-04 01:27:46 +05:30
1. Expand **Badges**.
1. Under **Name**, enter the name for the badge.
1. Under **Link**, enter the URL that the badge should point to.
1. Under **Badge image URL**, enter the URL that points directly to the custom image that should be
displayed.
1. Select **Add badge**.
To learn how to use custom images generated via a pipeline, see our documentation on
2023-01-13 00:05:48 +05:30
[accessing the latest job artifacts by URL](../../ci/pipelines/job_artifacts.md#access-the-latest-job-artifacts).
2021-09-04 01:27:46 +05:30
2018-05-09 12:01:36 +05:30
## 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).