배지

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

배지는 프로젝트에 대한 간략한 정보를 제공하는 통일된 방식입니다. 배지는 작은 이미지와 해당 이미지를 가리키는 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 매개변수를 추가하세요. 예를 들어, 다음과 유사한 코드를 사용하여 coverage 작업의 테스트 커버리지 보고서 배지를 Markdown 파일에 추가할 수 있습니다: 

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

테스트 커버리지 보고서 배지 색상과 제한

배지의 기본 색상과 제한은 다음과 같습니다:

  • 95% 이상 100%까지 - 좋음(#4c1)
  • 90% 이상 95% 미만 - 적절함(#a3c51c)
  • 75% 이상 90% 미만 - 보통(#dfb317)
  • 0% 이상 75% 미만 - 낮음(#e05d44)
  • 커버리지 없음 - 알 수 없음(#9f9f9f)

이상은 상한선을 포함하지 않음을 의미합니다.

다음과 같은 추가 매개변수를 사용하여 제한을 덮어쓸 수 있습니다(GitLab 14.4에서 도입됨):

  • min_good (기본값 95, 3에서 100 사이의 값 사용 가능)
  • min_acceptable (기본값 90, 2에서 min_good-1 사이의 값 사용 가능)
  • min_medium (기본값 75, 1에서 min_acceptable-1 사이의 값 사용 가능)

잘못된 경계가 설정된 경우 GitLab은 자동으로 유효한 값으로 조정합니다. 예를 들어, min_good가 80으로 설정되고 min_acceptable가 너무 높아 85로 설정된 경우 GitLab은 자동으로 min_acceptable을 79(min_good - 1)로 설정합니다.

최신 릴리스 배지

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

다음 링크를 사용하여 최신 릴리스 배지 이미지에 액세스할 수 있습니다: 

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

기본적으로 배지는 released_at 시간을 사용하여 릴리스를 정렬하며 ?order_by 쿼리 매개변수를 사용합니다. 

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. 이름 아래에 _파이프라인 상태_를 입력합니다.
  5. 링크 아래에 다음 URL을 입력합니다: https://gitlab.com/%{project_path}/-/commits/%{default_branch}
  6. 배지 이미지 URL 아래에 다음 URL을 입력합니다: https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg
  7. 배지 추가를 선택합니다.

그룹 배지

그룹에 배지를 추가하면 그룹에 속한 모든 프로젝트에 대해 프로젝트 수준 배지가 추가 및 적용됩니다. 그룹 배지는 그룹에 속하는 모든 프로젝트의 개요 페이지에 표시됩니다.

note
이러한 배지는 코드베이스에서 프로젝트 수준 배지로 표시되지만 프로젝트 수준에서 수정하거나 삭제할 수 없습니다.

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

뱃지 보기

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

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

뱃지 추가

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

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

파이프라인 뱃지의 URL 보기

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

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

파이프라인 뱃지

뱃지 사용자 정의

다음과 같은 뱃지의 다양한 측면을 사용자 정의할 수 있습니다:

  • 스타일
  • 텍스트
  • 너비
  • 이미지

뱃지 스타일 사용자 정의

파이프라인 뱃지는 URL에 style=style_name 매개변수를 추가하여 다양한 스타일로 렌더링될 수 있습니다. 두 가지 스타일을 사용할 수 있습니다:

  • Flat (기본값): 

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

    플랫 스타일 뱃지

  • Flat square (GitLab 11.8에서 도입됨): 

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

    플랫 스퀘어 스타일 뱃지

뱃지 텍스트 사용자 정의

뱃지의 텍스트는 동일한 파이프라인에서 실행되는 여러 커버리지 작업을 구분하기 위해 사용자 정의할 수 있습니다. URL에 key_text=custom_text 및 key_width=custom_key_width 매개변수를 추가하여 뱃지 텍스트와 너비를 사용자 정의합니다: 

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

사용자 정의 텍스트와 너비가 있는 뱃지

뱃지 이미지 사용자 정의

기본값이 아닌 뱃지를 사용하고 싶다면 프로젝트나 그룹에서 사용자 정의 뱃지 이미지를 사용할 수 있습니다.

전제 조건:

  • 뱃지에 표시할 원하는 이미지로 직접 가리키는 유효한 URL. 이미지가 GitLab 리포지터리에 있는 경우 이미지의 원시 링크를 사용합니다.

플레이스홀더를 사용하여 다음은 리포지터리 루트에 있는 원시 이미지를 가리키는 예제 뱃지 이미지 URL입니다: 

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

그룹이나 프로젝트에 사용자 정의 이미지가 있는 새로운 뱃지를 추가하려면:

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

파이프라인을 통해 생성된 사용자 정의 이미지를 사용하는 방법에 대해 알아보려면 URL을 통한 최신 작업 아티팩트에 액세스하는 방법 문서를 참조하세요.

뱃지 편집

프로젝트나 그룹에서 뱃지를 편집하려면:

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

뱃지 삭제

프로젝트나 그룹에서 뱃지를 삭제하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트 또는 그룹을 찾습니다.
  2. 설정 > 일반을 선택합니다.
  3. 뱃지를 확장합니다.
  4. 삭제하려는 뱃지 옆에서 삭제를 선택합니다 ().
  5. 확인 대화 상자에서 뱃지 삭제를 선택합니다.
  6. 변경 사항 저장을 선택합니다.
note
그룹과 연관된 뱃지는 그룹 수준에서만 편집하거나 삭제할 수 있습니다.

플레이스홀더

뱃지가 가리키는 URL과 이미지 URL에는 플레이스홀더를 포함할 수 있습니다. 뱃지를 표시할 때 평가하는 플레이스홀더는 다음과 같습니다:

  • %{project_path}: 상위 그룹을 포함한 프로젝트의 경로
  • %{project_title}: 프로젝트의 제목
  • %{project_name}: 프로젝트의 이름
  • %{project_id}: 프로젝트에 연결된 데이터베이스 ID
  • %{default_branch}: 프로젝트 리포지터리의 기본 브랜치 이름
  • %{commit_sha}: 프로젝트 리포지터리의 기본 브랜치에서 가장 최근의 커밋 ID
note
플레이스홀더를 사용하면 프로젝트의 리포지터리를 비공개로 구성한 경우와 같이 뱃지가 그렇지 않게 공개적으로 사용되어야 하는 경우 기본 브랜치나 커밋 SHA와 같은 프라이빗 정보를 노출할 수 있습니다. 이 동작은 뱃지가 공개적으로 사용되어야 한다는 취지에 일치하며, 민감한 정보인 경우 이러한 플레이스홀더를 사용하지 않도록 합니다.