배지는 프로젝트에 대한 정보를 압축해 일관된 방식으로 보여 주는 수단입니다. 배지는 작은 이미지와 그 이미지가 가리키는 URL로 구성됩니다. GitLab에서 배지는 프로젝트 개요 페이지의 프로젝트 설명 아래에 표시됩니다. 배지는 프로젝트 수준과 그룹 수준에서 사용할 수 있습니다.

사용 가능한 배지#

GitLab은 다음 파이프라인 배지를 제공합니다:

• 파이프라인 상태 배지
• 테스트 커버리지 보고서 배지
• 최신 릴리스 배지

GitLab은 배지 스타일 조정도 지원합니다.

파이프라인 상태 배지#

파이프라인 상태 배지는 프로젝트에서 가장 최근에 실행된 파이프라인의 상태를 나타냅니다. 파이프라인 상태에 따라 배지는 다음 값 중 하나를 가집니다:

• pending
• running
• passed
• failed
• skipped
• manual
• canceled
• unknown

다음 링크로 파이프라인 상태 배지 이미지에 접근할 수 있습니다:

https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg

건너뛰지 않은 상태만 표시#

파이프라인 상태 배지가 건너뛰지 않은 마지막 상태만 표시하게 하려면 ?ignore_skipped=true 쿼리 매개변수를 사용합니다:

https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ignore_skipped=true

테스트 커버리지 보고서 배지#

테스트 커버리지 보고서 배지는 프로젝트에서 테스트된 코드의 비율을 나타냅니다. 이 값은 가장 최근에 성공한 파이프라인을 기준으로 계산됩니다.

다음 링크로 테스트 커버리지 보고서 배지 이미지에 접근할 수 있습니다:

https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg

각 job 로그와 대조할 코드 커버리지 정규 표현식을 정의할 수 있습니다. 즉, 파이프라인의 job 마다 테스트 커버리지 비율 값을 정의할 수 있습니다.

특정 job의 커버리지 보고서를 가져오려면 URL에 job=coverage_job_name 매개변수를 추가합니다. 예를 들어 coverage job의 테스트 커버리지 보고서 배지를 Markdown 파일에 추가하려면 다음과 같은 코드를 사용할 수 있습니다:

![coverage](https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?job=coverage)

테스트 커버리지 제한 및 배지 색상#

다음 표는 기본 테스트 커버리지 제한과 배지 색상을 보여 줍니다:

기본 제한 변경#

커버리지 보고서 배지 URL에 다음 쿼리 매개변수를 전달해 기본 제한을 재정의할 수 있습니다:

예를 들면 다음과 같습니다:

https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?min_good=98&min_acceptable=75

유효하지 않은 경계값을 설정하면 GitLab 이 자동으로 유효한 값으로 조정합니다. 예를 들어 min_good을 80, min_acceptable을 85로 설정하면, 최소 허용 값이 최소 좋음 값보다 클 수 없으므로 GitLab은 min_acceptable을 79(min_good - 1)로 설정합니다.

최신 릴리스 배지#

최신 릴리스 배지는 프로젝트의 최신 릴리스 태그 이름을 나타냅니다. 릴리스가 없으면 none을 표시합니다.

다음 링크로 최신 릴리스 배지 이미지에 접근할 수 있습니다:

https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg

기본적으로 배지는 ?order_by 쿼리 매개변수와 함께 released_at 시각으로 정렬한 릴리스를 가져옵니다.

https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg?order_by=release_at

value_width 매개변수로 릴리스 이름 필드의 너비를 변경할 수 있습니다. 값은 1에서 200 사이여야 하며 기본값은 54입니다. 범위를 벗어난 값을 설정하면 GitLab 이 자동으로 기본값으로 조정합니다.

프로젝트 배지#

배지는 Maintainer 또는 Owner가 프로젝트에 추가할 수 있으며, 프로젝트의 Overview 페이지에 표시됩니다. 같은 배지를 여러 프로젝트에 반복해서 추가해야 한다면 그룹 수준에서 추가하는 방법을 고려합니다.

프로젝트 배지 예: 파이프라인 상태#

많이 쓰이는 프로젝트 배지로 GitLab CI 파이프라인 상태 배지가 있습니다.

이 배지를 프로젝트에 추가하려면 다음과 같이 합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Badges를 확장합니다.
4. Name 아래에 Pipeline Status 를 입력합니다.
5. Link 아래에 다음 URL을 입력합니다: https://gitlab.example.com/%{project_path}/-/commits/%{default_branch}
6. Badge image URL 아래에 다음 URL을 입력합니다: https://gitlab.example.com/%{project_path}/badges/%{default_branch}/pipeline.svg
7. Add badge를 선택합니다.

그룹 배지#

배지는 Owner가 그룹에 추가할 수 있으며, 해당 그룹에 속한 모든 프로젝트의 Overview 페이지에 표시됩니다. 그룹에 배지를 추가하면 그룹 내 모든 프로젝트에 프로젝트 수준 배지를 추가하고 적용하게 됩니다.

프로젝트마다 개별 배지가 필요하다면 다음 중 하나를 사용합니다:

• 프로젝트 수준에서 배지를 추가합니다.
• 자리 표시자를 사용합니다.

배지 보기#

프로젝트나 그룹에서 사용할 수 있는 배지를 보려면 다음과 같이 합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트나 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Badges를 확장합니다.

배지 추가#

프로젝트나 그룹에 새 배지를 추가하려면 다음과 같이 합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트나 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Badges를 확장합니다.
4. Add badge를 선택합니다.
5. Name 텍스트 상자에 배지 이름을 입력합니다.
6. Link 텍스트 상자에 배지가 가리킬 URL을 입력합니다.
7. Badge image URL 텍스트 상자에 배지로 표시할 이미지의 URL을 입력합니다.
8. Add badge를 선택합니다.

파이프라인 배지의 URL 보기#

배지의 정확한 링크를 확인할 수 있습니다. 이 링크로 HTML 이나 Markdown 페이지에 배지를 넣을 수 있습니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. General pipelines를 확장합니다.
4. Pipeline status, Coverage report, Latest release 섹션에서 이미지 URL을 확인합니다.

배지 사용자 지정#

히스토리

• GitLab 18.5에서 custom_project_badges라는 기능 플래그와 함께 도입됨. 기본적으로 비활성화됨.
• GitLab 18.6에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에 활성화됨.
• GitLab 19.2에서 일반 제공됨. 기능 플래그 custom_project_badges 제거됨.

프로젝트에서 배지가 보이는 방식을 사용자 지정할 수 있습니다:

• 기본 사용자 지정은 모든 배지 유형에 적용됩니다.
• 고급 사용자 지정은 사용자 정의 배지에만 적용됩니다.

기본 사용자 지정#

모든 배지 유형에서 다음 항목을 사용자 지정할 수 있습니다:

• 스타일
• 키 텍스트
• 키 너비
• 값 너비

스타일#

파이프라인, 커버리지, 릴리스, 사용자 정의 배지는 URL에 style=style_name 매개변수를 추가해 서로 다른 스타일로 렌더링할 수 있습니다. 두 가지 스타일을 제공합니다:

• Flat(기본값):

  https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat
  

  

• Flat square:

  https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square
  

  

키 텍스트#

배지 왼쪽에 표시되는 텍스트를 사용자 지정할 수 있습니다. 예를 들어 같은 파이프라인에서 실행되는 여러 커버리지 job을 구분할 때 사용합니다.

URL에 key_text=custom_text 매개변수를 추가해 배지 키 텍스트를 사용자 지정합니다:

https://gitlab.example.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130

키 너비#

URL에 key_width=width 매개변수를 추가해 배지 키 너비를 사용자 지정합니다:

https://gitlab.example.com/%{project_path}/-/badges/coverage.svg?key_width=130

값 너비#

URL에 value_width=width 매개변수를 추가해 배지 값 너비를 사용자 지정합니다:

https://gitlab.example.com/%{project_path}/-/badges/coverage.svg?value_width=130

사용자 정의 배지#

사용자 정의 배지를 사용하면 배지 양쪽을 모두 직접 제어할 수 있습니다. 파이프라인 상태처럼 미리 정해진 정보를 보여 주는 표준 배지와 달리, 사용자 정의 배지에서는 다음을 할 수 있습니다:

• 배지 양쪽에 원하는 텍스트를 표시합니다
• 사용자 지정 색상을 사용합니다
• 프로젝트별 정보를 표시합니다
• 자리 표시자로 동적 배지를 만듭니다

사용자 정의 배지는 기본 사용자 지정 옵션에 더해 다음 옵션도 지원합니다:

• 키 색상
• 값 색상
• 값 텍스트

다음 링크로 사용자 정의 배지를 추가할 수 있습니다:

https://gitlab.example.com/%{project_path}/-/badges/custom.svg

예를 들어 자리 표시자로 최신 태그 배지를 만들 수 있습니다:

https://gitlab.example.com/%{project_path}/-/badges/custom.svg?key_text=Latest_tag&value_text=%{latest_tag}&key_color=white&value_color=7bc043

값 텍스트#

URL에 value_text=text 매개변수를 추가해 오른쪽에 표시되는 텍스트를 사용자 지정합니다:

https://gitlab.example.com/%{project_path}/-/badges/custom.svg?value_text=badge

값 색상#

URL에 value_color=color 매개변수를 추가해 오른쪽 배경색을 사용자 지정합니다:

색상은 다음 형식으로 전달할 수 있습니다:

• 이름이 있는 색상, 예를 들어 blue
• fff 나 7bc043 같은 16진수 표기(앞의 # 없이)

https://gitlab.example.com/%{project_path}/-/badges/custom.svg?value_color=red

키 색상#

URL에 value_color=color 매개변수를 추가해 왼쪽 배경색을 사용자 지정합니다:

색상은 다음 형식으로 전달할 수 있습니다:

• 이름이 있는 색상, 예를 들어 blue
• fff 나 7bc043 같은 16진수 표기(앞의 # 없이)

https://gitlab.example.com/%{project_path}/-/badges/custom.svg?key_color=green

사용자 정의 배지 이미지 추가#

사전 요구 사항:

• 프로젝트 또는 그룹에 대한 Developer, Maintainer, Owner 권한이 필요합니다.
• 배지로 사용할 이미지를 직접 가리키는 유효한 URL 이 필요합니다. 이미지가 GitLab 리포지터리에 있다면 이미지의 raw 링크를 사용합니다.

이미지가 있는 사용자 정의 배지를 추가하려면 다음과 같이 합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트나 그룹을 찾습니다.

2. 왼쪽 사이드바에서 Settings > General을 선택합니다.

3. Badges를 확장합니다.

4. Name 아래에 배지 이름을 입력합니다.

5. Link 아래에 배지가 가리킬 URL을 입력합니다.

6. Badge image URL 아래에 사용자 정의 이미지의 URL을 입력합니다. 예를 들어 리포지터리의 이미지를 사용하려면 다음과 같이 입력합니다:

   https://gitlab.example.com/<project_path>/-/raw/<default_branch>/custom-image.svg
   

7. Add badge를 선택합니다.

파이프라인으로 생성한 사용자 정의 이미지를 사용하려면 URL로 최신 job 아티팩트에 접근하기를 참고합니다.

배지 편집#

프로젝트나 그룹에서 배지를 편집하려면 다음과 같이 합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트나 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Badges를 확장합니다.
4. 편집할 배지 옆에서 Edit(✏️)를 선택합니다.
5. Name, Link, Badge image URL을 편집합니다.
6. Save changes를 선택합니다.

배지 삭제#

프로젝트나 그룹에서 배지를 삭제하려면 다음과 같이 합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트나 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Badges를 확장합니다.
4. 삭제할 배지 옆에서 Delete([remove])를 선택합니다.
5. 확인 대화 상자에서 Delete badge를 선택합니다.

자리 표시자#

배지가 가리키는 URL과 이미지 URL에는 자리 표시자를 넣을 수 있으며, 자리 표시자는 배지를 표시할 때 평가됩니다. 사용할 수 있는 자리 표시자는 다음과 같습니다:

• %{project_path}: 상위 그룹을 포함한 프로젝트 경로
• %{project_title}: 프로젝트 제목
• %{project_name}: 프로젝트 이름
• %{project_id}: 프로젝트에 연결된 데이터베이스(DB) ID
• %{project_namespace}: 프로젝트의 프로젝트 네임스페이스
• %{group_name}: 프로젝트의 그룹
• %{gitlab_server}: 프로젝트의 서버
• %{gitlab_pages_domain}: GitLab Pages를 호스팅하는 도메인
• %{default_branch}: 프로젝트 리포지터리에 구성된 기본 브랜치 이름
• %{commit_sha}: 프로젝트 리포지터리의 기본 브랜치에 있는 가장 최근 커밋의 ID
• %{latest_tag}: 프로젝트 리포지터리에 추가된 최신 태그