히스토리

• GitLab 18.0에서 policy.yml 파일에 정의된 scheduled_pipeline_execution_policy_type 플래그와 함께 실험 기능으로 도입.
• GitLab 18.2에서 베타로 변경.
• GitLab 19.2에서 일반 공개.

파이프라인 실행 정책은 프로젝트 파이프라인에서 사용자 지정 CI/CD job을 강제합니다. 예약 파이프라인 실행 정책을 사용하면 이 강제 적용을 일정 주기(매일·매주·매월)로 확장해, 새 커밋이 없어도 컴플라이언스 스크립트, 보안 스캔, 그 밖의 사용자 지정 CI/CD job 이 실행되도록 할 수 있습니다.

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

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

주요 활용 사례는 다음과 같습니다.

• 컴플라이언스 요건을 충족하도록 보안 스캔을 일정 주기로 강제합니다.
• 프로젝트 설정을 주기적으로 점검합니다.
• 비활성 리포지터리에 의존성 스캔을 실행해 새로 발견된 취약점을 탐지합니다.
• 컴플라이언스 보고 스크립트를 일정에 따라 실행합니다.

예약 파이프라인 실행 정책 테스트#

예약 파이프라인 실행 정책을 모든 프로젝트에 적용하기 전에 테스트를 실행해 파이프라인이 동작하는지 확인하고 정책이 인프라에 미치는 영향을 파악할 수 있습니다. 테스트 실행은 실제 파이프라인을 실행하므로 정확한 소요 시간과 리소스 추정치를 얻을 수 있습니다.

테스트를 실행하려면 다음을 수행합니다.

1. 왼쪽 사이드바에서 Security > Policies를 선택합니다.
2. 테스트할 예약 파이프라인 실행 정책을 선택합니다.
3. Test runs 탭을 선택합니다.
4. 그룹 수준에서 정책을 보고 있다면 드롭다운 목록에서 대상 프로젝트를 선택합니다.
5. Begin test run을 선택합니다.

테스트 실행은 정책의 CI/CD 설정을 사용해 선택한 프로젝트에 파이프라인을 생성합니다. 테스트 실행 상태는 Test runs 탭에서 확인할 수 있습니다.

테스트 실행이 끝나면 Test runs 탭에 소요 시간과 오류 메시지를 포함한 결과가 표시됩니다.

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

예약 파이프라인 실행 정책을 설정하려면 보안 정책 프로젝트의 .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 절에서는 보안 정책 job 이 자동으로 실행되는 시점을 설정합니다. 실행 시각과 분산 구간을 지정해 매일·매주·매월 일정을 만들 수 있습니다.

일정 설정 옵션#

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초)입니다.
• monthly 일정에서 특정 달에 존재하지 않는 날짜(예: 2월의 31일)를 지정하면 그 실행은 건너뜁니다.
• 보안 정책 프로젝트 하나에는 예약 파이프라인 실행 정책을 최대 5개까지 둘 수 있습니다.
• 하나의 예약 정책은 한 번에 하나의 일정 설정만 가질 수 있습니다.
• 하나의 예약 정책은 최대 5개 브랜치를 대상으로 할 수 있습니다. branches를 생략하면 프로젝트 기본 브랜치에서만 실행됩니다.
• 정책을 여러 프로젝트에 적용할 때는 사용 가능한 러너 용량을 고려해 프로젝트 수를 감당할 만큼 시간 구간을 넉넉히 잡습니다. 예를 들어 1000개 프로젝트에 적용한 정책의 시간 구간이 1시간이면 파이프라인 생성이 그 1시간에 고르게 분산됩니다(분당 약 16개). 러너가 이 생성 속도를 감당할 수 있는지 확인하거나, 대기·지연을 피하려면 더 긴 시간 구간을 선택합니다.
• monthly 일정에서는 시간 구간 안의 무작위 분산 때문에 연속된 실행 간격이 달라질 수 있습니다. 예를 들어 이전 실행에서 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일 UTC 오후 4시 27분을 뜻합니다.

스누즈 해제#

만료 시각 전에 스누즈를 해제하려면 정책 설정에서 snooze 절을 제거하거나 until 값에 과거 날짜를 지정합니다.

CI/CD 변수 접근 제어#

기본적으로 예약 파이프라인 실행 정책 job은 프로젝트나 그룹의 CI/CD 변수에 접근할 수 없습니다. 이 보안 기본값은 정책이 민감한 프로젝트 설정을 의도치 않게 노출하는 것을 막습니다.

정책 job 이 프로젝트와 그룹의 CI/CD 변수에 접근할 수 있도록 하려면 정책 설정에 variables_override 옵션을 추가합니다.

pipeline_execution_schedule_policy:
- name: Scheduled Security Scan
  description: 'Run security scans with access to project variables'
  enabled: true
  content:
    include:
    - project: your-group/your-project
      file: security-scan.yml
  variables_override:
    allowed: true
  schedules:
  - type: daily
    start_time: '02:00'
    time_window:
      value: 3600
      distribution: random

variables_override 설정 옵션#

variables_override 예시#

특정 변수를 제외한 모든 프로젝트 변수를 차단합니다.

variables_override:
  allowed: false
  exceptions:
    - DEPLOY_TOKEN
    - API_KEY

민감한 변수를 제외한 모든 프로젝트 변수를 허용합니다.

variables_override:
  allowed: true
  exceptions:
    - SECRET_KEY
    - PRIVATE_TOKEN

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

기본적으로 일정은 기본 브랜치에서만 실행됩니다. 예약 파이프라인 실행 정책은 브랜치 필터링을 지원하므로 다른 브랜치에도 파이프라인을 예약할 수 있습니다. 프로젝트의 다른 주요 브랜치에서 정기적으로 스캔이나 점검을 수행하려면 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 설정 파일이 보안 정책 프로젝트 자체에 있다면 이 방법을 사용합니다. 이 설정은 파이프라인 실행 정책이 주입된 파이프라인을 트리거하는 모든 사용자에게 적용됩니다.

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

방법 2: 비공개 또는 내부 프로젝트 접근 허용#

정책의 include: 값이 보안 정책 프로젝트가 아닌 비공개 또는 내부 프로젝트에 저장된 CI/CD 설정 파일을 참조한다면 이 방법을 사용합니다.

1. CI/CD 파일을 저장한 비공개 또는 내부 프로젝트의 왼쪽 사이드바에서 Settings > General을 선택합니다.

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

3. Pipeline execution policies에서 Allow access to CI/CD configuration files in this project를 선택합니다.

4. Allowed file patterns에 접근을 허용할 파일을 지정하는 glob 패턴을 쉼표로 구분해 하나 이상 추가합니다.

5. 선택 사항입니다. Allowed group에서 그룹을 선택하면 그 그룹에 속한 프로젝트의 사용자만 CI/CD 설정 파일에 접근할 수 있습니다.

   지정하지 않으면 최상위 상위 그룹에 속한 모든 프로젝트의 사용자가 파일에 접근할 수 있습니다.

6. 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#

예약 파이프라인은 Security Policy Bot User가 실행합니다. 이 계정은 보안 정책이 적용되는 프로젝트마다 GitLab 이 자동으로 만드는 전용 시스템 계정입니다. 정책 실행을 격리하고 안전하게 유지하기 위해 이 봇 사용자에게는 다음 보안 제약이 있습니다.

• 봇 사용자는 해당 프로젝트의 멤버일 뿐이며, 그룹이나 다른 프로젝트에 추가할 수 없습니다.
• 봇 사용자는 외부 사용자로 취급되며 기본적으로 내부 프로젝트에 접근할 수 없습니다.
• 봇 사용자는 보안 정책 프로젝트와 공개 프로젝트의 파일에 접근할 수 있습니다.
• 비공개 또는 내부 프로젝트의 파일에는 그 프로젝트가 Pipeline execution policies 설정을 명시적으로 켜고 파일 경로가 프로젝트에 지정된 패턴과 일치할 때만 접근할 수 있습니다.

봇 사용자는 다른 프로젝트의 멤버가 아니므로 다음 동작은 수행할 수 없습니다.

• 접근을 허용하지 않거나 허용 파일 패턴과 일치하지 않는 비공개 또는 내부 프로젝트의 CI/CD 설정 파일에 접근합니다.
• 비공개 또는 내부 프로젝트를 대상으로 하는 다중 프로젝트 하위 파이프라인을 시작합니다.
• 비공개 또는 내부 프로젝트의 아티팩트나 리소스에 접근합니다.

예약 제한#

예약 파이프라인 실행 정책을 만들 때는 다음 제한을 고려합니다.

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

문제 해결#

첫 예약 실행 지연#

예약 파이프라인 실행 정책을 만들거나 업데이트하면 백그라운드 워커가 일정 레코드를 비동기로 생성합니다. 시스템 부하 등으로 백그라운드 워커 큐가 지연되면 워커가 의도한 첫 실행 시각이 지난 뒤에 일정 레코드를 생성할 수 있습니다. 이 경우 첫 실행은 즉시가 아니라 다음 예약 시점에 이뤄집니다.

예를 들어 오후 6시 실행을 목표로 오후 2시에 정책을 만들었는데 백그라운드 워커가 오후 7시에야 정책을 처리했다면, 첫 실행은 다음 날 오후 6시(또는 일정 설정에 따른 다음 해당 일자)로 예약됩니다.

이 동작을 우회하는 방법은 다음과 같습니다.

• 의도한 첫 실행 시각보다 충분히 앞서 정책을 만듭니다.
• 테스트 실행 기능으로 첫 예약 실행 전에 정책이 정상 동작하는지 확인합니다.

예약 파이프라인 미실행#

예약 파이프라인이 기대대로 실행되지 않는다면 다음 문제 해결 단계를 따릅니다.

1. 정책 접근 확인: 다음을 확인합니다.
   • CI/CD 설정 파일이 보안 정책 프로젝트, 공개 프로젝트, 또는 봇 접근이 허용되고 파일 패턴이 일치하는 비공개·내부 프로젝트에 있는지 확인합니다.
   • 보안 정책 프로젝트에서 Pipeline execution policies 설정이 켜져 있는지 확인합니다(Settings > General > Visibility, project features, permissions).
2. CI 설정 검증:
   • 지정한 경로에 CI/CD 설정 파일이 있는지 확인합니다.
   • 수동으로 파이프라인을 실행해 설정이 유효한지 확인합니다.
   • 설정에 예약 파이프라인에 맞는 워크플로 규칙이 포함되어 있는지 확인합니다.
3. 정책 설정 확인:
   • 정책이 활성화되어 있는지(enabled: true) 확인합니다.
   • 일정 설정의 형식이 올바르고 값이 유효한지 확인합니다.
   • 브랜치를 지정했다면 그 브랜치가 프로젝트에 있는지 확인합니다.
   • 시간대를 지정했다면 값이 올바른지 확인합니다.
4. 로그와 활동 검토:
   • 보안 정책 프로젝트의 CI/CD 파이프라인 로그에 오류가 있는지 확인합니다.
5. 러너 가용성 확인:
   • 러너가 사용 가능하고 올바르게 설정되어 있는지 확인합니다.
   • 러너가 예약된 job을 처리할 용량이 있는지 확인합니다.