- Placeholder tokens
- List all badges of a group
- Get a badge of a group
- Add a badge to a group
- Edit a badge of a group
- Remove a badge from a group
- Preview a badge from a group
Group badges API
Introduced 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:
- %{project_path}: will be replaced by the project path.
- %{project_id}: will be replaced by the project id.
- %{default_branch}: will be replaced by the project default branch.
- %{commit_sha}: will be replaced by the last project’s commit SHA.
Because these endpoints aren’t inside a project’s context, the information used to replace the placeholders will be from the first group’s project by creation date. If the group hasn’t got any project the original URL with the placeholders will be returned.
List all badges of a group
Gets a list of a group’s badges.
GET /groups/:id/badges
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the group owned by the authenticated user |
name
| string | no | Name of the badges to return (case-sensitive). |
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/badges?name=Coverage
Example response:
[
{
"name": "Coverage",
"id": 1,
"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",
"rendered_image_url": "https://shields.io/my/badge",
"kind": "group"
}
]
Get a badge of a group
Gets a badge of a group.
GET /groups/:id/badges/:badge_id
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the group owned by the authenticated user |
badge_id
| integer | yes | The badge ID |
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id
Example response:
{
"id": 1,
"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",
"rendered_image_url": "https://shields.io/my/badge",
"kind": "group"
}
Add a badge to a group
Adds a badge to a group.
POST /groups/:id/badges
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the group owned by the authenticated user |
link_url
| string | yes | URL of the badge link |
image_url
| string | yes | URL of the badge image |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/master&image_url=https://shields.io/my/badge1&position=0" https://gitlab.example.com/api/v4/groups/:id/badges
Example response:
{
"id": 1,
"link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master",
"image_url": "https://shields.io/my/badge1",
"rendered_link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master",
"rendered_image_url": "https://shields.io/my/badge1",
"kind": "group"
}
Edit a badge of a group
Updates a badge of a group.
PUT /groups/:id/badges/:badge_id
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the group owned by the authenticated user |
badge_id
| integer | yes | The badge ID |
link_url
| string | no | URL of the badge link |
image_url
| string | no | URL of the badge image |
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id
Example response:
{
"id": 1,
"link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master",
"image_url": "https://shields.io/my/badge",
"rendered_link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master",
"rendered_image_url": "https://shields.io/my/badge",
"kind": "group"
}
Remove a badge from a group
Removes a badge from a group.
DELETE /groups/:id/badges/:badge_id
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the group owned by the authenticated user |
badge_id
| integer | yes | The badge ID |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id
Preview a badge from a group
Returns how the link_url
and image_url
final URLs would be after resolving the placeholder interpolation.
GET /groups/:id/badges/render
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the group owned by the authenticated user |
link_url
| string | yes | URL of the badge link |
image_url
| string | yes | URL of the badge image |
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/badges/render?link_url=http%3A%2F%2Fexample.com%2Fci_status.svg%3Fproject%3D%25%7Bproject_path%7D%26ref%3D%25%7Bdefault_branch%7D&image_url=https%3A%2F%2Fshields.io%2Fmy%2Fbadge
Example response:
{
"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",
"rendered_image_url": "https://shields.io/my/badge",
}
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc