Code Quality

Code Quality는 유지보수성 문제가 기술 부채가 되기 전에 찾아내는 기능이에요. 코드 리뷰 중에 자동 피드백이 제공되면 팀이 더 나은 코드를 작성할 수 있도록 도와줍니다. 발견 사항이 MR에 직접 표시되어, 가장 비용 효율적으로 고칠 수 있는 때에 문제가 보이게 됩니다.

출처: 문서

본문

티어(Tier): Free, Premium, Ultimate
제공 방식(Offering): GitLab.com, GitLab Self-Managed, GitLab Dedicated

Code Quality는 여러 프로그래밍 언어와 함께 동작하며, 흔한 린터(linter), 스타일 검사기, 복잡도 분석기와 통합돼요. 기존 도구를 Code Quality 워크플로에 연결해, 결과가 표시되는 방식을 표준화하면서 팀의 선호도는 그대로 유지할 수 있습니다.

티어별 기능

GitLab 티어에 따라 사용할 수 있는 기능이 달라요. 다음 표를 참고하세요:

기능	Free	Premium	Ultimate
CI/CD job에서 Code Quality 결과 가져오기	✓	✓	✓
CodeClimate 기반 스캐닝 사용하기	✓	✓	✓
MR 리포트에서 발견 사항 보기	✓	✓	✓
파이프라인 리포트에서 발견 사항 보기	No	✓	✓
MR 변경 보기에서 발견 사항 보기	No	No	✓
프로젝트 품질 요약 뷰에서 전반적 상태 분석	No	No	✓

품질 위반을 위한 코드 스캔

Code Quality는 많은 스캐닝 도구의 결과를 가져올 수 있는 개방형 시스템이에요. 위반 사항을 찾아 표면화하려면 다음 중 하나를 할 수 있어요:

스캐닝 도구를 직접 사용하고 그 결과를 가져옵니다. (권장.)
내장 CI/CD 템플릿을 사용해 스캐닝을 활성화해요. 이 템플릿은 공개 오픈소스 도구를 감싸는 CodeClimate 엔진을 사용해요. (더 이상 사용하지 않음.)

단일 파이프라인에서 여러 도구의 결과를 담을 수 있어요. 예를 들어 코드 린터로 코드를 스캔하면서 언어 린터로 문서를 스캔하거나, 독립 도구를 CodeClimate 기반 스캐닝과 함께 사용할 수 있어요. Code Quality는 모든 리포트를 결합해서, 결과를 볼 때 모두 확인할 수 있습니다.

CI/CD job에서 Code Quality 결과 가져오기

많은 개발 팀이 이미 CI/CD 파이프라인에서 린터, 스타일 검사기, 기타 도구로 코딩 표준 위반을 자동 감지하고 있어요. 이 도구들의 발견 사항을 Code Quality와 통합하면 더 쉽게 보고 고칠 수 있습니다.

도구에 이미 문서화된 통합이 있는지 보려면 Code Quality와 공통 도구 통합하기를 참고하세요.

다른 도구를 Code Quality와 통합하려면:

도구를 CI/CD 파이프라인에 추가해요.
도구가 리포트를 파일로 출력하도록 구성해요. - 이 파일은 특정 JSON 형식을 사용해야 해요. - 많은 도구가 이 출력 형식을 기본 지원해요. "CodeClimate report", "GitLab Code Quality report" 등 여러 이름으로 부를 수 있어요. - 일부 도구는 사용자 지정 JSON 형식이나 템플릿으로 JSON 출력을 만들 수 있어요. 리포트 형식에 필수 필드가 몇 개 없으므로, 이런 출력 유형도 Code Quality 리포트로 동작할 수 있습니다.
이 파일과 일치하는 codequality 리포트 아티팩트를 선언해요.

이제 파이프라인이 실행된 후 품질 도구의 결과가 처리되고 표시됩니다.

내장 Code Quality CI/CD 템플릿 사용하기 (더 이상 사용하지 않음)

이 기능은 GitLab 17.3에서 더 이상 사용하지 않기로 결정되었고 19.0에서 제거될 예정이에요. 대신 지원되는 도구의 결과를 직접 통합하세요.

Code Quality에는 Code-Quality.gitlab-ci.yaml이라는 내장 CI/CD 템플릿도 포함돼 있어요. 이 템플릿은 오픈소스 CodeClimate 스캐닝 엔진에 기반한 스캔을 실행해요.

CodeClimate 엔진은 다음을 실행해요:

지원 언어 집합에 대한 기본 유지보수성 검사.
오픈소스 스캐너를 감싸는 구성 가능한 플러그인 집합으로 소스 코드를 분석.

자세한 내용은 CodeClimate 기반 Code Quality 스캐닝 구성하기를 참고하세요.

CodeClimate 기반 스캐닝에서 마이그레이션하기

CodeClimate 엔진은 구성 가능한 분석 플러그인 집합을 사용해요. 일부는 기본 활성화되고, 다른 것들은 명시적으로 활성화해야 합니다. 내장 플러그인을 대체할 수 있는 통합은 다음과 같아요:

플러그인	기본 활성화	대체
Duplication	✓	PMD Copy/Paste Detector 통합.
ESLint	✓	ESLint 통합.
gofmt	No	golangci-lint 통합 및 gofmt linter 활성화.
golint	No	golangci-lint 통합 및 golint를 대체하는 포함 린터 중 하나 활성화. golint는 더 이상 사용되지 않고 동결되었어요.
govet	No	golangci-lint 통합. golangci-lint는 govet를 기본 포함해요.
markdownlint	No (커뮤니티 지원)	markdownlint-cli2 통합.
pep8	No	Flake8, Pylint, Ruff 같은 대체 Python 린터 통합.
RuboCop	✓	RuboCop 통합.
SonarPython	No	Flake8, Pylint, Ruff 같은 대체 Python 린터 통합.
Stylelint	No (커뮤니티 지원)	Stylelint 통합.
SwiftLint	No	SwiftLint 통합.

Code Quality 결과 보기

Code Quality 결과는 다음 위치에 표시돼요:

MR 리포트

Code Quality 분석 결과는 MR의 Reports 탭에 표시돼요. 동일한 지문(fingerprint)을 가진 여러 발견 사항은 단일 항목으로 표시됩니다.

자세한 내용은 MR 리포트를 참고하세요.

MR 변경 뷰

티어(Tier): Ultimate
제공 방식(Offering): GitLab.com, GitLab Self-Managed, GitLab Dedicated

Code Quality 결과는 MR의 Changes 뷰에도 표시돼요. Code Quality 문제가 있는 라인은 가터(gutter) 옆에 기호로 표시됩니다. 기호를 선택하면 문제 목록이 보이고, 문제를 선택하면 세부 정보를 볼 수 있어요.

파이프라인 세부 정보 뷰

티어(Tier): Premium, Ultimate
제공 방식(Offering): GitLab.com, GitLab Self-Managed, GitLab Dedicated

파이프라인 세부 정보 페이지의 Code Quality 탭에는 파이프라인이 생성한 Code Quality 위반의 전체 목록이 표시돼요. 파이프라인 세부 정보 뷰는 실행된 브랜치에서 발견된 모든 Code Quality 발견 사항을 보여줍니다.

프로젝트 품질 뷰

티어(Tier): Ultimate
제공 방식(Offering): GitLab.com, GitLab Self-Managed
상태(Status): Beta

변경 이력

GitLab 14.5에서 도입, 기능 플래그 이름은 project_quality_summary_page. 이 기능은 베타 단계예요. 기본적으로 비활성화.

프로젝트 품질 뷰는 Code Quality 발견 사항의 개요를 표시해요. 이 뷰는 Analyze > CI/CD analytics에서 찾을 수 있고, 이 특정 프로젝트에 대해 project_quality_summary_page 기능 플래그가 활성화되어 있어야 해요.

Code Quality 리포트 형식

다음 형식으로 리포트를 출력할 수 있는 어떤 도구에서든 Code Quality 결과를 가져올 수 있어요. 이 형식은 CodeClimate 리포트 형식의 변형으로, 더 적은 수의 필드를 갖습니다.

Code Quality 리포트 아티팩트로 제공하는 파일은 단일 JSON 배열을 담아야 해요. 배열의 각 객체는 최소한 다음 속성을 가져야 합니다:

이름	유형	설명
`description`	String	코드 품질 위반에 대한 사람이 읽을 수 있는 설명.
`check_name`	String	이 위반과 관련된 검사(체크)나 규칙을 나타내는 고유 이름.
`fingerprint`	String	콘텐츠 해시 같은, 이 특정 코드 품질 위반을 식별하는 고유 지문.
`location.path`	String	코드 품질 위반이 있는 파일. 리포지토리 기준 상대 경로로 표현. `./`로 시작하지 마세요.
`location.lines.begin` 또는 `location.positions.begin.line`	Integer	코드 품질 위반이 발생한 라인.
`severity`	String	위반 심각도. `info`, `minor`, `major`, `critical`, `blocker` 중 하나.

이 형식은 CodeClimate 리포트 형식과 다음과 같이 달라요:

CodeClimate 리포트 형식은 더 많은 속성을 지원하지만, Code Quality는 앞서 나열한 필드만 처리해요.
GitLab 파서는 파일 시작 부분에 바이트 순서 표시(BOM)를 허용하지 않아요. 일부 도구, 특히 Windows나 .NET 환경에서 시작된 도구는 출력에 기본으로 UTF-8 BOM을 추가합니다. UTF-8 BOM을 확인하고 제거하려면 다음을 실행하세요: [ "$(head -c3 report.json | od -An -tx1 | tr -d ' \n')" = "efbbbf" ] && { sed -i.bak '1s/^\xEF\xBB\xBF//' report.json && echo "BOM removed" || echo "BOM detected but removal failed" } || echo "No BOM found, nothing changed"

예를 들어 다음은 규격에 맞는 리포트예요:

[
  {
    "description": "'unused' is assigned a value but never used.",
    "check_name": "no-unused-vars",
    "fingerprint": "7815696ecbf1c96e6894b779456d330e",
    "severity": "minor",
    "location": {
      "path": "lib/index.js",
      "lines": {
        "begin": 42
      }
    }
  }
]

Code Quality와 공통 도구 통합하기

많은 도구가 필요한 리포트 형식을 기본 지원해서 결과를 Code Quality와 통합할 수 있어요. "CodeClimate report", "GitLab Code Quality report" 등 여러 이름으로 부를 수 있습니다.

다른 도구는 사용자 지정 템플릿이나 형식 지정으로 JSON 출력을 만들도록 구성할 수 있어요. 리포트 형식에 필수 필드가 몇 개 없으므로, 이런 출력 유형도 Code Quality 리포트로 동작할 수 있습니다.

이미 CI/CD 파이프라인에서 도구를 사용한다면, 기존 job에 Code Quality 리포트를 추가하도록 적응시켜야 해요. 기존 job을 적응시키면 개발자를 혼란스럽게 하고 파이프라인 실행 시간을 늘릴 수 있는 별도 job을 실행하지 않게 됩니다.

도구를 아직 사용하지 않는다면 CI/CD job을 처음부터 작성하거나 CI/CD 카탈로그의 컴포넌트로 도구를 채택할 수 있어요.

코드 스캐닝 도구

ESLint

이미 CI/CD 파이프라인에 ESLint job이 있다면, 그 출력을 Code Quality로 보내는 리포트를 추가해야 해요.

출력을 통합하려면:

프로젝트의 개발 의존성으로 eslint-formatter-gitlab을 추가해요.
ESLint를 실행하는 명령에 --format gitlab 옵션을 추가해요.
리포트 파일 위치를 가리키는 codequality 리포트 아티팩트를 선언해요. - 기본적으로 포매터는 CI/CD 구성을 읽고 리포트를 저장할 파일명을 추론해요. 아티팩트 선언에 사용한 파일명을 포매터가 추론하지 못하면 CI/CD 변수 ESLINT_CODE_QUALITY_REPORT를 아티팩트에 지정한 파일명(예: gl-code-quality-report.json)으로 설정하세요.

ESLint CI/CD 컴포넌트를 사용하거나 적응시켜 스캔을 실행하고 출력을 Code Quality와 통합할 수도 있어요.

Stylelint

이미 CI/CD 파이프라인에 Stylelint job이 있다면, 그 출력을 Code Quality로 보내는 리포트를 추가해야 해요.

출력을 통합하려면:

프로젝트의 개발 의존성으로 @studiometa/stylelint-formatter-gitlab을 추가해요.
Stylelint를 실행하는 명령에 --custom-formatter=@studiometa/stylelint-formatter-gitlab 옵션을 추가해요.
리포트 파일 위치를 가리키는 codequality 리포트 아티팩트를 선언해요. - 기본적으로 포매터는 CI/CD 구성을 읽고 리포트를 저장할 파일명을 추론해요. 아티팩트 선언에 사용한 파일명을 포매터가 추론하지 못하면 CI/CD 변수 STYLELINT_CODE_QUALITY_REPORT를 아티팩트에 지정한 파일명(예: gl-code-quality-report.json)으로 설정하세요.

자세한 내용과 예시 CI/CD job 정의는 @studiometa/stylelint-formatter-gitlab 문서를 참고하세요.

MyPy

이미 CI/CD 파이프라인에 MyPy job이 있다면, 그 출력을 Code Quality로 보내는 리포트를 추가해야 해요.

출력을 통합하려면:

mypy-gitlab-code-quality를 프로젝트 의존성으로 설치해요.
mypy 명령이 출력을 파일로 보내도록 변경해요.
mypy-gitlab-code-quality로 파일을 필요한 형식으로 다시 처리하는 단계를 job script에 추가해요. 예를 들어: - mypy $(find -type f -name "*.py" ! -path "**/.venv/**") --no-error-summary > mypy-out.txt || true # "|| true" is used for preventing job failure when mypy find errors - mypy-gitlab-code-quality < mypy-out.txt > gl-code-quality-report.json
리포트 파일 위치를 가리키는 codequality 리포트 아티팩트를 선언해요.

MyPy CI/CD 컴포넌트를 사용하거나 적응시켜 스캔을 실행하고 출력을 Code Quality와 통합할 수도 있어요.

Flake8

이미 CI/CD 파이프라인에 Flake8 job이 있다면, 그 출력을 Code Quality로 보내는 리포트를 추가해야 해요.

출력을 통합하려면:

flake8-gl-codeclimate을 프로젝트 의존성으로 설치해요.
Flake8을 실행하는 명령에 --format gl-codeclimate --output-file gl-code-quality-report.json 인자를 추가해요.
리포트 파일 위치를 가리키는 codequality 리포트 아티팩트를 선언해요.

Flake8 CI/CD 컴포넌트를 사용하거나 적응시켜 스캔을 실행하고 출력을 Code Quality와 통합할 수도 있어요.

Pylint

이미 CI/CD 파이프라인에 Pylint job이 있다면, 그 출력을 Code Quality로 보내는 리포트를 추가해야 해요.

출력을 통합하려면:

pylint-gitlab을 프로젝트 의존성으로 설치해요.
Pylint를 실행하는 명령에 --output-format=pylint_gitlab.GitlabCodeClimateReporter 인자를 추가해요.
pylint 명령이 출력을 파일로 보내도록 변경해요.
리포트 파일 위치를 가리키는 codequality 리포트 아티팩트를 선언해요.

Pylint CI/CD 컴포넌트를 사용하거나 적응시켜 스캔을 실행하고 출력을 Code Quality와 통합할 수도 있어요.

Ruff

이미 CI/CD 파이프라인에 Ruff job이 있다면, 그 출력을 Code Quality로 보내는 리포트를 추가해야 해요.

출력을 통합하려면:

Ruff를 실행하는 명령에 --output-format=gitlab 인자를 추가해요.
ruff check 명령이 출력을 파일로 보내도록 변경해요.
리포트 파일 위치를 가리키는 codequality 리포트 아티팩트를 선언해요.

문서화된 Ruff GitLab CI/CD 통합을 사용하거나 적응시켜 스캔을 실행하고 출력을 Code Quality와 통합할 수도 있어요.

golangci-lint

이미 CI/CD 파이프라인에 golangci-lint job이 있다면, 그 출력을 Code Quality로 보내는 리포트를 추가해야 해요.

출력을 통합하려면:

golangci-lint를 실행하는 명령에 인자를 추가해요. - v1이라면 --out-format code-climate:gl-code-quality-report.json,line-number를 추가. - v2라면 --output.code-climate.path=gl-code-quality-report.json을 추가.
리포트 파일 위치를 가리키는 codequality 리포트 아티팩트를 선언해요.

golangci-lint CI/CD 컴포넌트를 사용하거나 적응시켜 스캔을 실행하고 출력을 Code Quality와 통합할 수도 있어요.

PMD Copy/Paste Detector

PMD Copy/Paste Detector (CPD)는 기본 출력이 필요한 형식을 따르지 않으므로 추가 구성이 필요해요.

PMD CI/CD 컴포넌트를 사용하거나 적응시켜 스캔을 실행하고 출력을 Code Quality와 통합할 수 있어요.

SwiftLint

SwiftLint는 기본 출력이 필요한 형식을 따르지 않으므로 추가 구성이 필요해요.

SwiftLint CI/CD 컴포넌트를 사용하거나 적응시켜 스캔을 실행하고 출력을 Code Quality와 통합할 수 있어요.

RuboCop

RuboCop은 기본 출력이 필요한 형식을 따르지 않으므로 추가 구성이 필요해요.

RuboCop CI/CD 컴포넌트를 사용하거나 적응시켜 스캔을 실행하고 출력을 Code Quality와 통합할 수 있어요.

Roslynator

Roslynator는 기본 출력이 필요한 형식을 따르지 않으므로 추가 구성이 필요해요.

Roslynator CI/CD 컴포넌트를 사용하거나 적응시켜 스캔을 실행하고 출력을 Code Quality와 통합할 수 있어요.

문서 스캐닝 도구

Code Quality로 리포지토리에 저장된 어떤 파일이든, 코드가 아니어도 스캔할 수 있어요.

Vale

이미 CI/CD 파이프라인에 Vale job이 있다면, 그 출력을 Code Quality로 보내는 리포트를 추가해야 해요.

출력을 통합하려면:

필요한 형식을 정의하는 Vale 템플릿 파일을 리포지토리에 만들어요. - GitLab 문서를 검사하는 데 쓰는 오픈소스 템플릿을 복사할 수 있어요. - 커뮤니티 gitlab-ci-utils Vale 프로젝트에서 쓰는 것 같은 다른 오픈소스 변형도 사용할 수 있어요. 이 커뮤니티 프로젝트는 같은 템플릿을 포함한 미리 만들어진 컨테이너 이미지도 제공해서 파이프라인에서 바로 사용할 수 있어요.
Vale을 실행하는 명령에 --output="$VALE_TEMPLATE_PATH" --no-exit 인자를 추가해요.
vale 명령이 출력을 파일로 보내도록 변경해요.
리포트 파일 위치를 가리키는 codequality 리포트 아티팩트를 선언해요.

오픈소스 job 정의를 사용하거나 적응시켜 스캔을 실행하고 출력을 Code Quality와 통합할 수도 있어요. 예를 들어:

GitLab 문서를 검사하는 데 쓰는 Vale 린팅 단계.
커뮤니티 gitlab-ci-utils Vale 프로젝트.

markdownlint-cli2

이미 CI/CD 파이프라인에 markdownlint-cli2 job이 있다면, 그 출력을 Code Quality로 보내는 리포트를 추가해야 해요.

출력을 통합하려면:

markdownlint-cli2-formatter-codequality를 프로젝트의 개발 의존성으로 추가해요.
아직 없다면 리포지토리 최상위에 .markdownlint-cli2.jsonc 파일을 만들어요.
.markdownlint-cli2.jsonc에 outputFormatters 지시어를 추가해요: { "outputFormatters": [ [ "markdownlint-cli2-formatter-codequality" ] ] }
리포트 파일 위치를 가리키는 codequality 리포트 아티팩트를 선언해요. 기본적으로 리포트 파일 이름은 markdownlint-cli2-codequality.json이에요. 1. 권장. 리포트 파일명을 리포지토리의 .gitignore 파일에 추가하세요.

자세한 내용과 예시 CI/CD job 정의는 markdownlint-cli2-formatter-codequality 문서를 참고하세요.

Code Quality

Code Quality

본문

티어별 기능

품질 위반을 위한 코드 스캔

CI/CD job에서 Code Quality 결과 가져오기

내장 Code Quality CI/CD 템플릿 사용하기 (더 이상 사용하지 않음)

CodeClimate 기반 스캐닝에서 마이그레이션하기

Code Quality 결과 보기

MR 리포트

MR 변경 뷰

파이프라인 세부 정보 뷰

프로젝트 품질 뷰

Code Quality 리포트 형식

Code Quality와 공통 도구 통합하기

코드 스캐닝 도구

ESLint

Stylelint

MyPy

Flake8

Pylint

Ruff

golangci-lint

PMD Copy/Paste Detector

SwiftLint

RuboCop

Roslynator

문서 스캐닝 도구

Vale

markdownlint-cli2

더 알아보기 (Learn more)