코드 품질에는 기본 제공 CI/CD 템플릿 Code-Quality.gitlab-ci.yaml이 포함됩니다. 이 템플릿은 오픈 소스 CodeClimate 스캔 엔진을 기반으로 스캔을 실행합니다.

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

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

CodeClimate 기반 스캔 활성화#

사전 조건:

• GitLab CI/CD 설정(.gitlab-ci.yml)에 test 스테이지가 포함되어야 합니다.
• 인스턴스 러너를 사용하는 경우 코드 품질 잡은 Docker-in-Docker 워크플로우에 맞게 구성되어야 합니다. 이 워크플로우를 사용할 때 보고서를 저장할 수 있도록 /builds 볼륨이 매핑되어야 합니다.
• 개인 러너를 사용하는 경우 코드 품질 분석을 더 효율적으로 실행하기 위해 권장되는 대체 설정을 사용해야 합니다.
• 러너는 생성된 코드 품질 파일을 저장하기에 충분한 디스크 공간이 있어야 합니다. 예를 들어, GitLab 프로젝트에서 파일 크기는 약 7GB입니다.

코드 품질을 활성화하려면 다음 중 하나를 수행하세요:

• Auto Code Quality가 포함된 Auto DevOps 활성화.

• .gitlab-ci.yml 파일에 코드 품질 템플릿 포함.

  예시:

     include:
     - template: Jobs/Code-Quality.gitlab-ci.yml
  

  코드 품질이 파이프라인에서 실행됩니다.

CodeClimate 기반 스캔 비활성화#

CI_DEBUG_SERVICES CI/CD 변수가 있으면 code_quality 잡이 실행되지 않습니다. 변수 정의 방법에 대한 자세한 내용은 GitLab CI/CD 변수를 참조하세요.

코드 품질을 비활성화하려면 다음 중 하나에 대해 CODE_QUALITY_DISABLED라는 커스텀 CI/CD 변수를 생성하세요:

• 전체 프로젝트.
• 단일 파이프라인.

CodeClimate 분석 플러그인 구성#

기본적으로 code_quality 잡은 CodeClimate를 다음과 같이 구성합니다:

• 특정 플러그인 집합 사용.
• 해당 플러그인에 대한 기본 설정 사용.

더 많은 언어를 스캔하려면 더 많은 플러그인을 활성화할 수 있습니다. code_quality 잡이 기본적으로 활성화하는 플러그인을 비활성화할 수도 있습니다.

예를 들어 SonarJava 분석기를 사용하려면:

1. 저장소 루트에 .codeclimate.yml이라는 파일을 추가하세요.

2. 저장소 루트의 .codeclimate.yml 파일에 플러그인의 활성화 코드를 추가하세요:

   version: "2"
   plugins:
     sonar-java:
       enabled: true
   

이렇게 하면 프로젝트에 포함된 기본 .codeclimate.yml의 plugins: 섹션에 SonarJava가 추가됩니다.

plugins: 섹션의 변경 사항은 기본 .codeclimate.yml의 exclude_patterns 섹션에 영향을 주지 않습니다. 자세한 내용은 파일 및 폴더 제외에 대한 Code Climate 문서를 참조하세요.

스캔 잡 설정 사용자 정의#

GitLab CI/CD YAML에서 CI/CD 변수를 설정하여 code_quality 스캔 잡의 동작을 변경할 수 있습니다.

코드 품질 잡을 구성하려면:

1. 템플릿 포함 후 코드 품질 잡과 동일한 이름으로 잡을 선언하세요.
2. 잡의 스탠자에 추가 키를 지정하세요.

예시는 HTML 형식으로 출력 다운로드를 참조하세요.

사용 가능한 CI/CD 변수 {#available-cicd-variables}#

사용 가능한 CI/CD 변수를 정의하여 코드 품질을 사용자 정의할 수 있습니다:

출력#

코드 품질은 발견된 이슈의 세부 사항이 포함된 보고서를 출력합니다. 이 보고서의 내용은 내부적으로 처리되고 결과가 UI에 표시됩니다. 보고서는 또한 code_quality 잡의 잡 아티팩트로 gl-code-quality-report.json이라는 이름으로 출력됩니다. 선택적으로 HTML 형식으로 보고서를 출력할 수 있습니다. 예를 들어 더 쉬운 검토를 위해 GitLab Pages에 HTML 형식 파일을 게시할 수 있습니다.

JSON 및 HTML 형식으로 출력#

코드 품질 보고서를 JSON과 HTML 형식으로 출력하려면 추가 잡을 만들어야 합니다. 이를 위해서는 각 파일 형식에 한 번씩 코드 품질을 두 번 실행해야 합니다.

HTML 형식으로 코드 품질 보고서를 출력하려면 extends: code_quality를 사용하여 템플릿에 다른 잡을 추가하세요:

include:
  - template: Jobs/Code-Quality.gitlab-ci.yml

code_quality_html:
  extends: code_quality
  variables:
    REPORT_FORMAT: html
  artifacts:
    paths: [gl-code-quality-report.html]

JSON과 HTML 파일 모두 잡 아티팩트로 출력됩니다. HTML 파일은 artifacts.zip 잡 아티팩트에 포함됩니다.

HTML 형식으로만 출력 {#output-in-only-html-format}#

코드 품질 보고서를 HTML 형식으로만 다운로드하려면 code_quality 잡의 기본 정의를 재정의하여 REPORT_FORMAT을 html로 설정하세요.

include:
  - template: Jobs/Code-Quality.gitlab-ci.yml

code_quality:
  variables:
    REPORT_FORMAT: html
  artifacts:
    paths: [gl-code-quality-report.html]

HTML 파일이 잡 아티팩트로 출력됩니다.

머지 요청 파이프라인과 함께 코드 품질 사용#

기본 코드 품질 설정은 머지 요청 파이프라인에서 code_quality 잡이 실행되도록 허용하지 않습니다.

머지 요청 파이프라인에서 코드 품질이 실행되도록 활성화하려면 현재 rules와 일치하도록 코드 품질 rules 또는 workflow: rules를 덮어쓰세요.

예를 들어:

include:
  - template: Jobs/Code-Quality.gitlab-ci.yml

code_quality:
  rules:
    - if: $CODE_QUALITY_DISABLED
      when: never
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" # 머지 요청 파이프라인에서 코드 품질 잡 실행
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH      # 기본 브랜치의 파이프라인에서 코드 품질 잡 실행 (다른 브랜치 파이프라인은 제외)
    - if: $CI_COMMIT_TAG                               # 태그 파이프라인에서 코드 품질 잡 실행

CodeClimate 이미지 다운로드 방법 변경#

CodeClimate 엔진은 각 플러그인을 실행하기 위해 컨테이너 이미지를 다운로드합니다. 기본적으로 이미지는 Docker Hub에서 다운로드됩니다. 성능 향상, Docker Hub 속도 제한 우회 또는 개인 레지스트리 사용을 위해 이미지 소스를 변경할 수 있습니다.

Dependency Proxy를 사용하여 이미지 다운로드#

종속성 다운로드 시간을 줄이기 위해 Dependency Proxy를 사용할 수 있습니다.

사전 조건:

• 프로젝트 그룹에서 Dependency Proxy가 활성화되어 있어야 합니다.

Dependency Proxy를 참조하려면 .gitlab-ci.yml 파일에서 다음 변수를 구성하세요:

• CODE_QUALITY_IMAGE
• CODECLIMATE_PREFIX
• CODECLIMATE_REGISTRY_USERNAME
• CODECLIMATE_REGISTRY_PASSWORD

예를 들어:

include:
  - template: Jobs/Code-Quality.gitlab-ci.yml

code_quality:
  variables:
    ## `$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`에 후행 슬래시를 추가해야 합니다.
    CODECLIMATE_PREFIX: $CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX/
    CODECLIMATE_REGISTRY_USERNAME: $CI_DEPENDENCY_PROXY_USER
    CODECLIMATE_REGISTRY_PASSWORD: $CI_DEPENDENCY_PROXY_PASSWORD

인증으로 Docker Hub 사용#

코드 품질 이미지의 대체 소스로 Docker Hub를 사용할 수 있습니다.

사전 조건:

• 프로젝트에서 사용자 이름과 비밀번호를 보호된 CI/CD 변수로 추가하세요.

DockerHub를 사용하려면 .gitlab-ci.yml 파일에서 다음 변수를 구성하세요:

• CODECLIMATE_PREFIX
• CODECLIMATE_REGISTRY_USERNAME
• CODECLIMATE_REGISTRY_PASSWORD

예시:

include:
  - template: Jobs/Code-Quality.gitlab-ci.yml

code_quality:
  variables:
    CODECLIMATE_PREFIX: "registry-1.docker.io/"
    CODECLIMATE_REGISTRY_USERNAME: $DOCKERHUB_USERNAME
    CODECLIMATE_REGISTRY_PASSWORD: $DOCKERHUB_PASSWORD

개인 컨테이너 이미지 레지스트리 사용 {#use-a-private-container-image-registry}#

개인 컨테이너 이미지 레지스트리를 사용하면 이미지 다운로드 시간을 줄이고 외부 의존성을 줄일 수 있습니다. 컨테이너 실행의 중첩 메서드 때문에 개별 엔진에 대한 CodeClimate의 후속 docker pull 명령에 전달되도록 레지스트리 접두사를 구성해야 합니다.

다음 변수들로 필요한 모든 이미지 풀을 처리할 수 있습니다:

• CODE_QUALITY_IMAGE: 잡 환경에서 접근 가능한 어디서나 위치할 수 있는 완전한 접두사가 있는 이미지 이름. GitLab 컨테이너 레지스트리를 사용하여 자체 복사본을 호스팅할 수 있습니다.
• CODECLIMATE_PREFIX: 의도한 컨테이너 이미지 레지스트리의 도메인. 이것은 CodeClimate CLI에서 지원하는 설정 옵션입니다. 다음을 수행해야 합니다:
  • 후행 슬래시(/) 포함.
  • https://와 같은 프로토콜 접두사 미포함.
• CODECLIMATE_REGISTRY_USERNAME: CODECLIMATE_PREFIX에서 파싱된 레지스트리 도메인의 사용자 이름을 지정하기 위한 선택적 변수.
• CODECLIMATE_REGISTRY_PASSWORD: CODECLIMATE_PREFIX에서 파싱된 레지스트리 도메인의 비밀번호를 지정하기 위한 선택적 변수.

include:
  - template: Jobs/Code-Quality.gitlab-ci.yml

code_quality:
  variables:
    CODE_QUALITY_IMAGE: "my-private-registry.local:12345/codequality:0.85.24"
    CODECLIMATE_PREFIX: "my-private-registry.local:12345/"

이 예시는 GitLab 코드 품질에 특화되어 있습니다. 레지스트리 미러로 DinD를 구성하는 방법에 대한 일반적인 지침은 Docker-in-Docker 서비스를 위한 레지스트리 미러 활성화를 참조하세요.

필요한 이미지#

기본 .codeclimate.yml에는 다음 이미지가 필요합니다:

• codeclimate/codeclimate-structure:latest
• codeclimate/codeclimate-csslint:latest
• codeclimate/codeclimate-coffeelint:latest
• codeclimate/codeclimate-duplication:latest
• codeclimate/codeclimate-eslint:latest
• codeclimate/codeclimate-fixme:latest
• codeclimate/codeclimate-rubocop:rubocop-0-92

커스텀 .codeclimate.yml 설정 파일을 사용하는 경우 지정된 플러그인을 개인 컨테이너 레지스트리에 추가해야 합니다.

Runner 설정 변경#

CodeClimate는 각 분석 단계에 대해 별도의 컨테이너를 실행합니다. CodeClimate 기반 스캔이 실행되거나 더 빠르게 실행되도록 Runner 설정을 조정해야 할 수 있습니다.

개인 러너 사용 {#use-private-runners}#

개인 러너가 있는 경우 다음 이유로 코드 품질 성능 향상을 위해 이 설정을 사용해야 합니다:

• 권한 모드가 사용되지 않습니다.
• Docker-in-Docker가 사용되지 않습니다.
• 모든 CodeClimate 이미지를 포함한 Docker 이미지가 캐시되고 후속 잡을 위해 다시 가져오지 않습니다.

이 대체 설정은 소켓 바인딩을 사용하여 러너의 Docker 데몬을 잡 환경과 공유합니다. 이 설정을 구현하기 전에 해당 제한 사항을 고려하세요.

개인 러너를 사용하려면:

1. 새 러너를 등록하세요:

   $ gitlab-runner register --executor "docker" \
     --docker-image="docker:cli" \
     --url "https://gitlab.com/" \
     --description "cq-sans-dind" \
     --docker-volumes "/cache"\
     --docker-volumes "/builds:/builds"\
     --docker-volumes "/var/run/docker.sock:/var/run/docker.sock" \
     --registration-token="<project_token>" \
     --non-interactive
   

2. 선택 사항이지만 권장됨: 잡 아티팩트가 러너 호스트에서 주기적으로 제거되도록 빌드 디렉토리를 /tmp/builds로 설정하세요. 이 단계를 건너뛰면 기본 빌드 디렉토리(/builds)를 직접 정리해야 합니다. 이전 단계에서 gitlab-runner register에 다음 두 플래그를 추가하여 수행할 수 있습니다.

   --builds-dir "/tmp/builds"
   --docker-volumes "/tmp/builds:/tmp/builds" # --docker-volumes "/builds:/builds" 대신 사용
   

   결과 설정:

   [[runners]]
     name = "cq-sans-dind"
     url = "https://gitlab.com/"
     token = "<project_token>"
     executor = "docker"
     builds_dir = "/tmp/builds"
     [runners.docker]
       tls_verify = false
       image = "docker:cli"
       privileged = false
       disable_entrypoint_overwrite = false
       oom_kill_disable = false
       disable_cache = false
       volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock", "/tmp/builds:/tmp/builds"]
       shm_size = 0
     [runners.cache]
       [runners.cache.s3]
       [runners.cache.gcs]
   

3. 템플릿으로 생성된 code_quality 잡에 두 가지 재정의를 적용하세요:

   include:
     - template: Jobs/Code-Quality.gitlab-ci.yml
   
   code_quality:
     services:            # Docker-in-Docker 종료
     tags:
       - cq-sans-dind     # 새로 만든 특수 러너에서만 이 잡이 실행되도록 설정
   

코드 품질이 이제 표준 Docker 모드에서 실행됩니다.

개인 러너로 루트리스 CodeClimate 실행#

개인 러너를 사용하고 루트리스 Docker 모드에서 코드 품질 스캔을 실행하려는 경우 코드 품질이 올바르게 실행되도록 특별한 변경이 필요합니다. 소켓 바인딩의 변경이 다른 잡에서 문제를 일으킬 수 있기 때문에 코드 품질 잡만 실행하는 전용 러너가 필요할 수 있습니다.

루트리스 개인 러너를 사용하려면:

1. 새 러너를 등록하세요:

   /run/user/<gitlab-runner-user>/docker.sock을 gitlab-runner 사용자의 로컬 docker.sock 경로로 교체하세요.

   $ gitlab-runner register --executor "docker" \
     --docker-image="docker:cli" \
     --url "https://gitlab.com/" \
     --description "cq-rootless" \
     --tag-list "cq-rootless" \
     --locked="false" \
     --access-level="not_protected" \
     --docker-volumes "/cache" \
     --docker-volumes "/tmp/builds:/tmp/builds" \
     --docker-volumes "/run/user/<gitlab-runner-user>/docker.sock:/run/user/<gitlab-runner-user>/docker.sock" \
     --token "<project_token>" \
     --non-interactive \
     --builds-dir "/tmp/builds" \
     --env "DOCKER_HOST=unix:///run/user/<gitlab-runner-user>/docker.sock" \
     --docker-host "unix:///run/user/<gitlab-runner-user>/docker.sock"
   

   결과 설정:

   [[runners]]
     name = "cq-rootless"
     url = "https://gitlab.com/"
     token = "<project_token>"
     executor = "docker"
     builds_dir = "/tmp/builds"
     environment = ["DOCKER_HOST=unix:///run/user/<gitlab-runner-user>/docker.sock"]
     [runners.docker]
       tls_verify = false
       image = "docker:cli"
       privileged = false
       disable_entrypoint_overwrite = false
       oom_kill_disable = false
       disable_cache = false
       volumes = ["/cache", "/run/user/<gitlab-runner-user>/docker.sock:/run/user/<gitlab-runner-user>/docker.sock", "/tmp/builds:/tmp/builds"]
       shm_size = 0
       host = "unix:///run/user/<gitlab-runner-user>/docker.sock"
     [runners.cache]
       [runners.cache.s3]
       [runners.cache.gcs]
   

2. 템플릿으로 생성된 code_quality 잡에 다음 재정의를 적용하세요:

   code_quality:
     services:
     variables:
       DOCKER_SOCKET_PATH: /run/user/997/docker.sock
     tags:
       - cq-rootless
   

코드 품질이 이제 표준 Docker 모드 및 루트리스로 실행됩니다.

코드 품질로 루트리스 Podman을 사용하여 Docker를 실행하는 것이 목표인 경우에도 동일한 설정이 필요합니다. /run/user/<gitlab-runner-user>/docker.sock을 시스템의 올바른 podman.sock 경로로 교체하세요. 예를 들어: /run/user/<gitlab-runner-user>/podman/podman.sock.

Kubernetes 또는 OpenShift 러너 설정#

코드 품질을 사용하려면 Docker 컨테이너에서 Docker(Docker-in-Docker)를 설정해야 합니다. Kubernetes 실행기는 Docker-in-Docker를 지원합니다.

Kubernetes 실행기에서 코드 품질 잡이 실행될 수 있도록 하려면:

• TLS를 사용하여 Docker 데몬과 통신하는 경우 실행기가 권한 모드에서 실행되어야 합니다. 또한 인증서 디렉토리가 볼륨 마운트로 지정되어야 합니다.
• 코드 품질 잡이 시작되기 전에 DinD 서비스가 완전히 시작되지 않을 수 있습니다. 이는 Kubernetes 실행기 문제 해결에 문서화된 제한 사항입니다. 이 문제를 해결하려면 before_script를 사용하여 Docker 데몬이 완전히 부팅될 때까지 기다리세요. 예시는 다음 섹션에서 설명하는 .gitlab-ci.yml 파일의 설정을 참조하세요.

Kubernetes#

Kubernetes에서 코드 품질을 실행하려면:

• Docker in Docker 서비스를 config.toml 파일에 서비스 컨테이너로 추가해야 합니다.
• 서비스 컨테이너의 Docker 데몬은 코드 품질이 두 소켓을 모두 필요로 하기 때문에 TCP 및 UNIX 소켓에서 수신 대기해야 합니다.
• Docker 소켓을 볼륨과 공유해야 합니다.

Docker 요구 사항으로 인해 서비스 컨테이너에서 권한 플래그를 활성화해야 합니다.

[runners.kubernetes]

[runners.kubernetes.service_container_security_context]
privileged = true
allow_privilege_escalation = true

[runners.kubernetes.volumes]

[[runners.kubernetes.volumes.empty_dir]]
mount_path = "/var/run/"
name = "docker-sock"

[[runners.kubernetes.services]]
alias = "dind"
command = [
    "--host=tcp://0.0.0.0:2375",
    "--host=unix://var/run/docker.sock",
    "--storage-driver=overlay2"
]
entrypoint = ["dockerd"]
name = "docker:29.1.4-dind"

최고의 전반적인 성능을 제공하는 overlay2 스토리지 드라이버를 사용하도록 하려면:

• Docker CLI가 통신하는 DOCKER_HOST를 지정하세요.
• DOCKER_DRIVER 변수를 비어 있게 설정하세요.

before_script 섹션을 사용하여 Docker 데몬이 완전히 부팅될 때까지 기다리세요. GitLab Runner v16.9부터 HEALTHCHECK_TCP_PORT 변수를 설정하는 것만으로도 이를 수행할 수 있습니다.

include:
  - template: Code-Quality.gitlab-ci.yml

code_quality:
  services: []
  variables:
    DOCKER_HOST: tcp://dind:2375
    DOCKER_DRIVER: ""
  before_script:
    - while ! docker info > /dev/null 2>&1; do sleep 1; done

OpenShift#

OpenShift의 경우 GitLab Runner Operator를 사용해야 합니다. 서비스 컨테이너의 Docker 데몬에 스토리지 초기화 권한을 부여하려면 /var/lib 디렉토리를 볼륨 마운트로 마운트해야 합니다.

Docker 데몬 권한을 설정하려면:

1. 이 설정 템플릿을 사용하여 러너의 설정을 사용자 정의하는 config.toml 파일을 만드세요:

[[runners]]

[runners.kubernetes]

[runners.kubernetes.service_container_security_context]
privileged = true
allow_privilege_escalation = true

[runners.kubernetes.volumes]

[[runners.kubernetes.volumes.empty_dir]]
mount_path = "/var/run/"
name = "docker-sock"

[[runners.kubernetes.volumes.empty_dir]]
mount_path = "/var/lib/"
name = "docker-data"

[[runners.kubernetes.services]]
alias = "dind"
command = [
    "--host=tcp://0.0.0.0:2375",
    "--host=unix://var/run/docker.sock",
    "--storage-driver=overlay2"
]
entrypoint = ["dockerd"]
name = "docker:29.1.4-dind"

1. 러너에 커스텀 설정 적용.

2. 선택 사항. 빌드 Pod에 privileged 서비스 계정 연결. 이는 OpenShift 클러스터 설정에 따라 달라집니다:

   oc create sa dind-sa
   oc adm policy add-scc-to-user anyuid -z dind-sa
   oc adm policy add-scc-to-user -z dind-sa privileged
   

3. [runners.kubernetes] 섹션에서 권한을 설정하세요.

4. Kubernetes 경우와 동일하게 잡 정의를 유지하세요:

   include:
   - template: Code-Quality.gitlab-ci.yml
   
   code_quality:
   services: []
   variables:
     DOCKER_HOST: tcp://dind:2375
     DOCKER_DRIVER: ""
   before_script:
     - while ! docker info > /dev/null 2>&1; do sleep 1; done
   

볼륨 및 Docker 스토리지#

Docker는 모든 데이터를 /var/lib 볼륨에 저장하며, 이는 대용량 볼륨이 될 수 있습니다. 클러스터 전체에서 Docker-in-Docker 스토리지를 재사용하려면 대안으로 영구 볼륨을 사용할 수 있습니다.