파이프라인 실행 정책

Tier: Ultimate Offering: GitLab.com, 자체 관리, GitLab 전용
이 기능의 가용성은 피처 플래그로 제어됩니다. 자세한 정보는 이력을 확인하세요.

파이프라인 실행 정책을 사용하여 모든 적용 가능한 프로젝트에 대해 CI/CD 작업을 실행합니다.

파이프라인 실행 정책 스키마

  • suffix 필드는 GitLab 17.4에서 소개되었습니다.

파이프라인 실행 정책을 가진 YAML 파일은 pipeline_execution_policy 키 아래 중첩된 파이프라인 실행 정책 스키마와 일치하는 객체 배열로 구성됩니다. 보안 정책 프로젝트 당 pipeline_execution_policy 키 아래 최대 다섯 개의 정책을 구성할 수 있습니다. 첫 다섯 개 이후 구성된 다른 정책은 적용되지 않습니다.

새 정책을 저장할 때 GitLab은 해당 내용을 이 JSON 스키마에 대해 유효성을 검사합니다. JSON 스키마의 읽는 방법을 잘 모르신다면, 다음 섹션 및 표가 대안으로 제공됩니다.

필드 유형 필수 설명
pipeline_execution_policy 파이프라인 실행 정책의 배열 true 파이프라인 실행 정책 목록 (최대 다섯 개)

파이프라인 실행 정책 스키마

필드 유형 필수 설명
name 문자열 true 정책의 이름. 최대 255자까지 가능합니다.
description (선택 사항) 문자열 true 정책 설명.
enabled 부울 true 정책을 활성화(true) 또는 비활성화(false)하는 플래그.
content content의 객체 true 프로젝트 파이프라인에 삽입할 CI/CD 구성에 대한 참조.
pipeline_config_strategy 문자열 false inject_ci 또는 override_project_ci 중 하나일 수 있습니다. 자세한 내용은 파이프라인 전략을 참조하세요.
suffix 문자열 false on_conflict(기본) 또는 never 중 하나일 수 있습니다. 프로젝트 및 모든 해당 정책에서 작업명이 고유하지 않은 작업명에 대해 작업명 충돌 처리 동작을 정의합니다. on_conflict는 고유성을 깨뜨리는 작업들을 위해 작업명 뒤에 고유한 접미사를 적용합니다. never는 프로젝트 및 모든 적용 가능한 정책에 걸쳐 작업명이 고유하지 않다면 파이프라인이 실패합니다.
policy_scope policy_scope의 객체 false 규정 프레임워크 레이블 또는 정의한 프로젝트를 기준으로 정책을 범위 지정합니다.

다음 사항을 유의하세요:

  • 파이프라인을 트리거하는 사용자는 파이프라인 실행 파일에 적어도 읽기 액세스해야 하며, 그렇지 않으면 파이프라인이 시작되지 않습니다.
  • 파이프라인 실행 파일이 삭제되거나 이름이 변경되면 정책이 실행된 프로젝트의 파이프라인이 작동을 멈출 수 있습니다.
  • 파이프라인 실행 정책 작업은 다음 두 예약된 단계 중 하나에 할당할 수 있습니다:
    • .pipeline-policy-pre: .pre 단계 앞에 처음에 기본으로 설정된 파이프라인 앞에서 실행됩니다.
    • .pipeline-policy-post: .post 단계 후에 기본으로 설정된 파이프라인의 마지막에 실행됩니다.
  • 예약된 단계 중 하나에 작업을 삽입하면 항상 작동할 수 있습니다. 실행 정책 작업은 표준(빌드, 테스트, 배포) 또는 사용자가 선언한 단계 중 하나에 할당될 수도 있습니다. 그러나 이 경우 프로젝트 파이프라인 구성에 따라 작업이 무시될 수 있습니다.
  • 파이프라인 실행 정책이 적용된 프로젝트에 CI/CD 구성 파일이 없어도 파이프라인 실행 정책은 계속 유지됩니다.
  • 정책의 순서는 적용된 접미사에 영향을 미칩니다.
  • 주어진 프로젝트에 적용된 모든 정책 중 하나라도 suffix: never를 가지고 있다면 다른 프로젝트의 파이프라인에 동일한 이름의 다른 작업이 이미 있으면 파이프라인이 실패합니다.

작업명 작성 규칙

  • GitLab 17.4에서 작업명 충돌 처리가 소개되었습니다.

보안 정책에서 나온 작업에 대한 시각적인 표시가 없습니다. 작업명에 고유한 접두사 또는 접미사를 추가하면 이를 식별하고 작업명 충돌을 피할 수 있습니다.

예시:

  • policy1:deployments:sast - 좋음, 정책 및 프로젝트 전체에서 고유합니다.
  • sast - 나쁨, 다른 곳에서 사용될 가능성이 높습니다.

파이프라인 실행 정책은 suffix 속성에 따라 이름 충돌을 처리합니다.

  • on_conflict(기본) 사용 시, 파이프라인의 작업명이 다른 작업명과 충돌하면 접미사가 추가됩니다.
  • never 사용 시, 충돌 시 접미사가 추가되지 않고 파이프라인이 실패합니다.

적용된 접미사는 다음과 같은 순서로 추가됩니다:

  1. 프로젝트 파이프라인 작업
  2. 프로젝트 정책 작업 (적용 가능한 경우)
  3. 그룹 정책 작업 (적용 가능한 경우, 계층 구조에 따라 정렬되며 최상위 그룹이 마지막으로 적용됨)

적용된 접미사의 형식은 다음과 같습니다:

:policy-<security-policy-project-id>-<policy-index>.

결과적으로 생성된 작업의 예시: sast:policy-123456-0.

보안 정책 프로젝트에서 여러 정책이 동일한 작업명을 정의하는 경우, 숫자 접미사는 충돌 정책의 인덱스에 해당합니다.

결과적으로 생성된 작업의 예시:

  • sast:policy-123456-0
  • sast:policy-123456-1

업무 단계 최상의 실천 방법

파이프라인 실행 정책에서 정의된 작업은 프로젝트의 CI/CD 구성에서 정의된 단계로 사용할 수 있으며, 또한 예약된 단계인 .pipeline-policy-pre와 .pipeline-policy-post도 사용할 수 있습니다.

참고: 정책에 .pre와 .post 단계에서만 작업이 포함된 경우, 정책의 파이프라인은 “비어있는”으로 평가되어 프로젝트의 파이프라인과 병합되지 않습니다. 파이프라인 실행 정책에서 .pre 및 .post 단계를 사용하려면 예를 들어 .pipeline-policy-pre에서 사용 가능한 다른 단계에서 실행되는 작업을 반드시 포함해야 합니다.

inject_ci 파이프라인 전략을 사용할 때 대상 프로젝트에 자체 .gitlab-ci.yml 파일이 없으면 기본 파이프라인 단계와 예약된 단계만 사용할 수 있습니다.

다른 프로젝트의 CI/CD 구성을 제어하지 않는 프로젝트에 파이프라인 실행 정책을 강제로 적용할 때, 반드시 작업을 .pipeline-policy-pre 및 .pipeline-policy-post 단계에 정의해야 합니다. 이러한 단계는 프로젝트의 CI/CD 구성 여부에 관계없이 항상 사용할 수 있습니다.

content 유형

필드 유형 필수 설명
project string true 동일한 GitLab 인스턴스의 프로젝트에 대한 전체 GitLab 프로젝트 경로입니다.
file string true 루트 디렉터리 (/)를 기준으로 한 전체 파일 경로입니다. YAML 파일은 .yml 또는 .yaml 확장자를 가져야 합니다.
ref string false 파일을 검색할 ref입니다. 지정되지 않은 경우 프로젝트의 HEAD가 기본값입니다.

정책에서 content 유형을 사용하여 다른 저장소에 저장된 CI/CD 구성을 참조할 수 있습니다. 이를 통해 동일한 CI/CD 구성을 여러 정책에서 재사용하여 이러한 구성을 유지하는 오버헤드를 줄일 수 있습니다. 예를 들어, 정책 A 및 정책 B에서 강제로 적용하려는 사용자 정의 비밀 감지 CI/CD 구성이 있다면, 단일 YAML 구성 파일을 작성하고 해당 구성을 둘 다 참조할 수 있습니다.

전제 조건:

  • content 유형을 포함하는 정책을 포함하는 프로젝트에서 파이프라인을 트리거하는 사용자는 해당 CI/CD를 포함하는 프로젝트에 대해 최소한 읽기 전용 액세스를 가져야 합니다.
  • 파이프라인 실행 정책을 강제로 적용하는 프로젝트에서, 사용자는 파이프라인을 트리거하기 위해 해당 프로젝트에 대해 최소한 읽기 전용 액세스를 가져야 합니다.

GitLab 17.4 이상에서 보안 정책 프로젝트에서 지정된 CI/CD 구성 파일에 대한 필요한 읽기 전용 액세스를 부여하려면, 일반 설정에서 파이프라인 실행 정책 설정을 활성화하면 됩니다. 이 설정을 활성화하면 파이프라인을 트리거한 사용자가 파이프라인 실행 정책에 의해 강제된 CI/CD 구성 파일을 읽을 수 있습니다. 이 설정은 구성 파일이 저장된 프로젝트의 다른 부분에 대한 사용자 액세스를 부여하지 않습니다.

policy_scope 스코프 유형

  • GitLab 17.4에서 도입된 그룹별 스코핑입니다. 소개됨.
필드 유형 가능한 값 설명
compliance_frameworks array   적용 범위 내의 컴플라이언스 프레임워크 ID 목록인 id 키를 가진 객체의 배열입니다.
projects object including, excluding excluding: 또는 including:를 사용한 다음 포함하거나 제외할 프로젝트의 ID 목록, id 키를 가진 객체의 배열입니다.
groups object including including:를 사용한 다음 포함할 그룹의 ID 목록, id 키를 가진 객체의 배열입니다.

예시:

특정 컴플라이언스 프레임워크를 사용하는 프로젝트: 

policy_scope:
  compliance_frameworks:
    - id: 1020076

특정 집합의 프로젝트만: 

policy_scope:
  projects:
    including:
      - id: 61213118
      - id: 59560885

한 가지 특정 프로젝트를 제외한 모든 프로젝트: 

policy_scope:
  projects:
    excluding:
      - id: 59560885

파이프라인 전략

파이프라인 구성 전략은 정책 구성을 프로젝트 파이프라인에 병합하는 방법을 정의합니다. 파이프라인 실행 정책은 독립적인 파이프라인에서 .gitlab-ci.yml 파일에 정의된 작업을 실행하여 대상 프로젝트의 파이프라인에 병합합니다.

inject_ci

이 전략은 프로젝트 파이프라인을 완전히 교체하지 않고 기존 프로젝트 파이프라인에 사용자 정의 CI/CD 구성을 추가하는 것입니다. 기존 파이프라인을 보강하거나 확장하고 싶을 때 보안 스캔, 컴플라이언스 검사 또는 사용자 정의 스크립트 추가 등의 추가 단계가 필요한 경우 적합합니다.

여러 정책이 활성화되어 있는 경우 모든 작업이 추가적으로 적용됩니다.

이 전략을 사용할 때 프로젝트의 .gitlab-ci.yml 파일이 없는 경우 이 전략을 사용하여 파이프라인에 정의된 작업만 포함된 파이프라인이 실행됩니다.

override_project_ci

이 전략은 파이프라인 실행 정책에 의해 정의된 새로운 CI/CD 구성으로 프로젝트의 기존 CI/CD 구성을 완전히 교체하는 것입니다. 이 전략은 조직 전체의 CI/CD 표준이나 컴플라이언스 요구 사항을 강제로 적용할 때 이상적입니다.

override_project_ci를 사용하는 다른 정책보다 이 전략이 우선합니다. override_project_ci가 포함된 정책이 적용되면 프로젝트 CI 구성이 무시됩니다. 다른 보안 정책 구성은 덮어쓰지 않습니다.

이 전략을 사용하면 사용자는 프로젝트 CI/CD 구성을 파이프라인 실행 정책 구성에 포함하여 정책 작업을 사용자 정의할 수 있습니다. 예를 들어, 정책 및 프로젝트 CI/CD 구성을 하나의 YAML 파일로 결합함으로써 사용자는 before_script 구성을 재정의할 수 있습니다.

참고: 파이프라인 실행 정책이 정책 작업의 실행을 방지하는 워크플로우 규칙을 사용하는 경우 프로젝트의 기존 CI/CD 구성은 덮어쓰지 않고 유지됩니다. 파이프라인 소스가 병합 요청 이벤트인 경우와 같이 정책이 프로젝트의 CI/CD 구성에 영향을 미치는 시기를 제어할 수 있는 조건적으로 파이프라인 실행 정책을 적용할 수 있습니다. 예를 들어, if: $CI_PIPELINE_SOURCE == "merge_request_event"라는 워크플로우 규칙을 설정하면 파이프라인 소스가 병합 요청 이벤트인 경우에만 프로젝트의 CI/CD 구성이 덮어씌워집니다.

파이프라인 실행 정책 구성에 프로젝트의 CI/CD 구성 포함

override_project_ci 전략을 사용할 때, 프로젝트 구성은 파이프라인 실행 정책 구성에 포함될 수 있습니다. 

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

compliance_job:
 ...

참고: 사용자 정의 stage에 정의된 프로젝트 구성의 작업은 최종 파이프라인에서 제외됩니다. 최종 구성에 작업을 포함하려면 해당 작업을 기본 파이프라인 단계나 예약 단계(.pipeline-policy-pre 또는 .pipeline-policy-post)로 정의하세요.

CI/CD 변수

파이프라인 실행 작업은 격리된 상태에서 실행됩니다. 다른 정책이나 프로젝트의 .gitlab-ci.yml 파일에서 정의된 변수는 파이프라인 실행 정책에서 사용할 수 없으며 외부에서 덮어쓸 수 없습니다.

변수는 그룹이나 프로젝트 설정을 사용하여 파이프라인 실행 정책과 공유될 수 있습니다. 만약 파이프라인 실행 정책에 변수가 정의되지 않은 경우, 해당 변수는 그룹이나 프로젝트 설정에서의 값이 적용됩니다. 만약 파이프라인 실행 정책에서 변수가 정의된 경우, 해당 그룹이나 프로젝트 설정은 덮어쓰기됩니다. 이 동작은 파이프라인 실행 정책 전략과는 독립적입니다.

UI에서 프로젝트나 그룹 변수를 정의할 수 있습니다.

예시

이 예시는 파이프라인 실행 정책으로 얻을 수 있는 것을 보여줍니다.

파이프라인 실행 정책

보안 정책 프로젝트에 저장된 .gitlab/security-policies/policy.yml 파일에서 다음 예제를 사용할 수 있습니다. 

---
pipeline_execution_policy:
- name: 나의 파이프라인 실행 정책
  description: CI/CD 작업 강제
  enabled: true
  pipeline_config_strategy: override_project_ci
  content:
    include:
    - project: verify-issue-469027/policy-ci
      file: policy-ci.yml
      ref: main # 옵션
  policy_scope:
    projects:
      including:
      - id: 361

프로젝트 변수에 기반하여 강제 작업 사용자 지정

프로젝트 변수의 존재 여부에 따라 강제 작업을 사용자 정의할 수 있습니다. 이 예에서 CS_IMAGE의 값은 정책에서 alpine:latest로 정의됩니다. 그러나 프로젝트에서도 CS_IMAGE의 값을 정의하면 해당 값을 사용합니다. CI/CD 변수는 프로젝트의 .gitlab-ci.yml 파일에 정의된 변수가 아니어야 합니다. 

variables:
  CS_ANALYZER_IMAGE: "$CI_TEMPLATE_REGISTRY_HOST/security-products/container-scanning:7"
  CS_IMAGE: alpine:latest

policy::container-security:
  stage: .pipeline-policy-pre
  rules:
    - if: $CS_IMAGE
      variables:
        CS_IMAGE: $PROJECT_CS_IMAGE
    - when: always
  script:
    - echo "CS_ANALYZER_IMAGE:$CS_ANALYZER_IMAGE"
    - echo "CS_IMAGE:$CS_IMAGE"

프로젝트 구성에서 before_script를 사용하여 보안 스캐너의 동작 사용자 정의

프로젝트의 .gitlab-ci.yml에서 정책에 의해 징발되는 보안 작업의 동작을 사용자 정의하기 위해, before_script를 재정의할 수 있습니다. 이를 위해 정책에서 override_project_ci 전략을 사용하고 프로젝트의 CI/CD 구성을 포함시킬 수 있습니다. 다음은 예제 파이프라인 실행 정책 구성입니다. 

# policy.yml
type: pipeline_execution_policy
name: Secret detection
description: >-
  This policy enforces secret detection and allows projects to override the
  behavior of the scanner.
enabled: true
pipeline_config_strategy: override_project_ci
content:
  include:
    - project: gitlab-org/pipeline-execution-policies/compliance-project
      file: secret-detection.yml

# secret-detection.yml
include:
  - project: $CI_PROJECT_PATH
    ref: $CI_COMMIT_SHA
    file: $CI_CONFIG_PATH
  - template: Security/Secret-Detection.gitlab-ci.yml

프로젝트의 .gitlab-ci.yml에서 보안 스캐너를 위한 before_script를 정의할 수 있습니다. 

include:
  - template: Jobs/Secret-Detection.gitlab-ci.yml

secret_detection:
  before_script:
    - echo "Before secret detection"

override_project_ci를 사용하여 프로젝트의 구성을 포함시키면 YAML 구성을 병합할 수 있습니다.

그룹 또는 프로젝트 변수를 파이프라인 실행 정책에서 사용

파이프라인 실행 정책에서 그룹 또는 프로젝트 변수를 사용할 수 있습니다.

프로젝트 변수 PROJECT_VAR="I'm a project"가 있을 때, 다음 파이프라인 실행 정책 작업은 I'm a project를 반환합니다. 

pipeline execution policy job:
    stage: .pipeline-policy-pre
    script:
    - echo "$PROJECT_VAR"

파이프라인 실행 정책을 사용하여 변수의 값 강제

파이프라인 실행 정책에서 정의된 변수 값이 동일한 이름을 가진 그룹 또는 정책 변수의 값보다 우선합니다. 이 예에서 변수 PROJECT_VAR의 프로젝트 값이 덮어씌워지고 작업은 I'm a pipeline execution policy를 반환합니다. 

variables:
  PROJECT_VAR: "I'm a pipeline execution policy"

pipeline execution policy job:
    stage: .pipeline-policy-pre
    script:
    - echo "$PROJECT_VAR"

보안 정책 범위가 있는 policy.yml 예제

이 예에서 보안 정책의 policy_scope는 다음을 포함합니다:

  • 코드 준수 프레임워크를 적용한 모든 프로젝트를 포함합니다(ID: 9).
  • ID: 456를 가진 프로젝트를 제외합니다. 
pipeline_execution_policy:
- name: Pipeline execution policy
  description: ''
  enabled: true
  pipeline_config_strategy: inject_ci
  content:
    include:
    - project: my-group/pipeline-execution-ci-project
      file: policy-ci.yml
  policy_scope:
    compliance_frameworks:
    - id: 9
    projects:
      excluding:
      - id: 456