코드 품질 문제 해결

요약

코드 품질 작업 시 다음 문제가 발생할 수 있습니다. Docker-in-Docker 소켓 바인딩 구성의 프라이빗 러너를 사용하고 있을 가능성이 높습니다. 흔한 문제는 Code Quality(GitLab 관련)와 Code Climate(GitLab이 사용하는 엔진)라는 용어가 매우 유사하다는 것입니다.

코드 품질 작업 시 다음 문제가 발생할 수 있습니다.

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

Docker-in-Docker 소켓 바인딩 구성의 프라이빗 러너를 사용하고 있을 가능성이 높습니다. 프라이빗 러너 사용에 문서화된 대로 워커에서 코드 품질 검사를 실행하도록 구성해야 합니다.

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

흔한 문제는 Code Quality(GitLab 관련)와 Code Climate(GitLab이 사용하는 엔진)라는 용어가 매우 유사하다는 것입니다. 기본 구성을 변경하려면 .codequality.yml이 아닌 .codeclimate.yml 파일을 추가해야 합니다. 잘못된 파일 이름을 사용하면 기본 .codeclimate.yml이 계속 사용됩니다.

머지 리퀘스트에 코드 품질 보고서가 표시되지 않음#

소스 또는 대상 브랜치의 코드 품질 보고서가 머지 리퀘스트에서 비교용으로 누락되어 정보를 표시할 수 없을 수 있습니다.

소스 브랜치의 보고서 누락은 다음으로 인한 것일 수 있습니다:

REPORT_STDOUT 환경 변수 사용 - 보고서 파일이 생성되지 않고 머지 리퀘스트에 아무것도 표시되지 않습니다.

대상 브랜치의 보고서 누락은 다음으로 인한 것일 수 있습니다:

.gitlab-ci.yml에 새로 추가된 코드 품질 잡.
파이프라인이 대상 브랜치에서 코드 품질 잡을 실행하도록 설정되어 있지 않습니다.
코드 품질 잡을 실행하지 않는 커밋이 기본 브랜치에 만들어집니다.
artifacts:expire_in CI/CD 설정으로 인해 코드 품질 아티팩트가 원하는 것보다 빨리 만료될 수 있습니다.

머지 리퀘스트 API를 사용하여 base_sha를 얻고 sha 속성이 있는 파이프라인 API를 사용하여 파이프라인이 실행되었는지 확인하여 기본 커밋에 보고서가 있는지 확인합니다.

변경 사항 보기에 코드 품질 기호 없음#

변경 사항 보기에 기호가 표시되지 않으면 코드 품질 보고서의 location.path가 다음을 확인합니다:

코드 품질 위반이 포함된 파일에 대한 상대 경로를 사용합니다.
./로 시작하지 않습니다. 예를 들어 path는 ./somedir/file1.rb 대신 somedir/file1.rb여야 합니다.

단일 코드 품질 보고서만 표시되지만 더 많이 정의됨#

코드 품질은 자동으로 여러 보고서를 결합합니다.

GitLab 15.6 이전에는 코드 품질이 최신 생성된 잡(가장 큰 잡 ID를 가진)의 아티팩트만 사용했습니다. 이전 잡의 코드 품질 아티팩트는 무시되었습니다.

RuboCop 오류#

Ruby 프로젝트에서 코드 품질 잡을 사용할 때 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

커스텀 도구를 사용할 때 머지 리퀘스트에 코드 품질이 표시되지 않음#

커스텀 도구를 사용할 때 머지 리퀘스트에 코드 품질 변경 사항이 표시되지 않으면 JSON의 모든 줄 속성이 integer인지 확인합니다.

오류: `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 플러그인 중 하나를 활성화했고 코드 품질 CI/CD 잡이 이 오류 메시지와 함께 실패하면 잡이 기본 타임아웃인 900초보다 오래 걸릴 가능성이 높습니다:

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

예를 들어:

code_quality:
  variables:
    TIMEOUT_SECONDS: 3600

Kubernetes 또는 OpenShift 러너와 함께 코드 품질 사용#

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

이를 수정하려면 /etc/docker/certs.d 디렉터리 안에 인증서를 넣어 Docker 데몬이 인증서를 신뢰하도록 구성합니다.

이 Docker 데몬은 GitLab 코드 품질 템플릿의 후속 코드 품질 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

ConfigMap을 지정하도록 GitLab Runner config.toml을 업데이트합니다:

[[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"

코드 품질 보고서 로드 실패#

아티팩트 파일에서 데이터를 파싱하는 데 문제가 있을 때 코드 품질 보고서가 로드에 실패할 수 있습니다. 오류에 대한 통찰력을 얻으려면 다음 단계를 사용하여 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
        }
      }
    }
  }
}

보고서 아티팩트가 생성되지 않음#

특정 러너 구성에서 코드 품질 스캐닝 잡이 소스 코드에 액세스하지 못할 수 있습니다. 이 경우 gl-code-quality-report.json 아티팩트가 생성되지 않습니다.

이 문제를 해결하려면 다음 중 하나를 수행합니다:

소켓 바인딩 대신 권한 있는 모드를 사용하는 Docker-in-Docker 문서화된 러너 구성을 사용합니다.
Docker 소켓 바인딩을 계속 사용하려면 이슈 32027의 커뮤니티 해결 방법을 적용합니다.

자세한 내용은 러너 구성 변경을 참조하세요.

코드 품질 문제 해결

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

원문 보기

번역일: 2026-05-22

요약

코드 품질 작업 시 다음 문제가 발생할 수 있습니다.

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

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

머지 리퀘스트에 코드 품질 보고서가 표시되지 않음#

소스 또는 대상 브랜치의 코드 품질 보고서가 머지 리퀘스트에서 비교용으로 누락되어 정보를 표시할 수 없을 수 있습니다.

소스 브랜치의 보고서 누락은 다음으로 인한 것일 수 있습니다:

REPORT_STDOUT 환경 변수 사용 - 보고서 파일이 생성되지 않고 머지 리퀘스트에 아무것도 표시되지 않습니다.

대상 브랜치의 보고서 누락은 다음으로 인한 것일 수 있습니다:

.gitlab-ci.yml에 새로 추가된 코드 품질 잡.
파이프라인이 대상 브랜치에서 코드 품질 잡을 실행하도록 설정되어 있지 않습니다.
코드 품질 잡을 실행하지 않는 커밋이 기본 브랜치에 만들어집니다.
artifacts:expire_in CI/CD 설정으로 인해 코드 품질 아티팩트가 원하는 것보다 빨리 만료될 수 있습니다.

변경 사항 보기에 코드 품질 기호 없음#

변경 사항 보기에 기호가 표시되지 않으면 코드 품질 보고서의 location.path가 다음을 확인합니다:

코드 품질 위반이 포함된 파일에 대한 상대 경로를 사용합니다.
./로 시작하지 않습니다. 예를 들어 path는 ./somedir/file1.rb 대신 somedir/file1.rb여야 합니다.

단일 코드 품질 보고서만 표시되지만 더 많이 정의됨#

코드 품질은 자동으로 여러 보고서를 결합합니다.

GitLab 15.6 이전에는 코드 품질이 최신 생성된 잡(가장 큰 잡 ID를 가진)의 아티팩트만 사용했습니다. 이전 잡의 코드 품질 아티팩트는 무시되었습니다.

RuboCop 오류#

/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 버전을 지원하지 않기 때문에 발생합니다.

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

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

커스텀 도구를 사용할 때 머지 리퀘스트에 코드 품질이 표시되지 않음#

커스텀 도구를 사용할 때 머지 리퀘스트에 코드 품질 변경 사항이 표시되지 않으면 JSON의 모든 줄 속성이 integer인지 확인합니다.

오류: `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

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

예를 들어:

code_quality:
  variables:
    TIMEOUT_SECONDS: 3600

Kubernetes 또는 OpenShift 러너와 함께 코드 품질 사용#

오류: `x509: certificate signed by unknown authority`#

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

이를 수정하려면 /etc/docker/certs.d 디렉터리 안에 인증서를 넣어 Docker 데몬이 인증서를 신뢰하도록 구성합니다.

이 Docker 데몬은 GitLab 코드 품질 템플릿의 후속 코드 품질 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

ConfigMap을 지정하도록 GitLab Runner config.toml을 업데이트합니다:

[[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"

코드 품질 보고서 로드 실패#

파이프라인 세부 정보 페이지로 이동합니다.
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
        }
      }
    }
  }
}

보고서 아티팩트가 생성되지 않음#

특정 러너 구성에서 코드 품질 스캐닝 잡이 소스 코드에 액세스하지 못할 수 있습니다. 이 경우 gl-code-quality-report.json 아티팩트가 생성되지 않습니다.

이 문제를 해결하려면 다음 중 하나를 수행합니다:

소켓 바인딩 대신 권한 있는 모드를 사용하는 Docker-in-Docker 문서화된 러너 구성을 사용합니다.
Docker 소켓 바인딩을 계속 사용하려면 이슈 32027의 커뮤니티 해결 방법을 적용합니다.

자세한 내용은 러너 구성 변경을 참조하세요.

코드 품질 문제 해결

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

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

머지 리퀘스트에 코드 품질 보고서가 표시되지 않음#

변경 사항 보기에 코드 품질 기호 없음#

단일 코드 품질 보고서만 표시되지만 더 많이 정의됨#

RuboCop 오류#

커스텀 도구를 사용할 때 머지 리퀘스트에 코드 품질이 표시되지 않음#

오류: Could not analyze code quality#

Kubernetes 또는 OpenShift 러너와 함께 코드 품질 사용#

오류: x509: certificate signed by unknown authority#

Docker#

Kubernetes#

코드 품질 보고서 로드 실패#

보고서 아티팩트가 생성되지 않음#

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

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

머지 리퀘스트에 코드 품질 보고서가 표시되지 않음#

변경 사항 보기에 코드 품질 기호 없음#

단일 코드 품질 보고서만 표시되지만 더 많이 정의됨#

RuboCop 오류#

커스텀 도구를 사용할 때 머지 리퀘스트에 코드 품질이 표시되지 않음#

오류: Could not analyze code quality#

Kubernetes 또는 OpenShift 러너와 함께 코드 품질 사용#

오류: x509: certificate signed by unknown authority#

Docker#

Kubernetes#

코드 품질 보고서 로드 실패#

보고서 아티팩트가 생성되지 않음#

오류: `Could not analyze code quality`#

오류: `x509: certificate signed by unknown authority`#

오류: `Could not analyze code quality`#

오류: `x509: certificate signed by unknown authority`#