Group badges API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Placeholder tokens

Badges support placeholders that are replaced in real time in both the link and image URL. The allowed placeholders are:

  • %{project_path}: replaced by the project path.
  • %{project_title}: replaced by the project title.
  • %{project_name}: replaced by the project name.
  • %{project_id}: replaced by the project ID.
  • %{project_namespace}: replaced by the project’s namespace full path.
  • %{group_name}: replaced by the project’s top-level group name.
  • %{gitlab_server}: replaced by the project’s server name.
  • %{gitlab_pages_domain}: replaced by the domain name hosting GitLab Pages.
  • %{default_branch}: replaced by the project default branch.
  • %{commit_sha}: replaced by the project’s last commit SHA.
  • %{latest_tag}: replaced by the project’s last tag.

Because these endpoints aren’t inside a project’s context, the information used to replace the placeholders comes from the first group’s project by creation date. If the group hasn’t got any project the original URL with the placeholders is returned.

List all badges of a group

Gets a list of a group’s badges.

Copy to clipboard
GET /groups/:id/badges
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
namestringnoName of the badges to return (case-sensitive).
Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/badges?name=Coverage"

Example response:

Copy to clipboard
[
  {
    "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=main",
    "rendered_image_url": "https://shields.io/my/badge",
    "kind": "group"
  }
]

Get a badge of a group

Gets a badge of a group.

Copy to clipboard
GET /groups/:id/badges/:badge_id
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
badge_idintegeryesThe badge ID
Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id"

Example response:

Copy to clipboard
{
  "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=main",
  "rendered_image_url": "https://shields.io/my/badge",
  "kind": "group"
}

Add a badge to a group

Adds a badge to a group.

Copy to clipboard
POST /groups/:id/badges
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
link_urlstringyesURL of the badge link
image_urlstringyesURL of the badge image
namestringnoName of the badge
Copy to clipboard
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&name=mybadge&position=0" \
     "https://gitlab.example.com/api/v4/groups/:id/badges"

Example response:

Copy to clipboard
{
  "id": 1,
  "name": "mybadge",
  "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.

Copy to clipboard
PUT /groups/:id/badges/:badge_id
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
badge_idintegeryesThe badge ID
link_urlstringnoURL of the badge link
image_urlstringnoURL of the badge image
namestringnoName of the badge
Copy to clipboard
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id"

Example response:

Copy to clipboard
{
  "id": 1,
  "name": "mybadge",
  "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.

Copy to clipboard
DELETE /groups/:id/badges/:badge_id
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
badge_idintegeryesThe badge ID
Copy to clipboard
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.

Copy to clipboard
GET /groups/:id/badges/render
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
link_urlstringyesURL of the badge link
image_urlstringyesURL of the badge image
Copy to clipboard
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:

Copy to clipboard
{
  "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=main",
  "rendered_image_url": "https://shields.io/my/badge"
}