코드 품질은 기술적 부채가 되기 전에 유지 관리 문제를 식별합니다. 코드 리뷰 중에 발생하는 자동화된 피드백은 팀이 더 나은 코드를 작성하는 데 도움이 됩니다. 결과는 머지 리퀘스트에 직접 표시되어 수정하기에 가장 비용 효율적인 시점에 문제를 볼 수 있게 합니다.

코드 품질은 여러 프로그래밍 언어와 함께 작동하며 일반적인 린터, 스타일 검사기, 복잡성 분석기와 통합됩니다. 기존 도구를 코드 품질 워크플로우에 연결하여 팀의 선호도를 유지하면서 결과 표시 방법을 표준화할 수 있습니다.

티어별 기능#

다음 표와 같이 다양한 GitLab 티어에서 다른 기능을 사용할 수 있습니다:

코드 품질 위반 검사#

코드 품질은 많은 스캔 도구의 결과를 가져오는 것을 지원하는 개방형 시스템입니다. 위반을 찾아 표면화하려면 다음을 수행할 수 있습니다:

• 스캐닝 도구를 직접 사용하고 결과를 가져옵니다. (권장)
• 내장 CI/CD 템플릿을 사용하여 스캐닝을 활성화합니다. 이 템플릿은 일반적인 오픈 소스 도구를 래핑하는 CodeClimate 엔진을 사용합니다. (더 이상 사용되지 않음)

단일 파이프라인에서 여러 도구의 결과를 캡처할 수 있습니다. 예를 들어, 코드를 스캔하는 코드 린터와 문서를 스캔하는 언어 린터를 실행하거나, 독립형 도구와 CodeClimate 기반 스캔을 함께 사용할 수 있습니다. 코드 품질은 모든 보고서를 결합하므로 결과를 볼 때 모두 표시됩니다.

CI/CD 작업에서 코드 품질 결과 가져오기#

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

도구에 이미 문서화된 통합이 있는지 확인하려면 일반 도구와 코드 품질 통합을 참조하세요.

다른 도구를 코드 품질과 통합하려면:

1. CI/CD 파이프라인에 도구를 추가합니다.
2. 도구를 구성하여 보고서를 파일로 출력합니다.
   • 이 파일은 특정 JSON 형식을 사용해야 합니다.
   • 많은 도구가 이 출력 형식을 기본적으로 지원합니다. "CodeClimate 보고서", "GitLab 코드 품질 보고서" 또는 유사한 이름으로 불릴 수 있습니다.
   • 다른 도구는 때로 사용자 정의 JSON 형식 또는 템플릿을 사용하여 JSON 출력을 만들 수 있습니다. 보고서 형식에는 몇 가지 필수 필드만 있으므로, 이 출력 유형을 사용하여 코드 품질 보고서를 만들 수 있습니다.
3. 이 파일과 일치하는 codequality 보고서 아티팩트를 선언합니다.

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

내장 코드 품질 CI/CD 템플릿 사용 (더 이상 사용되지 않음)#

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

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

• 지원되는 언어 세트에 대한 기본 유지 관리 검사.
• 소스 코드를 분석하기 위해 오픈 소스 스캐너를 래핑하는 구성 가능한 플러그인 세트.

자세한 내용은 CodeClimate 기반 코드 품질 스캔 구성을 참조하세요.

CodeClimate 기반 스캔에서 마이그레이션#

CodeClimate 엔진은 사용자 정의 가능한 분석 플러그인 세트를 사용합니다. 일부는 기본적으로 켜져 있고, 다른 것들은 명시적으로 활성화해야 합니다. 내장 플러그인을 대체하기 위해 다음 통합을 사용할 수 있습니다:

코드 품질 결과 보기#

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

• 머지 리퀘스트 위젯
• 머지 리퀘스트 변경 사항 뷰
• 파이프라인 상세 뷰
• 프로젝트 품질 뷰

머지 리퀘스트 위젯#

대상 브랜치에서 비교할 수 있는 보고서가 있는 경우 코드 품질 분석 결과가 머지 리퀘스트 위젯 영역에 표시됩니다. 머지 리퀘스트 위젯에는 머지 리퀘스트에서 변경된 사항으로 인해 도입된 코드 품질 결과 및 해결 사항이 표시됩니다. 동일한 지문을 가진 여러 코드 품질 결과는 머지 리퀘스트 위젯에 단일 항목으로 표시됩니다. 각 개별 결과는 파이프라인 세부 뷰에서 사용 가능한 전체 보고서에서 확인할 수 있습니다.

머지 리퀘스트 변경 사항 뷰#

코드 품질 결과는 머지 리퀘스트 변경 사항 뷰에 표시됩니다. 코드 품질 문제가 있는 줄은 거터 옆의 기호로 표시됩니다. 기호를 선택하여 문제 목록을 확인한 다음 문제를 선택하여 세부 정보를 확인합니다.

파이프라인 상세 뷰#

파이프라인에서 생성된 코드 품질 위반의 전체 목록은 파이프라인 상세 페이지의 코드 품질 탭에 표시됩니다. 파이프라인 상세 뷰에는 실행된 브랜치에서 발견된 모든 코드 품질 결과가 표시됩니다.

프로젝트 품질 뷰#

히스토리

• GitLab 14.5에서 project_quality_summary_page라는 플래그와 함께 도입. 이 기능은 베타입니다. 기본적으로 비활성화.

프로젝트 품질 뷰에는 코드 품질 결과 개요가 표시됩니다. 뷰는 분석 > CI/CD 분석에서 찾을 수 있으며, 이 특정 프로젝트에 대해 project_quality_summary_page 기능 플래그를 활성화해야 합니다.

코드 품질 보고서 형식#

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

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

이 형식은 다음 방식에서 CodeClimate 보고서 형식과 다릅니다:

• CodeClimate 보고서 형식이 더 많은 속성을 지원하지만, 코드 품질은 위에 나열된 필드만 처리합니다.
• GitLab 파서는 파일 시작 부분에 바이트 순서 표식을 허용하지 않습니다.

예를 들어, 다음은 준수하는 보고서입니다:

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

일반 도구와 코드 품질 통합#

많은 도구가 결과를 코드 품질과 통합하는 데 필요한 보고서 형식을 기본적으로 지원합니다. "CodeClimate 보고서", "GitLab 코드 품질 보고서" 또는 유사한 이름으로 불릴 수 있습니다.

다른 도구는 사용자 정의 템플릿 또는 형식 사양을 제공하여 JSON 출력을 만들도록 구성할 수 있습니다. 보고서 형식에는 몇 가지 필수 필드만 있으므로, 이 출력 유형을 사용하여 코드 품질 보고서를 만들 수 있습니다.

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

도구를 아직 사용하지 않는다면 CI/CD 작업을 처음부터 작성하거나 CI/CD 카탈로그의 구성 요소를 사용하여 도구를 채택할 수 있습니다.

코드 스캔 도구#

ESLint#

이미 CI/CD 파이프라인에 ESLint 작업이 있다면 출력을 코드 품질에 보내는 보고서를 추가해야 합니다. 출력을 통합하려면:

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

ESLint CI/CD 구성 요소를 사용하거나 수정하여 스캔을 실행하고 출력을 코드 품질과 통합할 수도 있습니다.

Stylelint#

이미 CI/CD 파이프라인에 Stylelint 작업이 있다면 출력을 코드 품질에 보내는 보고서를 추가해야 합니다. 출력을 통합하려면:

1. 프로젝트에 개발 의존성으로 @studiometa/stylelint-formatter-gitlab을 추가합니다.
2. Stylelint를 실행하는 명령에 --custom-formatter=@studiometa/stylelint-formatter-gitlab 옵션을 추가합니다.
3. 보고서 파일의 위치를 가리키는 codequality 보고서 아티팩트를 선언합니다.
   • 기본적으로 포매터는 CI/CD 구성을 읽고 보고서를 저장할 파일 이름을 유추합니다. 포매터가 아티팩트 선언에 사용한 파일 이름을 유추할 수 없는 경우 CI/CD 변수 STYLELINT_CODE_QUALITY_REPORT를 아티팩트에 지정된 파일 이름(예: gl-code-quality-report.json)으로 설정합니다.

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

MyPy#

이미 CI/CD 파이프라인에 MyPy 작업이 있다면 출력을 코드 품질에 보내는 보고서를 추가해야 합니다. 출력을 통합하려면:

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

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

3. mypy-gitlab-code-quality를 사용하여 파일을 필요한 형식으로 재처리하는 단계를 작업 script에 추가합니다. 예를 들어:

   - mypy $(find -type f -name "*.py" ! -path "**/.venv/**") --no-error-summary > mypy-out.txt || true  # "|| true"는 mypy가 오류를 발견할 때 작업이 실패하지 않도록 하는 데 사용됩니다
   - mypy-gitlab-code-quality < mypy-out.txt > gl-code-quality-report.json
   

4. 보고서 파일의 위치를 가리키는 codequality 보고서 아티팩트를 선언합니다.

MyPy CI/CD 구성 요소를 사용하거나 수정하여 스캔을 실행하고 출력을 코드 품질과 통합할 수도 있습니다.

Flake8#

이미 CI/CD 파이프라인에 Flake8 작업이 있다면 출력을 코드 품질에 보내는 보고서를 추가해야 합니다. 출력을 통합하려면:

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

Flake8 CI/CD 구성 요소를 사용하거나 수정하여 스캔을 실행하고 출력을 코드 품질과 통합할 수도 있습니다.

Pylint#

이미 CI/CD 파이프라인에 Pylint 작업이 있다면 출력을 코드 품질에 보내는 보고서를 추가해야 합니다. 출력을 통합하려면:

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

Pylint CI/CD 구성 요소를 사용하거나 수정하여 스캔을 실행하고 출력을 코드 품질과 통합할 수도 있습니다.

Ruff#

이미 CI/CD 파이프라인에 Ruff 작업이 있다면 출력을 코드 품질에 보내는 보고서를 추가해야 합니다. 출력을 통합하려면:

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

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

golangci-lint#

이미 CI/CD 파이프라인에 golangci-lint 작업이 있다면 출력을 코드 품질에 보내는 보고서를 추가해야 합니다. 출력을 통합하려면:

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 보고서 아티팩트를 선언합니다.

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 구성 요소를 사용하거나 수정하여 스캔을 실행하고 출력을 코드 품질과 통합할 수 있습니다.

문서 스캔 도구#

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

Vale#

이미 CI/CD 파이프라인에 Vale 작업이 있다면 출력을 코드 품질에 보내는 보고서를 추가해야 합니다. 출력을 통합하려면:

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

다음과 같은 오픈 소스 작업 정의를 사용하거나 수정하여 스캔을 실행하고 출력을 코드 품질과 통합할 수도 있습니다:

• GitLab 문서 검사에 사용되는 Vale 린팅 단계.
• 커뮤니티 gitlab-ci-utils Vale 프로젝트.

markdownlint-cli2#

이미 CI/CD 파이프라인에 markdownlint-cli2 작업이 있다면 출력을 코드 품질에 보내는 보고서를 추가해야 합니다. 출력을 통합하려면:

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

2. 아직 없는 경우 리포지터리 최상위 수준에 .markdownlint-cli2.jsonc 파일을 만듭니다.

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

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

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

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

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