Project 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.
List all badges of a project
Gets a list of a project’s badges and its group badges.
GET /projects/:id/badges| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | yes | The ID or URL-encoded path of the project |
name | string | no | Name of the badges to return (case-sensitive). |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/: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=main",
"rendered_image_url": "https://shields.io/my/badge",
"kind": "project"
},
{
"name": "Pipeline",
"id": 2,
"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 project
Gets a badge of a project.
GET /projects/:id/badges/:badge_id| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | yes | The ID or URL-encoded path of the project |
badge_id | integer | yes | The badge ID |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/badges/:badge_id"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=main",
"rendered_image_url": "https://shields.io/my/badge",
"kind": "project"
}Add a badge to a project
Adds a badge to a project.
POST /projects/:id/badges| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | yes | The ID or URL-encoded path of the project |
link_url | string | yes | URL of the badge link |
image_url | string | yes | URL of the badge image |
name | string | no | Name of the badge |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/main&image_url=https://shields.io/my/badge1&name=mybadge" \
"https://gitlab.example.com/api/v4/projects/:id/badges"Example response:
{
"id": 1,
"name": "mybadge",
"link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/main",
"image_url": "https://shields.io/my/badge1",
"rendered_link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/main",
"rendered_image_url": "https://shields.io/my/badge1",
"kind": "project"
}Edit a badge of a project
Updates a badge of a project.
PUT /projects/:id/badges/:badge_id| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | yes | The ID or URL-encoded path of the project |
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 |
name | string | no | Name of the badge |
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/badges/:badge_id"Example response:
{
"id": 1,
"name": "mybadge",
"link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/main",
"image_url": "https://shields.io/my/badge",
"rendered_link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/main",
"rendered_image_url": "https://shields.io/my/badge",
"kind": "project"
}Remove a badge from a project
Removes a badge from a project. Only project badges are removed by using this endpoint.
DELETE /projects/:id/badges/:badge_id| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | yes | The ID or URL-encoded path of the project |
badge_id | integer | yes | The badge ID |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/badges/:badge_id"Preview a badge from a project
Returns how the link_url and image_url final URLs would be after resolving the placeholder interpolation.
GET /projects/:id/badges/render| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | yes | The ID or URL-encoded path of the project |
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/projects/: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=main",
"rendered_image_url": "https://shields.io/my/badge"
}Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support