Skip to main content
Badges in GitLab offer a concise, visual way to display essential project metrics—such as build health and test coverage—directly in your repository. Each badge is a small image that links to a URL, and you can define them at either the project or group level. They appear right below your project description, keeping stakeholders informed at a glance.
The image shows a GitLab documentation page about badges, detailing their purpose and types, with a sidebar for navigation and a section on available badges.

​
Types of GitLab Badges

Use GitLab’s built-in badges or roll your own to surface the data your team cares about:
Badge TypeDescription
Pipeline statusShows the latest pipeline state (pending, running, passed, failed, etc.).
Test coverage reportDisplays the percentage of code covered by tests, based on your coverage job output.
Latest releaseIndicates your project’s most recent release version.
Custom badgeLet you specify any image URL and link for other metrics (e.g., security scan).
You can also adjust badge colors and styles to match your organization’s branding.
The image shows a GitLab documentation page about pipeline status badges, listing different badge statuses like pending, running, and passed. It includes navigation links on the left and a table of contents on the right.

​
Badge URL Example

If you prefer hosting your own SVG badges in the repository, reference them with a raw file URL: 
https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg
Hosting badges in your repo makes them versioned alongside your code. Just ensure the branch name and file path are correct.

​
Configuring Pipeline Status & Coverage Badges

  1. Navigate to Settings ➔ CI/CD in your project.
  2. Expand the General pipelines section.
  3. Scroll down to Pipeline status and Coverage report.
GitLab will automatically generate two badge URLs:
  • Pipeline status: Reflects the last pipeline’s outcome.
  • Coverage report: Shows the test coverage percentage only if a coverage job exists.
The image shows a GitLab CI/CD settings page with sections for pipeline status and coverage report, including dropdown menus and code snippets.
The coverage badge will appear only when your pipeline includes a job that outputs a coverage metric. Ensure you’ve configured a coverage: /regex/ in your job definition.
The image shows a GitLab pipeline interface for a NodeJS project, indicating a failed job with a code coverage of 86.48%.

​
Badge Formats & Customization

Badges support Markdown, HTML, and AsciiDoc embed formats. You can also target specific branches by appending ?ref=<branch> to the badge URL. Coverage badges change color based on percentage thresholds—up to five levels—which you can customize via URL parameters.
The image shows a GitLab CI/CD settings page with sections for coverage report and latest release, displaying HTML, Markdown, and AsciiDoc code snippets. The coverage report shows a coverage percentage of 86.48%.

​
Adding Badges to Your Project

To add badges under your project description:
  1. Go to Settings ➔ General.
  2. Find the Badges section and click Add badge.
  3. Complete the fields:
    • Name: A descriptive label (e.g., Pipeline Status).
    • Link URL: Destination when the badge is clicked.
    • Badge image URL: The SVG endpoint generated by GitLab.
  4. Click Add badge to save and preview.
The image shows a GitLab CI/CD settings page with sections for pipeline status and coverage report, displaying their respective statuses and code snippets for integration.

​
Example Configuration

  1. Pipeline Status
    • Name: Pipeline Status
    • Link: https://gitlab.example.com/<project_path>/pipelines
    • Image: Paste your pipeline status .svg URL.
  2. Code Coverage
    • Name: Code Coverage
    • Link: https://gitlab.example.com/<project_path>/pipelines
    • Image: Paste your coverage report .svg URL.
After saving, you’ll see a live preview. Confirm and you’re done!
The image shows a GitLab interface displaying project settings, including badges for pipeline status and code coverage report. The sidebar menu includes options like Code, Build, Secure, and Deploy.

​
Viewing Badges in Your Project

Return to your project’s main page. The badges now appear beneath the project description, instantly communicating your build health and code coverage to every visitor.
The image shows a GitLab repository interface for a project named "Solar System," displaying files, commit history, and project information such as branches and storage usage.

Watch Video

Practice Lab