뱃지

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 매개변수를 추가하세요. 예를 들어, Markdown 파일에 coverage 작업의 테스트 커버리지 보고서 뱃지를 추가하려면 다음과 같은 코드를 사용할 수 있습니다: 

![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)

*이상을 의미하는 것은 상한선을 포함하지 않고 그 이하를 의미합니다.

다음과 같은 추가 매개변수를 사용하여 제한을 덮어쓸 수 있습니다:

  • 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은 자동으로 기본값으로 조정합니다.

프로젝트 뱃지

유지자(Maintainer) 또는 소유자(Owner)가 프로젝트에 뱃지를 추가하고 프로젝트의 개요 페이지에서 그 뱃지를 볼 수 있습니다. 만약 여러 프로젝트에 동일한 뱃지를 추가해야 한다면, 그룹 레벨에서 그 뱃지를 추가할 수 있습니다.

프로젝트 뱃지 예시: 파이프라인 상태

일반적으로 프로젝트 뱃지는 GitLab CI 파이프라인 상태를 나타냅니다.

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 일반을 선택합니다.
  3. 뱃지를 확장합니다.
  4. 이름 아래에 _파이프라인 상태_를 입력합니다.
  5. 링크 아래에 다음 URL을 입력합니다: https://gitlab.com/%{project_path}/-/pipelines/%{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: 

    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와 같은 정보를 노출시킬 수 있습니다. 이러한 동작은 의도적이며, 배지는 공개적으로 사용되도록 의도되었습니다. 정보가 민감한 경우 이러한 플레이스홀더를 사용하지 마십시오.