スケジュールされたパイプライン実行ポリシー

パイプライン実行ポリシーは、プロジェクトのパイプラインでカスタムCI/CDジョブを強制します。スケジュールされたパイプライン実行ポリシーを使用すると、この強制を拡張して、通常のケイデンス（毎日、毎週、または毎月）でCI/CDジョブを実行し、新しいコミットがない場合でも、コンプライアンススクリプト、セキュリティポリシー、またはその他のカスタム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日など）を指定すると、それらの実行はスキップされます。
• スケジュールされたポリシーには、一度に1つのスケジュール設定のみを含めることができます。

スケジュールされたパイプライン実行ポリシーをスヌーズする

スヌーズ機能を使用すると、スケジュールされたパイプライン実行ポリシーを一時停止できます。メンテナンス期間、休日中、または特定の期間スケジュールされたパイプラインの実行を防止する必要がある場合は、スヌーズ機能を使用します。

スヌーズの仕組み

スケジュールされたパイプライン実行ポリシーをスヌーズすると:

• スヌーズ期間中は、新しいスケジュールされたパイプラインは作成されません。
• スヌーズの前に作成されたパイプラインは、引き続き実行されます。
• ポリシーは有効なままですが、スヌーズ状態になっています。
• スヌーズ期間が有効期限切れになると、スケジュールされたパイプライン実行ポリシーが自動的に再開されます。

スヌーズの設定

スケジュールされたパイプライン実行ポリシーをスヌーズするには、スケジュール設定に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つの個別のパイプライン（ブランチごとに1つ）を作成します。

要件

スケジュールされたパイプライン実行ポリシーを使用するには:

1. CI/CD設定をセキュリティポリシープロジェクトに保存します。
2. セキュリティポリシープロジェクトの設定>一般>可視性、プロジェクトの機能、権限セクションで、Grant security policy project access to CI/CD configuration（CI/CD構成へのセキュリティポリシープロジェクトアクセスを許可）設定を有効にします。
3. スケジュールされたパイプラインに適切なワークフロールールがCI/CD設定に含まれていることを確認します。

セキュリティポリシーボットは、セキュリティポリシーの実行を処理するためにGitLabが自動的に作成するシステムアカウントです。適切な設定を有効にすると、このボットには、CI/CD設定にアクセスしてスケジュールされたパイプラインを実行するために必要な権限が付与されます。権限は、CI/CD設定がパブリックプロジェクトにない場合にのみ必要です。

次の制限事項に注意してください:

• ブランチが指定されていない場合、スケジュールされたパイプライン実行ポリシーはデフォルトのブランチでのみ実行されます。
• branches配列で、最大5つの一意のブランチ名を指定できます。
• パイプラインの適切な分散を確保するには、時間枠を少なくとも10分（600秒）にする必要があります。
• セキュリティポリシープロジェクトごとにスケジュールされたパイプライン実行ポリシーの最大数は、1つのスケジュールで1つのポリシーに制限されています。
• この機能は実験的なものであり、今後のリリースで変更される可能性があります。
• 利用可能なRunnerが不足している場合、スケジュールされたパイプラインが遅延する可能性があります。
• スケジュールの最大頻度は毎日です。

トラブルシューティング

スケジュールされたパイプラインが期待どおりに実行されない場合は、次のトラブルシューティングの手順に従ってください:

1. Verify experimental flag（実験的フラグの確認）: policy.ymlファイルのexperimentsセクションで、pipeline_execution_schedule_policy: enabled: trueフラグが設定されていることを確認します。
2. Check policy access（ポリシーアクセスの確認）: 以下を確認します:
   • CI/CD設定ファイルは、別のプロジェクトからリンクされているのではなく、セキュリティポリシープロジェクトに保存されています。
   • パイプライン実行ポリシーの設定が、セキュリティポリシープロジェクト（設定>一般>可視性、プロジェクトの機能、権限）で有効になっている。
3. Validate CI configuration（CI設定）を検証する:
   • CI/CD設定ファイルが、指定されたパスに存在することを確認します。
   • 手動パイプラインを実行して、設定が有効であることを確認します。
   • 設定に、スケジュールされたパイプラインの適切なワークフロールールが含まれていることを確認します。
4. Verify policy configuration（ポリシー設定の検証）:
   • ポリシーが有効になっていることを確認します（enabled: true）。
   • スケジュール設定に正しい形式と有効な値があることを確認します。
   • ブランチを指定した場合は、ブランチがプロジェクトに存在することを確認します。
   • タイムゾーン設定が正しいことを確認します（指定されている場合）。
5. Review logs and activity（ログとアクティビティーのレビュー）:
   • セキュリティポリシープロジェクトのCI/CDパイプラインログにエラーがないか確認します。
6. Check runner availability（ランナーの可用性を確認）:
   • Runnerが利用可能で、適切に設定されていることを確認します。
   • Runnerに、スケジュールされたジョブを処理する能力があることを確認します。