파이프라인 실행 정책

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

이 기능의 사용 가능성은 기능 플래그로 제어됩니다.
자세한 내용은 기록을 참조하세요.

모든 적용 가능한 프로젝트에 대해 CI/CD 작업을 시행하기 위해 파이프라인 실행 정책을 사용하십시오.

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

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

새 정책을 저장할 때 GitLab은 이 JSON 스키마에 대해 해당 내용을 검증합니다.
JSON 스키마를 읽는 방법에 익숙하지 않은 경우, 다음 섹션과 표는 대안을 제공합니다.

필드 타입 필수 설명
pipeline_execution_policy array of pipeline execution policy true 파이프라인 실행 정책 목록(최대 다섯 개)

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

필드 타입 필수 설명
name string true 정책 이름. 최대 255자.
description (선택 사항) string true 정책 설명.
enabled boolean true 정책을 활성화하는 플래그(true) 또는 비활성화하는 플래그(false).
content object of content true 프로젝트 파이프라인에 주입할 CI/CD 구성 참조.
pipeline_config_strategy string false inject_ci 또는 override_project_ci 중 하나일 수 있습니다. 파이프라인 전략에 대한 자세한 내용은 참조하세요.
suffix string false on_conflict(기본값) 또는 never일 수 있습니다. 작업 이름 충돌 처리 방법을 정의합니다. on_conflict는 고유성을 깨뜨릴 작업에 고유 접미사를 적용합니다. never는 프로젝트와 모든 적용 가능한 정책에서 작업 이름이 고유하지 않으면 파이프라인이 실패하게 만듭니다.
policy_scope object of policy_scope false 준수 프레임워크 레이블 또는 정의한 프로젝트를 기반으로 정책의 범위를 설정합니다.

다음 사항에 유의하세요:

  • 파이프라인을 트리거하는 사용자는 파이프라인 실행 정책에서 지정한 파이프라인 실행 파일에 대해 최소한 읽기 권한을 가져야 하며, 그렇지 않으면 파이프라인이 시작되지 않습니다.
  • 파이프라인 실행 파일이 삭제되거나 이름이 변경되면 정책이 시행된 프로젝트의 파이프라인이 작동을 멈출 수 있습니다.
  • 파이프라인 실행 정책 작업은 두 개의 예약된 단계 중 하나에 할당될 수 있습니다:
    • .pipeline-policy-pre 파이프라인의 시작 부분, .pre 단계 이전에.
    • .pipeline-policy-post 파이프라인의 마지막, .post 단계 이후에.
  • 예약된 단계에서 작업을 주입하는 것은 항상 성공할 것으로 보장됩니다. 실행 정책 작업은 표준(빌드, 테스트, 배포) 또는 사용자 정의 단계에도 할당될 수 있습니다. 그러나 이 경우 작업은 프로젝트 파이프라인 구성에 따라 무시될 수 있습니다.
  • 파이프라인 실행 정책 외부의 예약된 단계에는 작업을 할당할 수 없습니다.
  • 파이프라인 실행 정책에 대해 고유한 작업 이름을 선택해야 합니다. 일부 CI/CD 구성은 작업 이름을 기반으로 하며, 동일한 파이프라인에 여러 번 존재하는 경우 원하지 않는 결과를 초래할 수 있습니다. 예를 들어, needs 키워드는 하나의 작업이 다른 작업에 의존하도록 만듭니다. 동일한 이름을 가진 여러 작업이 있는 경우 랜덤으로 그 중 하나에 의존하게 됩니다.
  • 파이프라인 실행 정책은 프로젝트에 CI/CD 구성 파일이 없는 경우에도 여전히 유효합니다.
  • 정책의 순서는 적용된 접미사에 영향을 미칩니다.
  • 주어진 프로젝트에 적용된 정책 중 suffix: never가 있는 경우, 파이프라인에서 이미 동일한 이름을 가진 다른 작업이 있는 경우 파이프라인이 실패합니다.

작업 명명 모범 사례

보안 정책에서 오는 작업에 대한 가시적 지표가 없습니다. 작업 이름에 고유한 접두사 또는 접미사를 추가하면 이를 식별하고 작업 이름 충돌을 피하는 데 도움이 됩니다.

예시:

  • 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 파일을 검색할 참조입니다. 지정하지 않으면 프로젝트의 HEAD가 기본값입니다.

정책에서 content 유형을 사용하여 다른 리포지토리에 저장된 CI/CD 구성을 참조하세요. 이를 통해 동일한 CI/CD 구성을 여러 정책 간에 재사용할 수 있으며, 이러한 구성을 유지 관리하는 오버헤드를 줄일 수 있습니다. 예를 들어, 정책 A와 정책 B에서 시행하려는 사용자 정의 비밀 탐지 CI/CD 구성이 있는 경우, 단일 YAML 구성 파일을 생성하고 두 정책 모두에서 구성을 참조할 수 있습니다.

전제 조건:

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

    파이프라인 실행 정책을 시행하는 프로젝트는 사용자가 CI/CD 구성이 포함된 프로젝트에 대해 최소한 읽기 전용 액세스 권한을 가져야 합니다.

    GitLab 17.4 이상 버전에서는 보안 정책 프로젝트에서 지정된 CI/CD 구성 파일에 필요한 읽기 전용 액세스를 content 유형을 사용하여 부여할 수 있습니다. 그렇게 하려면 보안 정책 프로젝트의 일반 설정에서 Pipeline execution policies 설정을 활성화하십시오. 이 설정을 활성화하면 파이프라인을 트리거한 사용자에게 파이프라인 실행 정책에서 시행된 CI/CD 구성 파일을 읽을 수 있는 액세스 권한이 부여됩니다. 이 설정은 구성 파일이 저장된 프로젝트의 다른 부분에 대한 사용자 액세스를 부여하지 않습니다.

policy_scope 범위 유형

필드 유형 가능한 값 설명
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 구성 요소를 추가하여 프로젝트의 원래 CI/CD 구성을 완전히 대체하지 않습니다. 새로운 보안 스캔, 규정 준수 검사 또는 사용자 지정 스크립트와 같은 추가 단계를 통해 현재 파이프라인을 개선하거나 확장하려는 경우에 적합합니다.

여러 정책이 활성화되면 모든 작업이 누적되어 삽입됩니다.

이 전략을 사용할 때, 프로젝트 CI/CD 구성은 정책 파이프라인에 정의된 모든 동작을 무시할 수 없습니다. 각 파이프라인은 격리된 YAML 구성을 가지기 때문입니다.

.gitlab-ci.yml 파일이 없는 프로젝트의 경우, 이 전략은 .gitlab-ci.yml 파일을 암묵적으로 생성합니다. 다시 말해, 파이프라인 실행 정책에 정의된 작업만 포함된 파이프라인이 실행됩니다.

override_project_ci

이 전략은 프로젝트의 기존 CI/CD 구성을 파이프라인 실행 정책에 의해 정의된 새로운 것으로 완전히 대체합니다. 이 전략은 전체 파이프라인을 표준화하거나 대체해야 할 때, 예를 들어 조직 전체의 CI/CD 표준 또는 규정 준수 요구 사항을 시행할 때 이상적입니다.

이 전략은 inject_ci 전략을 사용하는 다른 정책보다 우선합니다. override_project_ci가 적용되는 정책이 있는 경우, 프로젝트 CI 구성은 무시됩니다. 다른 보안 정책 구성은 덮어쓰이지 않습니다.

이 전략은 사용자가 파이프라인 실행 정책 구성에 프로젝트 CI/CD 구성을 포함할 수 있도록 하여 정책 작업을 사용자 지정할 수 있게 해줍니다. 예를 들어, 정책과 프로젝트 CI/CD 구성을 하나의 YAML 파일로 결합하여 before_script 구성을 덮어쓸 수 있습니다.

참고: 파이프라인 실행 정책이 정책 작업 실행을 방지하는 워크플로 규칙을 사용하는 경우, 프로젝트의 원래 CI/CD 구성은 덮어쓰이지 않고 그대로 남아있습니다. 정책이 프로젝트의 CI/CD 구성에 영향을 미치도록 하려면 조건부로 파이프라인 실행 정책을 적용할 수 있습니다. 예를 들어, 워크플로 규칙을 if: $CI_PIPELINE_SOURCE == "merge_request_event"로 설정하면, 파이프라인 소스가 병합 요청 이벤트일 때만 프로젝트 CI 구성이 덮어써집니다.

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

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

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

compliance_job:
 ...
note
사용자 정의 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: 비밀 감지
description: >-
  이 정책은 비밀 감지를 시행하며 프로젝트가
  스캐너의 동작을 덮어쓸 수 있도록 허용합니다.
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 "비밀 감지 이전"

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