컴플라이언스 파이프라인

Tier: Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

그룹 소유자는 다른 프로젝트와 별도로 프로젝트 내에서 컴플라이언스 파이프라인을 구성할 수 있습니다. 기본적으로 컴플라이언스 파이프라인 구성 (예: .compliance-gitlab-ci.yml)은 레이블이 지정된 프로젝트의 파이프라인 구성 (예: .gitlab-ci.yml) 대신 실행됩니다.

그러나 컴플라이언스 파이프라인 구성은 레이블이 지정된 프로젝트의 .gitlab-ci.yml 파일을 참조할 수 있어서 다음과 같은 사항이 가능합니다:

  • 컴플라이언스 파이프라인은 레이블이 지정된 프로젝트 파이프라인의 작업 또한 실행할 수 있습니다. 이는 파이프라인 구성의 중앙 제어를 가능하게 합니다.
  • 컴플라이언스 파이프라인에서 정의된 작업 및 변수는 레이블이 지정된 프로젝트의 .gitlab-ci.yml 파일의 변수에 의해 변경될 수 없습니다.
note
알려진 이슈로 인해 프로젝트 파이프라인은 컴플라이언스 파이프라인 구성 상단에 먼저 포함되어야 합니다. 이것은 하향 설정을 방지하기 위한 조치입니다.

자세한 내용은 다음을 참조하세요:

레이블이 지정된 프로젝트에 미치는 영향

사용자들은 컴플라이언스 파이프라인이 구성되었음을 알 방법이 없으며, 자신의 파이프라인이 전혀 실행되지 않거나 스스로 정의하지 않은 작업을 포함하는 이유에 혼란스러워할 수 있습니다.

레이블이 지정된 프로젝트에서 파이프라인을 작성할 때 컴플라이언스 파이프라인이 구성되었음을 나타내는 방법은 없습니다. 프로젝트 수준에서의 유일한 표시는 컴플라이언스 프레임워크 레이블 자체이지만, 해당 레이블이 컴플라이언스 파이프라인이 구성되어 있는지 여부를 나타내지 않습니다.

따라서 컴플라이언스 파이프라인 구성에 대해 프로젝트 사용자들과 의사 소통하여 불확실성과 혼란을 줄이세요.

컴플라이언스 파이프라인 구성

컴플라이언스 파이프라인을 구성하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
  2. 설정 > 일반을 선택합니다.
  3. 컴플라이언스 프레임워크 섹션을 확장합니다.

  4. 컴플라이언스 파이프라인 구성 (optional)에서 컴플라이언스 프레임워크 구성에 대한 경로를 추가합니다. path/file.y[a]ml@group-name/project-name 형식을 사용하세요. 예를 들어:

    • .compliance-ci.yml@gitlab-org/gitlab.
    • .compliance-ci.yaml@gitlab-org/gitlab.

이 구성은 적용된 컴플라이언스 프레임워크 레이블이 있는 프로젝트에서 상속됩니다. 적용된 컴플라이언스 프레임워크 레이블이 있는 프로젝트에서는 레이블이 지정된 프로젝트의 파이프라인 구성 대신 컴플라이언스 파이프라인 구성이 실행됩니다.

레이블이 지정된 프로젝트에서 파이프라인을 실행하는 사용자는 적어도 컴플라이언스 프로젝트에 대해 리포터 역할을 가져야 합니다.

스캔 실행을 강제로 실행하는 데 사용될 때, 이 기능은 스캔 실행 정책과 일부 중복됩니다. 이 두 기능에 대해 사용자 경험을 통합하지는 않았습니다. 이러한 기능 사이의 유사점과 차이점에 대한 자세한 내용은 스캔 실행 강제를 참조하세요.

예제 구성

다음 예제 .compliance-gitlab-ci.yml은 include 키워드를 포함하여 레이블이 지정된 프로젝트 파이프라인 구성도 실행되도록 합니다. 

include:  # 프로젝트의 개별 구성 실행(프로젝트가 .gitlab-ci.yml을 포함하는 경우)
  - project: '$CI_PROJECT_PATH'
    file: '$CI_CONFIG_PATH'
    ref: '$CI_COMMIT_SHA' # 정의되어 있어야 하며, 그렇지 않으면 MR 파이프라인은 항상 기본 브랜치를 사용합니다
    rules:
      - if: $CI_PROJECT_PATH != "my-group/project-1" #이 구성을 호스트하고 있는 프로젝트의 하드코딩 경로여야 합니다.

# 컴플라이언스 팀이 스테이지/잡의 순서와 중첩을 제어할 수 있습니다.
# 작업이 정의되지 않은 스테이지는 숨겨집니다.
stages:
  - pre-compliance
  - build
  - test
  - pre-deploy-compliance
  - deploy
  - post-compliance

variables:  # 프로젝트의 지역 .gitlab-ci.yml에서 작업별 변수를 설정하여 재정의할 수 있습니다.
  FOO: sast

sast:  # 프로젝트의 지역 .gitlab-ci.yml에서 작업별 변수로 재정의할 수 없습니다.
  variables:
    FOO: sast
  image: ruby:2.6
  stage: pre-compliance
  rules:
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
      when: never
    - when: always  # 또는 when: on_success
  allow_failure: false
  before_script:
    - "# 실행 전 스크립트 없음."
  script:
    - echo "$FOO 실행 중"
  after_script:
    - "# 실행 후 스크립트 없음."

sanity check:
  image: ruby:2.6
  stage: pre-deploy-compliance
  rules:
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
      when: never
    - when: always  # 또는 when: on_success
  allow_failure: false
  before_script:
    - "# 실행 전 스크립트 없음."
  script:
    - echo "$FOO 실행 중"
  after_script:
    - "# 실행 후 스크립트 없음."

audit trail:
  image: ruby:2.7
  stage: post-compliance
  rules:
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
      when: never
    - when: always  # 또는 when: on_success
  allow_failure: false
  before_script:
    - "# 실행 전 스크립트 없음."
  script:
    - echo "$FOO 실행 중"
  after_script:
    - "# 실행 후 스크립트 없음."

include 정의의 rules 구성은 컴플라이언스 파이프라인이 호스트 프로젝트에서 실행되어야 하는 경우에 원형 포함을 피하기 위해 필요합니다. 적용된 컴플라이언스 프레임워크 레이블이 있는 프로젝트에서만 컴플라이언스 파이프라인을 실행해야 하는 경우 이 부분을 뺄 수 있습니다.

외부에서 호스팅된 컴플라이언스 파이프라인 및 사용자 정의 파이프라인 구성

위의 예에서는 모든 프로젝트가 파이프라인 구성을 동일한 프로젝트에 호스팅한다고 가정합니다. 만약 어떤 프로젝트가 프로젝트 외부에서 호스팅된 구성을 사용한다면:

  • 예시로, 컴플라이언스 파이프라인 구성의 include 섹션을 조정해야 합니다. 예를 들어, include:rules를 사용하는 경우: 

    include:
  # 사용자 정의 경로 변수가 정의된 경우, 프로젝트의 외부 구성 파일을 포함합니다.
  - project: '$PROTECTED_PIPELINE_CI_PROJECT_PATH'
    file: '$PROTECTED_PIPELINE_CI_CONFIG_PATH'
    ref: '$PROTECTED_PIPELINE_CI_REF'
    rules:
      - if: $PROTECTED_PIPELINE_CI_PROJECT_PATH && $PROTECTED_PIPELINE_CI_CONFIG_PATH && $PROTECTED_PIPELINE_CI_REF
  # 사용자 정의 경로 변수가 정의되지 않은 경우, 프로젝트의 내부 구성 파일을 일반적으로 포함합니다.
  - project: '$CI_PROJECT_PATH'
    file: '$CI_CONFIG_PATH'
    ref: '$CI_COMMIT_SHA'
    rules:
      - if: $PROTECTED_PIPELINE_CI_PROJECT_PATH == null || $PROTECTED_PIPELINE_CI_CONFIG_PATH == null || $PROTECTED_PIPELINE_CI_REF == null

  • 외부 파이프라인 구성을 사용하는 프로젝트에는 CI/CD 변수를 추가해야 합니다. 예를 들어:

    • PROTECTED_PIPELINE_CI_PROJECT_PATH: 구성 파일을 호스팅하는 프로젝트의 경로, 예: group/subgroup/project.
    • PROTECTED_PIPELINE_CI_CONFIG_PATH: 프로젝트 내 구성 파일의 경로, 예: path/to/.gitlab-ci.yml.
    • PROTECTED_PIPELINE_CI_REF: 구성 파일 검색 시 사용할 참조, 예: main.

프로젝트 포크에서 발생하는 Merge Request의 컴플라이언스 파이프라인

Merge Request이 포크에서 발생하는 경우, 일반적으로 Merge할 브랜치는 포크에만 존재합니다. 이런 경우 컴플라이언스 파이프라인을 사용하는 프로젝트에서 이러한 Merge Request을 만들 때 위의 스니펫은 다음과 같은 오류 메시지 프로젝트 <프로젝트 이름> 참조 <브랜치 이름>이(가) 존재하지 않습니다!와 함께 실패합니다. 이 오류는 대상 프로젝트에서 $CI_COMMIT_REF_NAME이 존재하지 않는 브랜치 이름으로 평가되기 때문에 발생합니다.

올바른 컨텍스트를 얻으려면 $CI_PROJECT_PATH 대신 $CI_MERGE_REQUEST_SOURCE_PROJECT_PATH를 사용하세요. 이 변수는 Merge Request 파이프라인에서만 사용할 수 있습니다.

예를 들어, 프로젝트 포크에서 발생하는 Merge Request 파이프라인과 브랜치 파이프라인을 모두 지원하는 구성을 위해서는 두 include 지시문을 rules:if와 결합해야 합니다: 

include:  # 각 프로젝트의 개별 구성 실행(프로젝트에 .gitlab-ci.yml이 포함되어 있는 경우)
  - project: '$CI_MERGE_REQUEST_SOURCE_PROJECT_PATH'
    file: '$CI_CONFIG_PATH'
    ref: '$CI_COMMIT_REF_NAME'
    rules:
      - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
  - project: '$CI_PROJECT_PATH'
    file: '$CI_CONFIG_PATH'
    ref: '$CI_COMMIT_REF_NAME'
    rules:
      - if: $CI_PIPELINE_SOURCE != 'merge_request_event'

컴플라이언스 작업이 항상 실행되도록 보장

컴플라이언스 파이프라인은 GitLab CI/CD를 사용하여 어떠한 종류의 컴플라이언스 작업을 정의하는 데 놀라운 유연성을 제공합니다. 귀하의 목표에 따라 이러한 작업은 다음과 같이 구성될 수 있습니다:

  • 사용자에 의해 수정됨.
  • 수정할 수 없음.

일반적으로 컴플라이언스 작업의 값이:

  • 설정되면 프로젝트 수준의 구성에서 변경하거나 무시할 수 없습니다.
  • 설정되지 않으면 프로젝트 수준의 구성에서 설정하고 동작을 변경할 수 있습니다.

이용 사례에 따라 원하는 대로 원할 수도 있고 그렇지 않을 수도 있습니다.

다음은 이러한 작업이 항상 귀하가 정의한 대로 실행되고 하향식으로 프로젝트 수준의 파이프라인 구성에서 변경되지 않도록 보장하기 위한 몇 가지 모범 사례입니다:

  • 각각의 컴플라이언스 작업에 rules:when:always 블록을 추가합니다. 이렇게 하면 그들이 수정할 수 없으며 항상 실행됩니다.
  • 작업이 참조하는 변수를 명시적으로 설정합니다. 이렇게 하면 프로젝트 수준의 파이프라인 구성이 설정되어 수정되어 동작을 변경하지 않습니다. 예를 들어, 예시 구성에서 before_script 및 after_script 구성을 참조하세요.
  • 작업을 실행하는 컨테이너 이미지를 명시적으로 설정합니다. 이렇게 하면 스크립트 단계가 올바른 환경에서 실행됩니다.
  • 관련된 GitLab 사전 정의 작업 키워드를 명시적으로 설정합니다. 이렇게 하면 귀하가 의도한 설정을 사용하고 프로젝트 수준의 파이프라인에 의해 재정의되지 않습니다.

GitLab 14.7 및 이전 버전에서 상속된/자식 파이프라인 피하기

note
이 조언은 수정 사항이 추가된 GitLab 14.8 및 이후 버전에는 적용되지 않습니다. 이 수정 사항은 컴플라이언스 파이프라인, 상속된/자식 파이프라인을 조합하는 호환성을 추가했습니다.

컴플라이언스 파이프라인은 라벨링된 프로젝트의 모든 파이프라인 실행에서 시작됩니다. 이는 라벨이 붙은 프로젝트의 파이프라인이 자식 파이프라인을 트리거하는 경우에 컴플라이언스 파이프라인이 먼저 실행됨을 의미합니다. 이는 부모 파이프라인이 아닌 자식 파이프라인을 트리거할 수 있습니다.

따라서 컴플라이언스 프레임워크가 있는 프로젝트에서는 다음과 같이 부모-자식 파이프라인을 다음과 같이 대체해야 합니다.

  • 부모 파이프라인에 자식 파이프라인 구성을 제공하는 직접적인 include 문.
  • 부모-자식 파이프라인 기능이 아닌 트리거 API를 사용하여 다른 프로젝트에 있는 자식 파이프라인을 실행합니다.

이 대체본은 컴플라이언스 파이프라인이 부모 파이프라인을 다시 시작하지 않도록 보장합니다.

문제 해결

컴플라이언스 작업이 대상 리포지터리에 덮어씌워짐

컴플라이언스 파이프라인 구성에서 extends 문을 사용하면 대상 리포지터리 작업에 의해 컴플라이언스 작업이 덮어씌워집니다. 예를 들어, 다음과 같이 .compliance-gitlab-ci.yml 구성을 가질 수 있습니다: 

"컴플라이언스 작업":
  extends:
    - .compliance_template
  stage: build

.compliance_template:
  script:
    - echo "컴플라이언스 조치 실행"

다음과 같이 .gitlab-ci.yml 구성을 가질 수도 있습니다: 

"컴플라이언스 작업":
  stage: test
  script:
    - echo "컴플라이언스 조치 덮어쓰기"

이 구성은 대상 리포지터리 파이프라인이 컴플라이언스 파이프라인을 덮어씌우고 컴플라이언스 조치 덮어쓰기 메시지가 나타납니다.

컴플라이언스 작업을 덮어씌우지 않으려면 컴플라이언스 파이프라인 구성에서 extends 키워드를 사용하지 않습니다. 예를 들어, 다음과 같이 .compliance-gitlab-ci.yml 구성을 가질 수 있습니다: 

"컴플라이언스 작업":
  stage: build
  script:
    - echo "컴플라이언스 조치 실행"

다음과 같이 .gitlab-ci.yml 구성을 가질 수도 있습니다: 

"컴플라이언스 작업":
  stage: test
  script:
    - echo "컴플라이언스 조치 덮어쓰기"

이 구성은 컴플라이언스 파이프라인을 덮어쓰지 않으며 컴플라이언스 조치 실행 메시지가 나타납니다.

사전 입력된 변수 표시되지 않음

GitLab 15.3 이후의 컴플라이언스 파이프라인에서는 알려진 문제로 인해 매뉴얼으로 파이프라인을 시작할 때 사전 입력된 변수가 나타나지 않을 수 있습니다.

이 문제를 해결하기 위해 개별 프로젝트의 구성을 실행하는 include: 문에서 ref: '$CI_COMMIT_REF_NAME' 대신에 ref: '$CI_COMMIT_SHA'를 사용하십시오.

이 변경 사항이 반영된 예제 구성은 다음과 같습니다: 

include:
  - project: '$CI_PROJECT_PATH'
    file: '$CI_CONFIG_PATH'
    ref: '$CI_COMMIT_SHA'