배지는 프로젝트에 대한 간결한 정보 조각을 통일된 방식으로 표시합니다. 배지는 작은 이미지와 이미지가 가리키는 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

각 작업 로그가 일치하는 코드 커버리지에 대한 정규식을 정의할 수 있습니다. 이는 파이프라인의 각 작업에 테스트 커버리지 백분율 값이 정의될 수 있음을 의미합니다.

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

![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 매개변수를 사용하여 릴리스 이름 필드의 너비를 변경할 수 있습니다(GitLab 15.10에서 도입됨). 값은 1에서 200 사이여야 하며 기본값은 54입니다. 범위를 벗어난 값을 설정하면 GitLab이 자동으로 기본값으로 조정합니다.

프로젝트 배지#

배지는 유지 관리자 또는 소유자가 프로젝트에 추가할 수 있으며 프로젝트의 개요 페이지에 표시됩니다. 여러 프로젝트에 동일한 배지를 추가해야 한다면 그룹 수준에서 추가하는 것이 좋습니다.

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

일반적인 프로젝트 배지는 GitLab CI 파이프라인 상태를 표시합니다.

프로젝트에 이 배지를 추가하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 설정 > 일반을 선택합니다.
3. 배지를 확장합니다.
4. 이름 아래에 Pipeline Status 를 입력합니다.
5. 링크 아래에 다음 URL을 입력합니다: https://gitlab.com/%{project_path}/-/commits/%{default_branch}
6. 배지 이미지 URL 아래에 다음 URL을 입력합니다: https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg
7. 배지 추가를 선택합니다.

그룹 배지#

배지는 소유자가 그룹에 추가할 수 있으며 그룹에 속한 모든 프로젝트의 개요 페이지에 표시됩니다. 그룹에 배지를 추가하면 그룹의 모든 프로젝트에 대해 프로젝트 수준 배지를 추가하고 적용합니다.

각 프로젝트에 대한 개별 배지가 필요한 경우 다음 중 하나를 수행합니다:

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

배지 보기#

프로젝트 또는 그룹에서 사용 가능한 배지를 보려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 왼쪽 사이드바에서 설정 > 일반을 선택합니다.
3. 배지를 확장합니다.

배지 추가#

프로젝트 또는 그룹에 새 배지를 추가하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 왼쪽 사이드바에서 설정 > 일반을 선택합니다.
3. 배지를 확장합니다.
4. 배지 추가를 선택합니다.
5. 이름 텍스트 상자에 배지의 이름을 입력합니다.
6. 링크 텍스트 상자에 배지가 가리킬 URL을 입력합니다.
7. 배지 이미지 URL 텍스트 상자에 배지에 표시할 이미지의 URL을 입력합니다.
8. 배지 추가를 선택합니다.

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

배지의 정확한 링크를 볼 수 있습니다. 그런 다음 링크를 사용하여 HTML 또는 Markdown 페이지에 배지를 삽입할 수 있습니다.

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 설정 > CI/CD를 선택합니다.
3. 일반 파이프라인을 확장합니다.
4. 파이프라인 상태, 커버리지 보고서, 최신 릴리스 섹션에서 이미지의 URL을 봅니다.

배지 사용자 지정#

히스토리

• Introduced in GitLab 18.5 with a flag named custom_project_badges. Disabled by default.
• Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.6.

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

• 기본 사용자 지정은 모든 배지 유형에서 작동합니다.
• 고급 사용자 지정은 사용자 정의 배지에서만 사용 가능합니다.

기본 사용자 지정#

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

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

스타일#

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

• 플랫(기본값):

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

  

• 플랫 정사각형:

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

  

키 텍스트#

배지 왼쪽의 텍스트를 사용자 지정할 수 있습니다. 예를 들어 동일한 파이프라인에서 실행되는 여러 커버리지 작업을 구분하기 위해 사용할 수 있습니다.

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

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

키 너비#

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

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

값 너비#

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

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

사용자 정의 배지#

사용자 정의 배지를 사용하면 배지의 양쪽을 완전히 제어할 수 있습니다. 파이프라인 상태와 같은 사전 정의된 정보를 표시하는 표준 배지와 달리 사용자 정의 배지를 사용하면 다음을 수행할 수 있습니다:

• 배지의 양쪽에 임의의 텍스트 표시
• 사용자 정의 색상 사용
• 프로젝트별 정보 표시
• 자리 표시자를 사용하여 동적 배지 만들기

기본 사용자 지정 옵션 외에도 사용자 정의 배지는 다음 추가 사용자 지정 옵션을 지원합니다:

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

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

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

예를 들어 자리 표시자를 사용하여 최신 태그의 배지를 만들 수 있습니다:

https://%{gitlab_server}/%{project_path}/badges/custom.svg?key_text=Latest_tag&key_value=%{latest_tag}&key_color=white&value_color=7bc043

값 텍스트#

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

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

값 색상#

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

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

• 명명된 색상, 예: blue
• fff 또는 7bc043과 같은 16진수 표현(# 없이)

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

키 색상#

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

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

• 명명된 색상, 예: blue
• fff 또는 7bc043과 같은 16진수 표현(# 없이)

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

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

사전 요구 사항:

• 프로젝트 또는 그룹에 대한 개발자, 유지 관리자 또는 소유자 역할이 있어야 합니다.
• 배지에 원하는 이미지를 직접 가리키는 유효한 URL이 있어야 합니다. 이미지가 GitLab 저장소에 있는 경우 이미지의 raw 링크를 사용합니다.

이미지가 있는 사용자 정의 배지를 추가하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.

2. 왼쪽 사이드바에서 설정 > 일반을 선택합니다.

3. 배지를 확장합니다.

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

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

6. 배지 이미지 URL 아래에 사용자 정의 이미지의 URL을 입력합니다. 예를 들어 저장소의 이미지를 사용하려면:

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

7. 배지 추가를 선택합니다.

파이프라인을 통해 생성된 사용자 정의 이미지를 사용하려면 URL로 최신 작업 아티팩트 액세스를 참조하세요.

배지 편집#

프로젝트 또는 그룹에서 배지를 편집하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 왼쪽 사이드바에서 설정 > 일반을 선택합니다.
3. 배지를 확장합니다.
4. 편집할 배지 옆에서 편집 (✏️)을 선택합니다.
5. 이름, 링크, 또는 배지 이미지 URL을 편집합니다.
6. 변경 사항 저장을 선택합니다.

배지 삭제#

프로젝트 또는 그룹에서 배지를 삭제하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 왼쪽 사이드바에서 설정 > 일반을 선택합니다.
3. 배지를 확장합니다.
4. 삭제할 배지 옆에서 삭제 ([remove])를 선택합니다.
5. 확인 대화 상자에서 배지 삭제를 선택합니다.

자리 표시자#

배지가 가리키는 URL과 이미지 URL 모두 자리 표시자를 포함할 수 있으며 배지를 표시할 때 평가됩니다. 다음 자리 표시자를 사용할 수 있습니다:

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