코드 품질은 유지보수성 문제가 기술 부채가 되기 전에 이를 식별합니다. 코드 리뷰 중에 이루어지는 자동화된 피드백은 팀이 더 나은 코드를 작성하는 데 도움이 됩니다. 발견된 문제는 머지 리퀘스트에 직접 표시되므로, 수정 비용이 가장 낮은 시점에 문제를 확인할 수 있습니다.

코드 품질은 다양한 프로그래밍 언어에서 동작하며, 일반적으로 쓰이는 린터, 스타일 검사기, 복잡도 분석기와 통합됩니다. 기존에 사용하던 도구를 코드 품질 워크플로에 연동할 수 있으므로, 팀이 선호하는 도구는 그대로 유지하면서 결과 표시 방식만 표준화할 수 있습니다.

Features per tier#

다음 표와 같이 GitLab 티어에 따라 사용할 수 있는 기능이 다릅니다.

Scan code for quality violations#

코드 품질은 다양한 스캐닝 도구의 결과를 가져오도록 지원하는 개방형 시스템입니다. 위반 사항을 찾아 표시하려면 다음 방법을 사용할 수 있습니다.

• 스캐닝 도구를 직접 사용하고 그 결과를 가져옵니다. (권장)
• 내장된 CI/CD 템플릿을 사용하여 스캐닝을 활성화합니다. 이 템플릿은 일반적인 오픈 소스 도구를 감싸는 CodeClimate 엔진을 사용합니다. (지원 중단)

하나의 파이프라인에서 여러 도구의 결과를 함께 수집할 수 있습니다. 예를 들어 코드를 스캔하는 코드 린터와 문서를 스캔하는 언어 린터를 함께 실행하거나, 독립형 도구를 CodeClimate 기반 스캐닝과 함께 사용할 수 있습니다. 코드 품질은 모든 보고서를 통합하므로 결과를 볼 때 전체 내용을 한 번에 확인할 수 있습니다.

Import Code Quality results from a CI/CD job#

많은 개발 팀이 이미 CI/CD 파이프라인에서 린터, 스타일 검사기, 그 밖의 도구를 사용해 코딩 표준 위반 사항을 자동으로 감지하고 있습니다. 이러한 도구가 찾아낸 문제를 코드 품질과 통합하면 더 쉽게 확인하고 수정할 수 있습니다.

사용 중인 도구에 이미 문서화된 통합 방법이 있는지 확인하려면 코드 품질과 일반적인 도구 통합하기를 참고합니다.

다른 도구를 코드 품질과 통합하려면 다음과 같이 진행합니다.

1. CI/CD 파이프라인에 도구를 추가합니다.
2. 도구가 보고서를 파일로 출력하도록 설정합니다.
   • 이 파일은 특정 JSON 형식을 사용해야 합니다.
   • 많은 도구가 이 출력 형식을 기본으로 지원합니다. 이를 "CodeClimate report", "GitLab Code Quality report" 또는 이와 비슷한 이름으로 부르기도 합니다.
   • 다른 도구는 사용자 정의 JSON 형식이나 템플릿을 사용해 JSON 출력을 만들 수 있는 경우도 있습니다. 보고서 형식에는 필수 필드가 몇 개뿐이므로, 이런 출력 형태도 코드 품질 보고서로 사용할 수 있습니다.
3. 이 파일과 일치하는 codequality report artifact를 선언합니다.

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

Use the built-in Code Quality CI/CD template (deprecated)#

코드 품질에는 내장 CI/CD 템플릿인 Code-Quality.gitlab-ci.yaml도 포함되어 있습니다. 이 템플릿은 오픈 소스 CodeClimate 스캐닝 엔진을 기반으로 스캔을 실행합니다.

CodeClimate 엔진은 다음을 실행합니다.

• 지원되는 언어 목록에 대한 기본적인 유지보수성 검사
• 소스 코드를 분석하기 위해 오픈 소스 스캐너를 감싸는, 설정 가능한 플러그인 모음

Migrate from CodeClimate-based scanning#

CodeClimate 엔진은 사용자가 설정할 수 있는 분석 플러그인 모음을 사용합니다. 일부는 기본으로 켜져 있고, 나머지는 명시적으로 활성화해야 합니다. 내장 플러그인을 대체할 수 있는 통합은 다음과 같습니다.

View Code Quality results#

코드 품질 결과는 다음 위치에 표시됩니다.

• 머지 리퀘스트 보고서
• 머지 리퀘스트 변경 사항 보기
• 파이프라인 세부 정보 보기
• 프로젝트 품질 보기

Merge request reports#

코드 품질 분석 결과는 머지 리퀘스트의 Reports 탭에 표시됩니다. 지문(fingerprint)이 동일한 코드 품질 발견 사항은 하나의 항목으로 묶여 표시됩니다. 어떤 발견 사항이 새로 생겼거나 해결되었는지 판단하기 위해, GitLab은 발견 사항을 대상 브랜치의 기준 파이프라인에서 나온 발견 사항과 비교합니다.

자세한 내용은 머지 리퀘스트 보고서를 참고합니다.

Merge request changes view#

코드 품질 결과는 머지 리퀘스트의 Changes 보기에 표시됩니다. 코드 품질 문제가 있는 줄은 거터(gutter) 옆에 기호로 표시됩니다. 기호를 선택하면 문제 목록이 나타나고, 문제를 선택하면 세부 정보를 확인할 수 있습니다.

Pipeline details view#

파이프라인에서 생성된 코드 품질 위반 사항의 전체 목록은 파이프라인 세부 정보 페이지의 Code Quality 탭에 표시됩니다. 파이프라인 세부 정보 보기에는 파이프라인이 실행된 브랜치에서 발견된 모든 코드 품질 발견 사항이 표시됩니다.

Project quality view#

히스토리

• GitLab 14.5에서 project_quality_summary_page라는 이름의 기능 플래그와 함께 도입되었습니다. 이 기능은 베타 단계이며 기본적으로 비활성화되어 있습니다.

프로젝트 품질 보기에는 코드 품질 발견 사항에 대한 개요가 표시됩니다. 이 화면은 Analyze > CI/CD analytics 아래에서 찾을 수 있으며, 해당 프로젝트에서 project_quality_summary_page 기능 플래그가 활성화되어 있어야 합니다.

Code Quality report format#

다음 형식으로 보고서를 출력할 수 있는 도구라면 어떤 도구에서든 코드 품질 결과를 가져올 수 있습니다. 이 형식은 더 적은 필드를 포함하는, CodeClimate 보고서 형식의 한 버전입니다.

코드 품질 보고서 아티팩트로 제공하는 파일에는 하나의 JSON 배열만 있어야 합니다. 이 배열의 각 객체에는 최소한 다음 속성이 있어야 합니다.

이 형식은 다음과 같은 점에서 CodeClimate 보고서 형식과 다릅니다.

• CodeClimate 보고서 형식은 더 많은 속성을 지원하지만, 코드 품질은 앞서 나열한 필드만 처리합니다.

• GitLab 파서는 파일 시작 부분에 바이트 순서 표시(BOM)가 있는 것을 허용하지 않습니다. 일부 도구, 특히 Windows 나 .NET 환경에서 비롯된 도구는 기본적으로 출력에 UTF-8 바이트 순서 표시를 추가합니다. UTF-8 바이트 순서 표시를 확인하고 제거하려면 다음을 실행합니다.

  [ "$(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
      }
    }
  }
]

Integrate common tools with Code Quality#

많은 도구가 결과를 코드 품질과 통합하는 데 필요한 보고서 형식을 기본으로 지원합니다. 이를 "CodeClimate report", "GitLab Code Quality report" 또는 이와 비슷한 이름으로 부르기도 합니다.

다른 도구는 사용자 정의 템플릿이나 형식 명세를 제공하여 JSON 출력을 만들도록 설정할 수 있습니다. 보고서 형식에는 필수 필드가 몇 개뿐이므로, 이런 출력 형태도 코드 품질 보고서로 사용할 수 있습니다.

CI/CD 파이프라인에서 이미 도구를 사용하고 있다면, 기존 job을 수정해 코드 품질 보고서를 추가하는 것이 좋습니다. 기존 job을 수정하면 개발자를 혼란스럽게 하고 파이프라인 실행 시간을 늘릴 수 있는 별도의 job을 실행하지 않아도 됩니다.

아직 도구를 사용하고 있지 않다면, CI/CD job을 처음부터 작성하거나 CI/CD 카탈로그의 컴포넌트를 사용해 도구를 도입할 수 있습니다.

Code scanning tools#

ESLint#

CI/CD 파이프라인에 이미 ESLint job 이 있다면, 그 출력을 코드 품질로 보내는 보고서를 추가하는 것이 좋습니다. 출력을 통합하려면 다음과 같이 진행합니다.

1. 프로젝트에 개발 의존성으로 eslint-formatter-gitlab을 추가합니다.
2. ESLint를 실행하는 명령에 --format gitlab 옵션을 추가합니다.
3. 보고서 파일의 위치를 가리키는 codequality report artifact를 선언합니다.
   • 기본적으로 포매터는 CI/CD 설정을 읽어 보고서를 저장할 파일 이름을 추론합니다. 아티팩트 선언에 사용한 파일 이름을 포매터가 추론하지 못하는 경우, CI/CD 변수 ESLINT_CODE_QUALITY_REPORT를 gl-code-quality-report.json과 같이 아티팩트에 지정한 파일 이름으로 설정합니다.

스캔을 실행하고 그 출력을 코드 품질과 통합하기 위해 ESLint CI/CD 컴포넌트를 그대로 사용하거나 조정할 수도 있습니다.

Stylelint#

CI/CD 파이프라인에 이미 Stylelint job 이 있다면, 그 출력을 코드 품질로 보내는 보고서를 추가하는 것이 좋습니다. 출력을 통합하려면 다음과 같이 진행합니다.

1. 프로젝트에 개발 의존성으로 @studiometa/stylelint-formatter-gitlab을 추가합니다.
2. Stylelint를 실행하는 명령에 --custom-formatter=@studiometa/stylelint-formatter-gitlab 옵션을 추가합니다.
3. 보고서 파일의 위치를 가리키는 codequality report artifact를 선언합니다.
   • 기본적으로 포매터는 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 이 있다면, 그 출력을 코드 품질로 보내는 보고서를 추가하는 것이 좋습니다. 출력을 통합하려면 다음과 같이 진행합니다.

1. 프로젝트에 의존성으로 mypy-gitlab-code-quality를 설치합니다.

2. mypy 명령의 출력을 파일로 보내도록 변경합니다.

3. job의 script에, mypy-gitlab-code-quality를 사용해 파일을 필요한 형식으로 다시 처리하는 단계를 추가합니다. 예를 들면 다음과 같습니다.

   - 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
   

4. 보고서 파일의 위치를 가리키는 codequality report artifact를 선언합니다.

스캔을 실행하고 그 출력을 코드 품질과 통합하기 위해 MyPy CI/CD 컴포넌트를 그대로 사용하거나 조정할 수도 있습니다.

Flake8#

CI/CD 파이프라인에 이미 Flake8 job 이 있다면, 그 출력을 코드 품질로 보내는 보고서를 추가하는 것이 좋습니다. 출력을 통합하려면 다음과 같이 진행합니다.

1. 프로젝트에 의존성으로 flake8-gl-codeclimate를 설치합니다.
2. Flake8을 실행하는 명령에 --format gl-codeclimate --output-file gl-code-quality-report.json 인수를 추가합니다.
3. 보고서 파일의 위치를 가리키는 codequality report artifact를 선언합니다.

스캔을 실행하고 그 출력을 코드 품질과 통합하기 위해 Flake8 CI/CD 컴포넌트를 그대로 사용하거나 조정할 수도 있습니다.

Pylint#

CI/CD 파이프라인에 이미 Pylint job 이 있다면, 그 출력을 코드 품질로 보내는 보고서를 추가하는 것이 좋습니다. 출력을 통합하려면 다음과 같이 진행합니다.

1. 프로젝트에 의존성으로 pylint-gitlab을 설치합니다.
2. Pylint를 실행하는 명령에 --output-format=pylint_gitlab.GitlabCodeClimateReporter 인수를 추가합니다.
3. pylint 명령의 출력을 파일로 보내도록 변경합니다.
4. 보고서 파일의 위치를 가리키는 codequality report artifact를 선언합니다.

스캔을 실행하고 그 출력을 코드 품질과 통합하기 위해 Pylint CI/CD 컴포넌트를 그대로 사용하거나 조정할 수도 있습니다.

Ruff#

CI/CD 파이프라인에 이미 Ruff job 이 있다면, 그 출력을 코드 품질로 보내는 보고서를 추가하는 것이 좋습니다. 출력을 통합하려면 다음과 같이 진행합니다.

1. Ruff를 실행하는 명령에 --output-format=gitlab 인수를 추가합니다.
2. ruff check 명령의 출력을 파일로 보내도록 변경합니다.
3. 보고서 파일의 위치를 가리키는 codequality report artifact를 선언합니다.

스캔을 실행하고 그 출력을 코드 품질과 통합하기 위해 문서화된 Ruff GitLab CI/CD 통합을 그대로 사용하거나 조정할 수도 있습니다.

golangci-lint#

CI/CD 파이프라인에 이미 golangci-lint job 이 있다면, 그 출력을 코드 품질로 보내는 보고서를 추가하는 것이 좋습니다. 출력을 통합하려면 다음과 같이 진행합니다.

1. golangci-lint를 실행하는 명령에 인수를 추가합니다.

   • v1의 경우 --out-format code-climate:gl-code-quality-report.json,line-number를 추가합니다.
   • v2의 경우 --output.code-climate.path=gl-code-quality-report.json을 추가합니다.

2. 보고서 파일의 위치를 가리키는 codequality report artifact를 선언합니다.

스캔을 실행하고 그 출력을 코드 품질과 통합하기 위해 golangci-lint CI/CD 컴포넌트를 그대로 사용하거나 조정할 수도 있습니다.

PMD Copy/Paste Detector#

PMD Copy/Paste Detector(CPD)는 기본 출력이 필요한 형식을 따르지 않으므로 추가 설정이 필요합니다.

스캔을 실행하고 그 출력을 코드 품질과 통합하기 위해 PMD CI/CD 컴포넌트를 그대로 사용하거나 조정할 수 있습니다.

SwiftLint#

SwiftLint를 사용하려면 기본 출력이 필요한 형식을 따르지 않으므로 추가 설정이 필요합니다.

스캔을 실행하고 그 출력을 코드 품질과 통합하기 위해 SwiftLint CI/CD 컴포넌트를 그대로 사용하거나 조정할 수 있습니다.

RuboCop#

RuboCop을 사용하려면 기본 출력이 필요한 형식을 따르지 않으므로 추가 설정이 필요합니다.

스캔을 실행하고 그 출력을 코드 품질과 통합하기 위해 RuboCop CI/CD 컴포넌트를 그대로 사용하거나 조정할 수 있습니다.

Roslynator#

Roslynator를 사용하려면 기본 출력이 필요한 형식을 따르지 않으므로 추가 설정이 필요합니다.

스캔을 실행하고 그 출력을 코드 품질과 통합하기 위해 Roslynator CI/CD 컴포넌트를 그대로 사용하거나 조정할 수 있습니다.

Documentation scanning tools#

코드 품질을 사용하면 코드가 아니더라도 리포지터리에 저장된 모든 파일을 스캔할 수 있습니다.

Vale#

CI/CD 파이프라인에 이미 Vale job 이 있다면, 그 출력을 코드 품질로 보내는 보고서를 추가하는 것이 좋습니다. 출력을 통합하려면 다음과 같이 진행합니다.

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

예를 들어 다음과 같이 스캔을 실행하고 그 출력을 코드 품질과 통합하기 위해 오픈 소스 job 정의를 그대로 사용하거나 조정할 수도 있습니다.

• GitLab 문서를 검사할 때 사용하는 Vale 린팅 단계
• 커뮤니티의 gitlab-ci-utils Vale 프로젝트

markdownlint-cli2#

CI/CD 파이프라인에 이미 markdownlint-cli2 job 이 있다면, 그 출력을 코드 품질로 보내는 보고서를 추가하는 것이 좋습니다. 출력을 통합하려면 다음과 같이 진행합니다.

1. 프로젝트에 개발 의존성으로 markdownlint-cli2-formatter-codequality를 추가합니다.

2. 리포지터리 최상위에 .markdownlint-cli2.jsonc 파일이 아직 없다면 만듭니다.

3. .markdownlint-cli2.jsonc에 outputFormatters 지시문을 추가합니다.

   {
     "outputFormatters": [
       [ "markdownlint-cli2-formatter-codequality" ]
     ]
   }
   

4. 보고서 파일의 위치를 가리키는 codequality report artifact를 선언합니다. 기본적으로 보고서 파일 이름은 markdownlint-cli2-codequality.json입니다.

   1. 권장. 리포지터리의 .gitignore 파일에 보고서 파일 이름을 추가합니다.

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