히스토리

• GitLab 18.0에서 policy.yml 파일에 정의된 scheduled_pipeline_execution_policy_type 플래그와 함께 실험 기능으로 도입되었습니다.

파이프라인 실행 정책은 프로젝트 파이프라인에서 사용자 정의 CI/CD 작업을 강제 실행합니다. 예약된 파이프라인 실행 정책을 사용하면 이 강제 실행을 확장하여 CI/CD 작업을 정기적인 주기(일별, 주별 또는 월별)로 실행할 수 있으며, 새 커밋이 없는 경우에도 규정 준수 스크립트, 보안 스캔 또는 기타 사용자 정의 CI/CD 작업이 실행되도록 보장합니다.

파이프라인 실행 정책 예약하기#

기존 파이프라인에 작업을 주입하거나 재정의하는 일반 파이프라인 실행 정책과 달리, 예약된 정책은 정의한 일정에 따라 독립적으로 실행되는 새 파이프라인을 생성합니다. 예약된 파이프라인은 프로젝트의 .gitlab-ci.yml과는 별개이며 프로젝트의 CI/CD 작업을 실행하지 않습니다.

일반적인 사용 사례는 다음과 같습니다:

• 규정 준수 요구사항을 충족하기 위해 정기적인 주기로 보안 스캔을 강제 실행합니다.
• 프로젝트 구성을 주기적으로 확인합니다.
• 비활성 저장소에 대해 의존성 스캔을 실행하여 새로 발견된 취약점을 감지합니다.
• 일정에 따라 규정 준수 보고 스크립트를 실행합니다.

예약된 파이프라인 실행 정책 활성화#

예약된 파이프라인 실행 정책은 실험적 기능으로 제공됩니다. 환경에서 이 기능을 활성화하려면 보안 정책 구성에서 pipeline_execution_schedule_policy 실험을 활성화하세요. .gitlab/security-policies/policy.yml YAML 구성 파일은 보안 정책 프로젝트에 저장됩니다:

experiments:
  pipeline_execution_schedule_policy:
    enabled: true

예약된 파이프라인 실행 정책 구성#

예약된 파이프라인 실행 정책을 구성하려면 보안 정책 프로젝트의 .gitlab/security-policies/policy.yml 파일의 pipeline_execution_schedule_policy 섹션에 추가 구성 필드를 추가하세요:

pipeline_execution_schedule_policy:
- name: Scheduled Pipeline Execution Policy
  description: ''
  enabled: true
  content:
    include:
    - project: your-group/your-project
      file: security-scan.yml
  schedules:
  - type: daily
    start_time: '10:00'
    time_window:
      value: 600
      distribution: random

일정 구성 스키마#

schedules 섹션을 통해 보안 정책 작업이 자동으로 실행되는 시기를 구성할 수 있습니다. 특정 실행 시간 및 배포 창과 함께 일별, 주별 또는 월별 일정을 만들 수 있습니다.

일정 구성 옵션#

schedules 섹션은 다음 옵션을 지원합니다:

일정 예제#

일별, 주별 또는 월별 일정을 사용합니다.

일별 일정 예제#

schedules:
  - type: daily
    start_time: "01:00"
    time_window:
      value: 3600  # 1 hour window
      distribution: random
    timezone: "America/New_York"
    branches:
      - main
      - develop
      - staging

주별 일정 예제#

schedules:
  - type: weekly
    days:
      - Monday
      - Wednesday
      - Friday
    start_time: "04:30"
    time_window:
      value: 7200  # 2 hour window
      distribution: random
    timezone: "Europe/Berlin"

월별 일정 예제#

schedules:
  - type: monthly
    days_of_month:
      - 1
      - 15
    start_time: "02:15"
    time_window:
      value: 14400  # 4 hour window
      distribution: random
    timezone: "Asia/Tokyo"

시간 창 배포#

여러 프로젝트에 정책을 적용할 때 CI/CD 인프라가 과부하되지 않도록 예약된 파이프라인 실행 정책은 몇 가지 공통 규칙에 따라 시간 창에 걸쳐 파이프라인 생성을 배포합니다:

• 모든 파이프라인은 random으로 예약됩니다. 파이프라인은 지정된 시간 창 동안 무작위로 배포됩니다.
• 최소 시간 창은 10분(600초)이고 최대는 약 1개월(2,629,746초)입니다.
• 월별 일정의 경우, 특정 월에 존재하지 않는 날짜(2월의 31일 등)를 지정하면 해당 실행은 건너뜁니다.
• 보안 정책 프로젝트당 최대 5개의 예약된 파이프라인 실행 정책을 포함할 수 있습니다.
• 예약된 정책은 한 번에 하나의 일정 구성만 가질 수 있습니다.
• 여러 프로젝트에 정책을 적용할 경우, 사용 가능한 러너 용량에 따라 프로젝트 수를 수용할 만큼 시간 창이 충분히 크도록 하세요. 예를 들어 1시간 시간 창으로 1000개 프로젝트에 적용된 정책은 그 시간 동안 파이프라인 생성을 균등하게 배포합니다(분당 약 16개 파이프라인). 러너가 이 파이프라인 생성 속도를 처리할 수 있는지 확인하거나, 대기 또는 지연을 피하기 위해 더 큰 시간 창을 선택하세요.
• 월별 일정의 경우, 연속 실행 간격은 시간 창 내의 무작위 배포로 인해 다를 수 있습니다. 예를 들어 월별 일정이 이전 실행 후 20일 후에 실행되고, 그 다음 30일 후에 실행될 수 있습니다. 이 배포는 인프라 전반의 부하를 분산하는 데 도움이 되므로 예상되는 동작입니다.

예약된 파이프라인 실행 정책 스누즈#

스누즈 기능을 사용하여 예약된 파이프라인 실행 정책을 일시적으로 일시 중지할 수 있습니다. 유지 관리 기간, 휴일 또는 특정 기간 동안 예약된 파이프라인이 실행되지 않도록 해야 하는 경우 스누즈 기능을 사용하세요.

스누즈 작동 방식#

예약된 파이프라인 실행 정책을 스누즈하면:

• 스누즈 기간 동안 새로운 예약된 파이프라인이 생성되지 않습니다.
• 스누즈 전에 생성된 파이프라인은 계속 실행됩니다.
• 정책은 활성화되어 있지만 스누즈 상태입니다.
• 스누즈 기간이 만료되면 예약된 파이프라인 실행이 자동으로 재개됩니다.

스누즈 구성#

예약된 파이프라인 실행 정책을 스누즈하려면 일정 구성에 snooze 섹션을 추가하세요:

pipeline_execution_schedule_policy:
- name: Weekly Security Scan
  description: 'Run security scans every week'
  enabled: true
  content:
    include:
    - project: your-group/your-project
      file: security-scan.yml
  schedules:
  - type: weekly
    start_time: '02:00'
    time_window:
      value: 3600
      distribution: random
    timezone: UTC
    days:
      - Monday
    snooze:
      until: "2025-06-26T16:27:00+00:00"  # ISO8601 format
      reason: "Critical production deployment"

snooze.until 파라미터는 ISO8601 형식을 사용하여 스누즈 기간이 끝나는 시간을 지정합니다: YYYY-MM-DDThh:mm:ss+00:00 형식은 다음과 같습니다:

• YYYY-MM-DD: 연, 월, 일
• T: 날짜와 시간 사이의 구분자
• hh:mm:ss: 24시간 형식의 시, 분, 초
• +00:00: UTC로부터의 타임존 오프셋 (또는 UTC의 경우 Z)

예를 들어, 2025-06-26T16:27:00+00:00은 2025년 6월 26일 오후 4시 27분 UTC를 나타냅니다.

스누즈 제거#

만료 시간 전에 스누즈를 제거하려면 정책 구성에서 snooze 섹션을 제거하거나 until 값에 과거 날짜를 설정하세요.

특정 브랜치에 파이프라인 예약#

기본적으로 일정은 기본 브랜치에서만 실행됩니다. 예약된 파이프라인 실행 정책은 브랜치 필터링을 지원하며, 추가 브랜치에 대한 파이프라인을 예약할 수 있습니다. branches 속성을 사용하여 프로젝트의 다른 중요한 브랜치에 대해 정기적인 스캔 또는 확인을 수행하세요.

일정에서 branches 속성을 구성하면:

• 브랜치를 지정하지 않으면 예약된 파이프라인은 기본 브랜치에서만 실행됩니다.
• 브랜치를 지정하면 정책은 프로젝트에 실제로 존재하는 각 지정 브랜치에 대해 파이프라인을 예약합니다.
• 일정당 최대 5개의 고유 브랜치 이름을 지정할 수 있습니다.
• 각 브랜치 이름을 전체 이름으로 지정해야 합니다. 와일드카드 매칭은 지원되지 않습니다.

브랜치 필터링 예제#

pipeline_execution_schedule_policy:
- name: Scan Multiple Branches
  description: 'Run security scans on main, staging and develop branches'
  enabled: true
  content:
    include:
    - project: your-group/your-project
      file: security-scan.yml
  schedules:
  - type: weekly
    days:
      - Monday
    start_time: '02:00'
    time_window:
      value: 3600
      distribution: random
    branches:
      - main
      - staging
      - develop
      - feature/new-authentication

이 예제에서 지정된 브랜치가 모두 프로젝트에 있으면 정책은 4개의 별도 파이프라인을 생성합니다(각 브랜치당 하나씩).

사전 요구사항#

예약된 파이프라인 실행 정책을 사용하려면 프로젝트가 다음 요구사항을 충족해야 합니다:

• CI/CD 구성 파일이 다음 위치 중 하나에 저장되어 있어야 합니다:

  • 보안 정책 프로젝트
  • 공개 프로젝트
  • 액세스가 활성화된 프라이빗 프로젝트 (CI/CD 구성 파일에 대한 액세스 활성화 참조)

• CI/CD 구성 파일에 예약된 파이프라인에 적합한 워크플로우 규칙이 포함되어 있어야 합니다.

CI/CD 구성 파일에 대한 액세스 활성화#

정책이 CI/CD 구성 파일을 참조할 때 Security Policy Bot이 해당 파일에 액세스할 수 있어야 합니다. 공개 프로젝트의 파일은 기본적으로 액세스 가능합니다. 보안 정책 프로젝트 또는 다른 프라이빗 프로젝트의 파일의 경우 다음 옵션 중 하나를 사용하여 액세스를 활성화하세요.

옵션 1: 보안 정책 프로젝트의 파일에 액세스 부여#

CI/CD 구성 파일이 보안 정책 프로젝트 자체에 저장된 경우 이 옵션을 사용하세요. 이 설정은 파이프라인 실행 정책이 주입된 파이프라인을 트리거하는 모든 사용자에게 적용됩니다.

• 보안 정책 프로젝트의 왼쪽 사이드바에서 Settings > General을 선택합니다.
• Visibility, project features, permissions를 확장합니다.
• Grant security policy project access to CI/CD configuration을 켭니다.
• Save changes를 선택합니다.

옵션 2: Security Policy Bot의 프라이빗 프로젝트 액세스 허용#

정책의 include: 값이 보안 정책 프로젝트가 아닌 다른 프라이빗 프로젝트에 저장된 CI/CD 구성 파일을 참조하는 경우 이 옵션을 사용하세요. 이 설정은 Security Policy Bot 사용자에게만 적용되며 모든 프로젝트에서 활성화할 수 있습니다.

• 보안 정책 프로젝트에서 pipeline_execution_policy_bot_access 실험을 활성화합니다. .gitlab/security-policies/policy.yml 파일에 다음 줄을 추가합니다:

  experiments:
    pipeline_execution_policy_bot_access:
      enabled: true
  

  [!note] 프라이빗 프로젝트 또는 해당 부모 그룹 중 하나가 이 보안 정책 프로젝트에 연결되어 있어야 합니다. 아직 연결되지 않은 경우 보안 정책 프로젝트를 연결해야 합니다.

• CI/CD 파일을 저장하는 프라이빗 프로젝트의 왼쪽 사이드바에서 Settings > General을 선택합니다.

• Visibility, project features, permissions를 확장합니다.

• Security policy bot access에서 Allow security policy bots to access CI/CD configuration files in this project를 선택합니다.

• Allowed file patterns에서 봇이 액세스할 수 있는 파일을 지정하는 하나 이상의 glob 패턴을 쉼표로 구분하여 추가합니다.

• Save changes를 선택합니다.

허용된 파일의 glob 패턴은 include:file: 값에 지정된 경로와 일치해야 합니다. 예를 들어:

• include:file: ci/security-scan.yml의 경우 ci/**/*.yml 또는 ci/security-scan.yml을 사용합니다.
• include:file: policy-ci.yml의 경우 *.yml 또는 policy-ci.yml을 사용합니다.
• 여러 디렉토리의 경우 ci/**/*.yml, templates/**/*.yml과 같이 쉼표로 구분된 여러 패턴을 사용합니다.

Security Policy Bot User#

예약된 파이프라인은 GitLab이 보안 정책이 적용되는 각 프로젝트에 대해 자동으로 생성하는 전용 시스템 계정인 Security Policy Bot User에 의해 실행됩니다. 정책 실행이 격리되고 안전하게 유지되도록 봇 사용자에게는 다음과 같은 보안 제한이 있습니다:

• 봇 사용자는 해당 특정 프로젝트의 구성원입니다. 그룹이나 다른 프로젝트에 추가할 수 없습니다.
• 봇 사용자는 보안 정책 프로젝트와 공개 프로젝트의 파일에 액세스할 수 있습니다.
• 봇 사용자는 해당 프로젝트에서 Security policy bot access를 명시적으로 활성화하고 파일 경로가 프로젝트에 지정된 패턴과 일치하는 경우에만 프라이빗 프로젝트의 파일에 액세스할 수 있습니다.

봇 사용자가 다른 프로젝트의 구성원이 아니기 때문에 다음 작업을 완료할 수 없습니다:

• 봇 액세스를 허용하지 않거나 허용된 파일 패턴과 일치하지 않는 프라이빗 프로젝트의 CI/CD 구성 파일 액세스.
• 프라이빗 프로젝트를 대상으로 하는 멀티 프로젝트 자식 파이프라인 시작.
• 프라이빗 프로젝트의 아티팩트 또는 리소스 액세스.

예약 제한#

이 기능은 실험적이며 향후 릴리스에서 변경될 수 있습니다. 또한 예약된 파이프라인 실행 정책을 만들 때 다음 제한 사항에 유의하세요:

• 보안 정책 프로젝트당 예약된 파이프라인 실행 정책의 최대 수는 하나의 일정을 가진 하나의 정책으로 제한됩니다.
• 일정의 최대 빈도는 하루에 한 번(일별)입니다.
• 브랜치가 지정되지 않으면 예약된 파이프라인 실행 정책은 기본 브랜치에서만 실행됩니다.
• branches 배열에 최대 5개의 고유 브랜치 이름을 지정할 수 있습니다.
• 파이프라인의 충분한 배포를 보장하기 위해 시간 창은 최소 10분(600초)이어야 합니다.
• 사용 가능한 러너가 충분하지 않으면 예약된 파이프라인이 지연될 수 있습니다.

트러블슈팅#

예약된 파이프라인이 예상대로 실행되지 않으면 다음 트러블슈팅 단계를 따르세요:

1. 실험 플래그 확인: policy.yml 파일의 experiments 섹션에 pipeline_execution_schedule_policy: enabled: true 플래그가 설정되어 있는지 확인하세요.
2. 정책 액세스 확인: 다음을 확인하세요:
   • CI/CD 구성 파일이 다른 프로젝트에서 연결된 것이 아니라 보안 정책 프로젝트에 저장되어 있는지 확인합니다.
   • 보안 정책 프로젝트에서 Pipeline execution policies 설정이 활성화되어 있는지 확인합니다(Settings > General > Visibility, project features, permissions).
3. CI 구성 검증:
   • CI/CD 구성 파일이 지정된 경로에 있는지 확인합니다.
   • 수동 파이프라인을 실행하여 구성이 유효한지 확인합니다.
   • 구성에 예약된 파이프라인에 적합한 워크플로우 규칙이 포함되어 있는지 확인합니다.
4. 정책 구성 확인:
   • 정책이 활성화되어 있는지 확인합니다(enabled: true).
   • 일정 구성의 형식과 값이 올바른지 확인합니다.
   • 브랜치를 지정한 경우 해당 브랜치가 프로젝트에 있는지 확인합니다.
   • 타임존 설정이 올바른지 확인합니다(지정된 경우).
5. 로그 및 활동 검토:
   • 오류가 있는지 보안 정책 프로젝트의 CI/CD 파이프라인 로그를 확인합니다.
6. 러너 가용성 확인:
   • 러너가 사용 가능하고 올바르게 구성되어 있는지 확인합니다.
   • 러너가 예약된 작업을 처리할 용량이 있는지 확인합니다.