Code Quality 문제 해결

GitLab의 Code Quality 기능을 쓰다 보면 머지 리퀘스트에 리포트가 안 뜬다거나, 기본 구성이 바뀌지 않는 등 여러 문제를 만날 수 있어요. 이 글은 Code Quality 관련 흔한 오류들을 모아 각각의 원인과 해결 방법을 설명할게요.

출처: 문서

본문

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

코드를 찾을 수 없고 파이프라인이 항상 기본 구성으로 실행됨

아마도 Docker-in-Docker 소켓 바인딩 구성으로 프라이빗 러너를 사용하고 있는 것 같아요. 프라이빗 러너 사용 문서에 나온 대로 워커에서 Code Quality 검사를 실행하도록 구성해야 합니다.

기본 구성 변경이 효과가 없음

흔한 문제는 Code Quality(GitLab 전용)와 Code Climate(GitLab이 사용하는 엔진) 용어가 매우 비슷하다는 점이에요. 기본 구성을 바꾸려면 .codequality.yml 파일이 아니라 .codeclimate.yml 파일을 추가해야 합니다. 잘못된 파일 이름을 사용하면 기본 .codeclimate.yml이 계속 사용됩니다.

머지 리퀘스트에 Code Quality 리포트가 표시되지 않음

소스 또는 대상 브랜치의 Code Quality 리포트가 머지 리퀘스트 비교용으로 누락될 수 있어서 정보가 표시되지 않아요.

소스 브랜치의 리포트 누락 원인:

REPORT_STDOUT 환경 변수를 사용하면 리포트 파일이 생성되지 않아 머지 리퀘스트에 아무것도 표시되지 않아요.

대상 브랜치의 리포트 누락 원인:

.gitlab-ci.yml에 새로 추가된 Code Quality job
파이프라인이 대상 브랜치에서 Code Quality job을 실행하도록 설정되지 않음
Code Quality job을 실행하지 않는 커밋이 기본 브랜치에 만들어짐
artifacts:expire_in CI/CD 설정으로 Code Quality 아티팩트가 원하는 것보다 빨리 만료됨

머지 리퀘스트 API로 base_sha를 얻어 베이스 커밋의 리포트 존재를 확인하고, sha 속성을 가진 파이프라인 API로 파이프라인이 실행됐는지 확인해 보세요.

변경 사항 보기에 Code Quality 기호가 표시되지 않음

변경 사항 보기에 기호가 표시되지 않는다면, code quality 리포트의 location.path가 다음을 만족하는지 확인하세요.

코드 품질 위반이 있는 파일에 대한 상대 경로를 사용하는지
./로 시작하지 않는지 — 예를 들어 경로는 ./somedir/file1.rb가 아니라 somedir/file1.rb여야 해요.

하나의 Code Quality 리포트만 표시되는데 더 많이 정의됨

Code Quality는 여러 리포트를 자동으로 결합합니다.

RuboCop 오류

Ruby 프로젝트에서 Code Quality job을 사용할 때 RuboCop 실행 관련 문제가 발생할 수 있어요. 예를 들어 아주 최신 또는 아주 오래된 Ruby 버전을 사용할 때 다음 오류가 나타날 수 있습니다.

/usr/local/bundle/gems/rubocop-0.52.1/lib/rubocop/config.rb:510:in `check_target_ruby':
Unknown Ruby version 2.7 found in `.ruby-version`. (RuboCop::ValidationError)
Supported versions: 2.1, 2.2, 2.3, 2.4, 2.5

체크 엔진의 기본 RuboCop 버전이 사용 중인 Ruby 버전을 지원하지 않아요.

프로젝트가 사용하는 Ruby 버전을 지원하는 RuboCop 버전을 사용하려면, 프로젝트 저장소에 만든 .codeclimate.yml 파일로 구성을 덮어쓸 수 있어요.

예를 들어 RuboCop 릴리스 0.67을 사용하도록 지정하려면:

version: "2"
plugins:
  rubocop:
    enabled: true
    channel: rubocop-0-67

커스텀 도구 사용 시 머지 리퀘스트에 Code Quality가 표시되지 않음

커스텀 도구를 사용할 때 머지 리퀘스트에 Code Quality 변경이 표시되지 않는다면, JSON의 모든 line 속성이 정수인지 확인하세요.

오류: Could not analyze code quality

다음 오류를 받을 수 있습니다.

error: (CC::CLI::Analyze::EngineFailure) engine pmd ran for 900 seconds and was killed
Could not analyze code quality for the repository at /code

Code Climate 플러그인을 활성화했는데 Code Quality CI/CD job이 이 오류 메시지로 실패한다면, job이 기본 타임아웃인 900초보다 오래 걸리고 있는 것입니다.

이 문제를 해결하려면 .gitlab-ci.yml 파일에서 TIMEOUT_SECONDS를 더 높은 값으로 설정하세요.

예를 들어:

code_quality:
  variables:
    TIMEOUT_SECONDS: 3600

Kubernetes 또는 OpenShift 러너와 함께 Code Quality 사용하기

CodeClimate 기반 스캔에는 특별한 요구 사항이 있어요. 스캔이 제대로 동작하려면 CodeClimate 기반 스캔용 Kubernetes 또는 OpenShift 러너 구성이 필요할 수 있습니다.

오류: x509: certificate signed by unknown authority

CODE_QUALITY_IMAGE를 자체 서명 인증서처럼 신뢰할 수 없는 TLS 인증서를 사용하는 Docker 레지스트리에 호스팅된 이미지로 설정하면 다음 오류가 보일 수 있어요.

$ docker pull --quiet "$CODE_QUALITY_IMAGE"
Error response from daemon: Get https://gitlab.example.com/v2/: x509: certificate signed by unknown authority

이 문제를 해결하려면 인증서 신뢰를 위해 Docker 데몬을 구성해서 인증서를 /etc/docker/certs.d 디렉터리 안에 넣으세요.

이 Docker 데몬은 GitLab Code Quality 템플릿의 후속 Code Quality Docker 컨테이너에 노출되며, 인증서 구성이 적용되기를 원하는 다른 컨테이너에도 노출되어야 합니다.

Docker

GitLab Runner 구성에 접근할 수 있다면 볼륨 마운트로 디렉터리를 추가하세요.

gitlab.example.com을 레지스트리의 실제 도메인으로 바꾸세요.

예제:

[[runners]]
  ...
  executor = "docker"
  [runners.docker]
    ...
    privileged = true
    volumes = ["/cache", "/etc/gitlab-runner/certs/gitlab.example.com.crt:/etc/docker/certs.d/gitlab.example.com/ca.crt:ro"]

Kubernetes

GitLab Runner 구성과 Kubernetes 클러스터에 접근할 수 있다면 ConfigMap을 마운트할 수 있어요.

gitlab.example.com을 레지스트리의 실제 도메인으로 바꾸세요.

인증서로 ConfigMap을 만드세요.

kubectl create configmap registry-crt --namespace gitlab-runner --from-file /etc/gitlab-runner/certs/gitlab.example.com.crt

GitLab Runner config.toml을 업데이트해 ConfigMap을 지정하세요.

[[runners]]
  ...
  executor = "kubernetes"
  [runners.kubernetes]
    image = "alpine:3.12"
    privileged = true
    [[runners.kubernetes.volumes.config_map]]
      name = "registry-crt"
      mount_path = "/etc/docker/certs.d/gitlab.example.com/ca.crt"
      sub_path = "gitlab.example.com.crt"

Code Quality 리포트 로드 실패

아티팩트 파일에서 데이터를 파싱하는 데 문제가 있으면 Code Quality 리포트가 로드되지 않을 수 있어요. 오류를 파악하려면 다음 단계로 GraphQL 쿼리를 실행할 수 있습니다.

파이프라인 세부 정보 페이지로 이동하세요.

URL에 .json을 추가하세요.

파이프라인의 iid를 복사하세요.

인터랙티브 GraphQL 탐색기로 이동하세요.

다음 쿼리를 실행하세요.

{
  project(fullPath: "<fullpath-to-your-project>") {
    pipeline(iid: "<iid>") {
      codeQualityReports {
        count
        nodes {
          line
          description
          path
          fingerprint
          severity
        }
        pageInfo {
          hasNextPage
          hasPreviousPage
          startCursor
          endCursor
        }
      }
    }
  }
}

리포트 아티팩트가 생성되지 않음

특정 Runner 구성에서는 Code Quality 스캔 job이 소스 코드에 접근하지 못할 수 있어요. 이 경우 gl-code-quality-report.json 아티팩트가 생성되지 않습니다.

이 문제를 해결하려면 다음 중 하나를 수행하세요.

Docker 소켓 바인딩 대신 privileged 모드를 사용하는 Docker-in-Docker용 문서화된 Runner 구성을 사용하세요.
Docker 소켓 바인딩을 계속 사용하려면 이슈 32027의 커뮤니티 해결책을 적용하세요.

자세한 내용은 Runner 구성 변경을 참고하세요.

더 알아보기 (Learn more)

Code Quality 기능 자체의 사용법이 궁금하다면 Code Quality 문서를, 프라이빗 러너나 Kubernetes 러너 구성은 Code Climate 기반 스캔 문서를 참고하세요.